context model

Context model

A context is a named bundle of settings the CLI uses to reach a NoETL deployment. Contexts live in ~/.noetl/config.toml; one of them is the current context, and every command that talks to a server reads its endpoint and auth settings from the current context unless the global --context <name> flag overrides it.

What a context stores

Field	Purpose
server_url	HTTP base URL the CLI calls. For a gateway, this is the gateway's public URL; for a port-forward, the loopback URL the local kubectl tunnel is bound to; for direct, the dev server URL.
runtime	Default execution mode: local, distributed, or auto. Per-command --runtime flags override it.
auth0_domain	Auth0 tenant domain (e.g. acme.us.auth0.com). The gateway uses this per-request to validate tokens; the CLI uses it when building the Auth0 browser authorization URL.
auth0_client_id	Auth0 application client_id the SPA + this CLI both authenticate against.
auth0_redirect_uri	Auth0 callback URL the SPA registers. The CLI prints this in the PKCE pre-flight so operators can confirm it matches the Auth0 dashboard allowlist.
auth0_audience	Optional API audience for password grant.
auth0_client_secret	Optional Auth0 application client_secret (only required for password grant in some configurations).
gateway_session_token	Cached gateway session token after a successful noetl auth login.
kube_context	Kubernetes context name (e.g. gke_acme_us-central1_prod) used by noetl context port-forward.
kube_namespace	Namespace the in-cluster noetl service lives in.
kube_service	Service name (defaults to noetl).
kube_remote_port	In-cluster service port (defaults to 8082).

The kube_* fields are optional. They are only consulted by noetl context port-forward; commands like noetl exec and noetl catalog ignore them.

Which command writes which fields

Field	context add	context init --from-gateway	context update
server_url	required	from gateway URL	optional
runtime	default auto	default distributed (override with --runtime)	optional
auth0_*	from CLI flags	from GET /api/runtime/contract auth0 block	optional (empty string clears)
kube_*	from CLI flags	not set (use context update after)	optional (empty string clears)
gateway_session_token	not set	not set	not touched

gateway_session_token is only set by noetl auth login.

Creating, switching, inspecting

Goal	Command
Create from CLI flags	noetl context add
Bootstrap from a gateway URL	noetl context init --from-gateway
Patch fields in place	noetl context update
List all contexts	noetl context list
Show the current context	noetl context current
Switch the current context	noetl context use <name>
Delete a context	noetl context delete <name>
Set default runtime mode	noetl context set-runtime <local|distributed|auto>

See context-list-use-delete for the read / switch / delete subcommands.

Per-command override

noetl --context <name> <subcommand> runs one command against the named context's server_url, runtime, Auth0 settings, and cached session token without changing the current context. The named context must exist; the command errors out otherwise. Full reference: Global flags.

Storage location

~/.noetl/config.toml             # all contexts
~/.noetl/port-forwards/*.pid     # PID files for managed port-forwards

The PID directory is created on first noetl context port-forward --detach.

Security and the boundary

The CLI never reads or writes domain data directly — that's a gateway-violation per the architecture model. Every data operation routes through the gateway (Auth0-authenticated path) or directly to the noetl server (http://localhost:8082) which then dispatches playbook blocks. The context file only stores the addresses and identities needed to reach those entry points.

Business-logic secrets (third-party API tokens, tenant DSNs) do not go in the context file. They live in the NoETL keychain and are referenced by alias inside playbook steps. See the secrets and redaction wiki page.