crewship run

run invokes a named agent and streams its response over WebSocket. Unlike ask, the agent slug is positional (no default-agent fallback) and the command supports interactive sessions, follow-ups on an existing chat, and shell-friendly streaming. Defined in cmd/crewship/cmd_run.go.

crewship run <agent-slug> [prompt] [flags]
crewship run list
crewship run insights

Each invocation creates a new chat by default (origin=CLI, so the web UI sidebar tags it). Pass --chat <chat-id> to continue an existing thread. Auth: crewship login plus workspace context. Both checks are skipped in --dry-run / --estimate offline modes.

Subcommands

Command	Purpose
`run <agent-slug> [prompt]`	Start (or continue) a streamed run.
`run list`	List recent runs across every agent in the workspace (`GET /api/v1/runs`).
`run get <run-id>`	One run in detail, including session provenance (`GET /api/v1/runs/{id}`).
`run insights`	Fleet-ops snapshot over a window — outcome split, duration percentiles, and breakdowns by trigger/crew/model across all runs (`GET /api/v1/runs/insights`).

Session provenance

run get answers the questions a run record could not answer before: which CLI binary served this run, on which credential, and did everything it was configured with actually load. The values are ground truth from the CLI’s own session-init event, not from what Crewship asked for.

$ crewship run get msg_1786552750441963636_4bd885e80dc9485e
ID:               msg_1786552750441963636_4bd885e80dc9485e
Status:           COMPLETED
Agent:            riley
Model:            claude-haiku-4-5
CLI version:      2.1.204
Auth source:      ANTHROPIC_API_KEY
Permission mode:  bypassPermissions
Session:          sess-9f1c
MCP skipped:      crewship-memory (invalid_config)
Tools denied:     Bash ×39, Write

Field	Why it is there
`CLI version`	Agent containers install the CLI from a devcontainer feature, i.e. latest, while the adapter is validated against a pinned version. Without this, the two drift with nothing to point at.
`Auth source`	Which auth path resolved — i.e. whether the credential Crewship mounted is the one in use. Reported from a closed set; anything unrecognised reads `other` rather than being stored verbatim.
`Permission mode`	Confirms the permission flags took effect.
`MCP skipped`	A finding, not a label. A `--mcp-config` entry that fails validation is skipped and the run continues, exiting 0 — an agent that lost its memory server this way looks perfectly healthy. `run list` flags it under the table for the same reason.
`Tools denied`	Tools the CLI refused to let the agent use. Without it, a blocked run reads as one that chose not to act, sending you after a prompt problem instead of a permission rule. Tool names only — the denied input is arbitrary agent-generated text and never reaches the run record. A `×N` suffix is how many times that tool was refused: one refusal is an agent that tried, forty is an agent hammering a wall.

Both lists are deduplicated, bounded, and honest about what they could not read:

A shortfall line. … and 2 more the CLI reported in a shape this record could not identify means the CLI named more than the record can show. The alarm is never dropped for want of a readable name — a partial list that reads as complete is worse than one that admits it is partial.
(list capped) means the run hit the per-list bound. Only a run in real trouble reaches it — an agent retrying a denied tool in a loop, or an --mcp-config where most entries fail validation.
unrecognized_shape as a name means the CLI reported the field in a shape this build does not enumerate. The report is still surfaced, because whether a session was degraded is decided by the CLI having reported it, never by our being able to parse it.

The same rule holds on every surface: the chat card, the run.session_init journal entry and this view all treat presence as the signal. Fields are omitted entirely when unknown (older runs, and non-Claude adapters, which report none of this) — absence means “never reported”, not “empty”. The same provenance is recorded twice more: as a run.session_init journal entry at session start (crewship journal --type run.session_init, severity error when a server was skipped), and on the chat’s “Session started” card while the run is live. The journal entry and the run record are the durable copies — the chat card is live-stream only.

Flags

Flag	Default	Effect
`-p`, `--prompt <text>`	(unset)	Prompt text, `@path` to read a file, or `@-` for stdin.
`--interactive`	`false`	Drop into a REPL after the first prompt. Ctrl-D exits, Ctrl-C cancels the current turn.
`--chat <chat-id>`	(unset)	Continue an existing chat instead of creating one.
`--no-stream`	`false`	Wait for completion and print the final text only.
`--wait`	`false`	Alias for `--no-stream` — same spelling as `crewship pipeline run --wait` / `crewship hire --wait` / `crewship mission start --wait`, for scripts that want one consistent “block until done” flag across commands.
`--max-turns <n>`	`0`	Cap the agent loop at N turns for this run (`0` = adapter default, `50` interactive).
`-q`, `--quiet`	`false`	Suppress `[agent: …]` / `[thinking]` / `[done]` stderr chatter.
`--timeout <secs>`	`0`	HTTP timeout (`0` = unbounded).
`--with-git-diff`	`false`	Append `git diff` as context.
`--with-git-staged`	`false`	Append `git diff --staged`.
`--with-git-log`	`false`	Append the last 20 commits.
`--with-git-status`	`false`	Append `git status -s`.
`--with-file <path>`	(unset)	Append file contents. Repeatable.
`--with-cmd <shell>`	(unset)	Append the stdout of a shell command. Repeatable.
`--paste`	`false`	Append the system clipboard (`pbpaste` / `wl-paste` / `xclip` / `xsel`).
`--dry-run`	`false`	Print the assembled prompt and exit. No auth, no server.
`--estimate`	`false`	Print token-count + cost estimate and exit.
`--markdown`	`false`	Force markdown ANSI styling.
`--no-markdown`	`false`	Disable markdown ANSI styling.
`--save <path>`	(unset)	Tee the agent’s text (no ANSI) to `path` via an atomic tempfile — committed on a clean `done`, discarded on error.
`--plan`	`false`	Plan mode — step-by-step plan without executing tools.
`--effort <level>`	(unset)	Reasoning effort: `minimal	low	medium	high	xhigh`.
`--show-thinking`	`false`	Surface reasoning blocks on stdout (un-truncated).

When stdin is a pipe and a positional prompt is also given, the positional becomes the instruction and stdin is appended as context.

Examples

Run an agent

crewship run daniel "Create a REST API for the orders service"

Read the prompt from a file

crewship run daniel --prompt @task.txt
crewship run daniel --prompt @-          # stdin

Continue an existing chat

crewship run daniel --chat c_abc123 "follow-up: now write the integration test"

--chat skips the POST /api/v1/agents/{id}/chats step and sends the prompt straight to the existing session over agent:{agentId} WS.

Stdin as context

cat issue.md | crewship run daniel "fix this bug"
git diff | crewship run code-review "review" --with-git-status

Interactive REPL

crewship run daniel --interactive
# [agent: daniel] Ready. Type your message (Ctrl+D to exit):
#
# > help me design the migration
# ...response streams...
# > now write it

Ctrl-C cancels the current turn (sends a cancel message over WS) without killing the REPL. A second Ctrl-C exits.

Cancel-friendly streaming

crewship run daniel "long-running task"
# Ctrl-C → sends cancel, prints "[cancelled]", lets the server clean up
# A second Ctrl-C exits the process immediately

Save the answer to disk

crewship run daniel "generate ADR for sidecar isolation" --save adr.md

Saved bytes are sanitised — any ANSI / OSC sequences a tool result emitted are stripped before they hit the file, so cat adr.md is safe.

List recent runs

crewship run list
# ID                AGENT      STATUS     TRIGGER  CREATED              FINISHED
# r_xxxxxxx         daniel     COMPLETED  CLI      2026-05-19 14:02     2026-05-19 14:04
# r_yyyyyyy         viktor     RUNNING    CLI      2026-05-19 14:18     -

Use --format json for piping (crewship run list --format json | jq '.[] | select(.status=="FAILED")').

Fleet-ops insights

crewship run insights
crewship run insights --window 7d
crewship run insights --window 30d --format json

run insights aggregates every run in the workspace (not just routine runs) over a window into an ops snapshot: success/fail split, duration percentiles (p50/p95), and breakdowns by trigger, crew, and model. Backed by GET /api/v1/runs/insights?window=<w>.

Flag	Default	Effect
`--window <w>`	`24h`	Aggregation window — one of `24h`, `7d`, `30d`.

Honours the global --format json / --format yaml / --format ndjson for scripting; the default is a human-readable table.

Streaming protocol

run subscribes to session:{chatId} and posts via agent:{agentId}. Event types it renders:

Event	Where it goes	Visible
`text`	stdout (sanitised; markdown-styled if enabled)	always
`thinking`	stderr (truncated) or stdout (`--show-thinking`)	unless `--quiet`
`tool_call`	stderr, `[tool] …`	unless `--quiet`
`tool_result`	stderr, `[result] …`	`--verbose` only
`status`	stderr, `[status] …`	unless `--quiet`
`error`	stderr, `[error] …`; exit non-zero	always
`done`	stderr, `[done]`; commit `--save` tempfile	unless `--quiet`

A dropped WebSocket connection mid-run exits non-zero so wrapping scripts (crewship run x "y" || alert) catch it.

Common errors

prompt is required (provide as argument, --prompt flag, or use --interactive) — every path requires content unless you’re starting a REPL.
ws read: ... — the WebSocket dropped before done. Most often a server restart.
agent error: <message> — the model or a tool returned a hard error event. The exit code is non-zero and the message is sanitised before display.
save commit: ... — --save tempfile couldn’t be atomically renamed (disk full, permission denied). Reported separately from a stream error so neither one masks the other.

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

Run

crewship run

Subcommands

Session provenance

Flags

Examples

Run an agent

Read the prompt from a file

Continue an existing chat

Stdin as context

Interactive REPL

Cancel-friendly streaming

Save the answer to disk

List recent runs

Fleet-ops insights

Streaming protocol

Common errors

See also

​crewship run

​Subcommands

​Session provenance

​Flags

​Examples

​Run an agent

​Read the prompt from a file

​Continue an existing chat

​Stdin as context

​Interactive REPL

​Cancel-friendly streaming

​Save the answer to disk

​List recent runs

​Fleet-ops insights

​Streaming protocol

​Common errors

​See also

crewship run

Subcommands

Session provenance

Flags

Examples

Run an agent

Read the prompt from a file

Continue an existing chat

Stdin as context

Interactive REPL

Cancel-friendly streaming

Save the answer to disk

List recent runs

Fleet-ops insights

Streaming protocol

Common errors

See also