CLI Reference

CH-UI ships as a single binary with subcommands for every operational task.

Quick Start

Install and run locally (fastest way):

curl -fsSL https://ch-ui.com/install.sh | sh
ch-ui

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:8123

Top-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 update       # update binary to latest release
ch-ui version      # print version
ch-ui completion   # generate shell completion
ch-ui help         # show help

`server`

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 restart

Flags

Flag	Description	Default
`--port, -p`	HTTP port	`3488`
`--config, -c`	Path to `server.yaml`	auto-detected
`--detach`	Run in background	`false`
`--pid-file`	PID file location	auto
`--stop-timeout`	Graceful stop timeout	—
`--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 --takeover

Flags

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`

`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`	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 uninstall

Other Commands

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

CLI Reference

On this page