---
url: https://cuonghuunguyen.github.io/reference/cli.md
---
# CLI flags

```sh
claude-ui [options]
claude-ui update     # install the latest version; the next start runs it
claude-ui <command>  # ask the running daemon (below)
```

Example:

```sh
claude-ui --port 5000 --roots ~/projects:~/oss
```

## Commands

They talk to the daemon running on this computer. They never start it and never create the token file.

| Command | Does |
| --- | --- |
| `status` | Daemon up, version, port, sessions by state |
| `open [sessionId] [--print]` | Open claude-ui in your browser. `--print` prints the link instead. Without a session id the link holds the pairing token; with one it is a plain link for a browser that is already paired |
| `sessions` (`ls`) | List sessions. `--project <dir>`, `--state <idle\|running\|needs_input\|error\|closed>`, `--archived` (also show archived ones) |
| `projects` | List projects |
| `workers` | List orchestration workers by coordinator |

Options of every command: `--json` (machine-readable; fields may be added), `--port <n>` (default: the port of the running daemon from `daemon.json`, else `PORT`, else `4280`), `--token-file <path>` (default: `CLAUDE_UI_TOKEN_FILE`, else `token` in the config folder).

Exit codes: `0` ok, `1` the daemon refused (for example an unknown session id), `2` wrong usage, `3` daemon not running or token missing or rejected. Only `open --print` writes the token to the terminal.

After `claude-ui update` the global `claude-ui` command stays the old one: run `npm i -g claude-code-ui` to get the new launcher. An old launcher treats a command that fails within 10 seconds (for example `status` with no daemon running) as a broken new version.

Not yet: `new`, `send`, `tail`, `interrupt`, `doctor`, `logs`, `stop` (names reserved). A daemon on Windows cannot be reached from WSL; run `claude-ui` in PowerShell.

## Flags

| Flag | Environment variable | Default | Does |
| --- | --- | --- | --- |
| `--port <n>` | `PORT` | `4280` | Port to listen on |
| `--roots <paths>` | `CLAUDE_UI_ROOTS` | your home folder | Folders that sessions, files and terminals may use. Separate them like `PATH`: `:` (Windows: `;`) |
| `--tailscale` | `CLAUDE_UI_TAILSCALE=1` | off | Serve on your tailnet with `tailscale serve` and print the HTTPS link. See [Phone & remote access](../features/remote-access) |
| `--hostname <name>` | `CLAUDE_UI_HOSTNAME` | | HTTPS name of your own proxy in front of the daemon. Cannot be used with `--tailscale` |
| `--lan` | `CLAUDE_UI_LAN=1` | off | Also listen on the local network, plain HTTP |
| `--allow-bypass` | `CLAUDE_UI_ALLOW_BYPASS=1` | off | Offer the "Bypass permissions" mode |
| `--no-update-check` | `CLAUDE_UI_UPDATE_CHECK=0` | check on | Do not check npm for a new version |
| `--no-os-notify` | `CLAUDE_UI_OS_NOTIFY=0` | on | No desktop notifications on this computer |
| `--no-open` | `CLAUDE_UI_OPEN=0` | open | Do not open the web UI in this computer's browser at start. It never opens after an update restart, over SSH, or on Linux without a display |
| `-v`, `--version` | | | Print the version |
| `-h`, `--help` | | | Print the help |

A flag wins over its environment variable. Both win over the options saved in Settings › Launcher (port, roots, Tailscale, LAN, bypass, update check, desktop notification, open browser), which apply from the next start. Settings › Launcher also adds a launcher shortcut to Applications (macOS), the app menu (Linux) or the Start menu (Windows): a click opens claude-ui in the browser when it runs, else starts it in a terminal.

## Environment variables

Only as environment variables:

| Variable | Default | Does |
| --- | --- | --- |
| `CLAUDE_UI_IDLE_CLOSE_MINUTES` | `10` | Close the Claude process of an idle session that no tab shows after this many minutes. `0` = never. The next prompt resumes it. |
| `CLAUDE_UI_UPDATE_REGISTRY` | npm | An npm registry mirror for updates. Must be `https://` (plain `http://` only on localhost). |
| `CLAUDE_UI_CLAUDE_BIN` | the bundled one | Path to a different Claude Code binary. |

## Files

The **config folder** holds the daemon's own data:

| OS | Config folder |
| --- | --- |
| Linux, macOS | `$XDG_CONFIG_HOME/claude-ui`, else `~/.config/claude-ui` |
| Windows | `%APPDATA%\claude-ui` (or `~/.config/claude-ui` if that folder already exists or `XDG_CONFIG_HOME` is set) |

| File | Holds |
| --- | --- |
| `daemon.json` | Port, pid, version and start time of the running daemon (no token). Removed when it exits |
| `token` | The pairing token. Delete it and restart to unpair every browser. |
| `projects.json` | Your project list |
| `sessions.json` | Each session's model, mode, effort and worker links |
| `settings.json` | App-wide settings (see [Settings](settings)) |
| `vapid.json`, `push-subscriptions.json` | Push notification keys and subscribed browsers |
| `sides.json`, `side-pack/` | WSL and Docker sides |
| `versions/` | Installed updates |

Session history itself is not here. It stays in Claude Code's own transcripts in `~/.claude/projects/`.