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

# Wait

> Block until a run reaches a terminal status. kubectl-wait-style exit codes for shell scripting.

# Wait

`cmd/crewship/cmd_wait.go` polls a run's status until it transitions to a final state, then exits with a status-aware code so scripts can act on the outcome without re-parsing JSON.

The run id may be an **agent run or a routine (pipeline) run** — the agent-run endpoint is probed first, and a 404 falls through to the routine-run endpoint, so callers don't have to know which subsystem produced the id.

## `crewship wait <run-id>`

| Flag               | Type     | Default | Effect                                                                             |
| ------------------ | -------- | ------- | ---------------------------------------------------------------------------------- |
| `--timeout <dur>`  | duration | `30m`   | Hard ceiling on the wait. `0` = forever.                                           |
| `--interval <dur>` | duration | `2s`    | Poll cadence. Values ≤ 0 fall back to `2s`.                                        |
| `-q`, `--quiet`    | bool     | `false` | Print only the terminal status string (no `[wait]` log lines, no `[done]` banner). |
| `--routine`        | bool     | `false` | Treat `<run-id>` as a routine run id and skip the agent-run probe.                 |

A routine run parked on a human approval (status `waiting`) is **not** terminal — wait keeps polling until the waitpoint is approved/rejected and the run finishes, or `--timeout` fires.

When neither `--quiet` nor a structured `--format` (`json`/`yaml`/`ndjson`) is set, status transitions are logged to stderr as `[wait] <run> status=<S> elapsed=<dur>` and the final state lands on stdout as `[done] <run> status=COMPLETED elapsed=12s`.

### Exit codes

| Code | Meaning                                                                                |
| ---- | -------------------------------------------------------------------------------------- |
| `0`  | `COMPLETED` (or a routine `dry_run`)                                                   |
| `1`  | `FAILED` (or a routine `interrupted` by a server restart)                              |
| `2`  | `CANCELLED`                                                                            |
| `3`  | `TIMEOUT` — server-reported, or `--timeout` reached                                    |
| `4`  | Network/auth error before any status could be read, or the id matched neither run kind |

### Examples

```bash theme={null}
RUN=$(crewship ask --no-stream -q "do X" | jq -r .id)
crewship wait "$RUN" && echo "done" || echo "broke"

crewship wait r_abc --interval 500ms --timeout 5m
crewship wait r_abc --quiet                       # prints "COMPLETED" or similar
crewship wait r_abc --format json                 # full RunDetail on completion

# Routine runs work too — e.g. the run_id from `crewship routine run`
crewship wait prun_xyz --routine --timeout 10m
```

## See also

* [`crewship watch`](/cli/watch) — live event tail (use to follow what's happening *during* the run).
* [`crewship history`](/cli/history) — find a run-id to wait on.
* [`crewship retry <run-id>`](/cli/retry) — kick off a fresh run that you'll likely want to `wait` on.