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

# Command line

> The whileai command: sign in, check which key is in use, write an eval harness into a project, and read or promote what the platform tracks.

`pip install whileai` puts a `whileai` command on your path. Everything
else is Python.

| Command                                  | What it does                                                           |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| `whileai login`                          | Sign in from this terminal. Opens the browser, saves a key.            |
| `whileai signup --email you@example.com` | Create an account and a key, no browser.                               |
| `whileai status`                         | Show which key the SDK will use and where it came from.                |
| `whileai logout`                         | Delete the saved key.                                                  |
| `whileai init-evals`                     | Write an eval harness (agent, judge, run, test) wired to this project. |
| `whileai agents`                         | List the agents tracked on your account.                               |
| `whileai agent <id>`                     | One tracked agent: record, behaviors, verdict.                         |
| `whileai runs <id>`                      | The training runs of one agent, newest first.                          |
| `whileai verdict <id>`                   | Does the candidate beat the served version, and is it real.            |
| `whileai promote <id> <version>`         | Make a version the served one.                                         |
| `whileai live <id> ...`                  | Report one day of traffic on the served version.                       |
| `whileai keys`                           | List the API keys on your account, names and prefixes.                 |

## Sign in

```bash theme={null}
whileai login
```

The command prints a link and waits for you to approve it in the browser.
Then it saves a key on this machine. `--no-browser` prints the link only,
`--no-wait` returns at once so you can run it again to finish, `--name`
labels the key on your account (default `cli <host>`).

No browser at all, for example on a server:

```bash theme={null}
whileai signup --email you@example.com
```

That creates the account and saves its key in one step.

## Which key is in use

```bash theme={null}
whileai status
```

The SDK resolves a key in this order: an explicit `api_key=` argument,
the `WHILEAI_API_KEY` environment variable, then the saved credentials
from `login` or `signup`. `status` says which one won.

## Write an eval harness

```bash theme={null}
whileai init-evals --agent app.agent:answer --tools app.agent:TOOLS --system-prompt app.agent:SYSTEM
```

This writes five files into `evals/` (change with `--dir`): the agent
wrapper, a judge, a runner, a test that goes red in CI when the pass rate
drops, and a README. The three flags point at the callable, the tool list
and the system prompt as `module:name`. Leave them out and the command
looks for them in the project. `--force` overwrites files that are
already there.

What the harness computes and how to read it is on the
[evals guide](/evals).

## Read and promote what the platform tracks

The platform verbs a coding agent needs, as commands. Each is a thin call
into `whileai.platform`.

```bash theme={null}
whileai agents                 # tracked agents and what each serves
whileai agent <id>             # record, behaviors, verdict
whileai runs <id>              # the version table, newest first
whileai verdict <id> [--behavior <name>]
whileai promote <id> <version>
whileai live <id> --day YYYY-MM-DD --version <v> --replies N [--flagged N --p50 S --cost USD]
whileai keys
```

All of them take `--json` to print the API's JSON and `--api-key` to use
a key other than the saved one. Errors exit 1 with the reason on stderr.
`verdict` defaults to the latest run's target behavior; `--behavior`
picks another. `live` records a day of production traffic on the served
version: how many replies, how many failed a check, the median latency and
the spend, so the platform can compare production with the held-out
score.

<Note>
  The old `whileai purge` command is gone. `wai.purge_agent("name")` and
  `wai.delete_empty_datasets(max_rows=2)` remain in Python, both with
  `dry_run=True`, until the ingest module is retired.
</Note>