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).Subcommands
crewship agent list
List all agents in the workspace.
When the table is a window on a longer list, the human formats end with
showing 1–100 of 308 · next page: --offset 100; machine formats print the
rows only.
Output columns: SLUG, ROLE, CREW, STATUS, ADAPTER, MEMORY
crewship agent get
Show detailed information about an agent.
Pays with shows the provider and (restricted); this
does not mean the agent has no paying account.
Output fields: Name, Slug, ID, Role, Role Title (only when set), Crew, Status, CLI Adapter, Tool Profile, Memory, Timeout, Created, Skills count, Credentials count, Pays with (the provider login paying for the agent’s adapter — name, id, plan, owner and refresh state, or a dash when nothing in its delivery pays for it; see Provider logins). 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.
An agent’s memory and output live under its slug inside the crew. A slug that
another agent of the same crew used — deleted, renamed or moved away — stays
reserved for that agent, so
create (and renaming or moving an agent with
update) onto it fails with 409 instead of handing the new agent the old
one’s memory and output. The same slug is free in any other crew.
crewship agent update
Update an existing agent. Only changed flags are sent.
--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 "…".prompt 3 exceeds 120 characters (it has 154).
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.
forms.json
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 asform "receipt": template names {{suplier}}, which is not a field on that formand 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.
fileandphotofields render asattachments/<chat-id>/<name>, one per line for several files.
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:
--var month= and no --var category= were given, so both of those lines
are gone — that is rule 2 above, seen from the outside.
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.
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.
Deleting an agent stops that agent’s live runs and nothing else: its crew
runtime, sidecar services and the crew’s other agents keep running. No new run
of the agent can start, whichever way the work arrived (chat, assignment,
routine, schedule, webhook); a run accepted before the delete is refused at the
moment its process would start. The response reports the outcome as
runs:
The agent’s memory, chats and attachments are kept.
crewship agent runs
List runs for an agent.
crewship agent status
Fleet-wide agent status counts: every agent in the workspace bucketed by status, plus the number of QUEUED assignments waiting on one. This is the workspace toolbar snapshot — for one agent or one crew’s detail, see agent get and crew status instead.
The route this calls is
GET /api/v1/agents/crews-status — despite the “crews” in the path, the payload counts agents, not crews; the CLI command is named for what it returns.crewship agent load
Per-agent workload: every agent in the workspace with its live task counts (active, pending), today’s completions, and today’s token usage vs. budget — the per-agent breakdown behind agent status. agent get has an agent’s static config; this is the live load view across the whole fleet.
crewship agent stop
Stop a running agent.
Otherwise the server answers
502 with a stable code, the agent’s status
is left as it was, and the command fails with a non-zero exit — it never
prints a stop that did not happen:
“Nothing was running” is established only when the daemon owns no invocation
of the agent, its durable run store lists without error, every stored run
record is readable (or names another agent), and none of this agent’s records
is in a non-terminal state. A stored
running record — a run that outlived a
restart — is stopped at its recorded container and session and reported as
stopped once the runtime confirms it is gone.
After a server restart, persisted runtime identities remain visible until their processes can be confirmed stopped. Recovery protects the specific live run, not unrelated older traces of the same agent. Runs owned by the durable work queue keep that queue’s settlement and reconciliation rules; restarting the server does not turn an unknown work outcome into cancellation. Confirmed recovered stops retain a durable history update until it succeeds. A transient journal failure is retried in the background, including after another restart, without executing the agent again. Recovery advances through bounded batches, so a pending trace without a known outcome does not repeatedly delay later confirmed stops. Another durably recorded running invocation keeps the agent
RUNNING even when its journal start has not appeared yet. Unknown
runtime ownership leaves the history update pending instead of projecting a
false STOPPED status.
When a confirmed stop has no run.started event, recovery records exactly one
run.recovered_stop audit entry for the run ID, with start_recorded: false.
It never fabricates a start, duration or normal execution outcome. The captured
workspace and the existing, non-deleted agent must agree; missing or conflicting
ownership produces an operational warning and leaves the marker pending without
writing history or changing the agent’s status.
The audit entry does not invoke journal automations, bill usage, create approvals
or follow-up work, or count as a completed run. Work-owned attempts retain their
fenced settlement authority. A recorded start keeps the existing work-dispatcher
rules; a missing-start audit does not settle its attempt. Retries, including a
restart between journal commit and marker acknowledgement, cannot duplicate the
entry. Late lifecycle writes for the audited identity are rejected.
The journal explains the record as “Zastaveno během obnovy, začátek nebyl
zaznamenán.” It remains readable through the journal UI and CLI, including the
live journal stream:
crewship agent logs
Show agent container logs. An alias for the top-level crewship logs — same implementation, same output, and --tail is the same knob crewship logs --lines turns. Reach for crewship logs when you want --follow.
Logs come out of the agent’s crew container: an agent with no crew has none, and the command says so rather than printing an empty list.
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 skills
List skills assigned to an agent.
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.
GRANT says where the credential comes from, which decides how you take it away:
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.
This listing answers “what reaches the agent?”, not “can the agent call its model?”. One crew-scoped GH_TOKEN binding makes it non-empty for every agent in the crew, including one with no model credential at all. For that question use credential-readiness.
crewship agent credential-readiness
Report whether a credential the runtime will actually deliver authenticates this agent’s model provider.
The verdict is computed by the runtime’s own delivery rules, not by looking at the credential list: a Claude Code agent is served by the sidecar proxy (its env holds a dummy key by design), a Codex or Gemini login lands in a file under HOME, an OpenCode or Cursor key is written to the env. ready means the run’s own selector finds the credential; missing means it will not, and the first run fails at the first model call; unknown means the server has no opinion (an adapter it does not recognise, an OpenCode agent naming no provider, a local endpoint) and says nothing rather than guess.
SOURCE uses the vocabulary of crewship credential resolve (agent_grant, agent_binding, crew_binding, workspace_binding, crew_link). DELIVERY is the channel: sidecar (the proxy injects it, the env holds a dummy), login_env, login_file, env. Below the manage role the credential’s name is withheld, as it is from agent credentials; the verdict is not.
This command only reports. It assigns nothing.
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. The CLI cannot draw a render (the generator runs in the
browser), so agents created with crewship agent create start without one.
The dashboard stores renders when an agent is created or edited there, and
its Store missing avatars action fills in the rest — see
Agent avatars. Viewing an agent never
stores 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 set
Store an SVG as the agent’s avatar.
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.
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.
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):
add — binds a workspace or crew integration to the agent.
update — patch an existing binding (at least one flag required).
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.
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.
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.
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.
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?
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.
[...] and {"commits":[...]} shapes from the server side.
Backed by GET /api/v1/agents/{id}/git-log.