crewship inbox

The inbox is the unified “things needing a human” feed — waitpoints awaiting approval, escalations from agents, failed runs, and direct messages. The CLI is the scriptable mirror of the /inbox web page; cron + jq + inbox list is the canonical “ping Slack when unread piles up” recipe. Defined in cmd/crewship/cmd_inbox.go.

crewship inbox <subcommand> [flags]

Auth: every subcommand requires crewship login plus an active workspace. The inbox is backed by the inbox_items table (migration v85), written-through by waitpoint creation, escalation creation, and run-failure handlers.

Subcommands

Command	Purpose
`inbox list`	List inbox items (default: unread only).
`inbox get <id>`	Show a single item with its full body + structured payload.
`inbox count`	Print the bell-badge unread count (cheaper than `list` for polling).
`inbox read <id>`	Mark an item as read.
`inbox unread <id>`	Flip an item back to unread.
`inbox resolve <id>`	Mark resolved, optionally recording the action taken.
`inbox archive <id>`	Resolve with `resolved_action=archived` (Gmail-style clear without a decision).
`inbox bulk read`	Bulk-mark items as read.
`inbox bulk resolve`	Bulk-mark items as resolved.

Flags

`inbox list`

Flag	Default	Effect
`--state <enum>`	`unread`	Filter by state. One of `unread`, `read`, `resolved`, `all`.
`--kind <enum>`	(unset)	Filter by kind. One of `waitpoint`, `escalation`, `failed_run`, `message`.
`--limit <n>`	`50`	Max rows. Server caps at 500.

`inbox resolve`

Flag	Default	Effect
`--action <enum>`	(unset)	Record what was done: `approved`, `denied`, `retried`, `cancelled`, `acknowledged`, `dismissed`. Stored in `resolved_action` for the audit trail.

`inbox bulk read`

Flag	Default	Effect
`--ids <csv>`	(unset)	Comma-separated inbox item IDs.
`--all-unread`	`false`	Target every currently-unread item (server cap: 500 per call).

`inbox bulk resolve`

Flag	Default	Effect
`--ids <csv>`	(unset)	Comma-separated inbox item IDs.
`--all-unread`	`false`	Target every currently-unread item.
`--action <enum>`	(unset)	`approved	denied	retried	cancelled	acknowledged	dismissed`.

--ids and --all-unread are mutually exclusive on both bulk subcommands.

Examples

Triage

crewship inbox list                       # unread only (default)
crewship inbox list --state all           # include read + resolved
crewship inbox list --kind waitpoint      # narrow by kind
crewship inbox list --limit 200
crewship inbox list --format json | jq '.[] | {id, kind, title}'

Output is coloured by state (yellow=unread, cyan=read, green=resolved) and kind (yellow=waitpoint, red=escalation/failed_run, cyan=message), so a 50-row feed scans at a glance.

Polling the badge

while true; do
  if [ "$(crewship inbox count)" -gt 0 ]; then
    notify-send "Crewship: inbox needs attention"
  fi
  sleep 60
done

inbox count hits GET /api/v1/inbox/count (the bell-badge endpoint) — much cheaper than inbox list when you only need the integer.

Mark an item

crewship inbox get inbox_abc123           # full body + payload for one item
crewship inbox read inbox_abc123
crewship inbox unread inbox_abc123        # flip back (also restores an archived item)
crewship inbox resolve inbox_abc123 --action approved
crewship inbox resolve inbox_abc123 --action retried
crewship inbox resolve inbox_abc123       # generic, no action
crewship inbox archive inbox_abc123       # resolve with action=archived, no decision

inbox get <id> (backed by GET /api/v1/inbox/{id}) is the detail counterpart of list — it returns the markdown body and the structured payload that the list view omits. inbox archive <id> maps to a resolved PATCH with resolved_action=archived; only non-decision kinds (messages, failed-run notices, advisories) archive — the server 409s an archive on a source-managed waitpoint/escalation. On a CREDENTIAL escalation, inbox get also prints whether resolving it needs a second approver, and which of the two controls demands it:

2nd approver required · workspace policy + L4 · critical credentials
whoever owns nela cannot resolve it — someone else has to

The same answer rides the JSON as second_approver_required / second_approver_by_workspace / second_approver_by_tier / security_level_label, the fields the crew escalations list carries. It is computed when you read the row, not when the escalation was raised: the workspace toggle and the credential’s tier both change afterwards. Absent means the server said nothing, not that a single approver will do — see Keeper → The switch is a floor, not a master switch. resolve is the inbox-side only — it does not call the source endpoint. To actually approve a waitpoint through to the executor, use crewship approvals approve <id>. To resolve an escalation lifecycle, use crewship escalation resolve <id>. The inbox row tracks the decision; the source endpoint enacts it.

Bulk operations

# Mark a known set
crewship inbox bulk read --ids inbox_abc,inbox_def,inbox_ghi

# Wipe the unread queue (capped at 500 per call)
crewship inbox bulk read --all-unread

# Bulk-resolve with an action tag
crewship inbox bulk resolve --ids inbox_abc,inbox_def --action acknowledged

Bulk operations submit the whole id set to the server-side POST /api/v1/inbox/bulk endpoint (one request flips many rows), chunked at 500 ids per call — the endpoint’s id cap. On a resolve the server skips decision items (source-managed waitpoints/escalations and blocking rows) rather than closing them. The final line summarises the aggregated counts:

N updated · M skipped · K not found

A stale or already-resolved id lands in not found / skipped; it does not fail the command (the process exits 0). Only a transport error or a non-2xx bulk response exits non-zero. If --all-unread returns exactly the page cap (500), the CLI refuses to proceed and changes nothing, telling you to re-run after the batch or narrow with --ids, so the tail isn’t lost.

Sources

Kind	Created by
`waitpoint`	Waitpoint creation (mission step paused for human input).
`escalation`	Agent escalation (agent asked for help).
`failed_run`	Run-failure handler when a run exits non-zero.
`message`	A routine’s `notify` step, or an agent addressing a human directly (e.g. a hire request).

The inbox is human-attention-scoped: it holds the things somebody has to look at, not every event that happened. Where those items are delivered outward — email, webhook, chat, push — is crewship notifychannel.

Common errors

either --ids <csv> or --all-unread is required — bulk command needs one of them.
--ids and --all-unread are mutually exclusive — pick one.
--ids parsed to empty list (got "") — comma-string was blank after trimming.
hit the 500 unread-item page cap; no items were changed … pass --ids to target a specific subset — --all-unread returned a full page and can’t tell whether more remain, so it changes nothing. Re-run after clearing this batch, or target explicit --ids.

Getting started

Sessions & identity

Agents & conversations

Crews, projects & workspaces

Missions & routines

Issues & triage

Skills & integrations

Inbox & notifications

Memory & journal

Observability

Cost & paymaster

Approvals & hooks

Configuration & system

Utilities

Inbox

crewship inbox

Subcommands

Flags

`inbox list`

`inbox resolve`

`inbox bulk read`

`inbox bulk resolve`

Examples

Triage

Polling the badge

Mark an item

Bulk operations

Sources

Common errors

See also

​crewship inbox

​Subcommands

​Flags

​inbox list

​inbox resolve

​inbox bulk read

​inbox bulk resolve

​Examples

​Triage

​Polling the badge

​Mark an item

​Bulk operations

​Sources

​Common errors

​See also

crewship inbox

Subcommands

Flags

`inbox list`

`inbox resolve`

`inbox bulk read`

`inbox bulk resolve`

Examples

Triage

Polling the badge

Mark an item

Bulk operations

Sources

Common errors

See also