> ## 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.

# Approvals Commands

> List and decide Harbormaster human-in-the-loop approval requests.

# crewship approvals

Manage the [Harbormaster](/guides/harbormaster) approval queue — list pending human-in-the-loop requests and decide them.

```bash theme={null}
crewship approvals <subcommand> [flags]
```

<Note>
  `list` is safe for any workspace member; `approve`, `deny`, and `cancel`
  require `OWNER` or `ADMIN` role server-side (403 otherwise).
</Note>

## Subcommands

| Command                    | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `list`                     | List approval requests.                                              |
| `get <id>`                 | Fetch a single approval request with full detail.                    |
| `approve <id>`             | Approve a pending request.                                           |
| `deny <id>`                | Deny a pending request.                                              |
| `cancel <id>`              | Withdraw a pending request (moves it to `cancelled`).                |
| `reset-auto-tuning <tool>` | Wipe rolling reward history for a tool to re-train gate auto-tuning. |

***

## `crewship approvals list`

```bash theme={null}
crewship approvals list                                    # pending only (default)
crewship approvals list --status approved --limit 100
crewship approvals list --status all                        # full history
```

| Flag       | Type     | Default   | Description                                                            |
| ---------- | -------- | --------- | ---------------------------------------------------------------------- |
| `--status` | `string` | `pending` | One of `pending`, `approved`, `denied`, `timeout`, `cancelled`, `all`. |
| `--limit`  | `int`    | `50`      | Max rows (server caps at 200).                                         |

Sample output:

```
req_01HXYZABCDEF         [pending ]  destructive_op    backend-team      viktor            rm -rf /data/*
req_01HXYZGHIJKL         [approved]  cost_threshold    backend-team      eva               Claude Opus 4.7 $7.20 estimate
req_01HXYZMNOPQR         [denied  ]  target_environm   platform          oliver            ssh ops@prod-db-01
```

Columns: ID, status chip (colored), kind, crew, agent, reason (truncated).

***

## `crewship approvals approve <id>`

```bash theme={null}
crewship approvals approve req_01HXYZABCDEF --comment "reviewed with staging validation"
```

| Flag        | Type     | Default | Description                                  |
| ----------- | -------- | ------- | -------------------------------------------- |
| `--comment` | `string` |         | Optional comment recorded with the decision. |

Sample output:

```
✓ Approval req_01HXYZABCDEF: approved (by user_123)
```

***

## `crewship approvals deny <id>`

```bash theme={null}
crewship approvals deny req_01HXYZABCDEF --comment "wrong mission target"
```

| Flag        | Type     | Default | Description                                  |
| ----------- | -------- | ------- | -------------------------------------------- |
| `--comment` | `string` |         | Optional comment recorded with the decision. |

***

## `crewship approvals cancel <id>`

Withdraw a still-pending request without approving or denying it. The request moves to the `cancelled` status. Use this when the gated action is no longer relevant (mission aborted, agent retired, duplicate request). Only pending requests can be cancelled — an already-decided or already-cancelled request returns a conflict.

```bash theme={null}
crewship approvals cancel req_01HXYZABCDEF
crewship approvals cancel req_01HXYZABCDEF --reason "mission aborted"
```

| Flag       | Type     | Default | Description                                     |
| ---------- | -------- | ------- | ----------------------------------------------- |
| `--reason` | `string` |         | Optional reason recorded with the cancellation. |

Sample output:

```
✓ Approval req_01HXYZABCDEF: cancelled (by user_123)
```

***

## `crewship approvals get <id>`

Fetch one approval request and render its full detail (kind, args, reason, decision metadata). The entry is workspace-scoped — IDs from other workspaces return 404.

```bash theme={null}
crewship approvals get apr_abc123
crewship approvals get apr_abc123 --format json | jq .args
```

Text mode prints canonical fields (`id`, `status`, `kind`, `reason`, `crew_id`, `agent_id`, `mission_id`, `requested_by`, `decided_by`, `decided_at`, `comment`, `created_at`, `updated_at`) up top, then any extra keys verbatim so an evolving server payload still renders something useful.

***

## `crewship approvals reset-auto-tuning <tool>`

Wipe the reward history used by Harbormaster gate auto-tuning for the given tool. Auto-tuning downgrades sync→async after 90%+ approvals and upgrades async→sync after 70%+ denials, over the last 20 decisions per tool+args shape. When that window gets skewed (e.g. automation approving on humans' behalf for a stretch), reset to make the gate respect the configured mode again until humans re-train it naturally.

<Warning>
  Permanently wipes the rolling reward history for the tool (no
  confirmation). Requires `OWNER` or `ADMIN` on the caller's workspace.
</Warning>

```bash theme={null}
crewship approvals reset-auto-tuning shell.exec
crewship approvals reset-auto-tuning "terraform apply"
```

Output reports `rows_deleted` from `gate_reward_history`.

## Errors

| Exit | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| 401  | Not authenticated. Run `crewship login`.                 |
| 403  | Logged in but not `OWNER` or `ADMIN`.                    |
| 404  | Request ID not found in your workspace.                  |
| 409  | Request already decided (status is no longer `pending`). |

## Related

* [Harbormaster guide](/guides/harbormaster).
* [Approvals API](/api-reference/approvals).