crewship agent

Create, configure, and inspect the AI agents that do the work inside a crew. Reach for these commands to provision a new agent, tweak its adapter or model, browse its runs and chats, or peek inside its container (files, logs, git history, peer inbox).

crewship agent <subcommand> [flags]

Subcommands

Command	Description
`list`	List all agents in the workspace
`get`	Show agent details
`create`	Create a new agent
`update`	Update an agent
`rotate-webhook-secret`	Mint a new webhook signing secret (shown once)
`delete`	Delete an agent
`runs`	List runs for an agent
`chats`	List recent chats for an agent (alias: `sessions`)
`stop`	Stop a running agent
`logs`	Show agent container logs
`debug`	Show agent debug info (container state, env, crewshipd status)
`skills`	List skills assigned to an agent
`credentials`	List credentials assigned to an agent
`channels`	List notification channels the agent may send to
`avatar`	Inspect, set, or clear an agent’s stored avatar
`mcp`	Show or set MCP server configuration for an agent
`files`	List files in the agent’s working directory, or download a single file
`file-write`	Write a file into the agent’s working directory
`inbox`	Show peer messages received by the agent
`git-log`	Show git log inside the agent’s container

`crewship agent list`

List all agents in the workspace.

crewship agent list
crewship agent list --crew backend-team

Flag	Type	Default	Description
`--crew`	`string`		Filter by crew slug or ID.

Output columns: SLUG, ROLE, CREW, STATUS, ADAPTER, MEMORY

`crewship agent get`

Show detailed information about an agent.

crewship agent get <slug-or-id>

Output fields: Name, Slug, ID, Role, Role Title (only when set), Crew, Status, CLI Adapter, Tool Profile, Memory, Timeout, Created, Skills count, Credentials count. When a cron schedule is configured, additional rows appear: Schedule (<cron> (enabled|disabled)), Schedule Prompt, Next Run, and Last Run. When --webhook-require-timestamp is set on the agent, a Webhook Auth: timestamped signature required row appears.

`crewship agent create`

Create a new agent.

crewship agent create --name "Viktor" --crew backend-team --role LEAD

Flag	Type	Default	Description
`--name`	`string`	(required)	Agent name.
`--slug`	`string`	(auto from name)	Agent slug.
`--crew`	`string`		Crew slug or ID.
`--role`	`string`	`AGENT`	Agent role: `AGENT` or `LEAD`.
`--role-title`	`string`		Human-readable role title.
`--cli-adapter`	`string`	`CLAUDE_CODE`	CLI adapter: `CLAUDE_CODE`, `CODEX_CLI`, `GEMINI_CLI`, `OPENCODE`, `CURSOR_CLI`, `FACTORY_DROID`.
`--system-prompt`	`string`		System prompt text or `@file.txt` to read from file.
`--tool-profile`	`string`	`CODING`	Tool profile: `MINIMAL`, `CODING`, `FULL`.
`--llm-provider`	`string`		LLM provider: `ANTHROPIC`, `OPENAI`, `GOOGLE`.
`--llm-model`	`string`		LLM model (e.g., `claude-haiku-4-5`).
`--memory`	`bool`	`false`	Enable memory.
`--lead-mode`	`string`		Lead mode: `active` or `passive`.
`--timeout`	`int`	`0`	Timeout in seconds.
`--avatar-seed`	`string`	(agent name)	Avatar seed for avatar generation.
`--avatar-style`	`string`		Avatar style: `bottts-neutral`, `adventurer`, `fun-emoji`, `pixel-art`, `micah`, `notionists`, `thumbs`, `lorelei`, `big-smile`, `avataaars`.

Use @file.txt syntax with --system-prompt to load the prompt from a file:

crewship agent create --name Viktor --system-prompt @prompts/backend-lead.md

`crewship agent update`

Update an existing agent. Only changed flags are sent.

crewship agent update <slug-or-id> --role LEAD --memory

Flag	Type	Default	Description
`--name`	`string`		Agent name.
`--role`	`string`		Agent role.
`--role-title`	`string`		Human-readable role title.
`--cli-adapter`	`string`		CLI adapter.
`--system-prompt`	`string`		System prompt text or `@file.txt`.
`--tool-profile`	`string`		Tool profile.
`--llm-provider`	`string`		LLM provider: `ANTHROPIC`, `OPENAI`, `GOOGLE`.
`--llm-model`	`string`		LLM model.
`--memory`	`bool`	`false`	Enable memory.
`--suggested-prompts`	`string`		Chat suggestions shown as buttons under an empty conversation: one per line, max 8 lines, max 120 characters each. Text or `@file.txt`. Pass `""` to clear, after which the agent shows the built-in defaults.
`--ask-forms`	`string`		Ask forms as a JSON array: max 4 forms, max 6 fields each. Almost always `@forms.json`. Pass `""` to clear. Preview one with `agent ask-preview`.
`--lead-mode`	`string`		Lead mode.
`--timeout`	`int`	`0`	Timeout in seconds.
`--schedule-cron`	`string`		Cron expression to run the agent on a schedule (e.g. `/5 * * *`); empty string clears it.
`--schedule-prompt`	`string`		Prompt the scheduled run sends to the agent.
`--schedule-enabled`	`bool`	`false`	Enable/disable the agent’s cron schedule.
`--webhook-require-timestamp`	`bool`	`false`	Require inbound webhooks to use the timestamped signature scheme (rejects replayable body-only/plaintext deliveries).
`--self-learning`	`bool`	`false`	Enable/disable per-agent self-learning. Goes through a separate audited endpoint (`PATCH /api/v1/agents/{id}/learning`), so it cannot be combined with any other field update in one command, and requires `--learning-reason`.
`--learning-reason`	`string`		Audit reason recorded with the `--self-learning` change (required when `--self-learning` is set).
`--avatar-seed`	`string`		Avatar seed.
`--avatar-style`	`string`		Avatar style.

--self-learning is applied via its own audited endpoint and cannot be mixed with other field updates in the same invocation — run it on its own: crewship agent update <id> --self-learning[=false] --learning-reason "…".

Suggested prompts are what the agent offers as buttons under an empty conversation — the questions someone would otherwise type every morning. They are per agent, so two agents in one workspace can offer different ones, and an agent without any keeps showing the built-in defaults. The list is normalised on write (blank lines dropped, each line trimmed), and a rejection names the line: prompt 3 exceeds 120 characters (it has 154).

crewship agent update lucy --suggested-prompts "$(cat <<'EOF'
What shipped this week?
Which invoices are overdue?
Draft a reply to the last email
EOF
)"

crewship agent update lucy --suggested-prompts @questions.txt   # from a file
crewship agent update lucy --suggested-prompts ""               # back to defaults
crewship agent get lucy                                         # read them back

Ask forms

A suggested question is one line of text. An ask form is the same idea for the questions that need answers first: a chip that opens a short questionnaire, whose answers are rendered into an ordinary message and sent. There is no separate endpoint — forms ride the same agent PATCH — so they are written with --ask-forms, and in practice from a file, because a form with five fields and a template is not something anyone types on a command line.

crewship agent update lucy --ask-forms @forms.json
crewship agent update lucy --ask-forms ""            # remove every form
crewship agent get lucy                              # lists them: label, id, field count

forms.json

[{
  "id": "receipt",
  "label": "Add a receipt",
  "attachment": "required",
  "template": "Please file this receipt.\n\nSupplier: {{supplier}}\nAmount: {{amount}} {{amount_currency}}\nPeriod: {{month}}\nCategory: {{category}}\nDocument: {{document}}",
  "fields": [
    {"name": "supplier", "label": "Supplier", "type": "text", "required": true, "placeholder": "Vodafone"},
    {"name": "amount", "label": "Amount", "type": "money", "required": true, "currency": ["CZK", "EUR", "USD"]},
    {"name": "month", "label": "Period", "type": "month", "default": "2026-08"},
    {"name": "category", "label": "Category", "type": "select", "options": ["Telco", "Hosting"]},
    {"name": "document", "label": "Document", "type": "file"}
  ]
}]

Field types: text, textarea, number, money, date, month, select, multiselect, checkbox, file, photo. An unrecognised type is accepted and renders as a text input, so a newer server can offer a type this console does not know yet — except one whose name says the value is a secret (password, api_key, client_secret, otp…), which is refused here and renders no input in the chat. A form submit is an ordinary chat message that is stored, searchable and read by the agent; there is no field type that makes that safe. Put the credential in the vault and reference it by name. select and multiselect need options. Options are trimmed on save, exactly as an answer is on its way into the message — "Travel " is stored as "Travel", because an option spelled differently from the answer it produces is a choice the form renders and then refuses. Two options that differ only by whitespace are therefore the same option, and are refused as a duplicate rather than silently merged. A money field named amount answers to two placeholders: {{amount}} and {{amount_currency}}. A field may also carry min, max, pattern and multiple, all of which are checked when a user submits — min/max are a value on number/money, a length on text, and a count on multiselect/file/photo; pattern is an anchored full match on the text-ish types; multiple: false caps an upload field at one file. A constraint that would not be checked for its field type (a pattern on a checkbox, a bound on a date) is refused on save rather than stored and ignored, and so are min above max and a pattern that does not compile. Optional version is the author’s revision number, carried into every submission’s metadata. Full reference: Ask forms. Three rules decide what is sent:

Every {{placeholder}} must name a field on the same form, and that is checked when you save, not when a user clicks the chip. A typo comes back as form "receipt": template names {{suplier}}, which is not a field on that form and nothing is written.
An unanswered optional field takes its whole line with it, label included — the receipt above with no category sends no Category: line rather than a dangling one. This is the only rule you cannot read off the template.
Values go in verbatim (it is a user message), but control characters are stripped, each value caps at 2000 characters and the message at 32000. file and photo fields render as attachments/<chat-id>/<name>, one per line for several files.

Caps: 4 forms per agent, 6 fields per form, 48 characters per label, 2000 per template — all counted in characters, not bytes. schemas/ask-form.v1.json is the JSON Schema, for editor completion while writing forms.json.

`crewship agent ask-preview`

Render one of an agent’s ask forms and print the message it would send. This is how a template is tested without opening a browser, and it uses the same renderer the chat does — the two are pinned to one golden fixture (testdata/ask-templates.json), so what you see here is what gets sent. It also applies the same constraints the chat applies at submit, and prints the same sentences, so a preview cannot show a message the sheet would have refused:

crewship agent ask-preview lucy receipt --var amount=9000
# Error: these answers would be refused in the chat:
#   Amount must be at most 5000.

crewship agent ask-preview lucy receipt \
  --var supplier=Vodafone \
  --var amount=1249 \
  --var amount_currency=CZK \
  --var document=IMG_4821.heic \
  --chat-id chat_7f3a

Please file this receipt.

Supplier: Vodafone
Amount: 1249 CZK
Document: attachments/chat_7f3a/IMG_4821.heic

No --var month= and no --var category= were given, so both of those lines are gone — that is rule 2 above, seen from the outside.

Flag	Type	Default	Description
`--var`	`string`		Answer one field: `name=value`. Repeat for more fields, and repeat a name for a multi-value (several photos of one invoice, or a multiselect).
`--chat-id`	`string`	`preview`	Chat id used to build the `attachments/<chat-id>/<file>` paths.

Output is plain text on stdout with no framing, so it pipes into a file, a diff or a review comment.

`crewship agent rotate-webhook-secret`

Mint a new webhook signing secret for an agent. The new secret is printed only once; the previous secret stops validating immediately.

crewship agent rotate-webhook-secret viktor

Backed by POST /api/v1/agents/{id}/webhook-secret/rotate. Table output shows the secret once; --format json or --format yaml returns webhook_secret and rotated_at.

`crewship agent delete`

Delete an agent. Prompts for confirmation unless --yes is passed.

crewship agent delete <slug-or-id>
crewship agent delete viktor --yes

Flag	Short	Type	Default	Description
`--yes`	`-y`	`bool`	`false`	Skip confirmation prompt.

Deletion is permanent. --yes skips the prompt — reserve it for scripts where you already know the slug is correct.

`crewship agent runs`

List runs for an agent.

crewship agent runs <slug-or-id>

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

`crewship agent stop`

Stop a running agent.

crewship agent stop <slug-or-id>

`crewship agent logs`

Show agent container logs.

crewship agent logs <slug-or-id>
crewship agent logs viktor --tail 50

Flag	Type	Default	Description
`--tail`	`int`	`100`	Number of log lines to show.

`crewship agent debug`

Show agent debug info including container state, environment variables, and crewshipd status. Output defaults to JSON (there is no table form); --format yaml and --format ndjson are honoured too.

crewship agent debug <slug-or-id>

`crewship agent skills`

List skills assigned to an agent.

crewship agent skills <agent>

Output columns: SKILL ID, NAME, CATEGORY, ENABLED

`crewship agent credentials`

List every credential this agent receives — both the ones assigned to it directly and the ones it gets by belonging to a crew.

crewship agent credentials <slug-or-id>

Output columns: ID, NAME, PROVIDER, TYPE, ENV VAR, GRANT, LEASE, SOURCE GRANT says where the credential comes from, which decides how you take it away:

Grant	Meaning	To remove
`explicit`	assigned to this agent	`crewship credential unassign <cred> <agent>`
`crew`	the credential is linked to the agent’s crew	unlink it from the crew — there is no per-agent assignment to revoke

A crew row shows - for ID because no assignment row exists behind it. SOURCE is a different question: it names the approval that put a lease on the grant (manual, keeper_allow, escalation_approve), and is - for a standing grant.

`crewship agent avatar`

Inspect, set, or clear an agent’s stored avatar. Normally an agent’s face is drawn on the fly from its avatar_seed and avatar_style, which means it depends on the installed generator version — upgrading the avatar library repaints every agent. Once a render is stored, that exact image is served instead and the face stops moving. An agent with no stored render is in the normal, pre-persistence state, not a broken one.

`crewship agent avatar show`

Write the stored avatar SVG to stdout, or to a file with -o. Errors if the agent has no stored render.

crewship agent avatar show my-agent
crewship agent avatar show my-agent -o avatar.svg

Flag	Type	Default	Description
`--out`, `-o`	`string`	(stdout)	Write the SVG to this file instead of stdout.

`crewship agent avatar set`

Store an SVG as the agent’s avatar.

crewship agent avatar set my-agent --file avatar.svg
cat avatar.svg | crewship agent avatar set my-agent --file -

Flag	Type	Default	Description
`--file`	`string`		SVG file to store, or `-` to read from stdin. Required.

The server validates the SVG against an allowlist of inert drawing elements; anything that could load or execute something (scripts, event handlers, external references) is refused. Maximum 64 KiB. Storing is write-once — an agent that already has a stored avatar fails with a conflict. Run avatar clear first to replace one.

`crewship agent avatar clear`

Drop the stored render, returning the agent to generate-from-seed.

crewship agent avatar clear my-agent

You rarely need clear by hand: changing an agent’s --avatar-seed or --avatar-style, or applying a crew-wide style with crewship crew apply-avatar-style, drops the stale render automatically.

`crewship agent mcp`

Show or set MCP server configuration for an agent.

# Show agent-specific config
crewship agent mcp <agent-slug>

# Show effective (merged crew + agent) config
crewship agent mcp <agent-slug> --resolved

# Set from inline JSON
crewship agent mcp <agent-slug> --set '{"mcpServers":{...}}'

# Set from file
crewship agent mcp <agent-slug> --set-file agent-mcp.json

Flag	Type	Default	Description
`--set`	`string`		Set MCP config from JSON string. Pass empty string to clear.
`--set-file`	`string`		Set MCP config from file path.
`--resolved`	`bool`	`false`	Show the effective MCP surface: merged blob config (crew + agent, agent overrides crew) plus integration-table bindings (workspace/crew servers + agent bindings).

The JSON must contain a "mcpServers" object at the top level. --set and --set-file are mutually exclusive. --resolved cannot be combined with set operations.

MCP bindings subcommands

Beyond the bare config form above, agent mcp has CRUD subcommands over per-agent MCP server bindings (backed by /api/v1/agents/{id}/integrations):

crewship agent mcp list <agent>                       # list bindings
crewship agent mcp add <agent> <integration-id>       # bind an integration
crewship agent mcp update <agent> <binding-id>        # patch a binding
crewship agent mcp remove <agent> <binding-id>        # delete a binding (aliases: rm, delete)

add — binds a workspace or crew integration to the agent.

Flag	Type	Default	Description
`--scope`	`string`	`workspace`	Integration scope: `workspace` or `crew`.
`--credential`	`string`		Credential ID to attach to this binding.
`--cred-type`	`string`		Credential type: `bearer`, `api_key`, `basic`.
`--env-var`	`string`		Env var name to inject the credential under (stdio MCP servers).
`--enabled`	`bool`	`true`	Whether the binding is active at creation time.

update — patch an existing binding (at least one flag required).

Flag	Type	Default	Description
`--enabled`	`bool`	`false`	Set enabled/disabled state.
`--credential`	`string`		Replace bound credential (empty string unsets).
`--cred-type`	`string`		Replace credential type.
`--env-var`	`string`		Replace env var name (empty string unsets).
`--tools`	`string`		Comma-separated tool allowlist written to `config_override_json` (empty clears the override).

List output columns: ID, SERVER, SCOPE, ENABLED, CREDENTIAL.

`crewship agent chats`

List the agent’s recent chat sessions — id, title, status, message count, and start/end timestamps. Mirrors the SessionsSidebar panel in the web UI. Alias: sessions.

crewship agent chats viktor
crewship agent chats viktor --format json | jq '.[] | select(.status=="ACTIVE")'

Output columns: CHAT ID, TITLE, STATUS, MSGS, STARTED, ENDED. Backed by GET /api/v1/agents/{id}/chats.

`crewship agent channels`

List the notification channels an agent is allowed to post to. An empty list is normal because channel access is default-deny.

crewship agent channels viktor

Output columns: CHANNEL, TYPE, PROVIDER, ENABLED Backed by GET /api/v1/agents/{id}/notification-channels.

`crewship agent files`

List the agent’s /output/<slug>/ working-directory artefacts, or download a single file. Same view the web Files panel renders.

crewship agent files viktor
crewship agent files viktor --download README.md
crewship agent files viktor --download report.txt --out /tmp/saved.txt
crewship agent files viktor --filter '.[] | .name'      # piped through the jq binary

Flag	Type	Default	Description
`--download <name>`	string		Download this file instead of listing.
`--out <path>`	string	basename of file	Output path for `--download`. Pass `-` to stream the file body to stdout.
`--filter <expr>`	string		jq filter applied before rendering (when not downloading). Piped through the external `jq` binary on `PATH`; if `jq` is absent the raw output is shown.

Downloads stream into a tempfile next to the target and rename(2) only on success — Ctrl-C or transport errors mid-copy do not clobber an existing good file with a truncated one. Backed by GET /api/v1/agents/{id}/files and GET /api/v1/agents/{id}/files/download?path=….

`crewship agent file-write`

Upload bytes to the agent’s working directory. Source comes from --from (local file), --content (inline string), or stdin when neither flag is given. --content and --from are mutually exclusive.

echo "draft" | crewship agent file-write viktor notes/draft.md
crewship agent file-write viktor config/x.toml --from ./local.toml
crewship agent file-write viktor README.md --content "# hi"

Flag	Type	Default	Description
`--content`	string		Inline content string.
`--from`	string		Local file path to upload.

Backed by PUT /api/v1/agents/{id}/files/save?path=<path>. The handler reads r.Body raw — no JSON envelope — so binary uploads round-trip byte-for-byte.

`crewship agent inbox`

List peer-to-peer messages addressed to this agent. Useful for debugging cross-agent collaboration: did the message arrive? was it read?

crewship agent inbox viktor
crewship agent inbox viktor --filter '.[] | .from'

Output columns: WHEN, FROM (truncated to 15 chars), MESSAGE (truncated to 60 chars, newlines flattened). Backed by GET /api/v1/agents/{id}/inbox.

`crewship agent git-log`

Show the git commit log from inside the agent’s container — useful for inspecting what code-writing agents have committed locally before any push.

crewship agent git-log viktor
crewship agent git-log viktor --filter '.[] | .message'
crewship agent git-log viktor --format json

Default rendering prints short hash + relative date + truncated subject line. The handler tolerates both [...] and {"commits":[...]} shapes from the server side. Backed by GET /api/v1/agents/{id}/git-log.

​crewship agent

​Subcommands

​crewship agent list

​crewship agent get

​crewship agent create

​crewship agent update

​Ask forms

​crewship agent ask-preview

​crewship agent rotate-webhook-secret

​crewship agent delete

​crewship agent runs

​crewship agent stop

​crewship agent logs

​crewship agent debug

​crewship agent skills

​crewship agent credentials

​crewship agent avatar

​crewship agent avatar show

​crewship agent avatar set

​crewship agent avatar clear

​crewship agent mcp

​MCP bindings subcommands

​crewship agent chats

​crewship agent channels

​crewship agent files

​crewship agent file-write

​crewship agent inbox

​crewship agent git-log

crewship agent

Subcommands

`crewship agent list`

`crewship agent get`

`crewship agent create`

`crewship agent update`

Ask forms

`crewship agent ask-preview`

`crewship agent rotate-webhook-secret`

`crewship agent delete`

`crewship agent runs`

`crewship agent stop`

`crewship agent logs`

`crewship agent debug`

`crewship agent skills`

`crewship agent credentials`

`crewship agent avatar`

`crewship agent avatar show`

`crewship agent avatar set`

`crewship agent avatar clear`

`crewship agent mcp`

MCP bindings subcommands

`crewship agent chats`

`crewship agent channels`

`crewship agent files`

`crewship agent file-write`

`crewship agent inbox`

`crewship agent git-log`