> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt > Use this file to discover all available pages before exploring further. # Chat > Inspect, attach to, and react inside chat sessions — the persistent thread behind every agent run. # crewship chat A chat session is the thread that backs every `crewship run` or `crewship ask`. The top-level `chat ` 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`. ```bash theme={null} crewship chat [flags] crewship chat ... ``` 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 | Command | Purpose | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chat ` | Print the full message history of one chat as a rendered transcript. | | `chat list ` | List recent chats for an agent, ordered by last activity. Includes an `UNREAD` column (replies you haven't seen). | | `chat read ` | Mark a chat read for you: clears its unread count and the paired "agent replied" inbox notification. | | `chat attach ` | Upload a file into the chat (lands under `/output//attachments//` in the container). | | `chat react add ` | Add an emoji reaction to a single message. | | `chat react remove ` | Remove your reaction (`rm` / `delete` aliases). | | `chat react list ` | List reactions with counts and whether the caller already reacted. | | `chat participants list ` | 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 ` | 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 ` | Remove a user (`rm` / `delete` aliases). Cannot remove the chat owner. | ## Flags ### `chat ` | Flag | Default | Effect | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `--since ` | (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 ` | (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 ` | Flag | Default | Effect | | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `--agent ` | (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 ` | Flag | Default | Effect | | ---------------------- | ------- | ---------------------------------------------------------------- | | `--agent ` | (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 ` | Flag | Default | Effect | | ------------------------ | -------- | ---------------------------------------------------------------------------------- | | `--role ` | `member` | Role to grant the participant. Any value other than `owner` is stored as `member`. | ## Examples ### Print a transcript ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 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 : no such file or directory`** — `chat attach` couldn't open the local file. ## See also * [`crewship run`](/cli/run) — start an agent run (creates the chat). * [`crewship ask`](/cli/ask) — one-shot prompt (also creates a chat, tagged `origin=CLI`). * [`crewship session`](/cli/session) — browser session management, unrelated noun. * [Conversations API](/api-reference/conversations) — the underlying endpoints.