---
title: "Getting started with clickhousectl: the ClickHouse CLI for local and cloud"
description: "ClickHouse developers often face friction managing local versions, isolated instances, project scaffolding, and Cloud operations without relying on complex shell scripts. The open-source command-line tool clickhousectl addresses this by unifying local environment management and ClickHouse Cloud workflows. Locally, it downloads shared binaries, initializes standardized directory structures, and spins up named, isolated servers with automatic port assignments to facilitate upgrade testing. For cloud workflows, the CLI enforces a split authentication model where browser OAuth provides read-only access and API keys permit state mutations like service creation and scaling. Furthermore, the tool includes Claude Code agent skills covering best practices and deployment workflows, alongside support for CI/CD pipeline automation via environment variables and JSON output."
---

# Getting started with clickhousectl: the ClickHouse CLI for local and cloud

[Clickhouse](https://yomu.fyi/company/clickhouse) · Al Brown · Apr 16, 2026

**Type:** Tutorial

## Summary

ClickHouse developers often face friction managing local versions, isolated instances, project scaffolding, and Cloud operations without relying on complex shell scripts. The open-source command-line tool clickhousectl addresses this by unifying local environment management and ClickHouse Cloud workflows. Locally, it downloads shared binaries, initializes standardized directory structures, and spins up named, isolated servers with automatic port assignments to facilitate upgrade testing. For cloud workflows, the CLI enforces a split authentication model where browser OAuth provides read-only access and API keys permit state mutations like service creation and scaling. Furthermore, the tool includes Claude Code agent skills covering best practices and deployment workflows, alongside support for CI/CD pipeline automation via environment variables and JSON output.

## Context

ClickHouse users frequently require a clean local setup and a method to manage ClickHouse Cloud services from the terminal without relying on multiple custom shell scripts.

## Approach / What changed

The open-source CLI clickhousectl unifies local versioning, isolated server instances, directory scaffolding, and cloud management into a single tool featuring split OAuth/API-key authentication and coding agent skills.

## Takeaways

- Cloud authentication is split between read-only browser OAuth and API key authentication required for state-mutating actions such as creating or scaling services.
- clickhousectl supports running multiple isolated named local servers simultaneously across different ClickHouse versions with automatic port assignment for upgrade testing.
- The CLI includes Claude Code skills that install into .claude/skills/ to guide agents through best practices, local project setup, and cloud deployments.

**Tags:** [CI/CD](https://yomu.fyi/topic/ci-cd), [Data Pipelines](https://yomu.fyi/topic/data-pipelines), [Developer Experience](https://yomu.fyi/topic/developer-experience), [Open Source](https://yomu.fyi/topic/open-source), [Testing](https://yomu.fyi/topic/testing)

- Source: [Clickhouse](https://clickhouse.com/blog/getting-started-clickhousectl)
- Source URL: https://clickhouse.com/blog/getting-started-clickhousectl
- Ingested by Yomu: 2026-08-28T01:24:24.680Z

[Read original post](https://clickhouse.com/blog/getting-started-clickhousectl)