What's new in clickhousectl v0.3.0

clickhousectl is the CLI for ClickHouse, local and cloud, built to help both humans and AI agents develop with ClickHouse.

v0.2.0 brought managed Postgres, ClickPipes for eight data sources, and SQL-over-HTTP. v0.3.0 brings a raft of improvements for the agentic experience, more ways to install, OAuth support for Query Endpoints, and custom configs.

If you already have it installed, update in place:

1clickhousectl update

If not, install it using your favorite method below:

1curl https://clickhouse.com/cli | sh
2pip install clickhousectl
3uv tool install clickhousectl
4npm i -g clickhousectl
5cargo install clickhousectl

A global clickhouse on your PATH #

When you select a default ClickHouse version with clickhousectl local use latest, this now puts ClickHouse on your path at ~/.local/bin/clickhouse. It's similar to doing ./clickhouse install with the binary itself, but allows you to manage the version globally with clickhousectl. This means you can shell directly to the clickhouse binary to use its myriad of subcommands (local, benchmark, format, etc,.)

Improving the agent experience #

Structured output by default for agents #

In v0.3.0, clickhousectl can detect when it's running inside various coding agents, and optimise its behavior automatically. For example, it will now default to JSON output on stdout when running inside an agent.

This detection depends on agents self-declaring via non-sensitive environment variables (AGENT, AI_AGENT and some agent-specific variables that have not standardised yet).

Meaningful error codes #

Alongside this, exit codes now follow gh conventions, so agents and scripts can branch on why a command failed.

.env support for Cloud credentials #

clickhousectl now reads a .env file in your working directory for CLICKHOUSE_ environment variables. Add your Cloud API credentials in there and any cloud command will pick them up:

1CLICKHOUSE_CLOUD_API_KEY=your-key
2CLICKHOUSE_CLOUD_API_SECRET=your-secret

Query ClickHouse Cloud services with OAuth #

cloud service query runs SQL against a Cloud service over HTTP. Previously, it only supported using API keys for auth and required provisioning a Query Endpoint. v0.3.0 adds support for querying services with OAuth. When using OAuth, you do not need to first provision a Query Endpoint.

1clickhousectl cloud auth login
2clickhousectl cloud service query --name my-service --query "SELECT 1"

Querying an idled service wakes it automatically. A stopped service is never woken and fails with a hint to run clickhousectl cloud service start.

Custom config files for local servers #

Local servers start with sensible defaults, but sometimes you need to flip a setting. v0.3.0 lets you drop a config into ~/.clickhouse/configs/ and apply it by name:

1mkdir -p ~/.clickhouse/configs
2cat > ~/.clickhouse/configs/analytics.xml <<'EOF'
3<clickhouse>
4    <query_log>
5        <database>system</database>
6        <table>query_log</table>
7    </query_log>
8</clickhouse>
9EOF
10
11# See which configs are available
12clickhousectl local server configs
13
14# Start a server with one applied
15clickhousectl local server start --config-file analytics

The named file is overlaid on top of ClickHouse's built-in defaults, so it only needs to contain the settings you want to change, no need to reproduce a full config. Files can be .xml, .yaml, or .yml, and you can reference them by name with or without the extension.

More install options #

clickhousectl already ships via the install script, cargo binstall, npm, and crates.io. v0.3.0 adds the Python packaging ecosystem:

1pip install clickhousectl
2# or
3pipx install clickhousectl
4# or
5uv tool install clickhousectl

Postgres in local init #

local init scaffolds a standard folder structure for your ClickHouse project files. With managed and local Postgres now part of clickhousectl, init also lays down a postgres/ tree alongside the clickhouse/ one:

1clickhousectl local init

1clickhouse/
2├── tables/
3├── materialized_views/
4├── queries/
5└── seed/
6postgres/
7├── tables/
8├── views/
9├── functions/
10├── queries/
11└── seed/

Faster, offline-friendly version resolution #

When you ask for a version spec like stable or 26.5, clickhousectl now checks your already-installed versions before reaching out to the network. If you've got a match locally, commands like clickhousectl local use 26.5 resolve instantly and work offline, only falling back to a remote lookup when there's nothing suitable installed.

Deprecated fields removed #

Deprecated API fields are now hidden from CLI output to prevent confusing agents.