A lightweight ClickHouse CLI built on Bun.
npm install -g @obsessiondb/chcli
Provide a query inline, from a file, or piped via stdin:
chcli -q "SELECT 1" chcli -f query.sql echo "SELECT 1" | chcli
Connection can be configured via CLI flags or environment variables. Flags take precedence.
| Flag | Env var | Default |
|---|---|---|
--host <host> |
CLICKHOUSE_HOST |
localhost |
--port <port> |
CLICKHOUSE_PORT |
8123 |
-u, --user <user> |
CLICKHOUSE_USER |
default |
--password <pass> |
CLICKHOUSE_PASSWORD |
(empty) |
-d, --database <db> |
CLICKHOUSE_DATABASE |
default |
-s, --secure |
CLICKHOUSE_SECURE |
false |
# Local instance with defaults chcli -q "SHOW DATABASES" # Remote instance chcli --host ch.example.com --port 8443 --secure \ -u admin --password secret \ -d analytics -q "SELECT count() FROM events"
Or set your connection in a .env file (Bun loads it automatically):
CLICKHOUSE_HOST=ch.example.com CLICKHOUSE_PORT=8443 CLICKHOUSE_SECURE=true CLICKHOUSE_USER=admin CLICKHOUSE_PASSWORD=secret CLICKHOUSE_DATABASE=analytics
| Flag | Description |
|---|---|
-F, --format <fmt> |
Output format (see table below) |
-t, --time |
Print execution time to stderr |
-v, --verbose |
Print query metadata to stderr |
Default format is pretty in a terminal, tsv when piping.
| Alias | ClickHouse format |
|---|---|
json |
JSON |
jsonl / ndjson |
JSONEachRow |
csv |
CSVWithNames |
tsv |
TabSeparatedWithNames |
pretty |
PrettyCompactMonoBlock |
vertical |
Vertical |
markdown |
Markdown |
sql |
SQLInsert |
Any native ClickHouse format name is also accepted directly.
chcli -q "SELECT * FROM events LIMIT 5" -F json chcli -q "SHOW TABLES" -F csv > tables.csv
chcli ships as an Agent Skill so AI coding agents (Claude Code, Cursor, etc.) can query your ClickHouse databases directly.
npx skills add obsessiondb/chcli
Once installed, your agent can run SQL queries, explore schemas, and extract data using chcli — no manual copy-pasting required.
Sponsored by obsessiondb.com