Skip to main content

​
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) and a selected workspace. The transcript hits GET /api/v1/chats/{id}/messages?limit=500 — the cap is server-side and not paged today.

​
Subcommands

CommandPurpose
chat <chat-id>Print the full message history of one chat as a rendered transcript.
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 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>

FlagDefaultEffect
--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.
--markdownfalseForce markdown ANSI styling (overrides config).
--no-markdownfalseDisable 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>

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

FlagDefaultEffect
--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 participants add <chat-id> <user-id>

FlagDefaultEffect
--role <member|owner>memberRole to grant the participant. Any value other than owner is stored as member.

​
Examples

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.

​
See also