CLI Reference
Complete command reference for the CH-UI binary
CH-UI ships as a single binary with subcommands for every operational task.
Quick Start
Download and run locally (fastest way):
curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-arm64
chmod +x ch-ui
sudo install -m 755 ch-ui /usr/local/bin/ch-ui
ch-uiIf you run from a downloaded binary without global install, prefix commands with ./ch-ui. See Installation for all platforms.
Remote setup (VM2 server + VM1 ClickHouse):
# VM2
ch-ui server start --detach
ch-ui tunnel create --name "vm1-clickhouse" --url wss://ch-ui.yourcompany.com/connect
# VM1
ch-ui connect --url wss://ch-ui.yourcompany.com/connect --key cht_xxx --clickhouse-url http://127.0.0.1:8123Top-Level Commands
ch-ui # start server (default)
ch-ui server # run CH-UI web app/API/gateway
ch-ui connect # run connector agent next to ClickHouse
ch-ui tunnel # create/manage tunnel keys on server host
ch-ui service # install connector as OS service
ch-ui backup # consistent snapshot of the CH-UI database
ch-ui uninstall # best-effort local uninstall + cleanup hints
ch-ui update # update binary to latest release
ch-ui version # print version
ch-ui completion # generate shell completion
ch-ui help # show helpserver
Run the CH-UI web app, API, and tunnel gateway.
ch-ui server
ch-ui server start --detach
ch-ui server status
ch-ui server stop
ch-ui server restartFlags
| Flag | Description | Default |
|---|---|---|
--port, -p | HTTP port | 3488 |
--clickhouse-url | Local ClickHouse HTTP URL for embedded connection | http://localhost:8123 |
--connection-name | Display name for embedded local connection | Local ClickHouse |
--config, -c | Path to server.yaml | auto-detected |
--detach | Run in background | false |
--pid-file | Path to server PID file | ch-ui-server.pid |
--stop-timeout | Graceful stop timeout | 10s |
--dev | Development mode (frontend proxy) | false |
connect
Run the connector agent next to a ClickHouse instance. The agent opens an outbound WebSocket to the CH-UI server gateway.
ch-ui connect --url wss://ch-ui.yourcompany.com/connect --key cht_xxx --clickhouse-url http://127.0.0.1:8123
ch-ui connect --detach
ch-ui connect --takeoverFlags
| Flag | Description | Default |
|---|---|---|
--url | WebSocket tunnel URL (ws:// or wss://) | — |
--key | Tunnel token (cht_...) | — |
--clickhouse-url | ClickHouse HTTP endpoint | http://localhost:8123 |
--config, -c | Connector config file path | auto-detected |
--detach | Run in background | false |
--takeover | Replace currently connected agent for same token | false |
Note: if --url is omitted, the connector falls back to TUNNEL_URL or the tunnel_url in its config file — point it at your CH-UI server's /connect endpoint (wss://your-ch-ui-server/connect).
tunnel
Create and manage tunnel keys on the server host. These commands must be run on the machine where ch-ui.db lives.
ch-ui tunnel create --name "vm1-clickhouse"
ch-ui tunnel list
ch-ui tunnel show <connection-id>
ch-ui tunnel rotate <connection-id>
ch-ui tunnel delete <connection-id>Flags
| Flag | Description |
|---|---|
--config, -c | Path to server.yaml |
--db | Override SQLite database path |
--url | Public URL used when printing connect/service setup commands |
Commands
| Command | What it does |
|---|---|
create | Create a new connection and generate a tunnel token |
list | List all tunnel connections (--show-token prints full tokens instead of a masked preview) |
show | Show full token and setup commands for a connection |
rotate | Rotate token — old token becomes invalid immediately |
delete | Delete a tunnel connection |
service
Install and manage the connector as an OS service (systemd / launchd).
ch-ui service install --key cht_xxx --url wss://ch-ui.yourcompany.com/connect --clickhouse-url http://127.0.0.1:8123
ch-ui service status
ch-ui service start
ch-ui service stop
ch-ui service restart
ch-ui service logs -f
ch-ui service uninstallFlags
| Flag | Description | Default |
|---|---|---|
logs --follow, -f | Follow log output | false |
logs --lines, -n | Number of log lines to show | 50 |
uninstall --purge | Also remove binary and config files | false |
uninstall --force | Force uninstall even if errors occur | false |
backup
Create a consistent, point-in-time snapshot of the CH-UI SQLite database. Uses SQLite's VACUUM INTO, so the copy is fully consistent even while the server is running with WAL-mode writes in flight — unlike a plain cp of the live database file.
ch-ui backup # writes ch-ui-backup-<timestamp>.db
ch-ui backup /backups/ch-ui.db # explicit output fileThe command refuses to overwrite an existing file.
Flags
| Flag | Description | Default |
|---|---|---|
--config, -c | Path to config file (used to locate the database) | auto-detected |
--database-path | Path to the database (overrides config) | — |
The backup contains credentials encrypted with
APP_SECRET_KEY. Back that key up separately — it is not stored in the database, and a restore on another host needs the same key. To restore: stop the server, replace the database file with the backup, start with the sameAPP_SECRET_KEY.
Other Commands
ch-ui uninstall # best-effort local uninstall + manual cleanup commands
# --print-only prints the cleanup commands without executing
# --pid-file adds server PID files to stop/remove (repeatable)
ch-ui update # update binary to latest release
ch-ui version # print version
ch-ui completion bash # generate shell completion (bash, zsh, fish, powershell)
ch-ui help # show help