wehub-resource-sync
158 lines
4.9 KiB
Markdown
158 lines
4.9 KiB
Markdown
# Terminal Chat (TUI)
|
|
|
|
Terminal chat, also called the TUI, is the command-line chat surface for
|
|
OpenSquilla. Use it when you want an interactive conversation in a shell,
|
|
especially while working in a local project directory.
|
|
|
|
## Start Chat
|
|
|
|
Start the default terminal chat:
|
|
|
|
```sh
|
|
opensquilla chat
|
|
```
|
|
|
|
This uses the stable Python-native terminal backend. It does not require Bun,
|
|
npm, tmux, or OpenTUI dependencies.
|
|
|
|
If gateway-backed chat cannot connect, start the gateway first:
|
|
|
|
```sh
|
|
opensquilla gateway start --json
|
|
opensquilla chat
|
|
```
|
|
|
|
Use a specific model for the session:
|
|
|
|
```sh
|
|
opensquilla chat --model gpt-5.4-mini
|
|
```
|
|
|
|
Resume an existing session:
|
|
|
|
```sh
|
|
opensquilla chat --session <session-key>
|
|
```
|
|
|
|
Terminal chat is interactive and requires a real TTY. For scripts, pipes, CI,
|
|
or one-shot automation, use:
|
|
|
|
```sh
|
|
opensquilla agent -m "Inspect this workspace"
|
|
```
|
|
|
|
## Gateway and Standalone Modes
|
|
|
|
By default, `opensquilla chat` uses the gateway-backed chat path, so it shares
|
|
sessions, configuration, approvals, usage, and model/provider state with the Web
|
|
UI and other gateway clients.
|
|
|
|
Use standalone mode when you want direct terminal chat without the gateway
|
|
daemon:
|
|
|
|
```sh
|
|
opensquilla chat --standalone
|
|
```
|
|
|
|
Standalone mode accepts workspace flags for local file and tool work:
|
|
|
|
```sh
|
|
opensquilla chat --standalone --workspace /path/to/project --workspace-strict
|
|
```
|
|
|
|
In gateway mode, `--workspace` is ignored by terminal chat. Use a gateway-visible
|
|
path with `/path`, or use `/file` to upload a local file from the CLI machine.
|
|
|
|
## Common Commands
|
|
|
|
Type `/help` in terminal chat to see the commands supported by the current mode.
|
|
|
|
Commands available in both gateway and standalone chat include:
|
|
|
|
| Command | Purpose |
|
|
| --- | --- |
|
|
| `/help` | Show command help. |
|
|
| `/status` or `/session` | Show the active session and model. |
|
|
| `/new [title]` | Start a new session. |
|
|
| `/model [model]` | Show or change the active model. |
|
|
| `/cost` | Show usage for the current chat state. |
|
|
| `/clear` or `/reset` | Clear the current session context. |
|
|
| `/compact` or `/cmp` | Compact long context when possible. |
|
|
| `/save [path]` | Save the transcript. |
|
|
| `/image <path> [prompt]` | Send an image file with an optional prompt. |
|
|
| `/path <path> [prompt]` | Attach a file by path. |
|
|
| `/theme ...` | Change terminal theme settings when the active backend supports it. |
|
|
| `/quit` or `/exit` | Leave chat. |
|
|
|
|
Gateway-backed chat also supports session and operations commands:
|
|
|
|
| Command | Purpose |
|
|
| --- | --- |
|
|
| `/sessions [limit]` | List recent sessions. |
|
|
| `/resume <id>` | Resume a session. |
|
|
| `/delete <id>` | Delete a session. |
|
|
| `/models` | List available models. |
|
|
| `/usage` | Show aggregate usage. |
|
|
| `/meta` | List MetaSkills. |
|
|
| `/meta <name>` | Run a MetaSkill in the current session. |
|
|
| `/file <path> [prompt]` | Upload a local file and send it with a prompt. |
|
|
| `/permissions ...` | Inspect or change interactive permission mode. |
|
|
| `/approvals ...` | Inspect or reset approval state. |
|
|
| `/forget` | Clear remembered approvals. |
|
|
|
|
Standalone chat supports the core commands above, but `/models`, `/meta`, and
|
|
gateway-wide usage or approval commands require gateway mode.
|
|
|
|
## Files and Images
|
|
|
|
Use `/image` for image files:
|
|
|
|
```text
|
|
/image ./screenshot.png Describe the UI issue
|
|
```
|
|
|
|
Use `/path` when the file path is visible to the running chat process:
|
|
|
|
```text
|
|
/path ./docs/quickstart.md Summarize the setup steps
|
|
```
|
|
|
|
In gateway mode with a remote gateway, prefer `/file` so the CLI uploads the
|
|
local file before sending the turn:
|
|
|
|
```text
|
|
/file ./report.pdf Extract the action items
|
|
```
|
|
|
|
## OpenTUI Preview
|
|
|
|
The default terminal chat is the supported path for normal use. OpenTUI is an
|
|
opt-in preview backend for evaluating a richer terminal UI from a source
|
|
checkout. It is not required for day-to-day terminal chat.
|
|
|
|
From a source checkout:
|
|
|
|
```sh
|
|
bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package
|
|
OPENSQUILLA_TUI_BACKEND=opentui uv run opensquilla chat
|
|
```
|
|
|
|
Leave `OPENSQUILLA_TUI_BACKEND` unset to use the stable terminal chat.
|
|
|
|
Read [`features/tui-frontend.md`](features/tui-frontend.md) for OpenTUI backend
|
|
status, Router HUD details, and replay benchmarks. Read
|
|
[`tui-real-terminal-harness.md`](tui-real-terminal-harness.md) only when you are
|
|
running maintainer integration tests for terminal rendering.
|
|
|
|
## Related Pages
|
|
|
|
- [`cli.md`](cli.md) for the full CLI reference.
|
|
- [`sessions.md`](sessions.md) for listing, resuming, exporting, and deleting
|
|
sessions.
|
|
- [`approvals-and-permissions.md`](approvals-and-permissions.md) for permission
|
|
profiles and approval workflows.
|
|
- [`features/meta-skill-user-guide.md`](features/meta-skill-user-guide.md) for
|
|
`/meta` workflows.
|
|
|
|
[Docs index](README.md) · [Product guide](../README.product.md) · [Improve this page](contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)
|