> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Authentication

> Authenticate the DevHelm CLI — API tokens, environment variables, saved contexts, and interactive login

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:

1. **`--api-token` flag** on the command
2. **`DEVHELM_API_TOKEN`** environment variable
3. **Saved context** in `~/.devhelm/contexts.json`

The first match wins. If no token is found, the command fails with [exit code `4`](/cli/exit-codes) (validation — missing precondition).

## API URL resolution order

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

1. **`--api-url` flag** on the command
2. **`DEVHELM_API_URL`** environment variable
3. **Saved context** `apiUrl` field
4. 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)

```bash theme={null}
export DEVHELM_API_TOKEN=dh_live_xxxxxxxx
```

Set this in your CI/CD pipeline as a secret. All commands will use it automatically.

## Interactive login

Log in from your terminal to save credentials locally:

```bash theme={null}
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:

```bash theme={null}
devhelm auth login --token dh_live_xxxxxxxx
```

## Verify your identity

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
devhelm auth context list
```

The active context is marked with an asterisk.

### Switch context

```bash theme={null}
devhelm auth context use production
```

### Delete a context

```bash theme={null}
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:

```bash theme={null}
devhelm auth logout
```

## Display the current token

Useful for piping into other tools:

```bash theme={null}
devhelm auth token
```

## Precedence override

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

```bash theme={null}
devhelm monitors list --api-token dh_live_other_token
```

## Next steps

<CardGroup cols={2}>
  <Card title="Global flags" icon="sliders" href="/cli/global-flags">
    Output format, verbosity, and other global options.
  </Card>

  <Card title="Auth commands" icon="terminal" href="/cli/commands/auth">
    Full reference for all auth subcommands.
  </Card>
</CardGroup>