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

# Authentication and account

> Authenticate Miles, check readiness, and read account usage.

## `miles auth`

Device-code authentication. The user approves a code in their browser; the agent must never ask them to paste an account key into chat.

| Command                                                                                                                | Mode     | Use                                                  |
| ---------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------- |
| `miles auth status [--json]`                                                                                           | Headless | Show whether Miles is signed in and the active site. |
| `miles auth login [--json]`                                                                                            | Headless | Create a device code and approval URL, then exit.    |
| `miles auth poll [deviceCode] [--interval <seconds>] [--expires-in <seconds>] [--timeout <seconds>] [--once] [--json]` | Headless | Wait for the device-code approval.                   |
| `miles auth logout [--json]`                                                                                           | Headless | Remove local Miles credentials.                      |

`auth login --json` returns `userCode`, `verificationUrl`, `intervalSeconds`, `expiresInSeconds`, and `pendingState`. It also contains a private `deviceCode`; do not show that value to the user or put it in logs.

Show the user the code and URL, confirm the code matches in the browser, then run `auth poll`. Polling can return `authorized`, `pending`, `rate_limited`, `expired`, `denied`, `timeout`, `transport_error`, or `sandbox_network_blocked`.

## `miles doctor`

```bash theme={"dark"}
miles doctor --json
```

Checks the local CLI installation, runtime, credential state, and server capabilities. Run it when setup is incomplete or when a command reports that the connected Miles service does not support a feature.

## `miles account-status`

```bash theme={"dark"}
miles account-status --json
```

Returns the current `plan`, a `credits` object, `siteCount`, and `activeSite`. The credit fields include total spendable credits, allowance and top-up balances, usage percentage, and period end.

Use it before a full build or WordPress conversion when account headroom is uncertain.

## `miles usage-history`

```bash theme={"dark"}
miles usage-history [--limit <n>] [--offset <n>] [--type purchase|usage|bonus|adjustment] [--json]
```

Returns `transactions` and `pagination`. Each transaction includes `id`, `type`, `amountCredits`, `isDeduction`, `balanceAfterCredits`, `description`, and `createdAt`. `limit` is capped at 100.

## Supporting command

`miles balance` is a compatibility helper that reads available credits through the active site. Prefer `account-status` for new work because it does not require an active site and gives the fuller account picture.

Next: [Sites and context](/reference/miles-cli/sites-and-context).