# Client commands.

> Drive Koidog from a terminal with an API key.
> https://koi.dog/docs/client-commands/

## Setup.

These commands talk only to `/api/v1`. Create a key in Settings → API and put it in `KOIDOG_API_KEY`; no flag takes it.

| Variable | Default | What it is |
| --- | --- | --- |
| `KOIDOG_API_KEY` | None | An API key, kdk\_… Never printed. |
| `KOIDOG_URL` | Paired server | The Koidog server to talk to. |

- `--json`: Machine-readable output: one JSON document.
- `--url <u>`: The Koidog server, before `KOIDOG_URL` or the paired one.

## Key.

```text
koidog api whoami
```

Shows the key in use, its scopes and its rate limit.

## Crews.

```text
koidog crews list [flags]
```

Lists crews.

- `--project <id>`: Only this project's crews.
- `--state <states>`: Only these states, such as running,paused.
- `--limit n`: At most n crews.

```text
koidog crews get <crewId>
```

Shows one crew: state, project, mode, size and agents.

```text
koidog crews launch --project <id> --goal "..." [flags]
```

Prints the forecast and launches only with `--yes`. Uses paired machines only, unless `--cloud` is given.

- `--project <id>`: The project to work on. Required.
- `--goal "..."`: What the crew should do. Required.
- `--size n`: Requested workers.
- `--mode <mode>`: direct or managed.
- `--task "..."`: One task as "Title: instructions". Repeat for more.
- `--connection <id>`: The builders' connection, else the only usable one.
- `--cloud`: Use cloud VMs. Alone, cloud only.
- `--local`: With `--cloud`, use paired machines too.
- `--budget <usd>`: Hard cap on this crew's cloud compute.
- `--max-vms n`: At most n cloud VMs.
- `--timeout <minutes>`: Time limit for the crew.
- `--yes`: Launch. Without it, only the forecast prints.

```text
koidog crews watch <crewId>
```

Follows the crew's events until it ends. Exits 0 if it completed. With `--json`, one event per line.

```text
koidog crews cancel <crewId>
```

Cancels the crew and stops every agent.

## Pull requests.

```text
koidog prs list [flags]
```

Lists the pull requests Koidog opened.

- `--state <states>`: Only these states, such as open,merged.
- `--project <id>`: Only this project's pull requests.
- `--crew <id>`: Only this crew's pull requests.
- `--limit n`: At most n pull requests.

## Agents.

```text
koidog agents move <agentId> [flags]
```

Prints where the agent could go. Moves only with `--to` and `--yes`.

- `--to <where>`: stay, cloud, local or a node id. `local` keeps the agent's model, so it cannot be combined with `--connection`, `--model` or `--effort`.
- `--connection <id>`: Switch the agent to this connection.
- `--model <m>`: Switch the model.
- `--effort <e>`: Switch the effort: `low`, `medium`, `high`, `xhigh` or `max`.
- `--yes`: Move. Without it, only the choices print.

## Exit codes.

| Code | Means |
| --- | --- |
| `0` | Done. For crews watch: the crew completed. |
| `1` | The API refused the request, the forecast has blockers, or the watched crew ended without completing. |
| `64` | Wrong command or flag, or no `KOIDOG_API_KEY`. |
| `69` | The server could not be reached. |
| `70` | Anything else went wrong. |
| `130` | crews watch stopped before the crew ended. |
