global context flag

noetl --context <name> — per-command context override

The global --context <name> flag runs one command against the named context's server_url, runtime, Auth0 settings, and cached session token, without changing the current context.

Available since noetl v2.17.0 (PR #17).

noetl --context <name> <subcommand> [...]

Mirrors the UX of kubectl --context and gcloud --account.

Why this exists

The previous workflow for "run one command against a different deployment" was:

noetl context use gke-prod
noetl catalog list Playbook
noetl context use local

That mutated the current context twice for a single observation, which is awkward in scripts and confusing if the second context use is forgotten. With --context:

noetl --context gke-prod catalog list Playbook

The current context is unchanged.

Where the flag is valid

--context is a global clap flag (global = true), so it works in front of any subcommand. The CLI parses it before dispatching to the subcommand handler.

noetl --context gke-pf  catalog list Playbook
noetl --context smoke   register credential -f cred.json
noetl --context local   exec ./playbooks/foo.yaml

Errors

If the named context doesn't exist, the CLI exits with a descriptive message and a pointer to noetl context list:

$ noetl --context typo catalog list Playbook
Context 'typo' not found.  Run ``noetl context list`` to see
configured contexts, or create it with ``noetl context add`` /
``noetl context init --from-gateway``.

Interaction with --gateway and --session-token

The flag overrides the named context the CLI reads from, but existing global flags still win where they apply:

• --gateway forces gateway-proxy mode regardless of context.
• --session-token=<TOKEN> overrides whatever session token the selected context has cached.

These compose with --context:

noetl --context gke-prod --session-token=$NEW_TOKEN catalog list Playbook

What gets used from the override context

Behavior	Source under --context <name>
Where to send HTTP requests	<name>.server_url
Default runtime mode	<name>.runtime (unless --runtime is passed per command)
Auth0 fields for noetl auth login	<name>.auth0_*
Cached session token used for gateway calls	<name>.gateway_session_token

What is not changed

• The current context (~/.noetl/config.yaml is read but not written).
• The cached session token on the override context — --context does not write to the file.

To persist a switch, use noetl context use <name>.

Examples

# Inspect catalog on a remote gateway without leaving the local context
noetl --context gke-prod catalog list Playbook

# Register a credential against a port-forwarded server, current
# context stays put
noetl --context gke-pf register credential -f duffel.json

# Smoke test against multiple deployments in a loop
for ctx in local gke-pf gke-prod; do
  echo "=== $ctx ==="
  noetl --context "$ctx" catalog list Playbook
done

# Override session token for a one-off privileged call
noetl --context gke-prod --session-token=$ADMIN_TOKEN catalog register \
  -f ./playbooks/admin.yaml

See also

• Context model — what's stored per context.
• noetl context use — persistent switch.
• noetl context init --from-gateway — bootstrap a context once, then use --context to address it.