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

# Authenticate the Detail CLI with your Detail account

> Log in to the Detail CLI using a browser-based OAuth flow or pass a direct API token for CI/CD pipelines and headless environments.

Before using the Detail CLI, authenticate with your Detail account. The CLI supports a browser-based OAuth flow for local development and direct token entry via `--token` for CI/CD pipelines or headless environments.

## Browser-based login (recommended)

For local development, run `detail auth login` to open a browser window and complete the OAuth flow:

```bash theme={null}
detail auth login
```

The CLI opens `https://app.detail.dev/cli-auth` in your default browser. After you approve access, the CLI receives a token and saves it to `~/.config/detail-cli/config.toml`. You'll see a confirmation message like this one:

```text theme={null}
✓ Successfully authenticated!
Logged in as: user@example.com

Example commands:
  detail bugs list <owner>/<repo>
  detail bugs show <bug_id>
```

If your browser doesn't open automatically, the CLI prints the full URL so you can paste it yourself.

<Note>
  The browser flow uses PKCE (RFC 7636) for security. No client secret is transmitted — the CLI binds a local callback listener to receive the authorization code.
</Note>

## Token-based login

For automated pipelines or environments without a browser, pass an API token directly using `--token`:

```bash theme={null}
detail auth login --token dtl_live_YOUR_API_KEY
```

Tokens start with `dtl_`. Generate one in the Detail dashboard under **Settings → API Keys**.

<Tip>
  In automated pipelines, e.g. in CI or in your software factory of choice, store the token in a secret and pass it via an environment variable to avoid hard-coding credentials:

  ```bash theme={null}
  detail auth login --token $DETAIL_API_KEY
  ```
</Tip>

## Check authentication status

Verify that the CLI is authenticated and confirm which account is active:

```bash theme={null}
detail auth status
# ✓ Authenticated
# Email: user@example.com
```

If the stored token is invalid or has been revoked, `detail auth status` tells you to re-run `detail auth login`.

## Log out

Remove the stored token from your machine:

```bash theme={null}
detail auth logout
# ✓ Logged out successfully
```

This clears the `api_token` field from `~/.config/detail-cli/config.toml`. It does not revoke the token in the Detail dashboard; do that in **Settings → API Keys** if needed.

## Token storage

The CLI stores your token in `~/.config/detail-cli/config.toml` (Linux and macOS) or `%LOCALAPPDATA%\detail-cli\config.toml` (Windows). The file is created with permissions that restrict access to your user account.

<Warning>
  Do not commit `config.toml` to version control. Add `~/.config/detail-cli/` to your global `.gitignore` if you manage dotfiles in a public repository.
</Warning>

## Authentication subcommands summary

| Command              | Description                                  |
| -------------------- | -------------------------------------------- |
| `detail auth login`  | Log in via browser (PKCE OAuth) or `--token` |
| `detail auth status` | Show the currently authenticated account     |
| `detail auth logout` | Remove stored credentials                    |