core-agent-tui (CLI reference)

CLI reference for the core-agent-tui binary — the operator-facing terminal client for attach mode. Ships separately from core-agent so the daemon binary stays terminal-render-dependency-free (the whole reason for the split lives in the attach-tui behavior doc).

This page is the flag / env / exit-code lookup. For what the TUI does — observer mode, permission prompts, layout, keybindings, multi-daemon workflow — see Attach TUI.

Synopsis

core-agent-tui [FLAGS] [URL]

URL is optional — omit it and the TUI prompts on stdin for a connection URL. Flags may appear in any position (before, after, or interleaved with URL); the standard flag package’s stop-at-first-positional behavior is worked around internally so core-agent-tui http://... --token-env=T and core-agent-tui --token-env=T http://... both parse identically.

Flags

Flag	Type	Default	Purpose
`--token-env=<ENVVAR>`	string	`""`	Name of the env var holding the bearer token (e.g. `--token-env=ATTACH_TOKEN`). The secret never appears on the command line — the TUI reads `os.Getenv(<ENVVAR>)` at startup. Empty env value is legal (Posture B; see attach-tui: gateway postures).
`--token`	string	`""`	Deprecated (v3.0+) alias for `--token-env`, with identical meaning — it always took the env var’s name, never the token. Renamed because the old name read as an instruction to hand over the secret, and the failure mode for that misreading was a bare 401 with nothing pointing at the flag. Still works; warns on use.
`--auth=<strategy>`	string	`bearer`	Auth strategy for outbound attach requests. Values: `bearer` \| `google-id-token` \| `google-oauth`. See attach-tui: behind an identity gateway for full behavior and failure-mode table.
`--theme=<t>`	string	`""` (auto)	Force a glamour rendering theme. Values: `dark` \| `light` \| `""`. Empty auto-detects the terminal’s background via OSC 11. Switchable at runtime via `/theme dark\|light`.
`--alias=<label>`	string	`""` (session ID)	Display label for the agent identity in the status bar. Convenient when running multiple TUIs against different daemons in tmux panes — `--alias=prod`, `--alias=staging`.
`--new-session`	bool	`false`	Create a fresh session (`POST /sessions`, per-caller ACL-isolated) and attach to it in one shot; skips the picker. Requires the daemon to have `attach.multi_session.enabled` with a configured `SessionFactory` (see multi-session). Daemons without multi-session return 501 and the TUI exits with a clear error.
`--trusted-peers=<hosts>`	string	`""`	Comma-separated hostnames (no port) whose hub-advertised peer endpoints receive your credentials on peer enumeration and `/switch`. The hub’s own host is always trusted; every other peer endpoint is contacted credential-less so a hostile registration on the hub can’t capture your token (#384). Explicitly typed `/attach <url>` targets always use your credentials.
`--no-mouse`	bool	`false`	Start with terminal mouse capture off, restoring native click-drag text selection. Capture is on by default so the wheel scrolls the chat viewport; while it is on the terminal never sees click-drag. The bypass modifier is terminal-specific — Shift-drag on most terminals; in VS Code’s integrated terminal, Shift-drag, or Option-drag on macOS with `terminal.integrated.macOptionClickForcesSelection` on — so if selection appears broken, this flag is the reliable answer. Equivalent to typing `/mouse` at every launch: unlike `core-agent`, this client reads no config file, so the flag is the only way to make the choice stick.
`--version`	bool	`false`	Print build identity — `core-agent-tui v<semver> (commit <sha>, built <RFC3339>)` — and exit. Short-circuits before any other flag or arg processing.

Any unrecognized flag surfaces the standard flag provided but not defined error and exits with code 2. Explicit --help isn’t wired; core-agent-tui -h produces the auto-generated usage from the flag package.

URL grammar

URL (positional argument) accepts:

Form	Behavior
`http(s)://host:port`	Hub form — TUI opens the session picker, enumerating local + peer sessions in parallel.
`http(s)://host:port/sessions/<sid>`	Direct-jump — TUI skips the picker and enters that session.
`http(s)://host:port/sessions/<app>/<sid>`	Qualified direct-jump (multi-app daemons).
`unix:///path/to/socket`	Unix-socket hub.
`unix:///path/to/socket/sessions/<sid>`	Unix-socket direct-jump.
omitted	TUI prompts on stdin.

Same grammar as core-agent attach (the in-process attach subcommand); URLs are portable between both.

Session picker

The hub form opens a table of every session the authenticated caller can see — the daemon’s own plus, when it is a peer-registration hub, each peer’s — newest first, with a + New session row pinned to the top.

Column	Contents
`TITLE`	The session’s short label, as reported by `GET /sessions` — inferred from its first prompt, or set by hand with `/title`. `—` when the session has none: the listener predates attach protocol 1.6.0, the first turn hasn’t landed, or the host has `session_title` off.
`SESSION`	Session ID. Middle-elided when squeezed, because UUIDv7s differ in the tail.
`APP`	App name the session is registered under.
`USER`	Owning user ID.
`ORIGIN`	`local`, or the peer name the session was discovered on.
`AGE`	How long ago the session was created, decoded from a UUIDv7 session ID. `—` for an ID that carries no timestamp (a hand-picked one like `default`). Row ordering additionally falls back to the listener’s last-activity stamp; the column doesn’t.

Columns are measured against the rows actually on screen and squeezed to the terminal; a terminal too narrow for all of them drops APP first, then USER, ORIGIN, TITLE, and AGE, in that order. SESSION is never dropped — it is what identifies the row. A TITLE column that would be nothing but dashes (no session on screen has a title) isn’t shown at all, so a fleet on an older listener gets exactly the layout it had before titles existed.

Keys: ↑/↓ (or k/j) navigate, Enter attaches, r refreshes, q quits.

Environment variables

Name	Consumed by	Purpose
`<whatever>` (via `--token-env=<ENVVAR>`)	`core-agent-tui`	Bearer token for `bearer` auth. Convention: name it `ATTACH_TOKEN` to match `--attach-token=ATTACH_TOKEN` on the daemon side (the same env-var-name indirection).
`CORE_AGENT_TUI_DEBUG`	`core-agent-tui`	Path to append verbose adapter / bridge / SSE logs. Silent when unset. Pairs with `CORE_AGENT_DEBUG=<path>` on the daemon for a two-file view of the whole attach session.
`GOOGLE_APPLICATION_CREDENTIALS`	google.golang.org/api	Path to a service-account key JSON. Only consulted when `--auth=google-id-token` or `--auth=google-oauth`. Overrides Application Default Credentials discovery.
`NO_COLOR`	glamour / lipgloss	Standard — disables ANSI color output when set to any value. Useful for CI-piped `core-agent-tui < prompt.txt`-shape invocations, though the TUI’s Bubble Tea render loop expects a real terminal for full interactivity.

Exit codes

Code	When
`0`	Clean exit — Ctrl+D, `/quit`, or double-Ctrl+C.
`1`	Runtime error surfaced by `run()` — connection refusal, ADC failure, unresolvable URL, daemon 5xx during startup, session-picker cancellation with no fallback. Error message prints to stderr as `core-agent-tui: <reason>`.
`2`	Flag parse error — unknown flag, malformed `--auth` value, etc.

Kills via SIGINT / SIGTERM cancel the context and the TUI exits 0 (the Bubble Tea program handles the cancel cleanly).

Examples

Basic remote attach with bearer auth:

ATTACH_TOKEN=$(openssl rand -hex 32) \
  core-agent --no-repl --attach-listen=:7777 \
  --attach-token=ATTACH_TOKEN &

core-agent-tui http://localhost:7777 --token-env=ATTACH_TOKEN

Fresh session on a multi-session daemon:

core-agent-tui --new-session --token-env=ATTACH_TOKEN https://agent.example.com

Cloud Run IAM (identity gateway):

gcloud auth application-default login \
  --impersonate-service-account=operator@my-project.iam.gserviceaccount.com

core-agent-tui \
  --auth=google-id-token \
  --token-env=ATTACH_TOKEN \
  https://my-agent-abc123-uc.a.run.app

Multiple daemons, one TUI per pane, distinguishable aliases:

# pane A
core-agent-tui --alias=local          http://localhost:7777
# pane B — same operator, remote daemon
core-agent-tui --alias=prod-us-c1 --auth=google-id-token \
  --token-env=ATTACH_TOKEN https://agent.prod-us-central1.example.com

Or jump between them in a single pane via /switch and /attach — the multi-daemon workflow.

Debug a connection issue:

CORE_AGENT_TUI_DEBUG=/tmp/tui.log \
  core-agent-tui http://localhost:7777 --token-env=ATTACH_TOKEN &
tail -f /tmp/tui.log

Install

# From GitHub Releases (resolves the latest tag dynamically so the
# snippet doesn't rot on subsequent releases):
TAG=$(gh release view --repo go-steer/core-agent --json tagName -q .tagName)
OS=$(uname -s | tr A-Z a-z)
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
gh release download "$TAG" --repo go-steer/core-agent \
  --pattern "core-agent-tui_${TAG#v}_${OS}_${ARCH}.tar.gz"
tar xzf "core-agent-tui_${TAG#v}_${OS}_${ARCH}.tar.gz"
./core-agent-tui --version

# From source (Go 1.26+):
go install github.com/go-steer/core-agent/v2/cmd/core-agent-tui@latest

The daemon binary (core-agent) is a separate download — see the main install guide for both.