CLI Authentication

The CLI resolves credentials from flags, environment variables, and saved contexts. Choose the method that fits your workflow.

Token resolution order

The CLI checks for an API token in this order:

--api-token flag on the command
DEVHELM_API_TOKEN environment variable
Saved context in ~/.devhelm/contexts.json

The first match wins. If no token is found, the command fails with exit code 4 (validation — missing precondition).

API URL resolution order

The base URL the CLI talks to is resolved in the same precedence order:

--api-url flag on the command
DEVHELM_API_URL environment variable
Saved context apiUrl field
Built-in default (https://api.devhelm.io)

Use --api-url for ephemeral overrides; use a context for persistent multi-environment setups.

Environment variable (recommended for CI)

export DEVHELM_API_TOKEN=dh_live_xxxxxxxx

Set this in your CI/CD pipeline as a secret. All commands will use it automatically. Log in from your terminal to save credentials locally:

devhelm auth login

This prompts for your API token, validates it against the API, and saves it to ~/.devhelm/contexts.json under a named context (default name: default; override with --name). If the API rejects the token, nothing is saved and the command exits with code 11. To skip the interactive prompt:

devhelm auth login --token dh_live_xxxxxxxx

Verify your identity

devhelm auth me

Shows the API key identity, organization, plan tier, rate limits, and usage counters for the resolved token. Use --output json for machine-readable output.

Named contexts

Contexts let you switch between multiple accounts or environments without re-entering credentials.

Create a context

devhelm auth context create staging \
  --token dh_live_xxxxxxxx \
  --api-url https://api.devhelm.io

The new context becomes the active one. (--set-current defaults to true and cannot currently be disabled — create the context, then devhelm auth context use <previous-name> to switch back.)

List contexts

devhelm auth context list

The active context is marked with an asterisk.

Switch context

devhelm auth context use production

Delete a context

devhelm auth context delete staging

Log out

Remove the active context (its token and API URL) from ~/.devhelm/contexts.json. If other contexts remain, the first one becomes active:

devhelm auth logout

Display the current token

Useful for piping into other tools:

devhelm auth token

Precedence override

Even with a saved context, you can override on a per-command basis:

devhelm monitors list --api-token dh_live_other_token

Getting Started

Commands

CLI Authentication

Token resolution order

API URL resolution order

Environment variable (recommended for CI)

Verify your identity

Named contexts

Create a context

List contexts

Switch context

Delete a context

Log out

Display the current token

Precedence override

Next steps

Global flags

Auth commands

​Token resolution order

​API URL resolution order

​Environment variable (recommended for CI)

​Interactive login

​Verify your identity

​Named contexts

​Create a context

​List contexts

​Switch context

​Delete a context

​Log out

​Display the current token

​Precedence override

​Next steps

Global flags

Auth commands

Token resolution order

API URL resolution order

Environment variable (recommended for CI)

Interactive login

Verify your identity

Named contexts

Create a context

List contexts

Switch context

Delete a context

Log out

Display the current token

Precedence override

Next steps