# CLI

The kestrel command: set up a repo, start runs, read traces and edit memory from the terminal.

```bash Terminal
npm i -g kestrel   # or run any command with npx kestrel
```

The CLI reads `KESTREL_API_KEY`, or asks you to sign in in the browser the first time.

## Commands

| Command | What it does |
|---|---|
| `kestrel init` | Add a `kestrel.yaml` with commands it found in the repo |
| `kestrel run "<task>"` | Start a run on the current repo and follow it |
| `kestrel runs list` | List runs, newest first |
| `kestrel runs cancel <id>` | Cancel a queued or running run |
| `kestrel trace <id>` | Print a run's trace |
| `kestrel sandbox` | Open a shell in a new sandbox for the current repo |
| `kestrel memory list` | Show the repo's memory |
| `kestrel memory add "<fact>"` | Add a fact |
| `kestrel memory forget <topic>` | Remove facts on a topic |

## kestrel run

```bash Terminal
kestrel run "fix the flaky checkout test" --agent codex --repeat-tests 20 --no-follow
```

| Flag | Default | What it does |
|---|---|---|
| `--repo` | the current repo | Run on another repo |
| `--agent` | from `kestrel.yaml` | Pick the agent for this run |
| `--from` | none | Start from a snapshot |
| `--repeat-tests` | 1 | Run the tests this many times in the gate |
| `--no-follow` | off | Print the run id and return at once |
| `--json` | off | Print machine-readable output |

## Exit codes

| Code | Meaning |
|---|---|
| `0` | A pull request opened |
| `1` | The run stopped at the eval gate (`needs_review`) |
| `2` | The run failed or was cancelled |
| `3` | Bad input or a missing key |