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 attach <chat-id> <path>`	Upload a file into the chat (lands under `/output/<agent-slug>/attachments/<chat-id>/` in the container).
`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.

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

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 read <chat-id>`

`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

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 read <chat-id>

​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

​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 read <chat-id>`

`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

React to a message

Manage group-chat participants

Common errors

See also