CLI

chouse operates CHouse UI from the terminal, scripts and CI: query and explore, monitor the fleet, run the Doctor, manage scheduled work and data health, review fixes and agents. It authenticates with a personal access token, so it can do exactly what its owner can and nothing more. Output is a table in a terminal and JSON when piped; anything that changes data asks first (or needs --yes), and --dry-run previews where the server can.

For AI agents, use the MCP server instead; the CLI is for people, scripts and CI. Every command and flag is on the CLI command reference.

Install

curl -sSL https://github.com/daun-gatal/chouse-ui/releases/latest/download/install-cli.sh | bash
# pin a version (independent CLI line, tags cli-vX):
CHOUSE_VERSION=cli-v1.0.0 curl -sSL …/install-cli.sh | bash

The installer verifies sha256sum (or shasum on stock macOS), installs to /usr/local/bin (or ~/.chouse/bin fallback — a dedicated dir, predictable on Linux and macOS, never needs root), and wires the fallback into your PATH via your shell rc file (~/.bashrc+~/.profile, ~/.zshrc, or fish config.fish) — restart the shell or source the file afterwards. Opt out with CHOUSE_NO_MODIFY_PATH=1, override the destination with INSTALL_DIR.

Or download chouse-cli_<os>_<arch>.tar.gz (+.sig/.pem cosign signature) + checksums.txt from a cli-v* GitHub Release — cut only when cli/ changes, via cli-release.yml — verify (sha256sum -c checksums.txt), and put chouse on PATH. Shell completions: chouse completion bash|zsh|fish|powershell.

Requires Go 1.23+ to build from source (cd cli && go build ./cmd/chouse). CLI 1.0 targets servers 3.14.0 and later; chouse status reports the server version and whether this CLI supports it.

Log in

Mint one PAT in the UI (Preferences › Personal access tokens), then:

chouse auth login --server https://chouse.corp            # prompts for the token (hidden)
echo "$TOKEN" | chouse auth login --server https://chouse.corp --token-stdin   # CI
chouse auth status        # profile, server, connection, masked token
chouse auth whoami        # the token's user, roles and permissions
chouse auth logout

The token never needs to be an argument: login reads it from a hidden prompt, --token-stdin or CH_HOUSE_PAT. --token still works but warns, because arguments end up in shell history and the process list. Login remembers --server and --ca-cert for the profile.

Servers behind an internal CA: pass --ca-cert ca.pem (or set CHOUSE_CA_CERT). --insecure-skip-tls-verify (CHOUSE_INSECURE_SKIP_TLS_VERIFY=true) is for debugging only: it warns and is never remembered.

Profiles and settings

chouse config view                         # effective settings, token masked
chouse config set connection prod          # default connection (name or id)
chouse config set output json --profile ci
chouse config get server
chouse config unset connection
chouse config profiles                     # * marks the current one
chouse config use-profile staging
chouse config delete-profile old --yes

Settings resolve flag > environment > profile: --server/CHOUSE_SERVER, --token/CH_HOUSE_PAT (or the stored token), -c/CHOUSE_CONNECTION, -o/CHOUSE_OUTPUT, --ca-cert/CHOUSE_CA_CERT, --profile/CHOUSE_PROFILE. Profiles live in ~/.config/chouse/config.yaml; tokens in credentials.yaml (0600).

Everyday use

chouse status
chouse connection list
chouse table list -c prod                       # -c takes a connection name or id
chouse table schema analytics.events
chouse table sample analytics.events --limit 20
chouse query "SELECT name, engine FROM system.tables LIMIT 5"
chouse query -f report.sql --out report.csv     # format from the extension
chouse query "SELECT * FROM events LIMIT 1000" -o csv > events.csv
chouse query --explain plan "SELECT * FROM big WHERE day = today()"
chouse saved list && chouse saved run <id>
chouse metrics overview && chouse logs --limit 20
chouse live list
chouse fleet list && chouse doctor reports
chouse scheduled list && chouse health incidents
chouse alert rules && chouse audit list --limit 20

Performance, capacity and upgrades — read-only; assessments, replays and the collection schedule are changed in the UI:

chouse perf regressions -c prod              # query shapes slower than their own baseline
chouse perf shape <fingerprint> -c prod      # one shape's hourly history
chouse capacity -c prod --view growth        # also: forecasts (default), cold, trials
chouse upgrades list -c prod && chouse upgrades rollout
chouse upgrades get <assessmentId> -o yaml   # every rule and its evidence
chouse collectors status -c prod             # last run, last error, missing grants
chouse collectors schedule -c prod           # how often each collector runs, bytes read per day

Data observability:

chouse health dataset shop.orders            # trust state, freshness, open incidents
chouse lineage shop.orders --direction up    # sources, views, jobs, downstream
chouse lineage shop.orders --impact          # what a schema change would break
chouse incidents --all --limit 20            # data + pipeline incidents with root cause
chouse remediation list -c prod --status proposed
chouse remediation approve <actionId> --comment "reviewed" --yes
chouse context get shop.orders -c prod       # curated description, owner, grain, caveats
chouse context metrics gmv -c prod           # a defined business metric
chouse notebook show observe <incidentId>    # kinds: data-health, observe, doctor
chouse notebook export doctor <reportId> > postmortem.md

Approval rules are enforced server-side: a person may approve their own low-risk fix, high-risk fixes need two approvers other than the proposer, and a fix proposed by Chouse AI or an agent always needs someone else. The CLI never runs an action directly — the server runs it once approved (inside the maintenance window for window-only actions).

AI agents — read-only; an administrator changes MCP settings and agent policies in the UI:

chouse mcp status                     # on/off, endpoint (<server>/mcp), tools your token gets
chouse mcp tools                      # the tools an agent with your token sees
chouse mcp config claude-code | sh    # register this server with Claude Code
chouse mcp config cursor > .cursor/mcp.json   # also: codex, vscode, opencode
chouse mcp settings -o yaml           # AI Governance › MCP settings and every tool's state (agents:view)
chouse agents summary && chouse agents sessions --days 7
chouse agents session <sessionId>     # replay one session's tool calls
chouse agents policies

CHouse's own AI (AI activity, AI agents, AI guardrails) — read-only:

chouse ai usage --days 30 --by origin        # UI, MCP agents, tokens, background
chouse ai usage --by model
chouse ai egress --search customers          # tables and records sent to LLM providers
chouse ai requests --origin mcp --limit 20
chouse ai request <requestId> -o yaml        # every LLM and tool call
chouse ai agents                             # which agent each AI feature runs
chouse ai guardrails                         # what every AI run passes through
chouse ai guardrail-triggers --days 7        # matches: counts only, never the values

mcp config prints the raw snippet; every snippet reads the token from CH_HOUSE_PAT or a secret prompt, never inline.

Output

Tables show the useful columns of a list; JSON and YAML always carry every field, so scripts should use them. Query results keep ClickHouse's column order, and --out FILE writes them to a file (.csv, .json, .yaml). Notes such as row counts and confirmations go to stderr, so stdout pipes cleanly; -q silences them. audit export always writes CSV and mcp config a raw snippet.

Errors and exit codes

Errors print the server's request id, so an operator can find the request in the server logs, plus a hint where one helps. --debug traces every request on stderr — method, path, status, time and request id — and never prints the token.

Reads (GET) retry up to three times within --timeout on network errors, 429 and 502/503/504, honoring Retry-After, so a rolling restart does not fail a script. Writes are never retried.

Global flags

--server, --token, --profile, -c/--connection, -o/--output, --no-headers, --wide, -q/--quiet, --timeout (seconds, 1-600), --yes, --dry-run, --ca-cert, --insecure-skip-tls-verify, --debug. Details on the command reference.

Safety

Reads never prompt. Anything that changes data, sends notifications or spends LLM budget asks for a typed yes on a terminal and needs --yes without one — it fails closed otherwise, before any request is sent:

chouse live kill <queryId> --yes
chouse query --raw --dry-run "ALTER TABLE t DELETE WHERE day < today() - 30"   # estimate only
chouse query --raw --yes "ALTER TABLE t DELETE WHERE day < today() - 30"
chouse scheduled run <id> --yes
chouse remediation reject <actionId> --yes
chouse ai optimize -f slow.sql --yes

query runs SELECT/WITH/SHOW/DESCRIBE/EXPLAIN directly; anything else needs --raw. Every change prints an action=… target=… permission=… line on stderr. Break-glass administration — creating or deleting connections, SSO, AI provider keys, users and roles, data-access policies, MCP settings, agent policies, audit pruning, importing files — stays in the UI.

AI write tools

chouse action runs the same write tools the chat and MCP agents use, checked the same way by tier. Your token's write policy decides which you get.

chouse action tools                                   # what your token may run, and how each is checked
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 run create_dashboard --args '{"title":"Ingest","panels":[]}'
chouse action status <id>                             # status, result, whether it can be undone
chouse action undo <id> --yes                         # within 24 hours, unless it changed since
chouse action activity --limit 20                     # what AI agents changed for you

Arguments are key=value (values that parse as JSON are JSON) or one --args object. 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, and the command prints the action id to check.

Upgrading from 0.x

CLI 1.0 changes some commands and the default output:

• Output in a terminal is now a table; piped output is still JSON. CHOUSE_OUTPUT=json (or chouse config set output json) restores JSON everywhere.
• chouse table schema|sample also accept db.table (db table still works), and chouse table list [database] lists one row per table.
• chouse logs queries|patterns|tables|histogram became chouse logs (the four views were the same request).
• chouse saved create takes the SQL as arguments, -f FILE or --stdin instead of --query; chouse upload preview takes the file as an argument; chouse fleet query <metric> uses -c.
• Removed: auth login --pat (use the prompt or --token-stdin), connection create|delete|use, table create|drop, upload into, and logs subviews — commands that only pointed at the UI or repeated another.
• Field names in JSON are the server's (dryRun, not dry_run).