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.
`--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 "…".

`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

​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`

`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`