auth login

noetl auth login

Authenticate against the NoETL gateway and (optionally) cache the gateway session token in the current context.

noetl auth login [flags]

The CLI supports four input modes, picked by which flag you pass:

Mode	Flag	When to use
Raw token	--auth0-token <ID_TOKEN>	You already have an Auth0 ID/access token from another tool.
Callback URL	--auth0-callback-url <URL>	You logged in via the SPA and want to copy/paste the full callback URL with #id_token=….
Password grant	--auth0 <email> --password	Headless / scripts. Prompts for password in the terminal.
Browser PKCE	--browser-pkce	Interactive workstation login. The CLI runs a localhost callback server, opens the Auth0 authorization URL, and exchanges the code for a session token.
Browser (device)	--browser	gcloud-style device login without callback copy/paste.

A successful login caches the gateway session token onto the context (or --context <name> if passed). Subsequent CLI commands send that token to the gateway automatically.

Common flags

Flag	Purpose
--auth0 <EMAIL|TOKEN|URL>	Unified input — CLI infers shape.
--auth0-token <TOKEN>	Raw token mode (explicit).
--auth0-callback-url <URL>	Paste-callback mode (explicit).
--auth0-domain <DOMAIN>	Override the context's Auth0 domain.
--auth0-client-id <ID>	Override the context's Auth0 client_id.
--auth0-redirect-uri <URL>	Override the context's Auth0 redirect URI.
--auth0-audience <AUD>	Set / override the API audience.
--auth0-client-secret <SECRET>	For password grant when the Auth0 application requires it. Also reads NOETL_AUTH0_CLIENT_SECRET.
--browser	Device login flow.
--browser-pkce (alias --pkce)	Browser PKCE flow with localhost callback.
--pkce-port <PORT>	Local port for the PKCE callback (default 8765).
--no-browser-open	Don't auto-open the browser — print the URL only.
--password	Use Auth0 password grant. Prompts for password if not supplied.
--context <NAME>	Cache the resulting session token onto a specific context instead of the current one.

The full clap-level list is in noetl auth login --help; the table above covers the flags people actually reach for.

Browser PKCE flow

noetl auth login --browser-pkce

1. CLI prints a pre-flight notice (see below).
2. Local listener binds 127.0.0.1:<pkce-port>.
3. CLI opens the Auth0 authorization URL with response_type=code, the PKCE challenge, and a localhost redirect_uri.
4. After the user authenticates, Auth0 redirects to http://127.0.0.1:<pkce-port>/...?code=....
5. CLI exchanges the code for tokens, calls the gateway's /api/auth/login, and caches the returned session token.

PKCE pre-flight hint

Available since noetl v2.15.0 (PR #13).

Before launching the browser, the CLI prints:

Browser PKCE login.

  Auth0 tenant:    acme.us.auth0.com
  Client ID:       Abc123XYZ...
  Redirect URI:    http://127.0.0.1:8765/callback
  PKCE port:       8765

  This callback URL must be allowlisted on the Auth0 application.
  Dashboard: https://manage.auth0.com/dashboard/us/acme/applications/Abc123XYZ/settings

  If the browser shows "Callback URL mismatch", add the redirect URI
  above to "Allowed Callback URLs" in the dashboard and try again.

Opening browser ...

The dashboard URL is derived from auth0_domain (<tenant>.<region>.auth0.com → https://manage.auth0.com/dashboard/<region>/<tenant>/...). This exists because the most common PKCE failure mode is "Callback URL mismatch" — and the operator's first reaction is usually "where do I add it?" The hint answers that directly.

PKCE timeout hint

If no callback arrives within the wait window, the CLI prints the same callback URL again with a "did you remember to allowlist it?" nudge, so a long timeout doesn't waste a fresh --browser-pkce run.

Password grant flow

noetl auth login --auth0 user@example.com --password

Prompts for the password in the terminal (echo off), then performs the Auth0 password grant against <auth0_domain>/oauth/token. The ID token returned by Auth0 is sent to the gateway's /api/auth/login to get a session token.

Some Auth0 applications require a client_secret for password grant. Pass it via --auth0-client-secret or NOETL_AUTH0_CLIENT_SECRET.

Raw token / callback URL

When you already have an Auth0 token (or the full SPA callback URL including the #id_token= fragment), pass it directly:

noetl auth login --auth0-token "$ID_TOKEN"
noetl auth login --auth0-callback-url "https://app.acme.com/login#id_token=eyJh..."

The CLI extracts the token from the URL fragment if needed and posts it to the gateway.

Caching the token onto a different context

By default the session token is cached on the current context. Use --context to target a different one:

noetl auth login --browser-pkce --context gke-prod

This is most useful when you have multiple gateway contexts and want to refresh tokens for the right one without first running noetl context use.

After a successful login — do I need to export the token?

No. A successful noetl auth login writes the gateway session token directly onto the context file, and every subsequent CLI call against that context reads it from there. The "Use this session for CLI calls: export NOETL_SESSION_TOKEN=…" hint printed after login is for other tools that read the env var (e.g. curl against the gateway, ad-hoc scripts), not for the CLI itself.

After a login like this:

Gateway login successful.
  Gateway: https://gateway.acme.com
  User:    you@example.com
  Token:   69dd6f...2bc6
  Saved:   context 'gke-prod'

Use this session for CLI calls:
  export NOETL_SESSION_TOKEN='69dd6f8a7621ca3cd1e8924460842bc6'

…you're done. Verify with a one-shot command:

noetl --context gke-prod catalog list Playbook

A list of playbooks means you're authenticated end-to-end. To make the override persistent for the shell session, switch the current context:

noetl context use gke-prod
noetl catalog list Playbook

When to actually export NOETL_SESSION_TOKEN

Use the env-var path only when:

• You're calling the gateway from a tool that reads NOETL_SESSION_TOKEN (curl, custom scripts).
• You want a one-off command to use a token without writing it to the context file (e.g. testing an admin token nobody should persist).

For everyday CLI usage against the named context, ignore the export hint.

State after a login

~/.noetl/config.yaml
└── contexts.<name>
    ├── server_url             = https://gateway.acme.com
    ├── auth0_*                (set by context add / context init)
    └── gateway_session_token  = 69dd6f...2bc6   ← just cached

The token stays cached until either:

• The next noetl auth login --context <name> overwrites it.
• The gateway rejects it (session expired) — the CLI exits 77 at that point. See below.

Exit code 77 — gateway session expired

Available since noetl v2.15.0 (PR #13).

If any CLI command receives a 401 from the gateway while using a cached session token, the CLI exits with code 77 and a clear message:

Gateway returned 401 (session expired) for context 'gke-prod'.
  Refresh the session token:  noetl auth login --browser-pkce

Scripts can branch on exit code 77 to auto-trigger noetl auth login without having to grep stderr. See Exit codes for the full table.

See also

• Context model — Auth0 fields that drive this command.
• noetl context init --from-gateway — discover the Auth0 fields from the gateway runtime contract before logging in.
• Connecting to a cluster — full end-to-end flow.
• Exit codes — including 77 for "session expired".