Home

NoETL CLI

noetl is the command-line client for the NoETL runtime. It runs playbooks, registers credentials and catalog entries, manages executions, and configures local connections to NoETL servers and gateways.

This wiki is the developer / operator reference for the CLI. The in-repo README remains the quick-start; the pages here document each surface in depth.

Note on binary names. The release builds two interchangeable binaries from the same source tree: noetl and ntl. Examples in this wiki use noetl; substitute ntl if you installed that alias.

What the CLI does

• Run a playbook (noetl run, noetl exec).
• Inspect executions (noetl status, noetl list).
• Manage the catalog (noetl catalog list/register/explain).
• Manage credentials and the keychain.
• Run database and cluster lifecycle operations (noetl k8s deploy, noetl db init).
• Bridge to MCP for catalog-driven agent dispatch.

Connecting to a NoETL cluster

Pick the page that matches your situation:

You want to …	Read
Connect to a public gateway with Auth0 SSO	Connecting to a cluster → "Gateway-authenticated path"
Connect to a remote in-cluster server over kubectl port-forward	Connecting to a cluster → "Port-forward path" + noetl context port-forward
Connect to a local dev server (noetl server running locally)	Connecting to a cluster → "Direct path"
Bootstrap a new context from a gateway URL in one command	noetl context init --from-gateway
Tweak an existing context (e.g. paste in a new Auth0 client_id)	noetl context update

Context model

The CLI stores its server endpoints, Auth0 application metadata, runtime preference, and optional kube fields under named contexts in ~/.noetl/config.yaml. One context is current; noetl --context <name> … overrides it for a single command without changing the current one.

• Context model overview
• noetl context add — create from CLI flags
• noetl context init --from-gateway — bootstrap from the gateway runtime contract
• noetl context update — patch fields in place
• noetl context port-forward — managed kubectl port-forward daemon, one per context
• noetl context list / use / current / delete / set-runtime

Authentication

• noetl auth login — gateway login paths (password grant, browser PKCE, callback paste, raw token)
• Browser PKCE pre-flight now prints the Auth0 dashboard URL so operators can verify the callback URL is allowlisted before the browser opens. See auth-login → PKCE pre-flight hint.

Global flags

• noetl --context <name> — one-off context override (mirrors kubectl --context and gcloud --account).

Exit codes

• Exit codes — includes the dedicated 77 for gateway-401 stale-token responses, so calling scripts can branch on "session expired" without parsing stderr.

Distribution

Channel	Detail
crates.io	cargo install noetl
Container	docker pull noetl/cli:<tag>
Linux package	See apt wiki for the apt repo.

Cross-references

• noetl wiki — the runtime the CLI talks to.
• gateway wiki — the authenticated path the CLI uses for remote clusters; the GET /api/runtime/contract endpoint is what noetl context init --from-gateway reads.
• ops wiki — Kubernetes manifests and Helm install the CLI deploys.
• Ephemeral Blueprints — the architecture principle the CLI honors (gateway = gatekeeper, workers = atomic compute blocks, playbooks = ephemeral blueprints).