> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Auth commands
description: Reference for logging in, logging out, and checking authentication status from the CLI.
category: CLI
last_verified: 2026-07-24
hideRightSidebar: true
---

**`agnt5 auth`** manages the credentials the CLI uses to talk to the Control Plane. Authentication is required before you can create projects, deploy, or manage secrets. Credentials are stored in `~/.agnt5/config.yaml` and read on every invocation.


**Commands**: `agnt5 auth login [--api-key <value>]`, `agnt5 auth logout`, `agnt5 auth status`, `agnt5 auth whoami` (also `agnt5 whoami`)
**Credential store**: `~/.agnt5/config.yaml` (persisted on login, read on every invocation)
**Env overrides**: `AGNT5_API_KEY` bypasses the login command; `AGNT5_API_URL` overrides the Control Plane URL
**Auth flow**: browser-based OAuth via PropelAuth; CLI polls the Control Plane until an API key is issued


## Command summary

| Command | Purpose |
| --- | --- |
| `auth login` | Authenticate via the browser, or with an existing API key. |
| `auth logout` | Clear stored credentials. |
| `auth status` | Show authentication state, identity, and target API URL. |
| `auth whoami` | Print the authenticated user's email. Also `agnt5 whoami`. |

## `agnt5 auth login`

```bash
agnt5 auth login [options]
```

Launches the authentication flow. By default the CLI requests a short-lived session ID from the Control Plane, opens your browser to the login screen, and polls until an API key is issued. The key is persisted to `~/.agnt5/config.yaml` so subsequent commands can reuse it.

| Flag | Description |
| --- | --- |
| `--api-key <value>` | Skip the browser flow and provide an existing API key. The CLI validates the key by fetching the current user before saving it. |

```bash
agnt5 auth login
agnt5 auth login --api-key agnt5_sk_abc123...
```

<Callout type="info">
The CLI respects `AGNT5_API_URL` and other context settings when constructing the OAuth URLs, so confirm your [context](/docs/cli/context.md) is correct before logging in. In CI, set `AGNT5_API_KEY` in the environment to bypass the login command entirely.
</Callout>

## `agnt5 auth logout`

```bash
agnt5 auth logout
```

Clears stored API keys and tokens from `~/.agnt5/config.yaml`. Re-authenticate later with `agnt5 auth login`.

## `agnt5 auth status`

```bash
agnt5 auth status
```

Shows whether you are authenticated: the email tied to the stored key, the active environment, and the API base URL. If the saved key is invalid or expired, the command reports the failure and suggests `agnt5 auth login`.

## `agnt5 auth whoami`

```bash
agnt5 auth whoami
```

Prints the email address tied to the stored credentials, or `Not authenticated` when no valid key is present. Also available as the top-level shortcut `agnt5 whoami`.

```bash
agnt5 whoami
```

## Next steps

- [Project & workspace commands](/docs/cli/project.md): create or link a project after logging in.
- [Configuration](/docs/cli/configuration.md): where credentials and context settings live on disk.
- [Secrets](/docs/cli/secrets.md): store API keys and connection strings once you're authenticated.
- [Troubleshooting](/docs/cli/troubleshooting.md): fix a stuck or invalid login.