crewship chat

A chat session is the thread that backs every crewship run or crewship ask. The top-level chat <chat-id> command prints the whole transcript; the subcommands let you list recent chats per agent, upload attachments, and add emoji reactions. Defined in cmd/crewship/cmd_chat.go.

crewship chat <chat-id> [flags]
crewship chat <subcommand> ...

Auth: every subcommand requires an authenticated session (crewship login). All of them also require a selected workspace except chat stream, which resolves tenancy from the chat row itself and so needs only a token and a chat id. The transcript hits GET /api/v1/chats/{id}/messages?limit=500 — the cap is server-side and not paged today.

Subcommands

Command	Purpose
`chat <chat-id>`	Print the full message history of one chat as a rendered transcript.
`chat create <agent-slug-or-id>`	Open an empty chat session on an agent without sending anything to it. Prints the new chat id on stdout.
`chat list <agent-slug-or-id>`	List recent chats for an agent, ordered by last activity. Includes an `UNREAD` column (replies you haven’t seen).
`chat read <chat-id>`	Mark a chat read for you: clears its unread count and the paired “agent replied” inbox notification.
`chat rename <chat-id> <title>`	Give the session a name — what `chat list`, the sidebar and reply notifications call it. Alias: `title`.
`chat attach <chat-id> <path>`	Upload a file into the chat (lands under `/output/<agent-slug>/attachments/<chat-id>/<attachment-id>/` in the container).
`chat attachments list <chat-id>`	List the files attached to a chat: id, name, size, checksum and the path the agent reads. Alias: `attachment`.
`chat attachments delete <chat-id> <attachment-id>`	Remove one attachment — the row and the stored bytes. Idempotent. Aliases: `rm` / `remove`.
`chat react add <chat-id> <msg-id> <emoji>`	Add an emoji reaction to a single message.
`chat react remove <chat-id> <msg-id> <emoji>`	Remove your reaction (`rm` / `delete` aliases).
`chat react list <chat-id> <msg-id>`	List reactions with counts and whether the caller already reacted.
`chat steer <chat-id>`	Queue a mid-turn steering message for a chat (applied on the next turn if a run is in flight).
`chat stream <chat-id>`	Watch the session’s agent run live over HTTP — no WebSocket client needed. See Watching agent runs.
`chat participants list <chat-id>`	List the humans in a group chat (columns `USER ID` / `EMAIL` / `NAME` / `ROLE`). Prints `No participants (private chat).` when empty. Alias: `members`.
`chat participants add <chat-id> <user-id>`	Add a workspace user. Adding the first participant promotes the chat to a group, after which the agent only replies when @mentioned.
`chat participants remove <chat-id> <user-id>`	Remove a user (`rm` / `delete` aliases). Cannot remove the chat owner.

Flags

`chat <chat-id>`

Flag	Default	Effect
`--since <duration>`	(unset)	Only show messages newer than this. Accepts `1h`, `24h`, an RFC 3339 timestamp. Filtering is client-side over the 500-row server response.
`--markdown`	`false`	Force markdown ANSI styling (overrides config).
`--no-markdown`	`false`	Disable markdown ANSI styling.
`--filter <jq>`	(unset)	jq expression applied to the raw `[]message` JSON. Implies JSON output.

The transcript renders assistant / model messages through the markdown ANSI renderer; user and system messages stay plain. Each block carries a coloured role · timestamp header (yellow for user, green for assistant, dim for system).

`chat attach <chat-id> <path>`

Flag	Default	Effect
`--agent <slug-or-id>`	(auto)	Override the auto-resolved agent. By default the CLI walks `GET /api/v1/agents` and asks each agent for its chats until the chat id is found.

The upload is one multipart POST to POST /api/v1/agents/{agentId}/chats/{chatId}/attachments. The server caps the body at 25 MB; the CLI assembles the multipart body in memory rather than streaming because the bound is small. The crew has to be running. The file lands in the agent’s /output tree, which a provisioned crew owns as uid 1001 — the server cannot create attachments/<chat-id>/ there itself, so it writes through the crew container as that uid. On a stopped crew the upload returns 409 with failed to save attachment: the agent's output directory is owned by the crew runtime; … start the crew and retry. Start the crew and re-run the attach; nothing partial is left behind, and no attachment metadata row is recorded for an upload that did not land. Each upload gets its own directory. The file lands at attachments/<chat-id>/<attachment-id>/<filename> — the readable filename is still the last segment, and the id in front of it is what makes the location unique. Attaching two different files called evidence.pdf gives you two attachments and two blobs, each with its own checksum; neither replaces the other. Attaching the same file twice is a retry and resolves to the attachment that already exists. Both facts are printed by chat attachments list, which is also where you get the id that chat attachments delete takes.

`chat attachments list <chat-id>`

Flag	Default	Effect
`--agent <slug-or-id>`	(auto)	Override the auto-resolved agent (same lookup as `chat attach`).

Calls GET /api/v1/agents/{agentId}/chats/{chatId}/attachments. Columns are ID / FILENAME / SIZE / SHA256 (first 12 hex characters — the full digest is in --format json) / AGENT PATH / CREATED. An upload that did not finish is never listed.

`chat attachments delete <chat-id> <attachment-id>`

Flag	Default	Effect
`--agent <slug-or-id>`	(auto)	Override the auto-resolved agent (same lookup as `chat attach`).
`--yes`	`false`	Skip the confirmation prompt. Required in scripts — without a tty the prompt reads as “no” and the command aborts.

Calls DELETE /api/v1/agents/{agentId}/chats/{chatId}/attachments/{attachmentId}. Removes the stored file and then the metadata row. Idempotent: deleting an attachment that is already gone succeeds, because what you asked for is already true. This is the only way to reclaim a chat attachment’s bytes short of deleting the whole chat — chat blobs are not content-addressed (the path is what the agent is told to open), so they sit outside the background reclaim sweep that collects issue attachments. Like the upload, the removal goes through the crew container, so a stopped crew refuses it with failed to delete attachment: …. Nothing is lost — the row is kept and re-running the command after starting the crew completes the deletion.

`chat read <chat-id>`

Flag	Default	Effect
`--agent <slug-or-id>`	(auto)	Override the auto-resolved agent (same lookup as `chat attach`).

Calls PUT /api/v1/agents/{agentId}/chats/{chatId}/read. Your read cursor advances to now: UNREAD in chat list drops to 0 for the session, and the “agent replied” inbox item for it flips to read. Read state is per user — marking a shared group chat read doesn’t touch anyone else’s badge.

`chat rename <chat-id> <title>`

Flag	Default	Effect
`--agent <slug-or-id>`	(auto)	Override the auto-resolved agent (same lookup as `chat attach`).

Calls PATCH /api/v1/agents/{agentId}/chats/{chatId} with {"title": "..."}. Quote the title — it is one argument, not the rest of the line. The server normalises what you send before storing it: the whole title is folded onto one line (newlines and tab runs become a single space), control characters and invisible formatting characters are stripped, and the result is trimmed and capped at 200 characters (characters, not bytes — an emoji or a Czech title gets the same length as an English one). A title that is empty after that, or longer than the cap, is refused with 400 rather than silently truncated. Who may rename: the chat’s creator always, and anyone who can edit the agent for anyone else’s chats — the same gate as chat delete.

crewship chat rename c_abc123 "Refactor the queue worker"
crewship chat rename c_abc123 "Audit pass" --agent atlas
crewship chat rename c_abc123 "Audit pass" --format json

Human output is Chat <chat-id> renamed to "<title>". — the title in the message is the stored one, so normalisation is visible. --format json / yaml / ndjson emit {"id":"<chat-id>","title":"<stored title>"}.

`chat steer <chat-id>`

Flag	Default	Effect
`-m`, `--message <text>`	(required)	Steering message text. The text is scanned for prompt-injection before it is accepted.

The message POSTs to POST /api/v1/chats/{chatId}/steer. If a run is in flight, the message is held and applied on the next turn rather than interrupting the running one (live mid-turn injection is a planned follow-up).

crewship chat steer c_abc123 --message "focus on the auth bug first"
crewship chat steer c_abc123 -m "use the staging DB, not prod"

`chat stream <chat-id>`

Flag	Default	Effect
`--follow`	`false`	Keep the stream open past the run’s terminal event, so the next run on the same session streams too. Without it the command exits when the run finishes.
`--last-seq <n>`	`0`	Resume after this sequence number. Use the `last_seq` value from a previous run’s `stream.end` frame.
`--idle <seconds>`	`0` (server default, 300s)	Give up after this long with no event. Heartbeats do not reset it. `0` selects the server default rather than disabling the bound.
`--quiet`	`false`	Suppress the stderr chatter (thinking, tool calls, status). The run’s text still goes to stdout.

Reads GET /api/v1/chats/{chatId}/stream. The run’s text lands on stdout and nothing else does, so crewship chat stream c_abc123 > reply.md captures the reply and only the reply; thinking, tool calls and stream notices go to stderr. A run that ends in an error exits non-zero. Only a workspace-scoped token is needed — not a selected workspace. The route resolves tenancy from the chat itself, so CREWSHIP_TOKEN plus a chat id is enough. Any run that has a chat can be watched this way — a chat message, crewship run, crewship ask, a routine’s agent_run step, a webhook trigger or a scheduled agent. A run executed with no chat row has no session channel to attach to, and a delegated sub-agent’s output is reported as part of the delegating agent’s turn rather than as a stream of its own. --format ndjson (or json) switches to passthrough: every server frame is printed verbatim, one JSON object per line. That is the mode to script against.

crewship chat stream c_abc123
crewship chat stream c_abc123 --follow
crewship chat stream c_abc123 --format ndjson | jq -r 'select(.type=="text").content'

If the connection drops mid-run the command reconnects on a bounded backoff and resumes from the last sequence number it printed, so a blip neither loses nor duplicates output. Full frame reference: Watching agent runs.

`chat participants add <chat-id> <user-id>`

Flag	Default	Effect
`--role <member\|owner>`	`member`	Role to grant the participant. Any value other than `owner` is stored as `member`.

`crewship chat create <agent-slug-or-id>`

Create a chat session on an agent without sending it a message. Calls POST /api/v1/agents/{agentId}/chats with origin: CLI; the session starts empty and ACTIVE. Every other way to get a session — ask, run, routine iterate — creates it on the way to a model call, so none of them can produce one on an instance with no provider credential. chat create needs none, which makes it the way to set up scripted fixtures and to exercise chat stream’s idle contract (stream.open → stream.end / no_active_run) on a workspace where nothing has ever run. The chat id goes to stdout in every format, so it can be captured directly:

CHAT=$(crewship chat create atlas)
crewship chat stream "$CHAT" --idle 10
crewship chat delete "$CHAT" --yes

Format	Output
(default)	The chat id on stdout, plus `Chat <chat-id> created.` on stderr.
`--format json`	`{"id":"<chat-id>","agent_id":"<agent-id>"}`
`--format yaml` / `ndjson`	The same object as YAML / one JSON line.
`--format quiet`	The bare chat id, nothing else.

`crewship chat delete <chat-id>`

Delete a chat session, its messages, and read cursors. The operation is irreversible and requires confirmation unless --yes is supplied. The agent is resolved automatically; use --agent to select it explicitly.

crewship chat delete c_abc123 --yes
crewship chat delete c_abc123 --agent atlas

Flag	Default	Effect
`--yes`	`false`	Skip the interactive confirmation prompt.
`--agent <slug-or-id>`	(auto)	Override automatic chat-to-agent resolution.

Human output is Chat <chat-id> deleted. Machine output is {"chat_id":"<chat-id>","status":"deleted"} with --format json (or the equivalent YAML object with --format yaml).

`crewship chat react remove <chat-id> <message-id> <emoji>`

Remove your emoji reaction from a message. Aliases are rm and delete.

crewship chat react remove c_abc123 msg_7a3b "👍"
crewship chat react rm c_abc123 msg_7a3b "👍"

The command takes exactly the chat ID, message ID, and emoji; it has no command-specific flags. On success it prints Removed <emoji> from message <message-id>. Repeating the operation is safe because reactions are idempotent per chat, message, emoji, and user.

Examples

Print a transcript

crewship chat c_abc123
crewship chat c_abc123 --no-markdown
crewship chat c_abc123 --format json | jq '.[] | {role, content}'
crewship chat c_abc123 --since 24h

List an agent’s recent chats

crewship chat list daniel
# ID            TITLE                                 STATUS    MSGS  UNREAD  LAST ACTIVITY      ORIGIN
# c_abc123      Refactor the queue worker             active    14    2       2026-05-19 14:02   CLI
# c_xyz789      Audit pass on auth middleware         done      6     -       2026-05-19 09:18   web

Rows are ordered by LAST ACTIVITY (newest message, not creation time). UNREAD counts messages you haven’t seen — your own don’t count; - means fully read. The ORIGIN column distinguishes chats spawned by crewship run / crewship ask (CLI) from the web UI — handy when grep-ing for terminal sessions to attach a file to.

Catch up on a reply you missed

crewship chat list daniel            # UNREAD column shows what's waiting
crewship chat c_abc123 --since 24h   # read the tail of the transcript
crewship chat read c_abc123          # clear the badge + inbox notification

Attach a file

crewship chat attach c_abc123 ./diagram.png
crewship chat attach c_abc123 ./logs.tar.gz --agent daniel

List and remove a chat’s files

crewship chat attachments list c_abc123
# ID                    FILENAME       SIZE    SHA256        AGENT PATH                                                  CREATED
# cml9x2k4p0001qz8f     evidence.pdf   184320  9f2a1c7d4b30  /output/daniel/attachments/c_abc123/cml9x2k4p0001qz8f/evidence.pdf   2026-08-13 09:41
# cml9x8b2r0002qz8f     evidence.pdf   201114  1d77e0a95c62  /output/daniel/attachments/c_abc123/cml9x8b2r0002qz8f/evidence.pdf   2026-08-13 10:02

crewship chat attachments delete c_abc123 cml9x2k4p0001qz8f --yes

Two files with the same name are two attachments with two checksums and two paths — which is the point of the id segment. Use --format json when you want the full digest to compare against what an agent reported reading. Pass --agent when the auto-lookup is ambiguous (the chat lives on more than one agent in your visible set) or when you’ve already pre-resolved the slug.

React to a message

crewship chat react add c_abc123 msg_7a3b "👍"
crewship chat react list c_abc123 msg_7a3b
# EMOJI  COUNT  MINE
# 👍     2      yes
crewship chat react rm c_abc123 msg_7a3b "👍"

Server-side reactions are idempotent per (chat, message, emoji, user) — add and remove can be called blindly without first checking list.

Manage group-chat participants

crewship chat participants add c_abc123 usr_42            # promotes to group
crewship chat participants add c_abc123 usr_42 --role owner
crewship chat participants list c_abc123
crewship chat participants list c_abc123 --format json
crewship chat participants remove c_abc123 usr_42

Adding the first participant flips the chat to group visibility, after which the agent only replies when @mentioned. Mutations require the caller to be the chat owner or a workspace OWNER/ADMIN — otherwise the server returns 403. Adding a user who isn’t in the workspace returns 400 user is not a member of this workspace, and removing the chat owner returns 400 cannot remove the chat owner.

Common errors

chat <id> not found in any agent's recent sessions — chat attach auto-lookup walked every visible agent and didn’t find the chat. Pass --agent to short-circuit the search.
bad --since: ... — the value isn’t a Go duration (1h, 24h) or an RFC 3339 timestamp.
open <path>: no such file or directory — chat attach couldn’t open the local file.

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

Chat

crewship chat

Subcommands

Flags

`chat <chat-id>`

`chat attach <chat-id> <path>`

`chat attachments list <chat-id>`

`chat attachments delete <chat-id> <attachment-id>`

`chat read <chat-id>`

`chat rename <chat-id> <title>`

`chat steer <chat-id>`

`chat stream <chat-id>`

`chat participants add <chat-id> <user-id>`

`crewship chat create <agent-slug-or-id>`

`crewship chat delete <chat-id>`

`crewship chat react remove <chat-id> <message-id> <emoji>`

Examples

Print a transcript

List an agent’s recent chats

Catch up on a reply you missed

Attach a file

List and remove a chat’s files

React to a message

Manage group-chat participants

Common errors

See also

​crewship chat

​Subcommands

​Flags

​chat <chat-id>

​chat attach <chat-id> <path>

​chat attachments list <chat-id>

​chat attachments delete <chat-id> <attachment-id>

​chat read <chat-id>

​chat rename <chat-id> <title>

​chat steer <chat-id>

​chat stream <chat-id>

​chat participants add <chat-id> <user-id>

​crewship chat create <agent-slug-or-id>

​crewship chat delete <chat-id>

​crewship chat react remove <chat-id> <message-id> <emoji>

​Examples

​Print a transcript

​List an agent’s recent chats

​Catch up on a reply you missed

​Attach a file

​List and remove a chat’s files

​React to a message

​Manage group-chat participants

​Common errors

​See also

crewship chat

Subcommands

Flags

`chat <chat-id>`

`chat attach <chat-id> <path>`

`chat attachments list <chat-id>`

`chat attachments delete <chat-id> <attachment-id>`

`chat read <chat-id>`

`chat rename <chat-id> <title>`

`chat steer <chat-id>`

`chat stream <chat-id>`

`chat participants add <chat-id> <user-id>`

`crewship chat create <agent-slug-or-id>`

`crewship chat delete <chat-id>`

`crewship chat react remove <chat-id> <message-id> <emoji>`

Examples

Print a transcript

List an agent’s recent chats

Catch up on a reply you missed

Attach a file

List and remove a chat’s files

React to a message

Manage group-chat participants

Common errors

See also