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 the workspace’s ad-hoc agent runs (`GET /api/v1/runs/insights`). Routine runs are listed by `run list` but not aggregated here.

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
Kind:             agent
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.
`--project-file-version <version-id>`	(unset)	Explicit immutable project input for a restricted native run; repeat up to 16 times. Trusted runs reject this selection.
`--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`).
`--stdin`	`false`	Read stdin to EOF and append it as context after the prompt. Without it, stdin is read only when no prompt is given.
`--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`	Request a step-by-step plan through the prompt; tools remain available.
`--effort <level>`	(unset)	Reasoning effort: `minimal	low	medium	high	xhigh`.
`--show-thinking`	`false`	Surface reasoning blocks on stdout (un-truncated).

Stdin is read in exactly two cases. With no prompt argument and no --prompt, piped stdin is read to EOF and becomes the prompt (echo hi | crewship run mia). With a prompt given, stdin is appended as context only when you pass --stdin (git diff | crewship run mia --stdin "review"). Otherwise stdin is never touched, so a harness, CI step or cron job whose stdin is a pipe nobody closes cannot hang the command; when stdin is a pipe or a file the CLI prints a one-line [stdin not read …] hint on stderr.

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 --stdin "fix this bug"
git diff | crewship run code-review --stdin "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     KIND      TRIGGER  CREATED              FINISHED
# r_xxxxxxx         daniel     COMPLETED  agent     CLI      2026-05-19 14:02     2026-05-19 14:04
# r_yyyyyyy         viktor     RUNNING    agent     CLI      2026-05-19 14:18     -
# run_zzzzzzz       viktor     COMPLETED  pipeline           2026-05-19 13:00     2026-05-19 13:01

KIND says which engine produced the row: agent for an ad-hoc agent/chat run, pipeline for a routine run (#2284). A routine run’s TRIGGER cell is empty — the pipeline engine does not populate it — so the column is how a script tells the two apart without guessing. run get shows the same value as its Kind: row. 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 --crew backend
crewship run insights --agent viktor --window 30d --format json

run insights aggregates the workspace’s ad-hoc agent runs — chat, CLI, webhook and cron invocations of an agent — over a window into an ops snapshot: success/fail split, duration percentiles (p50/p95), and breakdowns by trigger, crew, and model. Routine runs are not counted: run list reads both engines (#2284), but the insights aggregate and the stats tiles were deliberately left ad-hoc-only, so a workspace that only runs routines reports No runs in this window here. Backed by GET /api/v1/runs/insights?window=<w>.

Flag	Default	Effect
`--window <w>`	`24h`	Aggregation window — one of `24h`, `7d`, `30d`.
`--agent <slug-or-id>`	—	Only this agent’s runs. Resolved to an id before the request; an unknown agent is refused with a `Did you mean` hint rather than answered with an empty snapshot. Sent as `agent_id`.
`--crew <slug-or-id>`	—	Only this crew’s runs. Resolved to an id before the request; an unknown crew is refused with a plain `crew not found` (no near-match hint). Sent as `crew_id`. Combines with `--agent` (AND).

The scope is applied before the aggregate is computed, so totals, percentiles and every breakdown describe that agent or crew alone — not a workspace-wide snapshot with one section filtered. 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
`agent_busy`	stderr, `[busy] …`; exit non-zero	always
`crew_provisioning`	stderr, `[building] …`; keeps waiting	unless `--quiet`
`done`	stderr, `[done]`; commit `--save` tempfile	unless `--quiet`

An agent runs one message at a time. A send that arrives while the agent already has a live run is bounced with agent_busy and no done follows it — that frame ends the exchange. run reports it and exits non-zero rather than waiting, so retry once the live run finishes. When the crew’s environment image has to be built first — a new crew, or a cache image that was removed — the send gets crew_provisioning followed by a done. That done only closes the deferral: the server replays the message on the same session once the build finishes, and run keeps waiting for that run’s own answer and done. A crew_provisioning with status failed means the build never started; run exits non-zero instead of waiting. Chat sends bounce; assignment dispatches do not. A dispatch that loses the same per-agent lock — an /assign or an @mention of a busy agent — is queued behind the live run with queued_reason: agent_busy and drained by the completion pump instead. Prefer that route when you want work to wait its turn rather than be rejected. 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.
agent busy: <message> — the agent already had a live run, so this message was rejected and never reached it. Nothing ran and nothing was persisted; send it again once the agent is free.
environment build failed to start: <message> — the crew needed a new environment image and the build could not be queued. Nothing ran; fix the cause shown and send again.
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