Infra Clickhouse Agent Skill

ClickHouse with clickhousectl

clickhousectl manages ClickHouse in two environments:

• Local — ClickHouse installed and running on the user's machine, for development.
• Cloud — managed ClickHouse Cloud services, for production: fully managed, automatic scaling, backups, and upgrades.

This file routes to the right reference. The step-by-step workflows live in ref/local.md and ref/cloud.md — read the one that matches the user's situation before running commands.

Which reference to use

| The user wants to... | Read |

|----------------------|------|

| Build an app with ClickHouse, develop or prototype locally, no cloud account needed | ref/local.md |

| Go to production, host a managed ClickHouse, or use ClickHouse Cloud explicitly | ref/cloud.md |

| Operate an existing cloud service (schemas, users, queries against it) | ref/cloud.md |

| Develop locally now, ship to production later | Start with ref/local.md; it points to ref/cloud.md when it's time to go to prod |

If it's genuinely ambiguous (e.g. "set up ClickHouse for my app"), default to local for development tasks and ask before creating anything in the cloud — cloud services cost money.

Prerequisites (both workflows)

Check that clickhousectl is installed:

which clickhousectl

If not found, install it:

curl -fsSL https://clickhouse.com/cli | sh

This installs to ~/.local/bin/clickhousectl (with a chctl alias). If the command is still not found, suggest export PATH="$HOME/.local/bin:$PATH" or a new terminal.

All commands accept --json for machine-readable output. Exit codes follow gh conventions: 0 success, 1 error, 2 cancelled, 4 auth required.

Related

• When designing schemas, consult the clickhouse-best-practices skill for ORDER BY selection, data types, and partitioning.
• For Postgres (local development or managed ClickHouse Cloud Postgres), use the infra-postgres skill.