openclaw/docs/cli/tui.md

---
summary: "CLI reference for `openclaw tui` (terminal UI connected to the Gateway)"
read_when:
  - You want a terminal UI for the Gateway (remote-friendly)
  - You want to pass url/token/session from scripts
title: "tui"
---

# `openclaw tui`

Open the terminal UI connected to the Gateway.

Related:

- TUI guide: [TUI](/web/tui)

Notes:

- `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
- When launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless `--session` is explicitly `agent:<id>:...`).

## Examples

```bash
openclaw tui
openclaw tui --url ws://127.0.0.1:18789 --token <token>
openclaw tui --session main --deliver
# when run inside an agent workspace, infers that agent automatically
openclaw tui --session bugfix
```
docs(cli): add per-command CLI pages 2026-01-15 06:12:54 +00:00			`---`
refactor: rename to openclaw 2026-01-30 03:15:10 +01:00			summary: "CLI reference for `openclaw tui` (terminal UI connected to the Gateway)"
docs(cli): add per-command CLI pages 2026-01-15 06:12:54 +00:00			`read_when:`
			`- You want a terminal UI for the Gateway (remote-friendly)`
			`- You want to pass url/token/session from scripts`
Docs: add nav titles across docs (#5689) 2026-01-31 16:04:03 -05:00			`title: "tui"`
docs(cli): add per-command CLI pages 2026-01-15 06:12:54 +00:00			`---`

refactor: rename to openclaw 2026-01-30 03:15:10 +01:00			# `openclaw tui`
docs(cli): add per-command CLI pages 2026-01-15 06:12:54 +00:00
			`Open the terminal UI connected to the Gateway.`

			`Related:`
chore: Run `pnpm format:fix`. 2026-01-31 21:13:13 +09:00
docs: canonicalize docs paths and align zh navigation (#11428) * docs(navigation): canonicalize paths and align zh nav * chore(docs): remove stray .DS_Store * docs(scripts): add non-mint docs link audit * docs(nav): fix zh source paths and preserve legacy redirects (#11428) (thanks @sebslight) * chore(docs): satisfy lint for docs link audit script (#11428) (thanks @sebslight) 2026-02-07 15:40:35 -05:00			`- TUI guide: [TUI](/web/tui)`
docs(cli): add per-command CLI pages 2026-01-15 06:12:54 +00:00
Gateway: add SecretRef support for gateway.auth.token with auth-mode guardrails (#35094) 2026-03-05 12:53:56 -06:00			`Notes:`

			- `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
feat(tui): infer workspace agent when launching TUI (#39591) Merged via squash. Prepared head SHA: 23533e24c4cbb91fd5c3006485c9a5d69bd5c2fb Co-authored-by: arceus77-7 <261276524+arceus77-7@users.noreply.github.com> Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com> Reviewed-by: @altaywtf 2026-03-08 06:31:11 -04:00			- When launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless `--session` is explicitly `agent:<id>:...`).
Gateway: add SecretRef support for gateway.auth.token with auth-mode guardrails (#35094) 2026-03-05 12:53:56 -06:00
docs(cli): add per-command CLI pages 2026-01-15 06:12:54 +00:00			`## Examples`

			```bash
refactor: rename to openclaw 2026-01-30 03:15:10 +01:00			`openclaw tui`
			`openclaw tui --url ws://127.0.0.1:18789 --token <token>`
			`openclaw tui --session main --deliver`
feat(tui): infer workspace agent when launching TUI (#39591) Merged via squash. Prepared head SHA: 23533e24c4cbb91fd5c3006485c9a5d69bd5c2fb Co-authored-by: arceus77-7 <261276524+arceus77-7@users.noreply.github.com> Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com> Reviewed-by: @altaywtf 2026-03-08 06:31:11 -04:00			`# when run inside an agent workspace, infers that agent automatically`
			`openclaw tui --session bugfix`
docs(cli): add per-command CLI pages 2026-01-15 06:12:54 +00:00			```