---
title: Chat and Interactive Shell
description: Talk to the workspace copilot from the terminal — one-shot messages, readline shell, full-screen TUI, and slash commands.
---

The `chat` command is the terminal face of the same assistant that powers **[Home (Assistant)](/docs/using-the-app/copilot)** in the app. It calls `copilot.session.*` on the sidecar — authenticate first, then ensure the sidecar is reachable (`akos serve` locally or `AKOS_HEADLESS_URL`).

## One-shot message

Send a single prompt and wait for the reply (default timeout 30 s):

```bash
akos chat "summarize today's failed runs"
akos chat "draft a cron trigger for nightly backups"
```

Continue an existing session:

```bash
akos chat --session sess_abc "now add error handling to that flow"
```

Stream tokens as they arrive (ADR-0133 polling stream):

```bash
akos chat --stream "explain our egress policy"
```

Enqueue without waiting for the assistant to finish:

```bash
akos chat --no-wait "start a long research task"
akos chat sessions
akos chat show sess_abc --json
```

### Options

| Flag | Description |
|---|---|
| `--session <id>` | Continue an existing copilot session |
| `--workspace <id>` | Workspace for newly created sessions |
| `--principal <id>` | Principal id (default: `cli`) |
| `--role <role>` | `orchestrator`, `chat`, `coder`, `reviewer`, or `embedder` |
| `--stream` | Print assistant tokens incrementally |
| `--no-wait` | Return after the message is enqueued |
| `--timeout-ms <ms>` | Max wait for a final reply (default: `30000`) |
| `--poll-ms <ms>` | Poll interval while waiting (default: `500`) |
| `--json` | Emit raw session/send envelopes |

## Interactive readline shell

Open the portable slash-command shell (also used when you run `akos` with no args on a TTY):

```bash
akos chat --interactive
# shorthand:
akos chat -i
```

Type natural language or slash commands (`/help`, `/flows`, `/inbox`, …). Lists remember the last result so you can select by number (`/run-flow 2`, `/approve 1`).

## Full-screen TUI

For the Ink-based terminal UI (transcript pane, themes, governance badges, proposal cards):

```bash
akos chat --tui
```

Requires a real TTY. Without one, the CLI exits with a hint to use `--interactive` or a one-shot message.

### TUI highlights

- **Themes** — `/theme ocean|grape|forest|ember|mono|midnight|sunset|nord`; persisted in `~/.akos/tui.json`. `NO_COLOR` forces monochrome.
- **Editing** — readline chords (`Ctrl+A/E`, `Ctrl+W`, `Ctrl+U/K/Y`), `↑`/`↓` history, `Tab` completes `/commands` and `@mentions`.
- **Keybindings** — optional overrides in `~/.akos/keys.json` (approve, cancel, scroll).
- **Governance** — header badges for pending HITL and in-flight runs; `Ctrl+G` approves the next gate inline.
- **Proposals** — assistant flow/agent proposals render as cards; `/apply <n>` materializes the chosen proposal.
- **Resume** — transcripts reload from the sidecar when switching sessions (`/sessions` picker in TUI).
- **Offline** — unreachable sidecar shows a banner; the CLI can auto-start a local sidecar on first use.

## Slash command cheat sheet

| Slash | Action |
|---|---|
| `/help` | List slash commands |
| `/workspaces`, `/workspace <id\|n>` | List / switch workspace |
| `/sessions`, `/use <id\|n>`, `/new` | List / switch / create chat session |
| `/flows`, `/flow <id\|n>`, `/run-flow <id\|n>` | List / show / run a flow |
| `/agents`, `/agent <id\|n>` | List / show an agent |
| `/inbox`, `/approve <id\|n>`, `/reject <id\|n>` | HITL queue |
| `/runs`, `/run <id\|n>`, `/watch <id\|n>`, `/logs <id\|n>` | Run inspection |
| `/connect …` | Provider setup / OAuth completion |
| `/apply <n>` | Approve the n-th assistant proposal |
| `/export [path]` | Save conversation to markdown |
| `/quit` | Exit (`Ctrl-C` / `Ctrl-D` also work) |

Full table (including `/verticals`, `/theme`, `/cost`, …): **[Command reference](/docs/cli/command-reference)** › Interactive shell.

## Session management

```bash
akos chat sessions --json
akos chat show sess_abc
akos chat cancel sess_abc      # stop an in-progress turn
akos chat delete sess_abc     # remove session + transcript
```

## Scripting copilot primitives

For automation that parses slash commands or builds proactive cards without the interactive shell:

```bash
akos copilot slash list
akos copilot slash parse "/run-flow nightly-backup"
akos copilot mention parse "ask @billing about limits"
akos copilot proactive '{"kind":"run.failed","runId":"run_1"}' --json
```

Registry-backed integration setup steps also surface in chat — see **[Connections](/docs/cli/connections)** (`connections guide`) and **[Integration setup](/docs/using-the-app/integration-setup)**.

## Related topics

- **[Home (Assistant)](/docs/using-the-app/copilot)** — same copilot in the browser/desktop UI.
- **[Flows and Runs](/docs/cli/flows-and-runs)** — `/run-flow` and scriptable `flows run`.
- **[Connections](/docs/cli/connections)** — `/connect` and OAuth completion from the shell.
- **[Knowledge and RAG](/docs/cli/knowledge-and-rag)** — `/knowledge` and indexed docs for retrieval.
- **[Command reference](/docs/cli/command-reference)** — streaming, exit codes, non-TTY usage.