CLI command reference
Every chouse command, subcommand and flag — generated from the CLI itself.
- Source
- Generated from the chouse command tree (src/content/reference/cli.json), so it always matches the code.
Every chouse command and flag, generated from the CLI itself. For installing, signing in, profiles, output formats and exit codes, read the CLI guide first.
Global flags
Every command accepts these. Most can also come from the environment or the active profile.
| Flag | Type | Default | Description |
|---|---|---|---|
--ca-cert | string | PEM CA bundle to trust for the server, e.g. an internal CA (env CHOUSE_CA_CERT) | |
-c, --connection | string | ClickHouse connection name or id (env CHOUSE_CONNECTION) | |
--debug | trace each request (method, path, status, time, request id) on stderr; never prints tokens | ||
--dry-run | preview a change without making it, where supported | ||
--insecure-skip-tls-verify | do not verify the server certificate — debugging only (env CHOUSE_INSECURE_SKIP_TLS_VERIFY) | ||
--no-headers | omit the header row in table and csv output | ||
-o, --output | string | output format: auto|table|csv|json|yaml (default auto: table on a terminal, json when piped; env CHOUSE_OUTPUT) | |
--profile | string | config profile (env CHOUSE_PROFILE) | |
-q, --quiet | no notes on stderr (results and errors still print) | ||
--server | string | CHouse UI server URL (env CHOUSE_SERVER) | |
--timeout | int | 60 | request timeout in seconds (1-600) |
--token | string | personal access token ch_pat_… (env CH_HOUSE_PAT; prefer the env or auth login) | |
--wide | do not truncate long table cells | ||
--yes | approve changes without a prompt (required without a terminal) |
Getting started
chouse auth
Log in with a personal access token.
Manage the personal access token (PAT) this CLI uses. Tokens are stored 0600 in ~/.config/chouse/credentials.yaml and never printed (only a masked form). Log in once per profile; every other command then just works.
chouse authchouse auth login --server https://chouse.corp
echo "$TOKEN" | chouse auth login --server https://chouse.corp --token-stdin
chouse auth status
chouse auth whoamichouse auth login
Validate a token and store it for the profile.
Validate a personal access token against the server and store it (0600) for the profile, remembering --server and --ca-cert so later commands need no flags. The token is read from a hidden prompt, --token-stdin or CH_HOUSE_PAT — never pass it as an argument. Mint it once in the UI: Preferences → Personal access tokens.
chouse auth login [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--token-stdin | read the token from stdin |
chouse auth login --server https://chouse.corp
chouse auth login --server https://chouse.internal --ca-cert corp-ca.pem --profile prod
echo "$TOKEN" | chouse auth login --server https://chouse.corp --token-stdinchouse auth logout
Remove the stored token for the profile.
Delete the profile's stored token from this machine. The token stays valid on the server — revoke it in the UI to retire it.
chouse auth logoutchouse auth logout
chouse auth logout --profile prodchouse auth status
Show the effective profile without printing secrets.
Show the resolved profile, server, connection, CA bundle and masked token — fully offline, safe to run any time to check what later commands use.
chouse auth statuschouse auth status
chouse auth status -o jsonchouse auth whoami
Show the token's user, roles and permissions.
Ask the server who the token belongs to: user, roles, permissions and data-access rules.
chouse auth whoamichouse auth whoami
chouse auth whoami -o json | jq .permissionschouse config
Profiles and their settings.
Profiles hold non-secret defaults — server, connection, output and CA bundle — in ~/.config/chouse/config.yaml. Tokens live separately in credentials.yaml and are set with chouse auth login. --profile (or CHOUSE_PROFILE) picks a profile for one command; use-profile switches the default.
chouse configchouse config view
chouse config set connection prod
chouse config use-profile staging
chouse config profileschouse config delete-profile
Delete a profile and its stored token.
chouse config delete-profile <name>chouse config delete-profile old --yeschouse config get
Print one profile setting (server, connection, output, ca_cert).
Print one setting stored in the profile (not the flag or environment override).
chouse config get <key>chouse config get serverchouse config profiles
List profiles.
chouse config profileschouse config profileschouse config set
Set a profile setting (server, connection, output, ca_cert).
Store a non-secret setting in the profile (current, or --profile). connection takes a name or an id; output takes auto, table, csv, json or yaml; ca_cert is stored as an absolute path. Tokens are not settable here — use chouse auth login.
chouse config set <key> <value>chouse config set server https://chouse.corp
chouse config set connection prod
chouse config set output json --profile cichouse config unset
Clear a profile setting.
chouse config unset <key>chouse config unset connectionchouse config use-profile
Make a profile the default.
Switch the default profile. It must already exist (create one with chouse auth login --profile NAME).
chouse config use-profile <name>chouse config use-profile prodchouse config view
Show the effective settings and where each comes from.
Show the settings this invocation resolves to (flags > environment > profile), with the token masked.
chouse config viewchouse config view
chouse config view --profile prod -o yamlchouse connection
ClickHouse connections you can use.
List, inspect and check the ClickHouse connections your token can use. Every command takes -c with a connection name or id; set a default with chouse config set connection NAME. Creating and deleting connections stores or removes credentials, so it stays in the UI (Admin › Connections).
chouse connectionAliases: conn, connections
chouse connection list
chouse connection get prod
chouse connection can-i analytics events -c prod
chouse connection runs-aschouse connection can-i
Check whether you may read a database or table.
Ask the server whether your token may read a database, or one table, on the -c connection. Run it before scripting anything that assumes access.
chouse connection can-i <database> [table]chouse connection can-i analytics -c prod
chouse connection can-i analytics events -c prod -o jsonchouse connection get
Show one connection (no password).
chouse connection get <name|id>chouse connection get prod -o yamlchouse connection identity
A connection's kind, roles and health (super admin).
How a connection reaches ClickHouse: its kind (shared login, role ceiling or personal), the roles it names, whether its login passes CHouse UI's checks, and which kinds its server can run. Switching the kind and editing the role map store credentials and decide what ClickHouse lets every account do, so they stay in the UI (Admin › Connections › ClickHouse login). Only a super admin, with a token that has no scopes. Needs server 3.18 or newer.
chouse connection identitychouse connection identity get prod
chouse connection identity recheck prodchouse connection identity get
Show the kind, roles, health and which kinds the server can run.
chouse connection identity get <name|id>chouse connection identity get prod -o yamlchouse connection identity recheck
Run the login's checks now and store the result.
Run CHouse UI's checks on a connection's stored login now instead of waiting for the five-minute round. A failing result makes the connection refuse every request until a later check passes; a passing one lets people back in. Nothing about the login is changed. Exits with 5 when the login fails its checks.
chouse connection identity recheck <name|id>chouse connection identity recheck prodchouse connection links
Links between accounts and ClickHouse users (super admin).
On a personal connection each account's statements run as the ClickHouse user it is linked to. These commands list a connection's links, print the GRANT statements for your ClickHouse administrator, add a link, re-check and remove one. Confirming or removing a suspended link stays in the UI: a suspension means the person behind the account may have changed, and lifting it is a person's decision. Only a super admin, with a token that has no scopes. Needs server 3.18 or newer.
chouse connection linkschouse connection links list prod
chouse connection links add prod --account ann.lee --user alice
chouse connection links grants prod | clickhouse-client --multiquerychouse connection links add
Link an account to a ClickHouse user.
Link one CHouse account to one ClickHouse user on a connection. --account takes the account's username, email or id; it must match exactly one account. The link is active once ClickHouse lets the connection act as the user; until then it waits, and "links grants" prints the statement to run. CHouse UI stores no password for the ClickHouse user.
chouse connection links add <connection> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--account | string | the CHouse account: username, email or id | |
--user | string | the ClickHouse user its statements run as |
chouse connection links add prod --account ann.lee --user alice --yeschouse connection links check
Re-check one link against ClickHouse now.
Run a link's checks now: a waiting link becomes active once the grant is there. A suspended or disabled link is not changed by a check.
chouse connection links check <connection> <account|link-id>chouse connection links check prod ann.leechouse connection links grants
Print the GRANT statements for your ClickHouse administrator.
Print one GRANT per link that is waiting for it, as SQL on stdout. CHouse UI cannot run these: hand them to a ClickHouse administrator, or pipe them to a client that connects as one. With --revokes, print instead the REVOKE for each ClickHouse user the connection may still act as although no link uses it. Nothing is printed when there is nothing to run. Always SQL, whatever -o says.
chouse connection links grants <connection> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--revokes | print the REVOKE statements for ClickHouse users no link uses |
chouse connection links grants prod
chouse connection links grants prod --revokeschouse connection links list
List a connection's links and their state.
chouse connection links list <connection>chouse connection links list prod -o jsonchouse connection links remove
Remove a link.
Remove a link: the account's statements are refused on the connection from its next request. The GRANT in ClickHouse stays; "links grants --revokes" prints the statement that takes it away.
chouse connection links remove <connection> <account|link-id>chouse connection links remove prod ann.lee --yeschouse connection list
List the connections you can use (no passwords).
chouse connection list [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 0 | max rows (0: all) |
--search | string | filter by name or host |
chouse connection list
chouse connection list --search prod -o jsonchouse connection runs-as
Which ClickHouse user or role your statements run with.
For each connection you can use, show the ClickHouse identity your statements run with: the connection's login (a shared login), a ClickHouse role (a role ceiling), or your own linked ClickHouse user (a personal connection), and whether it is usable now.
"ready" means the identity is in place; ClickHouse grants and your permissions still decide each statement. Any other state names what is missing, and DETAIL (in -o json or yaml) says who can fix it. A personal connection also lists the statement forms it refuses. Needs server 3.18 or newer.
chouse connection runs-as [name|id]chouse connection runs-as
chouse connection runs-as prod -o yamlchouse connection test
Check that a connection is reachable.
Dial a saved connection and report reachability and the server version. Nothing is stored or changed. Testing ad-hoc credentials stays in the UI.
chouse connection test <name|id>chouse connection test prodchouse status
Server health, version, compatibility and migration status.
Probe the configured server: health, version and whether this CLI supports it, plus (with a token) the RBAC migration state. Run it before debugging anything else.
chouse statuschouse status
chouse status -o jsonchouse version
Print the CLI version (server version: chouse status).
Print the CLI version, build commit and date. Always offline — it never contacts a server, so it doubles as the install check. chouse status shows the server version and whether this CLI supports it.
chouse versionchouse version
chouse version -o jsonQuery and explore
chouse query
Run SQL: read-only by default, writes with --raw.
Run SQL on the -c connection. SELECT, WITH, SHOW, DESCRIBE and EXPLAIN run directly and print as a table (or -o csv/json/yaml). Anything else needs --raw, and then a confirmation or --yes; --dry-run estimates it without running it. Give SQL as arguments, -f FILE (- for stdin) or --stdin. --out FILE writes the result to a file (format from the extension).
chouse query [sql] [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--explain | string | show the plan instead of running: plan|ast|syntax|pipeline|estimate | |
-f, --file | string | read SQL from a file (- for stdin) | |
--format | string | JSON | with --raw: the server result format (JSON, JSONEachRow, CSV, TabSeparated) |
--limit | int | 1000 | max result rows (1-100000) |
--out | string | write the result to a file (.csv, .json, .yaml) | |
--raw | allow any SQL (writes need confirmation or --yes) | ||
--stdin | read SQL from stdin |
chouse query "SELECT name, engine FROM system.tables LIMIT 5"
chouse query -f report.sql --out report.csv
chouse query "SELECT * FROM events LIMIT 1000" -o csv > events.csv
chouse query --explain plan "SELECT * FROM big WHERE day = today()"
chouse query --raw --dry-run "ALTER TABLE t DELETE WHERE id = 2"
chouse query --raw --yes "ALTER TABLE t DELETE WHERE id = 2"chouse saved
Saved queries: list, show, run, create, delete.
Named queries shared with the UI. run executes one through the read-only path (saved writes are refused — use query --raw); delete asks first (or needs --yes).
chouse savedAliases: saved-queries
chouse saved list
chouse saved run 3f2a… -o csv > out.csv
chouse saved create --name daily-orders -f orders.sqlchouse saved create
Save a query (SQL as arguments, -f FILE or --stdin).
chouse saved create [sql] [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | description | |
-f, --file | string | read SQL from a file (- for stdin) | |
--name | string | name (required) | |
--public | share with everyone | ||
--stdin | read SQL from stdin |
chouse saved create --name six-seven "SELECT 6*7 AS x"
chouse saved create --name daily -f daily.sql --public -c prodchouse saved delete
Delete a saved query.
chouse saved delete <id>chouse saved delete 3f2a… --yeschouse saved get
Show one saved query and its SQL.
chouse saved get <id>chouse saved get 3f2a… -o yamlchouse saved list
List saved queries (scoped to -c when given).
chouse saved list [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 0 | max rows (0: all) |
chouse saved list -c prodchouse saved run
Run a saved query (read-only).
chouse saved run <id> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 1000 | max result rows |
--out | string | write the result to a file (.csv, .json, .yaml) |
chouse saved run 3f2a…
chouse saved run 3f2a… --out result.csvchouse table
Databases, tables, schemas and samples (read-only).
Explore what your token can see on the -c connection: databases and tables, a table's columns and CREATE statement, and sample rows. All read-only; run DDL with chouse query --raw.
chouse tableAliases: tables, explorer
chouse table list
chouse table list analytics
chouse table schema analytics.events
chouse table sample analytics.events --limit 20chouse table list
List tables (optionally in one database).
chouse table list [database]chouse table list -c prod
chouse table list analytics -o csvchouse table sample
Show sample rows.
chouse table sample <db.table | db table> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 20 | rows (max 1000) |
chouse table sample analytics.events --limit 20
chouse table sample analytics.events -o csvchouse table schema
Show a table's engine, columns and CREATE statement.
chouse table schema <db.table | db table>chouse table schema analytics.events
chouse table schema analytics.events -o jsonchouse upload
Check how a CSV/TSV/JSON file would import.
Send the first megabyte of a file for column inference — names, types, nullability and sample values. Nothing is stored. Importing the file stays in the UI (Explorer › Upload), or use chouse query --raw with INSERT.
chouse uploadchouse upload preview rows.csv
chouse upload preview rows.tsv --format TSV --header=false -o jsonchouse upload preview
Infer columns from a file.
chouse upload preview <file> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--format | string | CSV | file format: CSV, TSV or JSON |
--header | true | the first row is a header |
chouse upload preview rows.csvOperate
chouse alert
Alert channels, rules and deliveries.
Inspect alerting: channels (secrets masked), rules and recent deliveries. test sends a real notification, so it asks first (or needs --yes). Editing rules and channels stays in the UI.
chouse alertchouse alert channels
chouse alert events --limit 10
chouse alert test 51b0… --yeschouse alert channels
Notification channels (secrets masked).
chouse alert channelschouse alert channelschouse alert events
Recent alert deliveries, newest first.
chouse alert events [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 50 | max events |
chouse alert events --limit 10chouse alert rules
Alert rules.
chouse alert ruleschouse alert ruleschouse alert test
Send a test notification through a channel.
chouse alert test <channelId>chouse alert test 51b0… --yeschouse audit
Audit log: list and export.
Who did what, when and from where. You see your own entries unless you hold audit:view. export writes CSV (audit:export). Pruning stays in the UI.
chouse auditchouse audit list --limit 20
chouse audit list --action mcp.tool_call --status failed
chouse audit export --limit 5000 > audit.csvchouse audit export
Export entries as CSV (up to 10000).
Write audit entries as CSV to stdout (always CSV; -o does not apply). Same filters as list.
chouse audit export [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--action | string | only this action, e.g. mcp.tool_call | |
--limit | int | 1000 | max rows |
--status | string | success or failed | |
--user | string | only this user id |
chouse audit export --limit 1000 > audit.csvchouse audit list
List entries, newest first.
chouse audit list [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--action | string | only this action, e.g. mcp.tool_call | |
--limit | int | 50 | max rows |
--status | string | success or failed | |
--user | string | only this user id |
chouse audit list --limit 20chouse capacity
Disk forecasts, table growth, cold tables and codec trials.
Capacity of the -c connection (Monitoring › Capacity): days until each node's disk reaches its threshold (--view forecasts), the fastest-growing tables (growth), tables nobody read in 7 days (cold) and codec trials (trials). -o json shows everything, with cost by consumer when you have cost:view.
chouse capacity [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--view | string | forecasts | table to show: forecasts, growth, cold or trials |
chouse capacity -c prod
chouse capacity -c prod --view growth
chouse capacity -c prod -o jsonchouse collectors
Observability collectors: last runs, errors and schedule.
The collectors that feed Data, Monitoring and alerting from ClickHouse system tables. status shows each collector's last run, last error, missing grants and what it read on the -c connection; schedule shows how often each runs (the defaults, or the -c connection's own schedule with its bytes read per day). Read-only; the schedule is edited in Admin › Connections.
chouse collectorschouse collectors status -c prod
chouse collectors schedule
chouse collectors schedule -c prodchouse collectors schedule
How often each collector runs (defaults, or the -c connection's).
chouse collectors schedulechouse collectors schedule -c prod -o jsonchouse collectors status
Each collector's state, last run and last error.
chouse collectors statuschouse collectors status -c prodchouse dashboard
Dashboards: list, show, run a panel, export, apply, versions, snapshots, Grafana import.
Custom dashboards (ADR 0021, ADR 0023) as code. export writes a dashboard as JSON; apply creates a dashboard from that JSON, or updates the dashboard its id names so it matches the file exactly (panels left out are removed with their alerts). run-panel runs one panel's read-only query with your own data access. versions and restore read and roll back its history; snapshot freezes its results for a range. import-grafana converts a Grafana dashboard. delete and restore ask first (or need --yes).
chouse dashboardAliases: dashboards
chouse dashboard list
chouse dashboard export 7c1e… > orders.json
chouse dashboard apply -f orders.json
chouse dashboard run-panel 7c1e… 2b9d… --range 24h --var db=shop
chouse dashboard import-grafana -f grafana.json --applychouse dashboard apply
Create or update a dashboard from an export.
With "id": null in the file, a new dashboard is created (yours, with new panel ids). With an id, that dashboard is updated to match the file: panels keep their ids, panels missing from the file are removed together with their alerts. The server validates every panel; nothing is partly applied. An export from before CHouse 3.16 (chouse.dashboard/v1) is converted.
chouse dashboard apply -f FILE [flags]| Flag | Type | Default | Description |
|---|---|---|---|
-f, --file | string | the export to apply (- for stdin) |
chouse dashboard apply -f orders.json
chouse dashboard export 7c1e… | chouse dashboard apply -f -chouse dashboard delete
Delete a dashboard with its panels and alerts.
chouse dashboard delete <id>chouse dashboard delete 7c1e… --yeschouse dashboard export
Write a dashboard as JSON (the format apply takes).
chouse dashboard export <id> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--out | string | write to this file instead of stdout |
chouse dashboard export 7c1e… > orders.json
chouse dashboard export 7c1e… --out orders.jsonchouse dashboard get
Show a dashboard's panels (-o json for everything).
chouse dashboard get <id>chouse dashboard get 7c1e…chouse dashboard import-grafana
Convert a Grafana dashboard, and with --apply import it.
Prints what converts: each Grafana panel is ready, changed (with what changed) or skipped (with why). Only ClickHouse panels convert. Nothing is saved without --apply, which imports the convertible panels like apply -f. The dashboard is assigned to the -c connection, or to every connection with --all-connections.
chouse dashboard import-grafana -f FILE [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--all-connections | assign the dashboard to every connection instead of -c | ||
--apply | import the convertible panels | ||
-f, --file | string | the Grafana dashboard JSON (- for stdin) |
chouse dashboard import-grafana -f grafana.json -c prod
chouse dashboard import-grafana -f grafana.json -c prod --applychouse dashboard list
List the dashboards you may view.
chouse dashboard listchouse dashboard list -o jsonchouse dashboard restore
Save an old version as the newest one.
Restoring saves the old version's document as a new version, so it can be undone by restoring the version before it. Panels the old version does not have are removed with their alerts; restore lists those alerts and asks first (or needs --yes).
chouse dashboard restore <id> <version>chouse dashboard restore 7c1e… 12 --yeschouse dashboard run-panel
Run one panel's read-only query.
chouse dashboard run-panel <dashboardId> <panelId> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--range | string | 1h | how far back: 15m, 1h, 3h, 6h, 12h, 24h, 2d, 7d, 30d |
--var | stringArray | a variable value as name=value (repeatable; repeat a name for a multi-value variable) |
chouse dashboard run-panel 7c1e… 2b9d… -c prod --range 24h
chouse dashboard run-panel 7c1e… 2b9d… --var db=shop -o csv
chouse dashboard run-panel 7c1e… 2b9d… --var status=ok --var status=errchouse dashboard snapshot
Freeze a dashboard's results for a range, and read them back.
A snapshot stores every chart panel's result for a range ending now, run as you on the -c connection (at most 10 MiB). You, and the shared roles you name with --role, can open it until it expires; whoever opens it still only sees what their own access allows.
chouse dashboard snapshotchouse dashboard snapshot create 7c1e… --name "Incident 42" --range 6h -c prod
chouse dashboard snapshot list 7c1e…
chouse dashboard snapshot get 7c1e… 9a0f… --out incident-42.jsonchouse dashboard snapshot create
Take a snapshot.
chouse dashboard snapshot create <dashboardId> --name NAME [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--expires-days | int | 30 | days until it expires (1 to 365) |
--name | string | the snapshot's name | |
--range | string | 1h | the range to freeze, ending now: 15m, 1h, 3h, 6h, 12h, 24h, 2d, 7d, 30d |
--role | stringArray | a role id the dashboard is shared with that may open it (repeatable) | |
--var | stringArray | a variable value as name=value (repeatable) |
chouse dashboard snapshot create 7c1e… --name "Incident 42" --range 6h -c prod --role team-b-role-id --expires-days 90chouse dashboard snapshot get
Write a snapshot (document and results) as JSON.
chouse dashboard snapshot get <dashboardId> <snapshotId> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--out | string | write to this file instead of stdout |
chouse dashboard snapshot get 7c1e… 9a0f… --out incident-42.jsonchouse dashboard snapshot list
List the snapshots you may open.
chouse dashboard snapshot list <dashboardId>chouse dashboard snapshot list 7c1e…chouse dashboard versions
List a dashboard's last 50 saves.
chouse dashboard versions <id>chouse dashboard versions 7c1e…chouse fleet
Every connection at once: health snapshots and history.
The latest health snapshot of every connection you can see, their history, and fixed server-side metrics (no ad-hoc SQL).
chouse fleetchouse fleet list
chouse fleet history --metric summary --from 2026-10-01T00:00:00Zchouse fleet history
Snapshot history in an RFC3339 window.
chouse fleet history [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--from | string | RFC3339 start | |
--limit | int | 100 | max rows |
--metric | string | summary | metric name |
--to | string | RFC3339 end |
chouse fleet history --metric summary --limit 50chouse fleet list
Latest snapshot per connection.
chouse fleet listchouse fleet listchouse fleet query
One fixed server-side metric for the -c connection.
chouse fleet query <metric>chouse fleet query summary -c prodchouse live
Running queries: list, and kill runaways.
See what is running on the -c connection and kill runaways. You see your own queries unless you hold live_queries:kill_all. kill changes things, so it asks first (or needs --yes).
chouse livechouse live list
chouse live kill 8f1c… --yeschouse live kill
Kill a running query.
chouse live kill <queryId>chouse live kill 8f1c2d… --yeschouse live list
List running queries.
chouse live listchouse live list -o json | jq -r '.queries[].query_id'chouse logs
Recent queries on the connection.
The most recent queries on the -c connection, newest first: when, how long, and whether they finished or failed. With query:history:view:all you see everyone's, from ClickHouse's query log (last 7 days); otherwise only the queries you ran in CHouse UI. --user narrows the list to one ClickHouse user; it never shows more than you may see.
chouse logs [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 20 | max rows (1-100) |
--user | string | only this ClickHouse user |
chouse logs
chouse logs --user etl --limit 50 -o csvchouse metrics
ClickHouse server metrics (read-only).
Server stats, the largest tables, recent errors, part pressure, your own SELECT as a metric, and the impact of an ALTER UPDATE/DELETE — which is estimated, never run.
chouse metricschouse metrics overview
chouse metrics top-tables --limit 5
chouse metrics simulate "ALTER TABLE t DELETE WHERE day < today() - 30"chouse metrics custom
Run your own SELECT as a metric.
chouse metrics custom [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--query | string | SELECT … (required) |
chouse metrics custom --query "SELECT count() FROM system.query_log"chouse metrics errors
Server errors in the last --interval minutes.
chouse metrics errorschouse metrics errors --interval 60chouse metrics overview
Server stats and resource use.
chouse metrics overviewchouse metrics overviewchouse metrics parts-pressure
Tables with too many parts or slow merges.
chouse metrics parts-pressurechouse metrics parts-pressurechouse metrics simulate
Estimate the rows an ALTER UPDATE/DELETE would touch (never runs it).
chouse metrics simulate <ALTER …>chouse metrics simulate "ALTER TABLE t UPDATE x = 1 WHERE id = 2"chouse metrics top-tables
Largest tables.
chouse metrics top-tableschouse metrics top-tables --limit 5chouse perf
Query regressions against their own baseline.
Query shapes on the -c connection that got slower or heavier than their own baseline, lined up with the upgrades, DDL and setting changes around their onset (Monitoring › Performance). Sample query text needs query:history:view:all.
chouse perfchouse perf regressions -c prod
chouse perf shape 9f2c41d0a1b2 -c prodchouse perf regressions
Open regressions, worst first.
chouse perf regressionschouse perf regressions -c prod -o jsonchouse perf shape
Hourly history of one query shape.
chouse perf shape <fingerprint>chouse perf shape 9f2c41d0a1b2 -c prodchouse scheduled
Scheduled queries: jobs, runs, run now.
Scheduled query jobs and their runs. preview checks a SELECT without creating anything; run and delete ask first (or need --yes). Creating and editing jobs stays in the UI.
chouse scheduledAliases: jobs
chouse scheduled list -c prod
chouse scheduled runs 4d2e… --limit 5
chouse scheduled run 4d2e… --yeschouse scheduled delete
Delete a job.
chouse scheduled delete <id>chouse scheduled delete 4d2e… --yeschouse scheduled get
Show one job.
chouse scheduled get <id>chouse scheduled get 4d2e… -o yamlchouse scheduled list
List jobs (scoped to -c when given).
chouse scheduled listchouse scheduled list -c prodchouse scheduled preview
Check a SELECT as a job body without creating anything.
chouse scheduled preview [flags]| Flag | Type | Default | Description |
|---|---|---|---|
-f, --file | string | read the SELECT from a file (- for stdin) | |
--query | string | SELECT to check |
chouse scheduled preview -c prod --query "SELECT count() FROM events"
chouse scheduled preview -c prod -f job.sqlchouse scheduled run
Run a job now.
chouse scheduled run <id>chouse scheduled run 4d2e… --yeschouse scheduled runs
A job's runs, newest first.
chouse scheduled runs <id> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 20 | max runs |
chouse scheduled runs 4d2e… --limit 5chouse upgrades
ClickHouse version status and upgrade checks.
Upgrades (Monitoring › Upgrades): where a connection's ClickHouse version stands and the targets worth moving to, and the upgrade checks run against your real workload (exact against a connection on the target line, or from the release notes, with the top queries planned on the server with the target's settings). Read-only; checks are started in the UI.
chouse upgradeschouse upgrades status -c prod
chouse upgrades fleet
chouse upgrades list -c prod
chouse upgrades get 3d1e… -o yamlchouse upgrades fleet
Every connection's version, support status and last upgrade check.
chouse upgrades fleetAliases: rollout
chouse upgrades fleetchouse upgrades get
One upgrade check: its findings, their sources and evidence.
chouse upgrades get <checkId>chouse upgrades get 3d1e… -o yamlchouse upgrades list
Upgrade checks of the -c connection.
chouse upgrades listchouse upgrades list -c prodchouse upgrades status
The -c connection's version, support status and upgrade targets.
chouse upgrades statuschouse upgrades status -c prod -o yamlData observability
chouse context
Curated table context and metric definitions.
What people wrote down about the data on the -c connection (Data › Context): a table's description, owner, grain, column notes and caveats, and the defined business metrics. Read-only; context is edited in the UI.
chouse contextchouse context get shop.orders -c prod
chouse context metrics -c prod
chouse context metrics gmv -c prod -o jsonchouse context get
One table's curated context.
chouse context get <database.table>chouse context get shop.orders -c prod -o yamlchouse context metrics
Metric definitions (all, or one by name).
chouse context metrics [name]chouse context metrics gmv -c prodchouse health
Data health: promises, incidents, dataset trust.
Data health promises and their incidents, one table's trust state, and the actions to re-run checks or acknowledge an incident (both ask first, or need --yes).
chouse healthchouse health list -c prod
chouse health incidents
chouse health dataset shop.orders -c prod
chouse health ack 9a1f… --yeschouse health ack
Acknowledge an incident.
chouse health ack <incidentId>chouse health ack 9a1f… --yeschouse health dataset
One table's trust state, freshness and open incidents.
How far to trust one table right now: trust state, freshness, volume baseline, open incidents, owners and recent writers.
chouse health dataset <database.table>chouse health dataset shop.orders -c prodchouse health incidents
Data health incidents, newest first.
chouse health incidents [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 50 | max rows |
chouse health incidents --limit 10chouse health list
List promises (scoped to -c when given).
chouse health listchouse health list -c prodchouse health run
Run a promise's checks now.
chouse health run <promiseId>chouse health run 2b7c… --yeschouse health timeline
A promise's check history.
chouse health timeline <promiseId> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 50 | max samples |
chouse health timeline 2b7c… --limit 10chouse incidents
Data and pipeline incidents with their root cause.
Incidents from Data Health promises and the observability platform (pipelines, freshness, volume, parts, replication) with severity, subject and root cause. Active only unless --all; scoped to -c when given.
chouse incidents [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--all | include recovered incidents | ||
--limit | int | 50 | max rows |
chouse incidents
chouse incidents --all --limit 20 -o jsonchouse lineage
Where a table's data comes from and where it goes.
Lineage around one table, built from ClickHouse metadata, query logs and scheduled jobs. --impact lists everything downstream that a change to the table would affect (what schema preflight checks before DDL).
chouse lineage <database.table> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--depth | int | 3 | hops to follow (1-8) |
--direction | string | both | up, down or both |
--impact | list what a change to the table would affect |
chouse lineage shop.orders -c prod
chouse lineage shop.orders --direction up --depth 2
chouse lineage shop.orders --impactchouse notebook
Investigation notebooks of incidents and Doctor reports.
The investigation notebook of an incident or Doctor report: Chouse AI findings, query snapshots, notes and actions. <kind> is data-health (a Data Health incident), observe (an observability incident, see chouse incidents) or doctor (a Doctor report). export writes it as a Markdown postmortem to stdout. Read-only; notebooks are written in the UI.
chouse notebookchouse notebook show observe 4b2e…
chouse notebook export doctor 91fa… > postmortem.mdchouse notebook export
Write a notebook as a Markdown postmortem to stdout.
Write the notebook as Markdown to stdout (always Markdown; -o does not apply).
chouse notebook export <kind> <ref>chouse notebook export observe 4b2e… > postmortem.mdchouse notebook show
A notebook's cells in order.
chouse notebook show <kind> <ref>chouse notebook show data-health 12 -o yamlchouse remediation
Review, approve or reject proposed fixes.
Fixes proposed for incidents (by people, Chouse AI or MCP agents) from the remediation catalog. Approving is how a fix gets to run. The server enforces who may approve: a person may approve their own low-risk fix, but high-risk fixes need two approvers other than the proposer, and a fix proposed by Chouse AI or an agent always needs someone else. approve and reject ask first (or need --yes).
chouse remediationAliases: fixes
chouse remediation list -c prod --status proposed
chouse remediation get 6e0b…
chouse remediation approve 6e0b… --comment "checked the plan" --yeschouse remediation approve
Approve a proposed action.
Approve one proposed action — review it with get first. The server enforces the approval rules and records the decision with channel=cli.
chouse remediation approve <actionId> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--comment | string | decision comment |
chouse remediation approve 6e0b… --comment "reviewed" --yeschouse remediation get
One action: statements, approvals, executions.
chouse remediation get <actionId>chouse remediation get 6e0b… -o yamlchouse remediation list
Actions on the -c connection, newest first.
chouse remediation list [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 50 | max rows |
--status | string | comma-separated: proposed, approved, executing, executed, verified, failed_verification, failed, rolled_back, rejected |
chouse remediation list -c prod --status proposed,approvedchouse remediation reject
Reject a proposed action.
Reject one proposed action — review it with get first. The server enforces the approval rules and records the decision with channel=cli.
chouse remediation reject <actionId> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--comment | string | decision comment |
chouse remediation reject 6e0b… --comment "reviewed" --yesAI and agents
chouse action
AI write tools: list, run, status, undo, activity.
The same write tools the CHouse Assistant and MCP agents use (ADR 0025), checked the same way. An undoable change runs at once; a change that asks once prompts on a terminal (or needs --yes); a high-risk change is always sent to a second person to approve in CHouse — --yes never covers it. Your token's write policy decides which tools you get.
chouse actionAliases: actions
chouse action tools
chouse action run create_saved_query name=orders query="SELECT 1"
chouse action run run_sql_change sql="INSERT INTO db.t VALUES (1)" --yes
chouse action undo 3f2a…chouse action activity
What AI agents changed for you, newest first.
chouse action activity [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 50 | max actions (1-200) |
chouse action activity --limit 20chouse action run
Run one write tool.
Values are JSON when they parse as JSON (numbers, booleans, arrays, objects) and strings otherwise; --args takes a whole JSON object.
chouse action run <tool> [key=value ...] [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--args | string | the tool's arguments as one JSON object |
chouse action run pause_scheduled_job id=3f2a…
chouse action run create_dashboard --args '{"title":"Ingest","panels":[…]}'chouse action status
Show one action: its status, result and whether it can be undone.
chouse action status <id>chouse action status 3f2a…chouse action tools
List the write tools your token may run, with how each is checked.
chouse action toolschouse action tools -o jsonchouse action undo
Undo an undoable action (within 24 hours, unless it changed since).
chouse action undo <id>chouse action undo 3f2a… --yeschouse agents
Agent activity: sessions, queries, budgets (agents:view).
What agents connected over MCP or with personal access tokens did: sessions with their queries, bytes read and policy outcomes, and the budget policies that apply. Read-only; policies and the pause switch stay in the UI.
chouse agentschouse agents summary
chouse agents sessions --days 7
chouse agents session <sessionId>
chouse agents policieschouse agents policies
Budget policies (per token, per role, default).
Budget policies checked with EXPLAIN ESTIMATE before agent queries run: per-query and daily read limits, partition-filter thresholds and what happens on tables with an open incident. The most specific policy wins: token, then role, then the default.
chouse agents policieschouse agents policieschouse agents session
One session with every tool call (replay).
Replay one session: every tool call with its arguments, outcome, policy notices and bytes read. Arguments of other people's sessions need query:history:view:all.
chouse agents session <sessionId>chouse agents session pat-123:1790000000000chouse agents sessions
Agent sessions in the last --days (1-30).
Every MCP and personal-access-token session in the window, newest first, with its queries, bytes read and how many calls were warned or blocked. A session is consecutive calls from one token with gaps under 30 minutes.
chouse agents sessions [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--days | int | 1 | window in days (1-30) |
chouse agents sessions --days 7chouse agents summary
Last 24 hours: active agents, queries, warnings, blocks, pause state.
Agent activity over the last 24 hours: active agents and sessions, queries and bytes read, results that carried a health warning, queries blocked by a budget policy, and whether agent access is paused.
chouse agents summarychouse agents summarychouse ai
Chouse AI: optimize SQL (LLM cost), usage, cost and agents.
Ask Chouse AI to optimize or diagnose SQL. Advisory only — it never runs anything — but it calls the AI model (LLM cost), so it asks first (or needs --yes). Listing capabilities and models is free, and so are the governance reads: usage and estimated cost, data sent to providers, recent requests, and how CHouse's AI agents are set up.
chouse aichouse ai optimize -f slow.sql --yes
chouse ai optimize --capability debug-query "SELECT …" --yes
chouse ai models
chouse ai usage --by origin --days 30
chouse ai requests --origin mcpchouse ai agents
CHouse's AI agents: what each feature runs, models, tools (ai_agents:view).
The AI agents CHouse runs (AI Governance › Assistant): each agent with its model config, harness, tools, skills and subagents, whether it is built in or customized and has an update, and which agent each AI feature is bound to (-o json for features, harnesses and skills). Read-only; agents are edited in the UI.
chouse ai agentschouse ai agents
chouse ai agents -o json | jq '.features'chouse ai capabilities
What Chouse AI can do for your token.
chouse ai capabilitieschouse ai capabilitieschouse ai egress
Tables, columns and records AI tools sent to LLM providers.
Data CHouse's AI tools returned to an LLM provider in the last --days, by source (a table or a CHouse record type), most rows first: columns, rows, bytes, users, requests and providers. --search narrows the sources on the server.
chouse ai egress [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--days | int | 7 | window in days (capped at the server's retention) |
--search | string | only sources whose name contains this text |
chouse ai egress --days 30
chouse ai egress --search customerschouse ai guardrail-triggers
Recent guardrail triggers: stage, action, matches, agent and tool.
Guardrail triggers of the last --days, newest first: the guardrail, the stage, the action and mode, how many values matched, the agent and tool, and the AI request. Matched values are never stored.
chouse ai guardrail-triggers [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--days | int | 7 | window in days (capped at the server's retention) |
--guardrail | string | only this guardrail's triggers (id from chouse ai guardrails) | |
--limit | int | 100 | rows to return (1-500) |
--offset | int | 0 | rows to skip, for paging |
chouse ai guardrail-triggers
chouse ai guardrail-triggers --guardrail builtin-guardrail-pii --days 7
chouse ai guardrail-triggers --limit 50 --offset 50chouse ai guardrails
AI guardrails: what every AI run passes through (ai_guardrails:view).
The guardrails CHouse applies to its AI runs and, where enabled, to MCP tool results (AI Governance › Guardrails): kind, stages, action, shadow or enforce mode, whether it is on, and its triggers in the last 24 hours. Read-only; guardrails are edited in the UI or the REST API.
chouse ai guardrailschouse ai guardrails
chouse ai guardrails -o json | jq '.guardrails[] | select(.enabled)'chouse ai models
Active AI models.
chouse ai modelschouse ai modelschouse ai optimize
Optimize or diagnose SQL (LLM cost).
chouse ai optimize [sql] [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--capability | string | optimize-query | optimize-query|debug-query|diagnose-error|diagnose-parts|diagnose-schema |
-f, --file | string | read SQL from a file (- for stdin) | |
--model | string | AI model id | |
--stdin | read SQL from stdin |
chouse ai optimize -f slow.sql --yes -o jsonchouse ai request
One AI request step by step: LLM calls, tool calls, queries, data sent.
chouse ai request <requestId>chouse ai request 0c5f… -o yamlchouse ai requests
Recent AI requests: who started them, tokens, cost, status.
AI requests of the last --days, newest first: the user, where it came from (--origin ui, mcp, token or background), the token and client of MCP and token requests, the agent, tokens, estimated cost, ClickHouse read and status. Prompt and response text are never stored.
chouse ai requests [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--days | int | 7 | window in days (capped at the server's retention) |
--limit | int | 50 | rows to return (1-200) |
--offset | int | 0 | rows to skip, for paging |
--origin | string | only requests started from ui, mcp, token or background | |
--search | string | match on user, agent, feature, client, token name or a table sent to the model |
chouse ai requests --origin mcp
chouse ai requests --search ci-agent --limit 20
chouse ai requests --days 30 -o jsonchouse ai usage
What CHouse's AI used and cost (tokens, est. cost, data sent).
CHouse's own AI (the chat and every AI feature) in the last --days: requests, tokens, estimated cost over priced models, ClickHouse read by AI tools and rows sent to LLM providers. --by origin splits it by who started the requests (the UI, MCP agents, access tokens, background); --by model shows usage per model. With ai_usage:view it covers everyone, otherwise only your own requests (the "scope" field says which).
chouse ai usage [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--by | string | origin or model | |
--days | int | 7 | window in days (capped at the server's retention) |
chouse ai usage --days 30
chouse ai usage --by origin
chouse ai usage --by model -o jsonchouse doctor
Chouse AI Doctor: fleet health reports.
Read past Doctor reports for free. A new scan calls the AI model (LLM cost) and stores a report, so it asks first (or needs --yes). Advisory only — it never changes data.
chouse doctorchouse doctor reports
chouse doctor get 7c1e…
chouse doctor scan --hours 24 --yeschouse doctor get
Show one report.
chouse doctor get <reportId>chouse doctor get 7c1e… -o yamlchouse doctor reports
List reports.
chouse doctor reportschouse doctor reportschouse doctor scan
Run a scan (LLM cost).
chouse doctor scan [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--connections | stringSlice | only these connection ids | |
--hours | int | 24 | look back 1-72 hours |
--model | string | AI model id (default: the server's) |
chouse doctor scan --hours 12 --yeschouse doctor schedule
Show the scan schedule.
chouse doctor schedulechouse doctor schedulechouse mcp
The MCP endpoint for AI agents: status, tools, client setup.
The server's MCP endpoint (ADR 0013, ADR 0017) is served at /mcp on the same address as the UI. An administrator turns it on and picks the tools in the UI (AI Governance › MCP); these commands show what your token gets there and print setup for agent hosts. They never change the server's MCP settings.
chouse mcpchouse mcp status
chouse mcp tools
chouse mcp config claude-code | shchouse mcp config
Print agent host setup for this server's MCP endpoint.
Print ready-to-use setup that points an agent host at this profile's server. The token is read from CH_HOUSE_PAT (VS Code prompts for it), so no secret is written into a config file. Output is the raw snippet (it bypasses -o): a shell command for claude-code/codex, JSON for the others.
chouse mcp config <claude-code|codex|cursor|vscode|opencode>chouse mcp config claude-code | sh
chouse mcp config cursor > .cursor/mcp.json
chouse mcp config vscode > .vscode/mcp.jsonchouse mcp settings
The server's MCP settings and every tool's state (agents:view).
Show what an administrator configured in AI Governance › MCP: whether the endpoint is on, allowed origins, the tool call timeout, and every tool with its access level, required permissions and whether it is on (-o yaml for everything). Changing them stays in the UI.
chouse mcp settingschouse mcp settings -o yamlchouse mcp status
Whether MCP is on, its endpoint, and how many tools your token gets.
Report whether an administrator turned the MCP endpoint on, the URL agents connect to (this server's address plus /mcp), and — when it is on and a token is configured — how many tools that token gets.
chouse mcp statuschouse mcp status
chouse mcp status -o jsonchouse mcp tools
The MCP tools your token gets.
List the tools an agent using your token sees: the ones an administrator turned on in AI Governance › MCP that your permissions allow.
chouse mcp toolschouse mcp tools
chouse mcp tools -o yaml