wehub-resource-sync
4.9 KiB
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:
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:
opensquilla gateway start --json
opensquilla chat
Use a specific model for the session:
opensquilla chat --model gpt-5.4-mini
Resume an existing session:
opensquilla chat --session <session-key>
Terminal chat is interactive and requires a real TTY. For scripts, pipes, CI, or one-shot automation, use:
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:
opensquilla chat --standalone
Standalone mode accepts workspace flags for local file and tool work:
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:
/image ./screenshot.png Describe the UI issue
Use /path when the file path is visible to the running chat process:
/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:
/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:
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 for OpenTUI backend
status, Router HUD details, and replay benchmarks. Read
tui-real-terminal-harness.md only when you are
running maintainer integration tests for terminal rendering.
Related Pages
cli.mdfor the full CLI reference.sessions.mdfor listing, resuming, exporting, and deleting sessions.approvals-and-permissions.mdfor permission profiles and approval workflows.features/meta-skill-user-guide.mdfor/metaworkflows.
Docs index · Product guide · Improve this page · Report a docs issue