Quick start

Gateway mode

  1. Start the Gateway.
apus gateway
  1. Open the TUI.
apus tui
  1. Type a message and press Enter.

Remote Gateway:

apus tui --url ws://<host>:<port> --token <gateway-token>

Use --password if your Gateway uses password auth.

Local mode

Run the TUI without a Gateway:

apus chat
# or
apus tui --local

What you see

Mental model: agents + sessions

Sending + delivery

Pickers + overlays

Esc or Ctrl+C closes a picker. In the session picker, the first press clears a nonempty filter. Press again to close it.

The model picker opens immediately, showing a checking state if no models are known yet. In Gateway mode, it reuses the selected agent's last known list while refreshing in the background. Catalog changes update an open picker without clearing its search or moving its highlighted choice when that model is still present. It lists the current model and each provider's recommended models first. Choose All models (N) to show the rest; typing a search always matches every model.

Questions

When the agent calls ask_user, the TUI opens a question prompt for the active session. This works in Gateway mode and local mode (apus chat or apus tui --local). Prompts with up to three questions show one at a time, with a stepper and the time remaining.

Use arrow keys or number keys to choose an option, then Enter to continue. For multi-select questions, toggle the choices you want and accept them. Other… always lets you type your own answer, and Skip declines the entire prompt. After the final question, the TUI submits the answers and shows a compact system notice.

Press Esc to collapse the prompt and return to the composer. The question stays pending with a slim status indicator. /question reopens it. A normal reply still answers eligible pending questions from an active run. Expired questions and questions answered elsewhere close automatically. Reconnecting or switching sessions restores pending questions for the selected session. In local mode, pending questions last only for the current TUI process.

Gateway-connected secrets requests use a masked input that renders bullets and keeps the value out of chat and input history. The prompt shows the entry name, reason, and proposed allowed hosts. Hosts are read-only here: submitting accepts the list as shown. Use the Control UI to edit it. Local mode cannot fulfill store-bound requests. Use apus secrets store or the Control UI with a running Gateway. Enter credentials only in a masked prompt, never in the composer.

Keyboard shortcuts

Slash commands

Multiline input follows the normal chat path instead of the TUI's local command dispatcher. Pasting /exit with a trailing newline keeps the TUI open. Shared chat commands such as /stop and /btw retain their normal meaning.

Core:

Gateway-connected model updates honor the optional agents.defaults.modelSelectionScope setting. When it is unset, they retain their existing configured-default behavior for admins. The embedded local TUI stays session-only regardless of this setting.

Session controls:

Session lifecycle:

When the current session is reset, the TUI reports it after refreshing the transcript. This includes resets started by another client.

Local mode only:

Local mode implements the same queue modes inside the embedded runtime. A mid-run prompt follows the session's /queue policy: steer injects when the runtime can accept it, followup waits for a separate turn, collect combines pending prompts, and interrupt stops the current run before starting the new one. Explicit /steer <message> is Gateway-only. Use /queue steer plus a normal message in local mode.

Apus:

Other Gateway slash commands (for example, /context) are forwarded to the Gateway and shown as system output. See Slash commands.

Local Chrome setup

Use /browser-setup (or /browser-setup inspect) to inspect Chrome extension setup on the TUI process host, not the connected Gateway. /browser-setup install explicitly prepares automatic local setup; /browser-setup verify checks the local authenticated extension relay. No pairing code is requested for supported local native bootstrap. Chrome still requires its own extension installation and permission approval, and existing pairings and automatic-setup opt-outs are preserved.

These commands are deterministic local CLI operations, not messages to the agent. Do not paste credentials into them. /stop, /abort, Escape, or exiting the TUI cancels a pending setup command. After interruption, inspect again to reconcile any preparation that already completed. When the TUI runs through SSH, setup runs on the SSH host; the physical terminal viewer is not assumed to host Chrome.

Local shell commands

Apus setup and repair helper

Apus is the ring-zero setup/repair assistant. It is exposed as apus setup after the configured default model passes a live inference check. If inference is unavailable, an interactive invocation returns to inference onboarding and automation fails with repair guidance. It runs inside the same local TUI shell as apus tui --local, backed by an AI agent restricted to Apus's typed, approval-gated operations:

apus setup                       # start interactively
apus setup -m "status"           # run one request and exit
apus setup -m "set default model openai/gpt-5.2" --yes   # apply a config write

Use local mode when the current config already passes validation and you want the embedded agent to work on it. That agent inspects the config on the same machine, compares it against the docs, and helps repair drift. Local mode does not depend on a running Gateway.

If apus config validate is already failing, start with apus configure or apus doctor --fix first. apus chat still needs a loadable config to start.

Typical loop:

  1. Start local mode:
apus chat
  1. Ask the agent what you want checked, for example:
Compare my gateway auth config with the docs and suggest the smallest fix.
  1. Use local shell commands for exact evidence and validation:
!apus config file
!apus docs gateway auth token secretref
!apus config validate
!apus doctor
  1. Apply narrow changes with apus config set or apus configure, then rerun !apus config validate.
  2. If Doctor recommends an automatic migration or repair, review it and run !apus doctor --fix.

Tips:

Tool output

Image previews

The TUI displays static previews of received and generated image attachments in compatible terminals, including Ghostty, iTerm2, and Kitty. Previews also appear when reopening a conversation or reconnecting. Tool image results appear in their tool cards; restored tool output follows the session's verbose setting.

Gateway mode retrieves managed attachments from the connected Gateway using the same media access rules as the Control UI. Local mode reads managed attachments through the local media store. Image links in ordinary Markdown do not trigger downloads.

Gateway image previews work even when Control UI hosting is disabled.

Previews preserve aspect ratio and fit within 60 columns and 20 rows. The TUI keeps up to four previews per message and the 24 most recent previews in the visible transcript. PNG, JPEG, GIF, and WebP inputs are displayed as static PNG thumbnails; GIF animation is not supported. Large or unavailable images show a preview notice. Use the Control UI to inspect the original image or resolve a media access failure.

Terminals without a supported graphics protocol keep text output. Images are disabled by default inside tmux and GNU Screen. Sixel is not supported.

Terminal colors

History + streaming

Connection details

Options

When you set --url, the TUI does not fall back to config or environment credentials. Pass --token or --password explicitly, plus --tls-fingerprint when the target uses a pinned certificate. Missing explicit credentials is an error. In local mode, do not pass --url, --token, --password, or --tls-fingerprint.

Troubleshooting

No output after sending a message:

Connection troubleshooting

Related