CLI Reference
CH-UI ships as a single binary with subcommands for every operational task.
Quick Start
Section titled “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-arm64chmod +x ch-uisudo install -m 755 ch-ui /usr/local/bin/ch-uich-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):
# VM2ch-ui server start --detachch-ui tunnel create --name "vm1-clickhouse" --url wss://ch-ui.yourcompany.com/connect
# VM1ch-ui connect --url wss://ch-ui.yourcompany.com/connect --key cht_xxx --clickhouse-url http://127.0.0.1:8123Top-Level Commands
Section titled “Top-Level Commands”ch-ui # start server (default)ch-ui server # run CH-UI web app/API/gatewaych-ui connect # run connector agent next to ClickHousech-ui tunnel # create/manage tunnel keys on server hostch-ui service # install connector as OS servicech-ui backup # consistent snapshot of the CH-UI databasech-ui reset-admin # recover the CH-UI admin rolech-ui uninstall # best-effort local uninstall + cleanup hintsch-ui update # update binary to latest releasech-ui version # print versionch-ui completion # generate shell completionch-ui help # show helpAt startup every command reads a .env file in the current working directory,
if there is one. Each KEY=value line becomes an environment variable unless
that variable is already set, so real environment variables always win. Blank
lines and lines starting with # are skipped, and surrounding quotes are
stripped from values.
server
Section titled “server”Run the CH-UI web app, API, and tunnel gateway.
ch-ui serverch-ui server start --detachch-ui server statusch-ui server stopch-ui server restart| 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 (server restart --detach defaults to true) |
false |
--pid-file |
Path to server PID file | ch-ui-server.pid |
--stop-timeout |
Graceful stop timeout | 10s |
--dev |
Development mode (frontend proxy) | false |
--allow-login-url |
Allow sign-in with a ClickHouse URL typed on the login page. The server connects to it, so trusted networks only. See Configuration | false |
--trusted-proxies |
Comma-separated IPs or CIDRs of reverse proxies whose X-Forwarded-For is trusted; none trusts no proxy. See Configuration |
loopback, private and link-local ranges |
connect
Section titled “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:8123ch-ui connect --detachch-ui connect --takeover| Flag | Description | Default |
|---|---|---|
--url |
WebSocket tunnel URL (ws:// or wss://) |
ws://127.0.0.1:3488/connect |
--key |
Tunnel token (cht_...) |
none |
--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, then the tunnel_url in its config file, then ws://127.0.0.1:3488/connect. For a remote server, point it at the server’s /connect endpoint (wss://your-ch-ui-server/connect).
tunnel
Section titled “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 listch-ui tunnel show <connection-id>ch-ui tunnel rotate <connection-id>ch-ui tunnel delete <connection-id>| Flag | Description |
|---|---|
--config, -c |
Path to server.yaml |
--db |
Override SQLite database path |
--url |
Public URL used when printing connect/service setup commands |
create --name |
Connection name (required) |
list --show-token |
Print full tokens instead of a masked preview |
delete --force |
Allow deleting the embedded connection, which is refused otherwise |
Commands
Section titled “Commands”| Command | What it does |
|---|---|
create |
Create a new connection and generate a tunnel token |
list |
List all tunnel connections |
show |
Show full token and setup commands for a connection |
rotate |
Rotate token. The old token stops working immediately |
delete |
Delete a tunnel connection |
service
Section titled “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:8123ch-ui service statusch-ui service startch-ui service stopch-ui service restartch-ui service logs -fch-ui service uninstall| Flag | Description | Default |
|---|---|---|
install --key |
Tunnel token. Writes a fresh connector config file; without it, install needs an existing config file |
none |
install --url |
Server WebSocket URL written to the config | ws://127.0.0.1:3488/connect |
install --clickhouse-url |
ClickHouse HTTP URL written to the config | http://localhost:8123 |
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
Section titled “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. A plain cp of the live database file is not.
ch-ui backup # writes ch-ui-backup-<timestamp>.dbch-ui backup /backups/ch-ui.db # explicit output fileThe command refuses to overwrite an existing file.
| Flag | Description | Default |
|---|---|---|
--config, -c |
Path to config file (used to locate the database) | auto-detected |
--database-path |
Path to the database (overrides config) | none |
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.
reset-admin
Section titled “reset-admin”Recover the CH-UI admin role when nobody who holds it can sign in. The first ClickHouse admin who signs in becomes the CH-UI admin; after that only an existing CH-UI admin can grant the role, so this is the way back in when that person is gone.
ch-ui reset-admin # remove every CH-UI adminch-ui reset-admin --user alice # make alice an admin, keep existing adminsdocker exec <container> ch-ui reset-adminWith no flags it removes every CH-UI admin assignment, and the next ClickHouse
admin who signs in becomes the CH-UI admin, as on a fresh install. Other roles
(analyst, viewer) are kept, and sessions of removed admins drop to viewer right
away. With --user, use the ClickHouse username for a password login or
sso:<email> for someone who signs in with SSO.
It is safe to run while the server is up. It opens the server’s database
directly, so run it on the server host (or with docker exec), and it refuses
to run when the database file does not exist. Each run is recorded in the audit
log as user_role.reset_admin. See
Can’t login? for the full recovery
steps.
| Flag | Description | Default |
|---|---|---|
--config, -c |
Path to config file (used to locate the database) | auto-detected |
--database-path |
Path to the database (overrides config) | none |
--user |
Make this user an admin instead of clearing admins | none |
update
Section titled “update”Download the latest release from GitHub and replace the current binary in
place. The download is checked against the release’s checksums.txt; if that
file is missing, has no entry for your platform, or the hash does not match,
the update is refused and the old binary stays.
If a server is running (found through its PID file), update stops it and
starts the new version in the background. On Linux it reuses the running
server’s arguments; elsewhere it starts ch-ui server --pid-file <file>. Pass
--restart-server=false to skip that and restart it yourself.
ch-ui updatech-ui update --pid-file /var/run/ch-ui-server.pidch-ui update --restart-server=false| Flag | Description | Default |
|---|---|---|
--restart-server |
Restart a running server after the update | true |
--pid-file |
Server PID file used to find and restart the running server | ch-ui-server.pid |
--stop-timeout |
Graceful stop timeout when restarting | 10s |
uninstall
Section titled “uninstall”Best-effort local uninstall: stops services and processes, removes local CH-UI files, and prints manual cleanup commands for anything that still needs a privileged shell.
ch-ui uninstallch-ui uninstall --print-only| Flag | Description | Default |
|---|---|---|
--config, -c |
Server config file, used to locate the database | auto-detected |
--db |
Override the server SQLite database path | none |
--force |
Continue even if some steps fail | false |
--print-only |
Only print the cleanup commands, do not uninstall | false |
--pid-file |
Extra server PID file to stop and remove (repeatable) | none |
Other Commands
Section titled “Other Commands”ch-ui version # print versionch-ui completion bash # generate shell completion (bash, zsh, fish, powershell)ch-ui help # show help