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

# Account and authentication

> Authenticate the Archal CLI with archal login, sign out, and check your active workspace, plan, and pooled clone-minute usage from the terminal.

These commands manage your CLI account session: signing in, signing out, and
checking your active workspace.

## `archal login`

```bash theme={null}
archal login [options]
```

Opens a browser window to authenticate. Local credentials are saved under
`~/.archal/`.

| Flag              | Description                                                        | Default       |
| ----------------- | ------------------------------------------------------------------ | ------------- |
| `--no-browser`    | Print the login URL instead of opening it automatically            | opens browser |
| `--device`        | Use device login for SSH or containers                             | off           |
| `--token <token>` | Use an API key or token directly (for CI or headless environments) | -             |

### Where credentials are stored

`~/.archal/credentials.json` stores your account identity, active workspace,
workspace role, workspace plan snapshot, workspace clone catalog, expiry, and encrypted
token fields. On macOS, Archal uses Keychain when available.

You can also set the `ARCHAL_TOKEN` environment variable for CI or other non-interactive environments.

## `archal logout`

```bash theme={null}
archal logout
```

Removes `~/.archal/credentials.json`. Commands that need auth will prompt you
to log in again.

## `archal whoami`

```bash theme={null}
archal whoami [options]
```

Displays your active workspace, workspace plan, and pooled workspace usage.

| Flag        | Description                                       | Default |
| ----------- | ------------------------------------------------- | ------- |
| `--refresh` | Fetch fresh usage from the server before printing | `false` |
| `--live`    | Alias for `--refresh`                             | `false` |

```bash theme={null}
archal whoami --live
```

```
Workspace: acme-prod (550e8400-e29b-41d4-a716-446655440000)
Workspace plan: pro

Workspace session-minutes: 47 / 5000 used (4953 remaining)
Active workspace sessions: 1 / 10

Workspace LLM request caps (not the eval-session pool):
  Eval model calls: 12 / 100 calls/day (88 remaining)
```

`archal plan`, `archal whoami`, and `archal usage` show the same active
workspace usage. Switch workspaces when you want the CLI to use a different
project's pooled usage.