chm CLI

chm is the standalone terminal CLI for chmonitor (crate chmonitor). The full alias chmonitor is the same binary. Run chm with no subcommand to open the live TUI (chm tui is the same UI) on the Overview dashboard charts. chm --help / chm help / chm -h still print help. By default it talks to chmonitor Cloud at https://dash.chmonitor.dev (hosts, charts, tables, TUI, agent). Point --base-url / CHM_BASE_URL / chm config set base_url at your self-hosted dashboard when needed.

chm doctor --ch-host (no dashboard account or backend) is a separate mode: it connects straight to a ClickHouse host with no dashboard account or backend.

Install

One line — no Rust toolchain, no account. The script detects OS/arch, downloads the matching binary from GitHub Releases, verifies the checksum, installs chm, and symlinks chmonitor → chm:

curl -sSf https://chmonitor.dev/install.sh | bash

# Beta channel (prereleases)
CHM_CHANNEL=beta bash <(curl -sSf https://chmonitor.dev/install.sh)

Pin a release with CHM_VERSION=chm-vX.Y.Z (vX.Y.Z / X.Y.Z also work). Override the install directory with CHM_INSTALL_DIR (default $HOME/.local/bin). The installer never invokes sudo.

Already have a Rust toolchain?

cargo install chmonitor
# both `chm` and `chmonitor` land in ~/.cargo/bin

Channels

install.sh and chm update honour the same channel.

Auth (chm auth login)

Most subcommands call the dashboard /api/v1/* API. Default base URL: https://dash.chmonitor.dev.

chm auth login probes GET /api/v1/auth/cli (public) once and branches — there is no auth_mode in chm.toml / config:

chm auth login
chm auth status
chm auth logout

See API keys and Environment variables — CLI client.

Update

chm update prints current → target version and updates in place from GitHub Releases — no re-running the install script, and it never invokes sudo:

chm update                     # latest stable
chm update --check             # report only (exit 1 if newer exists)
chm update --beta              # install latest beta and save channel=beta
chm update --stable            # install latest stable and save channel=stable
chm update --channel beta      # this run only
chm update --version chm-v0.2.0

Checksum verification is mandatory. Failures print a copy-pasteable fallback (scripts/install.sh or cargo install chmonitor --force).

Common dashboard commands

chm                        # live TUI (default) — Overview charts
chm tui                    # same UI
chm dashboard list         # pick Overview or a saved dashboard
chm dashboard open Overview
chm config                 # interactive config dialog
chm config show            # files + inherit order + resolved
chm hosts
chm chart query-count --limit 50
chm table running-queries --limit 30
chm doctor                 # CLI + dashboard connectivity (no ClickHouse host)
chm agent "why are merges slow?"
# same binary: chmonitor hosts

The default TUI fetches Overview charts (query-count, counts, disk size) from GET /api/v1/charts/{name}?hostId= and skips 404s. chm dashboard list always includes built-in Overview; saved dashboards come from GET /api/dashboards/list when signed in (401/501 still list Overview). On a TTY the list is a ratatui picker (j/k, Enter, q). Piped stdout or --json prints names without a picker.

Config priority: CLI flags → env (CHM_BASE_URL, CHM_HOST_ID, CHM_API_KEY, CHM_TOKEN, CHM_CHANNEL, …) → project ./chm.toml / ./.chm/config.toml → user ~/.config/chm/config.toml → defaults (base_url = https://dash.chmonitor.dev). chm config show prints each layer's path, whether it exists, redacted file contents, env/flag overrides, and the resolved values.

Zero-signup cluster health (chm doctor)

chm doctor --ch-host is a one-shot health check for a ClickHouse cluster that needs no chmonitor account and no backend — the binary talks directly to ClickHouse's HTTP interface, runs a fixed set of read-only checks, and prints a scored report to your terminal.

Without --ch-host / CLICKHOUSE_HOST, chm doctor stays a local CLI + dashboard connectivity check and prints a one-line hint for the cluster scan.

CLICKHOUSE_HOST=http://localhost:8123 CLICKHOUSE_USER=default chm doctor # pragma: allowlist secret
chm doctor --ch-host http://localhost:8123
# same binary: chmonitor doctor --ch-host http://localhost:8123

CLICKHOUSE_HOST=http://localhost:8123 CLICKHOUSE_USER=default \ # pragma: allowlist secret
  cargo run --manifest-path rust/ch-monitor-cli/Cargo.toml -- doctor --ch-host http://localhost:8123

cargo build --release --manifest-path rust/ch-monitor-cli/Cargo.toml
CLICKHOUSE_HOST=http://localhost:8123 CLICKHOUSE_USER=default \ # pragma: allowlist secret
  ./rust/target/release/chm doctor

Doctor configuration

Same env var names the dashboard uses, so if you already have CLICKHOUSE_HOST / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD set for a self-hosted deploy, chm doctor picks them up as-is and runs the cluster scan. Flags override env vars.

What it checks

Twelve independent, read-only checks across the system tables that matter most for day-to-day ClickHouse health:

Every query forces ClickHouse's readonly setting — chm doctor never mutates the target cluster. Each check is independent and best-effort: a missing table or a permission error just skips that one finding rather than failing the whole run, so it degrades gracefully against minimal or locked-down deployments.

Reading the report

chmonitor diagnostics — http://localhost:8123
[REDACTED] 24.8.1.1 · uptime 3.2h

Score: 82/100 (B) · 12 checks run · 2 findings

┌──────────┬─────────────┬─────────────────────────────┬──────────────────────────────┐
│ Severity │ Category    │ Finding                      │ Detail                        │
├──────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ WARNING  │ storage     │ default.events is fragmented │ 412 active parts (2.1 GiB)... │ <!-- pragma: allowlist secret -->
│ NOTICE   │ reliability │ Replication is lagging       │ Most-delayed replica is 90s...│
└──────────┴─────────────┴─────────────────────────────┴──────────────────────────────┘

Deep dive, live charts, and the AI advisor: https://dash.chmonitor.dev (hosted) or self-host: https://docs.chmonitor.dev

• Score starts at 100 and deducts per finding (critical −20, warning −8, notice −2, floored at 0), bucketed into a letter grade.
• Exit code is 1 if any finding is critical, 0 otherwise — safe to wire into a CI step or cron job.
• Each finding's detail line names the exact next step (e.g. OPTIMIZE, review a partition key, check system.mutations.latest_fail_reason).

For live charts, alerting, the AI advisor, and multi-host clusters, point the same [REDACTED] credentials at the full dashboard — self-host it or use the hosted dash.chmonitor.dev.

Anonymous telemetry

The CLI sends an anonymous, opt-out usage ping (CLI version, command name, OS/arch, and a random install id) — a separate stream from the dashboard's telemetry, with no [REDACTED] host, query text, or arguments. Disable it with CHM_TELEMETRY=off or DO_NOT_TRACK=1. See Product Telemetry for the full field list and every opt-out.