`apus tui`

Open the terminal UI connected to the Gateway, or run it in local embedded mode.

apus tui [target]

target can be a Control UI session URL, a compact host/agent/ref, a bare short reference such as movies-a1166b81, or a literal agent:... session key. A URL or host target authoritatively selects that Gateway; a bare reference uses the configured or default Gateway. You can also paste a Control UI URL directly as apus <url> and place the TUI options before or after it, for example apus <url> --token <token> --deliver.

The bare-URL form accepts --token, --password, --tls-fingerprint, --deliver, --thinking, --message, --timeout-ms, and --history-limit. URL-valued messages work in either position, including apus --message https://example.com/article <url>. Use apus tui <url> when you need another TUI option; --local, --url, and --session conflict with a session URL.

Related guide: TUI

Options

Flag	Default	Description
`--local`	`false`	Run against the local embedded agent runtime instead of a Gateway.
`--url <url>`	`gateway.remote.url` from config	Gateway WebSocket URL.
`--token <token>`	(none)	Gateway token if required.
`--password <pass>`	(none)	Gateway password if required.
`--tls-fingerprint <sha256>`	`gateway.remote.tlsFingerprint`	Expected TLS certificate fingerprint for a pinned `wss://` Gateway.
`--session <key>`	`main` (or `global` when scope is global)	Session key. Inside an agent workspace it auto-selects that agent unless prefixed.
`--deliver`	`false`	Deliver assistant replies through configured channels.
`--thinking <level>`	(model default)	Thinking level override.
`--message <text>`	(none)	Send an initial message after connecting.
`--timeout-ms <ms>`	`agents.defaults.timeoutSeconds`	Agent timeout. Invalid values log a warning and are ignored.
`--history-limit <n>`	`200`	History entries to load on attach.

Aliases: apus chat and apus terminal invoke this command with --local implied.

Notes

--local cannot combine with --url, --token, --password, or --tls-fingerprint.
Pass only one Gateway target. A URL target cannot combine with --url, and any positional target cannot combine with --session or local mode.
A URL or host target never reuses configured credentials or APUS_GATEWAY_TOKEN / APUS_GATEWAY_PASSWORD. It uses the stored device token for that exact Gateway origin, or explicit --token/--password credentials. On first contact, pass one of those credentials once, approve the pairing request in that Gateway's Control UI, and retry; see Devices.
Session URLs must stay credential-free. Userinfo and sensitive query or fragment parameters such as token and password are rejected.
Short references resolve through the Gateway. If a short reference is ambiguous, the CLI prints candidate names and longer ID prefixes without attaching to either session.
With no URL/host target or explicit --url, tui resolves configured Gateway auth SecretRefs for token/password auth when possible (env/file/exec/store providers).
When the configured remote Gateway is behind an identity-aware proxy, tui resolves gateway.remote.edgeAuth SecretInputs and sends those headers only to that configured Gateway scope. URL or host targets for other origins never inherit them.
With no explicit URL or port, tui follows the active local Gateway port recorded by the running Gateway. Explicit --url, APUS_GATEWAY_URL, APUS_GATEWAY_PORT, and remote Gateway config keep precedence.
Launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless --session is explicitly agent:<id>:...).
Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
Local mode requires exclusive ownership of the configured state directory. It refuses to start while a Gateway or another embedded writer owns that state; run without --local to use the active Gateway, or stop it first with apus gateway stop.
Local mode adds /auth [provider] to the TUI command surface.
Plugin approval gates still apply in local mode: tools that require approval prompt for a decision in the terminal, nothing is silently auto-approved.
ask_user questions appear as interactive prompts in both modes. Esc collapses a prompt without answering; /question reopens it.
Gateway mode accepts secrets requests in a masked input with a read-only allowed-host list. Local mode cannot fulfill store-bound requests; use apus secrets store or the Control UI with a running Gateway.
Session goals appear in the footer and can be managed with /goal.

Session target errors

Failure	Recovery
The Gateway predates short-link resolution	Copy the full session key from that Gateway's Control UI.
Session missing or short ref ambiguous	For the configured/local Gateway, run `apus sessions list`; for a URL/host target, choose a longer or full key in that Gateway's Control UI.
Gateway unreachable	The error names the selected origin. For a `*.ts.net` host, connect Tailscale and confirm the Gateway is reachable on the tailnet.
Identity-aware proxy rejected the upgrade	Configure `gateway.remote.edgeAuth` for the configured remote Gateway; the error includes the relevant remote-access docs link.
Stored device token revoked or rotated	Rotate it with `apus devices rotate --device <deviceId> --role operator`, then reconnect.
TLS certificate pin mismatch	The original TLS fingerprint error passes through unchanged; verify the configured or explicit pin before retrying.

Examples

apus chat
apus tui --local
apus tui
apus tui https://gateway.example/dashboard/main/movies-a1166b81
apus https://gateway.example/dashboard/main/movies-a1166b81 --token <token>
apus tui movies-a1166b81
apus tui --url ws://127.0.0.1:18789 --token <token>
apus tui --session main --deliver
apus chat --message "Compare my config to the docs and tell me what to fix"
# when run inside an agent workspace, infers that agent automatically
apus tui --session bugfix

Config repair loop

Use local mode to have the embedded agent inspect the current config, compare it against the docs, and help repair it from the same terminal.

If apus config validate is already failing, run apus configure or apus doctor --fix first; apus chat does not bypass the invalid-config guard.

apus chat

Then inside the TUI:

!apus config file
!apus docs gateway auth token secretref
!apus config validate
!apus doctor

Apply targeted fixes with apus config set or apus configure, then rerun apus config validate. See TUI and Config.

CLI reference
TUI
Control UI URLs
Devices
Goal
apus attach — launch Claude Code with a temporary session-scoped Gateway MCP grant
apus resume — attach this TUI to an existing Gateway session