Crewship CLI

The crewship command-line interface is the supported way to drive a Crewship instance from your terminal — and the same surface agents use to operate Crewship themselves. It covers everything from running an agent and tailing the journal to managing crews, skills, credentials, routines, and workspace administration. This page is the index: global flags and authentication first, then the top-level commands grouped by what they do. Multi-subcommand areas (agent, crew, issue, routine, workspace, integration) each have their own dedicated page.

crewship [command] [flags]

Global Flags

Every command inherits these persistent flags:

Flag	Short	Type	Default	Description
`--server`	`-s`	`string`	`http://localhost:8080`	Server URL. Also via `CREWSHIP_SERVER` env var.
`--workspace`	`-w`	`string`	(from config)	Workspace ID or slug. Also via `CREWSHIP_WORKSPACE` env var.
`--profile`		`string`		Server profile to target (manage with `crewship server`). Also via `CREWSHIP_PROFILE` env var.
`--format`	`-f`	`string`	`table`	Output format: `table`, `json`, `yaml`, `ndjson`, or `quiet`.
`--verbose`	`-v`	`bool`	`false`	Verbose output.
`--no-color`		`bool`	`false`	Disable ANSI colors.
`--server-allow-mismatch`		`bool`	`false`	Allow sending the stored auth token to a `--server` host that differs from the one it was issued for. Also via `CREWSHIP_ALLOW_SERVER_MISMATCH` env var.

In addition: CREWSHIP_DEFAULT_AGENT env var sets the default agent for crewship ask / crewship explain. Resolution order: command-line flag → env var → config key.

Exit codes & machine-readable errors

Every command exits with a classified code, so scripts and agents can branch on the kind of failure without parsing error prose:

Code	Meaning
`0`	Success
`1`	Unclassified error
`2`	Validation failure (HTTP 400 / 422, or a missing precondition such as no workspace set)
`3`	Not found (HTTP 404, or a client-side lookup miss — an agent/crew/workspace slug or resource name that doesn’t resolve)
`4`	Auth failure (HTTP 401 / 403, not logged in, token-host mismatch)
`5`	Conflict (HTTP 409)
`6`	Rate-limited (HTTP 429)
`7`	Server error (HTTP 5xx)
`8`	Network failure — the request never produced a response

crewship wait keeps its own run-outcome codes (0 completed / 1 failed / 2 cancelled / 3 timeout / 4 connection error) — those describe the run’s terminal state, not a command failure. See the Wait page. When the output format is json, ndjson, or yaml, errors are emitted on stderr as a structured envelope in that same format (stdout stays reserved for success output):

{
  "error": {
    "message": "API error (404): agent not found",
    "status": 404,
    "detail": "agent not found",
    "exit_code": 3
  }
}

Extension members from RFC 7807 responses (e.g. missing_integrations) pass through under error.extensions.

Discovering the CLI surface

crewship commands dumps the full command tree — every command, subcommand, and flag — as a machine-readable manifest. This is the recommended way for an agent to learn the CLI in one call instead of scraping --help page by page:

crewship commands --format json | jq '.commands[].path'

Token-host binding. Your CLI bearer token is bound to the host it was issued for (the server stored in ~/.crewship/cli-config.yaml). If --server or CREWSHIP_SERVER points a command at a different host, the CLI refuses to attach the token and aborts the request before it hits the network — so a copy-pasted crewship --server http://attacker.example me can never leak your credential to an attacker-controlled host. When you intentionally retarget (SSH tunnel, the server moved), either re-run crewship login --server <url> to rebind the token or pass --server-allow-mismatch / CREWSHIP_ALLOW_SERVER_MISMATCH=1.

Authentication

`crewship init`

Initialize Crewship with the first admin user on a fresh database.

crewship init --email admin@crewship.ai --name "Pavel Srba"

This command only works on an empty database (no existing users). It creates an admin user with OWNER role and returns a CLI token.

Flag	Type	Default	Description
`--server`	`string`	`http://localhost:8080`	Crewship server URL.
`--email`	`string`	(required)	Admin email address.
`--name`	`string`	(required)	Admin full name.
`--password`	`string`	(prompted)	Admin password (min 8 chars). Prompted interactively if omitted.

Authenticate the CLI with a Crewship server.

# Interactive mode (email + password)
crewship login

# Token mode
crewship login --token <api-token>

Flag	Type	Default	Description
`--token`	`string`		API token for non-interactive login.

The token is saved to ~/.crewship/cli-config.yaml.

`CREWSHIP_TOKEN` (headless auth)

For CI jobs and agent containers, export CREWSHIP_TOKEN instead of running crewship login — no config file needed:

export CREWSHIP_SERVER=https://crewship.example.com
export CREWSHIP_TOKEN=cst_…
crewship whoami

The env token wins over any stored config/profile token and is scoped to the shell. Unlike the persisted token it is not host-bound: you provided it for this exact environment, so the token-host guard (which protects the on-disk credential from --server exfiltration) does not apply.

`crewship logout`

Remove the stored authentication token.

crewship logout

`crewship whoami`

Display the current user and workspace info.

crewship whoami

Outputs the user email, server URL, active workspace name, and user role.

Server

`crewship start`

Start the Crewship server.

crewship start
crewship start --config config.yaml --no-docker

Flag	Type	Default	Description
`--config`	`string`		Path to config file (YAML).
`--db`	`string`	`~/.crewship/crewship.db`	Database URL.
`--no-docker`	`bool`	`false`	Start without Docker (dashboard only, no agents).

A container runtime (Docker, Podman, Colima, OrbStack, Apple Containers) is required to run AI agents. Use --no-docker for dashboard-only mode.

Agent Execution

`crewship run`

Run an agent with a prompt and stream output to the terminal.

crewship run <agent-slug> [prompt]
crewship run viktor "Create a REST API"
crewship run viktor --prompt @task.txt
crewship run viktor --prompt @-                     # read prompt from stdin
cat error.log | crewship run viktor "what's wrong?" # auto-append stdin as context
crewship run viktor "review" --with-git-diff
crewship run viktor "explain" --with-file notes.md --with-file plan.md
crewship run viktor --interactive
crewship run viktor --chat <chatId> "follow-up question"

Flag	Short	Type	Default	Description
`--prompt`	`-p`	`string`		Prompt text, `@file.txt`, or `@-` for stdin.
`--interactive`		`bool`	`false`	Interactive chat mode (REPL).
`--chat`		`string`		Continue an existing chat by chat ID.
`--no-stream`		`bool`	`false`	Wait for completion, show only the final result.
`--quiet`	`-q`	`bool`	`false`	Only output text, suppress meta info.
`--timeout`		`int`	`0`	Timeout in seconds (0 = no timeout).
`--with-git-diff`		`bool`	`false`	Append `git diff` (working tree) as context.
`--with-git-staged`		`bool`	`false`	Append `git diff --staged` as context.
`--with-git-log`		`bool`	`false`	Append last 20 commits as context.
`--with-git-status`		`bool`	`false`	Append `git status -s` as context.
`--with-file`		`[]string`		Append file contents as context (repeatable).
`--with-cmd`		`[]string`		Append shell command output as context (repeatable).
`--paste`		`bool`	`false`	Append system clipboard as context.
`--save`		`string`		Tee response to this path (atomic write, no ANSI).
`--dry-run`		`bool`	`false`	Print assembled prompt and exit without sending.
`--estimate`		`bool`	`false`	Print token count + cost estimate and exit.
`--markdown`		`bool`	auto on TTY	Force markdown ANSI styling.
`--no-markdown`		`bool`	`false`	Disable markdown ANSI styling.

In interactive mode, press Ctrl+C to cancel the current run. Press Ctrl+D to exit the session.Stdin is auto-detected when piped — git diff | crewship run viktor "review" works without an explicit flag. Piped data is appended after the positional prompt under a --- stdin --- separator. Each context block is capped at 64 KiB and labelled.

`crewship run list`

List recent runs across all agents. See also crewship history for a friendlier view with optional prompt previews.

crewship run list

Output columns: ID, AGENT, STATUS, TRIGGER, CREATED, FINISHED

`crewship ask`

Low-friction one-shot prompt against a default agent. Inherits the same --with-*, --save, --markdown, --dry-run, --estimate, and --paste flags as run. The agent is resolved from --agent flag → CREWSHIP_DEFAULT_AGENT env var → default-agent config key → interactive picker (TTY) → error. --agents <list> runs the same prompt against multiple agents in parallel.

crewship ask "what time is it?"
git diff | crewship ask "review this change"
crewship ask "summarize" --with-file notes.md
crewship ask --agent viktor "explain how the journal works"
crewship ask --prompt @-                              # full prompt from stdin

# One-time setup so future asks don't need --agent:
crewship config set default-agent viktor

Run crewship ask with no positional arg or default to launch a huh picker that lists every agent in the workspace. The picker offers to save the choice as the new default.

`crewship retry`

Re-run a previous run. Recovers the original first user prompt from the chat history and starts a new run on the same agent.

crewship retry r_abc                       # same agent, same prompt, NEW chat
crewship retry r_abc --continue            # append to the SAME chat
crewship retry r_abc --new-prompt "be more specific"

Flag	Type	Default	Description
`--new-prompt`	`string`		Override the original prompt.
`--continue`	`bool`	`false`	Append to the original chat instead of starting fresh.
`--quiet`	`bool`	`false`	Only output text.
`--no-stream`	`bool`	`false`	Wait for completion, show only result.
`--save`	`string`		Tee the response to this path.

`crewship copy-prompt`

Recover the original prompt of a previous run without running anything. Pairs naturally with crewship retry --new-prompt for tweak-and-rerun loops.

crewship copy-prompt r_abc                  # to stdout
crewship copy-prompt r_abc --clipboard      # to system clipboard
crewship copy-prompt r_abc > prompt.txt

`crewship explain`

Summarize what happened in a run via the default agent. Fetches journal entries scoped to the run’s agent + start window and asks the agent for a 3-6 bullet summary.

crewship explain r_abc
crewship explain r_abc --agent reviewer
crewship explain r_abc --types error,keeper.decision,peer.escalation

`crewship watch`

Live-tail the Crew Journal. Top-level alias for journal --follow.

crewship watch
crewship watch --severity warn,error
crewship watch --crew backend-team

`crewship inspect`

Show a structured journal timeline of a run (no LLM, instant). Sibling of explain.

crewship inspect r_abc
crewship inspect r_abc --types error,exec.error,keeper.decision
crewship inspect r_abc --filter '.entries[] | select(.severity=="error")'
crewship inspect r_abc --watch 2s         # follow a running mission

`crewship apply`

Apply a YAML manifest describing a crew or workspace (agents + skills + credentials + sidecar services). Idempotent, plan-then-confirm. See CLI → apply and Guides → Workspace Manifests.

crewship apply --file team.yaml --from-env       # convergent sync
crewship apply --file team.yaml --dry-run        # plan only
crewship apply --file team.yaml --strict         # fail if any resource exists

`crewship export`

Two distinct shapes:

# Manifest export — round-trip partner of apply
crewship export crew code-review > code-review.crew.yaml
crewship export workspace > acme.workspace.yaml

# Run export — bundle one run's chat + journal for post-mortems
crewship export r_abc                 # ./run-r_abc/{prompt,response,messages,journal,timeline}
crewship export r_abc --out /tmp/pm

See CLI → export for details.

`crewship prompt`

Local prompt library at ~/.crewship/prompts/<name>.md. Server-free.

crewship prompt save sec-review --content "Review this diff for security issues."
crewship prompt list
crewship prompt use sec-review | crewship ask
crewship prompt path sec-review
crewship prompt edit sec-review
crewship prompt delete sec-review

`crewship open`

Open a web UI deep-link in your default browser.

crewship open chat viktor
crewship open mission MIS-42
crewship open journal
crewship open --print-only mission MIS-42

Resources: inbox (dashboard, home), activity, agents, agent <slug>, crews, crew <slug>, chat <agent-slug>, mission <id>, journal, approvals, integrations, routines, issues [id], runs, settings, admin, audit, credentials.

`crewship chat`

Print the full message history of a chat session as a rendered transcript.

crewship chat c_abc123
crewship chat c_abc123 --no-markdown
crewship chat c_abc123 --since 24h

`crewship agent files | inbox | git-log`

Per-agent introspection beyond agent debug:

crewship agent files viktor                       # list agent's working dir
crewship agent files viktor --download report.md  # download
crewship agent inbox viktor                       # peer messages received
crewship agent git-log viktor                     # git log inside container

`crewship triage | recurring | saved-view | mcp-calls | metrics`

Thin surfaces over existing API endpoints — --filter for jq, --format json|yaml for scripts.

crewship triage list
crewship triage process
crewship recurring list
crewship saved-view list
crewship mcp-calls --limit 50
crewship metrics                       # mission summary
crewship metrics --series active_runs --range 24h

`crewship lint | doctor --fix | config validate`

Local hygiene:

crewship lint              # static-analyse config + prompt library
crewship lint --strict     # warnings also fail (CI-friendly)
crewship doctor --fix      # safe auto-repairs (creates missing data dir)
crewship config validate   # token + workspace + default-agent sanity

`crewship logs`

View agent logs.

crewship logs <agent-slug>
crewship logs viktor --follow
crewship logs viktor --lines 50

Flag	Short	Type	Default	Description
`--lines`	`-n`	`int`	`100`	Number of log lines to show.
`--follow`	`-F`	`bool`	`false`	Stream logs in real-time via WebSocket.

Observability

`crewship activity`

View the cross-crew activity feed including assignments, peer conversations, and escalations.

crewship activity
crewship activity --crew backend-team
crewship activity --lines 20

Flag	Type	Default	Description
`--crew`	`string`		Filter by crew slug or ID.
`--lines`	`int`	`50`	Number of activity entries.

`crewship audit`

View audit logs for the workspace.

crewship audit
crewship audit --action agent.run
crewship audit --action credential.rotate --lines 100

Flag	Type	Default	Description
`--action`	`string`		Filter by action (domain verb, e.g. `agent.run`, `credential.rotate`, `workspace.create`).
`--lines`	`int`	`50`	Number of audit entries.

`crewship cost`

Single-screen spend summary: total, top spenders, per-crew rollup, active subscription plans.

crewship cost                # last 24h, top 5 spenders
crewship cost --range 7d
crewship cost --range 30d --limit 10
crewship cost --format json  # for scripts

Flag	Type	Default	Description
`--range`	`string`	`24h`	Time window (`1h`, `24h`, `7d`, `30d`).
`--limit`	`int`	`5`	Number of top spenders to show.

For per-crew or per-agent rollups in full fidelity, see crewship paymaster.

`crewship recall`

Free-text search across the Crew Journal. Renders matched entries as snippet cards with the search term highlighted.

crewship recall "auth migration"
crewship recall "rate limit" --since 30d --limit 30
crewship recall "keeper denied" --crew backend-team
crewship recall "deploy" --format json | jq '.[].summary'

Flag	Type	Default	Description
`--limit`	`int`	`20`	Max matches to return.
`--since`	`string`		Time window (`1h`, `24h`, `7d`, or RFC3339).
`--crew`	`string`		Filter by crew slug or ID.
`--agent`	`string`		Filter by agent ID.

Hits the /api/v1/journal?q= FTS5 endpoint. Server caps the query at 200 chars.

`crewship history`

Recent runs across the workspace with timestamp, agent, status, and trigger. Optional prompt preview per run.

crewship history
crewship history --limit 50
crewship history --since 7d --status failed
crewship history --prompts        # also fetch first user prompt per run

Flag	Type	Default	Description
`--limit`	`int`	`20`	Max runs to list.
`--since`	`string`	`24h`	Time window (filtered client-side).
`--status`	`string`		Filter by status (`running`, `completed`, `failed`).
`--agent`	`string`		Filter by agent slug or ID.
`--prompts`	`bool`	`false`	Fetch first user prompt per run (slower; one extra GET each).

Token Management

`crewship token list`

List all CLI tokens.

crewship token list

Output columns: ID, NAME, CREATED, LAST USED, STATUS

`crewship token create`

Create a new CLI token.

crewship token create [name]

The name argument defaults to "CLI token" if omitted.

The token value is displayed only once at creation time. Store it securely.

`crewship token revoke`

Revoke a CLI token.

crewship token revoke <token-id>

Revocation is immediate and irreversible — any session or script still using that token stops working at once.

`crewship token validate`

Validate the current CLI token.

crewship token validate

Diagnostics

`crewship version`

Print version information including commit hash, build date, Go version, and OS/architecture.

crewship version

`crewship doctor`

Check system requirements and health: container runtime detection, data directory, and database status.

crewship doctor

`crewship completion`

Generate shell completion scripts.

crewship completion [bash|zsh|fish|powershell]

Shell completion setup

Bash:

source <(crewship completion bash)
# Persistent:
crewship completion bash > /etc/bash_completion.d/crewship

Zsh:

source <(crewship completion zsh)
# Persistent:
crewship completion zsh > "${fpath[1]}/_crewship"

Fish:

crewship completion fish | source
# Persistent:
crewship completion fish > ~/.config/fish/completions/crewship.fish

Seed Data

`crewship seed`

Seed demo data via the API. Creates a complete demo environment: admin user, workspace, crews, agents with system prompts, credentials, integrations, and sample issues.

crewship seed
crewship seed --nuke
crewship seed --skip-issues

Flag	Type	Default	Description
`--nuke`	`bool`	`false`	Delete all workspace contents before seeding.
`--skip-issues`	`bool`	`false`	Skip issue/project/label seeding.
`--password`	`string`	`password123`	Admin password for bootstrap.

--nuke deletes all existing workspace contents before seeding. There is no undo — only run it against a throwaway dev instance.

On a fresh database, seed automatically bootstraps the first admin user. On an existing database, it requires authentication via crewship login.

Output Formats

All list and detail commands support --format (-f):

Format	Description
`table`	Human-readable table (default).
`json`	JSON output, suitable for piping to `jq`.
`yaml`	YAML output.
`ndjson`	Newline-delimited JSON (one record per line), for streaming pipelines.
`quiet`	Minimal output (IDs only).

crewship agent list -f json | jq '.[].slug'

The guarantee is uniform: commands that emit structured output honor all three machine formats (json, yaml, ndjson) equivalently on stdout, and under a machine format errors go to stderr as a structured envelope in that same format (see Exit codes & machine-readable errors above). A few commands have a different default than table:

journal and its subcommands default to text.
Structured-record commands with no canonical table — agent debug and system onboarding status — default to json (with yaml/ndjson honoured), and metrics defaults to json (with yaml honoured).

The one documented exception is crewship wait: it owns its run-outcome exit codes and prints [wait] error: diagnostics to stderr as plain text even under a machine --format (no structured error envelope). See the Wait page.

Resolving resource references

Anywhere a command takes an agent, crew, skill, or credential reference, you can pass either the record id or the human identifier — the slug for agents, crews, and skills (display names don’t resolve), and the name for credentials and integrations (which have no slug) — including slugs that happen to look like ids. CUID-shaped input is first verified with a single lookup; on a miss the CLI falls back to slug/name resolution, so a slug like customersuccessemea42 resolves correctly instead of failing as an unknown id. A reference that resolves to nothing exits with the not-found code (3) rather than a confusing server-side error.

Other commands (run `--help` for details)

The list below covers top-level commands that ship in the binary but don’t yet have a dedicated page on this site. Most are stable; some are internal or experimental. Use crewship <command> --help for the full flag list while we work through expanding the per-command reference.

Command	Purpose	Note
`crewship admin`	Operate on the local DB directly when `crewshipd` is stopped (reset password, promote, list users)	See the Admin CLI guide
`crewship telemetry`	Manage crash-reporting consent (`on` / `off` / `status`)	See the Telemetry guide
`crewship diff`	Diff two runs side by side (`diff <run-a> <run-b>`)	—
`crewship escalation`	List, inspect, and resolve agent escalations recorded by the sidecar	—
`crewship expose`	Audit (`list`) and tear down (`revoke`) agent-initiated port exposures for a crew	See Port-expose API
`crewship integration`	Manage workspace integrations (Linear, GitHub App, Slack, …)	See the Integrations guide
`crewship mcp`	Inspect, register, and remove MCP servers attached to an agent	See the MCP / multi-CLI guide
`crewship notify`	Manage desktop notifications (`enable` / `disable` / `status` / `test` / `send`)	—
`crewship routine`	Manage workspace routines (declarative DSL workflows; alias: `pipeline`)	See the Routines guide
`crewship plan`	Run the default agent in read-only PLAN mode (architect mode; no tools, no changes)	—
`crewship project`	Manage projects (and `project milestone` subcommands) inside the issue tracker	—
`crewship recap`	AI-generated summary of a chat session (`recap <chat-id>`)	—
`crewship resume`	Pick up an existing CLI session by chat-id, run-id, or PR URL	—
`crewship session`	List and revoke the caller’s active browser sessions (`list` / `revoke`)	—
`crewship setup`	Finish onboarding on an already-authenticated instance (first crew template + adapter + CLI token)	—
`crewship shell`	Interactive REPL: each line is a prompt to the default agent (slash-commands control state)	—
`crewship slash`	Run a saved slash-command shortcut against the default agent	—
`crewship template`	Manage agent and crew templates	—
`crewship tui`	Launch the interactive terminal UI	—
`crewship wait`	Block until a run, mission, or waitpoint reaches a terminal state	—
`crewship workspace`	List, switch, and manage workspaces	Touched briefly in Authentication above
`crewship me` / `today` / `now`	Quick-action dashboards composed from multiple REST endpoints (`me` = your missions/approvals/runs, `today` = today’s runs + spend, `now` = live status board)	—

Anything missing from this table that you reach for often is a docs bug — open an issue or PR.

​Crewship CLI

​Global Flags

​Exit codes & machine-readable errors

​Discovering the CLI surface

​Authentication

​crewship init

​crewship login

​CREWSHIP_TOKEN (headless auth)

​crewship logout

​crewship whoami

​Server

​crewship start

​Agent Execution

​crewship run

​crewship run list

​crewship ask

​crewship retry

​crewship copy-prompt

​crewship explain

​crewship watch

​crewship inspect

​crewship apply

​crewship export

​crewship prompt

​crewship open

​crewship chat

​crewship agent files | inbox | git-log

​crewship triage | recurring | saved-view | mcp-calls | metrics

​crewship lint | doctor --fix | config validate

​crewship logs

​Observability

​crewship activity

​crewship audit

​crewship cost

​crewship recall

​crewship history

​Token Management

​crewship token list

​crewship token create

​crewship token revoke

​crewship token validate

​Diagnostics

​crewship version

​crewship doctor

​crewship completion

​Seed Data

​crewship seed

​Output Formats

​Resolving resource references

​Other commands (run --help for details)

Crewship CLI

Global Flags

Exit codes & machine-readable errors

Discovering the CLI surface

Authentication

`crewship init`

`crewship login`

`CREWSHIP_TOKEN` (headless auth)

`crewship logout`

`crewship whoami`

Server

`crewship start`

Agent Execution

`crewship run`

`crewship run list`

`crewship ask`

`crewship retry`

`crewship copy-prompt`

`crewship explain`

`crewship watch`

`crewship inspect`

`crewship apply`

`crewship export`

`crewship prompt`

`crewship open`

`crewship chat`

`crewship agent files | inbox | git-log`

`crewship triage | recurring | saved-view | mcp-calls | metrics`

`crewship lint | doctor --fix | config validate`

`crewship logs`

Observability

`crewship activity`

`crewship audit`

`crewship cost`

`crewship recall`

`crewship history`

Token Management

`crewship token list`

`crewship token create`

`crewship token revoke`

`crewship token validate`

Diagnostics

`crewship version`

`crewship doctor`

`crewship completion`

Seed Data

`crewship seed`

Output Formats

Resolving resource references

Other commands (run `--help` for details)