> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r5d.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# r5dchat CLI

> The workspace daemon and conversation commands available inside every workspace.

`r5dchat` is a compiled binary at `/usr/local/bin/r5dchat` in the workspace
image. It runs the workspace daemon and gives the agent read access to its own
conversation history.

```
Usage:
  r5dchat daemon
  r5dchat conversation read <conversation-id> [--json]
  r5dchat conversation overview <conversation-id> [--json]
  r5dchat conversation turn <conversation-id> <turn-id> [--json]
```

`convo` is an alias for `conversation`.

## r5dchat daemon

Starts the workspace daemon. This is the container's default command, so you
rarely run it manually except in local development.

The daemon listens on port 7337 and serves an authenticated private HTTP
protocol for file, search, and process operations, plus an unauthenticated
`/healthz` endpoint used by the readiness and liveness probes.

<ResponseField name="R5DCHAT_HOME" type="string" default="/home/r5d">
  Root directory the daemon operates in.
</ResponseField>

<ResponseField name="R5DCHAT_PORT" type="integer" default="7337">
  Port the daemon listens on.
</ResponseField>

<ResponseField name="R5DCHAT_DAEMON_TOKEN" type="string" required>
  Bearer token required on every request. Supplied from the workspace identity
  Secret in Kubernetes.
</ResponseField>

<ResponseField name="R5DCHAT_WORKSPACE_TOKEN" type="string">
  Workspace identity presented when calling back into the control plane, which
  is how the conversation commands authenticate.
</ResponseField>

<ResponseField name="R5DCHAT_CONTROL_PLANE_URL" type="string">
  Control-plane base URL used by the conversation commands.
</ResponseField>

<ResponseField name="R5DCHAT_USER_ID" type="string">
  The owning user's ID, set by the controller.
</ResponseField>

Run it locally with:

```bash theme={null}
mkdir -p .local-workspace
HOME="$PWD/.local-workspace" \
R5DCHAT_HOME="$PWD/.local-workspace" \
R5DCHAT_DAEMON_TOKEN=development-only-token \
bun run runtime -- daemon
```

## Conversation commands

These let the agent recover context after a fresh-context boundary without
keeping the entire transcript in the model's context window.

Requests authenticate with workspace identity, and the server independently
re-checks that the workspace's user owns the requested conversation.

### overview

```bash theme={null}
r5dchat conversation overview <conversation-id> [--json]
```

Returns a condensed map of the conversation: its turns, their IDs, and short
summaries. This is the recommended starting point after a fresh context, because
it is small enough to read cheaply.

### turn

```bash theme={null}
r5dchat conversation turn <conversation-id> <turn-id> [--json]
```

Returns the full detail of one turn, including tool calls and results. Use it to
drill into a specific turn identified from the overview.

### read

```bash theme={null}
r5dchat conversation read <conversation-id> [--json]
```

Returns the complete transcript in Markdown, with fresh-context boundaries
marked. Use it as a fallback when the overview is not enough, keeping in mind
that a long conversation can consume a large amount of context.

<Note>
  `r5dchat conversation <conversation-id>` without a subcommand still performs a
  full read, for backwards compatibility.
</Note>

### Output format

Human-readable Markdown by default:

```markdown theme={null}
## user

Summarize the quarterly report in ~/artifacts.

## assistant · fresh context

I read the report and produced a summary...
```

Pass `--json` for machine-readable output when scripting.

## Typical agent workflow

<Steps>
  <Step title="A fresh context begins">
    The flagged system prompt instructs the agent to orient itself before
    continuing.
  </Step>

  <Step title="The agent reads the overview">
    `bash r5dchat conversation overview abc123 `
  </Step>

  <Step title="It drills into relevant turns">
    `bash r5dchat conversation turn abc123 turn-7 `
  </Step>

  <Step title="It falls back to a full read only if needed">
    `bash r5dchat conversation read abc123 `
  </Step>
</Steps>

This keeps the durable transcript complete while the provider context stays
small.