clickhousectl - ClickHouse Documentation

clickhousectl é a CLI do ClickHouse: local e na nuvem. Com o clickhousectl, você pode:

Instalar e gerenciar versões locais do ClickHouse
Iniciar e gerenciar servidores locais do ClickHouse
Executar e gerenciar instâncias locais do Postgres
Executar consultas em servidores do ClickHouse
Configurar o ClickHouse Cloud e criar clusters do ClickHouse gerenciados na nuvem
Criar e gerenciar serviços Postgres no ClickHouse Cloud
Gerenciar recursos do ClickHouse Cloud
Criar e gerenciar ClickPipes para ingestão de dados (S3, Kafka, Kinesis, Postgres, MySQL, MongoDB, BigQuery)
Instalar as ClickHouse Agent Skills oficiais de agent do ClickHouse em agentes de codificação compatíveis
Enviar seu ambiente local de desenvolvimento com ClickHouse para a nuvem

O clickhousectl ajuda pessoas e agentes de IA a desenvolver com ClickHouse.

Instalação

Instalação rápida

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

O script de instalação baixa a versão correta para o seu sistema operacional e a instala em ~/.local/bin/clickhousectl. Um alias chctl também é criado automaticamente para facilitar.

Requisitos

macOS (aarch64, x86_64) ou Linux (aarch64, x86_64)
Os comandos do Cloud exigem uma API key do ClickHouse Cloud

Local

Instalando e gerenciando versões do ClickHouse

clickhousectl baixa os binários do ClickHouse de builds.clickhouse.com e usa packages.clickhouse.com (Linux) ou os lançamentos do GitHub (macOS) como alternativa quando uma compilação não está disponível lá.

# Install a version
clickhousectl local install latest          # Latest release (recommended)
clickhousectl local install 26.5            # Latest 26.5.x.x
clickhousectl local install 26.5.2.39       # Exact version

# List versions
clickhousectl local list                    # Installed versions
clickhousectl local list --remote           # Available for download

# Manage default version
clickhousectl local use latest              # Latest release (installs if needed, recommended)
clickhousectl local use 26.5                # Latest 26.5.x.x (installs if needed)
clickhousectl local use 26.5.2.39           # Exact version
clickhousectl local use latest --no-global  # Set default but don't touch ~/.local/bin/clickhouse
clickhousectl local which                   # Show current default

# Remove a version
clickhousectl local remove 26.5.2.39

local use também cria um link simbólico em ~/.local/bin/clickhouse apontando para o binário da versão selecionada, para que o comando clickhouse simples (por exemplo, clickhouse local, clickhouse client) fique no PATH. Passe --no-global para ignorar isso. Se já existir um arquivo comum nesse caminho, ele será mantido como está, com um aviso. O local remove da versão padrão ativa também remove o link simbólico.

Armazenamento dos binários do ClickHouse

Os binários do ClickHouse ficam armazenados em um repositório global, para que possam ser usados por vários projetos sem duplicar o armazenamento. Os binários são armazenados em ~/.clickhouse/:

~/.clickhouse/
├── versions/
│   └── 26.5.2.39/
│       └── clickhouse
└── default              # tracks the active version

Iniciando um projeto

clickhousectl local init

init prepara seu diretório de trabalho atual com uma estrutura de pastas padrão para os arquivos do seu projeto ClickHouse e Postgres. É opcional; se preferir, você pode usar sua própria estrutura de pastas. Ele cria a seguinte estrutura:

clickhouse/
├── tables/                 # Table definitions (CREATE TABLE ...)
├── materialized_views/     # Materialized view definitions
├── queries/                # Saved queries
└── seed/                   # Seed data / INSERT statements

postgres/
├── tables/                 # Table definitions (CREATE TABLE ...)
├── views/                  # View definitions
├── functions/              # Function definitions
├── queries/                # Saved queries
└── seed/                   # Seed data / INSERT statements

Executar consultas

# Conectar a um servidor em execução com clickhouse-client
clickhousectl local client                           # Conecta ao servidor "default"
clickhousectl local client --name dev                # Conecta ao servidor "dev"
clickhousectl local client --query "SHOW DATABASES"  # Executa uma consulta
clickhousectl local client --queries-file schema.sql # Executa consultas a partir de um arquivo
clickhousectl local client --host remote-host --port 9000  # Conecta a um host/porta específicos

Como criar e gerenciar servidores ClickHouse

Inicie e gerencie instâncias do servidor ClickHouse. Cada servidor recebe seu próprio diretório de dados isolado em .clickhouse/servers/<name>/data/.

# Start a server (runs in background by default)
clickhousectl local server start                          # Named "default"
clickhousectl local server start --name dev               # Named "dev"
clickhousectl local server start --version stable         # Use a specific version (installs if needed, doesn't change default)
clickhousectl local server start --foreground             # Run in foreground (-F / --fg)
clickhousectl local server start --http-port 8124 --tcp-port 9001  # Explicit ports
clickhousectl local server start --config-file querylog          # Apply a named custom config

# List all servers (running and stopped)
clickhousectl local server list
clickhousectl local server list --global                  # List servers across all projects

# Stop servers
clickhousectl local server stop default                   # Stop by name
clickhousectl local server stop default --global          # Stop from any project
clickhousectl local server stop-all                       # Stop all running servers

# Remove a stopped server and its data
clickhousectl local server remove test

# Write connection env vars to a .env file
clickhousectl local server dotenv                         # From "default" server → .env
clickhousectl local server dotenv --name dev              # From "dev" server → .env
clickhousectl local server dotenv --local                 # Write to .env.local instead

Nomeação do servidor: Sem --name, o primeiro servidor recebe o nome “default”. Se “default” já estiver em execução, um nome aleatório será gerado (por exemplo, “bold-crane”). Use --name para ter identidades estáveis que possam ser iniciadas e interrompidas repetidamente. Portas: As portas padrão são HTTP 8123 e TCP 9000. Se essas portas já estiverem em uso, portas livres serão atribuídas automaticamente e exibidas na saída. Use --http-port e --tcp-port para definir portas específicas. Gerenciamento global de servidores: Use --global com list, stop e stop-all para operar em todos os projetos do sistema. server list --global mostra todos os servidores ClickHouse em execução, com uma coluna Project indicando a qual diretório cada um pertence.

Arquivos de configuração personalizados para servidores locais

Os servidores locais são iniciados com padrões adequados, mas às vezes é necessário ajustar uma configuração. Coloque um arquivo de configuração em ~/.clickhouse/configs/ e aplique-o pelo nome ao iniciar um servidor:

mkdir -p ~/.clickhouse/configs
cat > ~/.clickhouse/configs/querylog.yaml <<'EOF'
query_log:
    database: system
    table: query_log
EOF

# See which configs are available
clickhousectl local server configs

# Start a server with one applied
clickhousectl local server start --config-file querylog

O arquivo especificado é aplicado sobre as configurações padrão internas do ClickHouse (via config.d), portanto ele só precisa conter as configurações que você deseja alterar, e não há necessidade de reproduzir uma configuração completa. Os arquivos podem ser .xml, .yaml ou .yml, e você pode referenciá-los pelo nome com ou sem a extensão.

Diretório local de dados do projeto

Todos os dados do servidor ficam em .clickhouse/, no diretório do seu projeto:

.clickhouse/
├── .gitignore              # auto-created, ignores everything
├── credentials.json        # cloud API credentials (if configured)
└── servers/
    ├── default/
    │   └── data/           # ClickHouse data files for "default" server
    └── dev/
        └── data/           # ClickHouse data files for "dev" server

Cada servidor nomeado tem seu próprio diretório de dados, portanto os servidores ficam totalmente isolados entre si. Os dados persistem entre reinicializações. Pare e inicie um servidor pelo nome para continuar de onde parou. Use clickhousectl local server remove <name> para excluir permanentemente os dados de um servidor.

Executando o Postgres local

Além do ClickHouse, o clickhousectl pode executar e gerenciar instâncias locais do Postgres. O Postgres local usa o Docker como base, portanto o Docker deve estar instalado e em execução. Cada instância é identificada pelo nome e pela versão principal, então várias versões do Postgres podem ser executadas lado a lado, com diretórios de dados separados.

# Optionally pre-pull a Postgres image (supports 17, 18 and tags like 18-alpine)
clickhousectl local install postgres@18

# Start an instance (defaults to postgres:18 on port 5432)
clickhousectl local postgres start
clickhousectl local postgres start --name dev --version 17 --port 5433
clickhousectl local postgres start --user app --password s3cret --database myapp
clickhousectl local postgres start -e POSTGRES_INITDB_ARGS=--data-checksums

# Connect with psql
clickhousectl local postgres client --name dev
clickhousectl local postgres client --name dev --query "SELECT 1"

# Export connection variables to a .env file
clickhousectl local postgres dotenv --name dev

# Stop (preserves data) and remove (deletes data)
clickhousectl local postgres stop dev
clickhousectl local postgres remove dev

Autenticação

Faça a autenticação no ClickHouse Cloud usando API keys (recomendado) ou OAuth (no navegador). Se você ainda não tem uma conta no ClickHouse Cloud, clickhousectl cloud auth signup abre a página de cadastro no seu navegador.

API key/segredo da API (recomendado)

As API keys são a forma recomendada de autenticação, especialmente ao usar a CLI com um agente de IA. Você pode criar API keys com escopo que concedem apenas as permissões que você escolher (read-only ou leitura/gravação), e cada key está vinculada a uma única organização. Isso torna essa uma forma segura, com privilégio mínimo, de dar acesso à CLI.

# Non-interactive (CI-friendly)
clickhousectl cloud auth login --api-key YOUR_KEY --api-secret YOUR_SECRET

# Interactive prompt
clickhousectl cloud auth login --interactive

As credenciais são salvas em .clickhouse/credentials.json (local do projeto). Você também pode usar variáveis de ambiente, exportadas na sua sessão:

export CLICKHOUSE_CLOUD_API_KEY=your-key
export CLICKHOUSE_CLOUD_API_SECRET=your-secret

Ou colocadas em um arquivo .env no diretório de trabalho atual:

CLICKHOUSE_CLOUD_API_KEY=your-key
CLICKHOUSE_CLOUD_API_SECRET=your-secret

Ou passe as credenciais diretamente por meio de flags em qualquer comando:

clickhousectl cloud --api-key KEY --api-secret SECRET ...

clickhousectl cloud auth login

Isso abre seu navegador para autenticação pelo fluxo de dispositivo do OAuth. Os tokens são salvos em .clickhouse/tokens.json (local ao projeto).

No momento, o acesso OAuth é somente leitura e concede acesso a todas as organizações às quais você pertence. Para acesso de gravação ou para limitar a CLI a uma única organização, crie uma API key com escopo.

Status da autenticação e logout

clickhousectl cloud auth status    # Show current auth state
clickhousectl cloud auth logout    # Clear all saved credentials (credentials.json & tokens.json)

Ordem de resolução de credenciais: flags da CLI > .clickhouse/credentials.json > variáveis de ambiente exportadas > arquivo .env > tokens OAuth.

Como depurar qual fonte de credenciais foi usada

Passe --debug em qualquer comando cloud para exibir em stderr a fonte de credenciais determinada (e a URL da API) antes da execução do comando.

clickhousectl cloud --debug service list
# [debug] auth source: credentials file (.clickhouse/credentials.json)
# [debug] api url: https://api.clickhouse.cloud/v1
# ... normal output ...

Cloud

Gerencie os serviços do ClickHouse Cloud pela API.

Organizações

clickhousectl cloud org list              # Listar organizações
clickhousectl cloud org get <org-id>      # Obter detalhes da organização
clickhousectl cloud org update <org-id> --name "Renamed Org"
clickhousectl cloud org update <org-id> \
  --remove-private-endpoint pe-1,cloud-provider=aws,region=us-east-1 \
  --enable-core-dumps false
clickhousectl cloud org prometheus <org-id> --filtered-metrics true
clickhousectl cloud org usage <org-id> \
  --from-date 2024-01-01 \
  --to-date 2024-01-31

Serviços

# List services
clickhousectl cloud service list

# Get service details
clickhousectl cloud service get <service-id>

# Create a service (minimal)
clickhousectl cloud service create --name my-service

# Create with scaling options
clickhousectl cloud service create --name my-service \
  --provider aws \
  --region us-east-1 \
  --min-replica-memory-gb 8 \
  --max-replica-memory-gb 32 \
  --num-replicas 2

# Create with specific IP allowlist
clickhousectl cloud service create --name my-service \
  --ip-allow 10.0.0.0/8 \
  --ip-allow 192.168.1.0/24

# Create from backup
clickhousectl cloud service create --name restored-service --backup-id <backup-uuid>

# Create with release channel
clickhousectl cloud service create --name my-service --release-channel fast

# Create with GA request-only extras
clickhousectl cloud service create --name my-service \
  --tag env=prod \
  --enable-endpoint mysql \
  --private-preview-terms-checked \
  --enable-core-dumps true

# Start/stop a service
clickhousectl cloud service start <service-id>
clickhousectl cloud service stop <service-id>

# Run SQL over HTTP via the Query API (no local clickhouse binary needed)
clickhousectl cloud service query --name my-service --query "SELECT 1"
clickhousectl cloud service query --id <service-id> --query "SELECT count() FROM system.tables" --format JSONEachRow
clickhousectl cloud service query --name my-service --queries-file schema.sql   # "-" reads from stdin
clickhousectl cloud service query --name my-service --database mydb --query "SHOW TABLES"
echo "SELECT 1+1" | clickhousectl cloud service query --name my-service

# Update service metadata and patches
clickhousectl cloud service update <service-id> \
  --name my-renamed-service \
  --add-ip-allow 10.0.0.0/8 \
  --remove-ip-allow 0.0.0.0/0 \
  --add-private-endpoint-id pe-1 \
  --release-channel fast \
  --enable-endpoint mysql \
  --add-tag env=staging \
  --transparent-data-encryption-key-id tde-key-1 \
  --enable-core-dumps false

# Update replica scaling
clickhousectl cloud service scale <service-id> \
  --min-replica-memory-gb 24 \
  --max-replica-memory-gb 48 \
  --num-replicas 3 \
  --idle-scaling true \
  --idle-timeout-minutes 10

# Reset password with generated credentials
clickhousectl cloud service reset-password <service-id>

# Delete a service (must be stopped first)
clickhousectl cloud service delete <service-id>

# Force delete: stops a running service then deletes
clickhousectl cloud service delete <service-id> --force

Opções de criação do serviço

Option	Description
`--name`	Nome do serviço (obrigatório)
`--provider`	provedor de Cloud: `aws`, `gcp`, `azure` (padrão: `aws`)
`--region`	Região (padrão: `us-east-1`)
`--min-replica-memory-gb`	Memória mínima por réplica em GB (8-356, múltiplo de 4)
`--max-replica-memory-gb`	Memória máxima por réplica em GB (8-356, múltiplo de 4)
`--num-replicas`	Número de réplicas (1-20)
`--idle-scaling`	Permitir redução para zero (padrão: `true`)
`--idle-timeout-minutes`	Tempo mínimo de inatividade em minutos (>= 5)
`--ip-allow`	CIDR de IP a permitir (repetível, padrão: `0.0.0.0/0`)
`--backup-id`	ID do backup a partir do qual restaurar
`--release-channel`	Canal de lançamento: `slow`, `default`, `fast`
`--data-warehouse-id`	ID do data warehouse (para réplicas de leitura)
`--readonly`	Tornar o serviço somente leitura
`--encryption-key`	Chave de criptografia de disco do cliente
`--encryption-role`	ARN da role para criptografia de disco
`--enable-tde`	Ativar Transparent Data Encryption
`--compliance-type`	Conformidade: `hipaa`, `pci`
`--profile`	Perfil da instância (Enterprise)
`--tag`	Adicionar uma tag de serviço GA (`key` ou `key=value`)
`--enable-endpoint` / `--disable-endpoint`	Ativar ou desativar endpoints GA do serviço (atualmente `mysql`)
`--private-preview-terms-checked`	Aceitar os termos de private preview quando necessário
`--enable-core-dumps`	Ativar ou desativar a coleta de core dumps do serviço

Modos de autenticação da Query API

cloud service query é a maneira padrão de executar SQL em um serviço na nuvem via HTTP, sem exigir o binário clickhouse nem a senha do serviço. Ele funciona com ambos os modos de credenciais:

Autenticação por API key (leitura + escrita de SQL): na primeira vez que cloud service query é executado em um serviço sem uma chave armazenada, ele provisiona um endpoint da Query API para esse serviço e cria uma API key dedicada vinculada a ele. A chave (keyId, keySecret e endpointId) é armazenada em .clickhouse/credentials.json, em service_query_keys.<service-id>. A chave fica restrita a um único serviço, portanto pode ler e escrever (SELECT, INSERT, DDL) nesse serviço, mas não pode acessar nenhum outro serviço na org. Passe --no-auto-enable para falhar em vez de provisionar.
OAuth (cloud auth login): a consulta é executada com a sua própria identidade, assim como no console SQL da web. Suas permissões de SQL no serviço são somente leitura ao usar OAuth. Nenhuma API key da Query API é provisionada nem armazenada. --no-auto-enable não tem efeito nesse modo.

Consultar um serviço inativo o reativa automaticamente em ambos os modos de autenticação (a primeira consulta pode levar um minuto). Um serviço parado nunca é reativado: a consulta falha com uma dica para executar cloud service start. Defina CLICKHOUSE_CLOUD_QUERY_HOST para substituir o host derivado da Query API.

Gerenciamento de endpoints de consulta

clickhousectl cloud service query-endpoint get <service-id>
clickhousectl cloud service query-endpoint create <service-id> \
  --role admin \
  --open-api-key key-1 \
  --allowed-origins https://app.example.com
clickhousectl cloud service query-endpoint delete <service-id>

Gerenciamento de Private Endpoint

clickhousectl cloud service private-endpoint create <service-id> --endpoint-id vpce-123
clickhousectl cloud service private-endpoint get-config <service-id>

Configuração do Backup

clickhousectl cloud service backup-config get <service-id>
clickhousectl cloud service backup-config update <service-id> \
  --backup-period-hours 24 \
  --backup-retention-period-hours 720 \
  --backup-start-time 02:00

Serviços Postgres

clickhousectl também pode criar e gerenciar serviços ClickHouse Cloud Postgres, seguindo o mesmo padrão dos comandos de serviço do ClickHouse acima. O GCP está em private preview; passe --provider gcp com uma região e um tamanho de instância do GCP.

# List and inspect
clickhousectl cloud postgres list
clickhousectl cloud postgres list --filter state=running
clickhousectl cloud postgres get <pg-id>

# Create a service on AWS (the default provider)
clickhousectl cloud postgres create \
  --name my-pg \
  --region us-east-1 \
  --size m7i.2xlarge \
  --pg-version 17 \
  --ha-type sync

# Create a service on GCP (private preview); region and size use GCP names
clickhousectl cloud postgres create \
  --name my-pg \
  --provider gcp \
  --region us-central1 \
  --size c4-standard-4 \
  --pg-version 18

# Update and delete
clickhousectl cloud postgres update <pg-id> --size m7i.4xlarge
clickhousectl cloud postgres update <pg-id> --add-tag env=prod --remove-tag legacy
clickhousectl cloud postgres delete <pg-id>

# Connection certificates
clickhousectl cloud postgres certs get <pg-id>                   # raw PEM to stdout
clickhousectl cloud postgres certs get <pg-id> --output ca.pem   # write to a file

# Configuration
clickhousectl cloud postgres config get <pg-id>
clickhousectl cloud postgres config replace <pg-id> --file cfg.json
clickhousectl cloud postgres config patch <pg-id> --set max_connections=500

# Reset the password
clickhousectl cloud postgres reset-password <pg-id> --generate

# Lifecycle: restart and high-availability promotion/switchover
clickhousectl cloud postgres restart <pg-id>
clickhousectl cloud postgres promote <pg-id>
clickhousectl cloud postgres switchover <pg-id>

# Réplicas de leitura and point-in-time restore
clickhousectl cloud postgres read-replica create <pg-id> --name replica-1
clickhousectl cloud postgres restore <pg-id> --name restored --restore-target 2026-04-16T12:00:00Z

Opções de criação do serviço Postgres

Opção	Descrição
`--name`	Nome do serviço (obrigatório)
`--region`	Região, por exemplo `us-east-1` na AWS ou `us-central1` no GCP (obrigatório)
`--size`	Tamanho da instância, por exemplo `m7i.2xlarge` na AWS ou `c4-standard-4` no GCP (obrigatório)
`--provider`	provedor de Cloud: `aws`, `gcp` (padrão: `aws`)
`--pg-version`	Versão principal: `18`, `17`
`--ha-type`	Alta disponibilidade: `none`, `async`, `sync`
`--tag`	Tag de recurso `key` ou `key=value` (repetível)
`--pg-config-file`	Caminho para um arquivo JSON com um objeto `PgConfig`
`--pg-bouncer-config-file`	Caminho para um arquivo JSON com um objeto `PgBouncerConfig`

Backups

clickhousectl cloud backup list <service-id>
clickhousectl cloud backup get <service-id> <backup-id>

ClickPipes

Gerencie ClickPipes para ingestão de dados no ClickHouse Cloud a partir de fontes externas.

# List ClickPipes for a service
clickhousectl cloud clickpipe list <service-id>

# Get ClickPipe details
clickhousectl cloud clickpipe get <service-id> <clickpipe-id>

# Start/stop/resync a ClickPipe
clickhousectl cloud clickpipe start <service-id> <clickpipe-id>
clickhousectl cloud clickpipe stop <service-id> <clickpipe-id>
clickhousectl cloud clickpipe resync <service-id> <clickpipe-id>   # CDC pipes only

# Delete a ClickPipe
clickhousectl cloud clickpipe delete <service-id> <clickpipe-id>

# Update scaling
clickhousectl cloud clickpipe scale <service-id> <clickpipe-id> \
  --replicas 2 --cpu-millicores 250 --memory-gb 1

# Get/update settings
clickhousectl cloud clickpipe settings get <service-id> <clickpipe-id>
clickhousectl cloud clickpipe settings update <service-id> <clickpipe-id> \
  --streaming-max-insert-wait-ms 10000

Criando ClickPipes

Cada tipo de origem tem seu próprio subcomando no clickpipe create:

# From S3 / object storage
clickhousectl cloud clickpipe create object-storage <service-id> \
  --name my-s3-pipe \
  --source-url 'https://bucket.s3.us-east-1.amazonaws.com/data/**' \
  --format JSONEachRow \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From Google Cloud Storage (object storage)
clickhousectl cloud clickpipe create object-storage <service-id> \
  --name my-gcs-pipe \
  --storage-type gcs \
  --source-url 'https://storage.googleapis.com/bucket/data/**' \
  --format JSONEachRow \
  --service-account-file ./sa-key.json \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From Kafka / Redpanda / Confluent / MSK
clickhousectl cloud clickpipe create kafka <service-id> \
  --name my-kafka-pipe \
  --brokers 'broker:9092' --topics events \
  --format JSONEachRow \
  --kafka-type redpanda \
  --auth SCRAM-SHA-256 --username user --password pass \
  --ca-certificate ./ca.crt \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From Amazon Kinesis
clickhousectl cloud clickpipe create kinesis <service-id> \
  --name my-kinesis-pipe \
  --stream-name events --region us-east-1 \
  --format JSONEachRow \
  --auth IAM_USER --access-key-id AKIA... --secret-key ... \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From PostgreSQL (CDC)
clickhousectl cloud clickpipe create postgres <service-id> \
  --name my-pg-pipe \
  --host db.example.com --pg-database mydb \
  --username pguser --password pgpass \
  --table-mapping "public.users:public_users" \
  --table-mapping "public.orders:public_orders"

# From MySQL (CDC)
clickhousectl cloud clickpipe create mysql <service-id> \
  --name my-mysql-pipe \
  --host mysql.example.com \
  --username root --password pass \
  --table-mapping "mydb.users:mydb_users"

# From MongoDB (CDC)
clickhousectl cloud clickpipe create mongodb <service-id> \
  --name my-mongo-pipe \
  --uri 'mongodb+srv://cluster.example.net/mydb' \
  --username mongouser --password mongopass \
  --table-mapping "mydb.users:mydb_users"

# From BigQuery (snapshot)
clickhousectl cloud clickpipe create bigquery <service-id> \
  --name my-bq-pipe \
  --service-account-file ./sa-key.json \
  --staging-path gs://bucket/staging \
  --table-mapping "dataset.table:target_table"

Use clickhousectl cloud clickpipe create <source> --help para ver a lista completa de opções para cada tipo de origem.

Membros

clickhousectl cloud member list
clickhousectl cloud member get <user-id>
clickhousectl cloud member update <user-id> --role-id <role-id>
clickhousectl cloud member remove <user-id>

Convites

clickhousectl cloud invitation list
clickhousectl cloud invitation create --email dev@example.com --role-id <role-id>
clickhousectl cloud invitation get <invitation-id>
clickhousectl cloud invitation delete <invitation-id>

Chaves

clickhousectl cloud key list
clickhousectl cloud key get <key-id>
clickhousectl cloud key create --name ci-key --role-id <role-id> --ip-allow 10.0.0.0/8
clickhousectl cloud key update <key-id> \
  --name renamed-key \
  --expires-at 2025-12-31T00:00:00Z \
  --state disabled \
  --ip-allow 0.0.0.0/0
clickhousectl cloud key delete <key-id>

Atividade

clickhousectl cloud activity list --from-date 2024-01-01 --to-date 2024-12-31
clickhousectl cloud activity get <activity-id>

Saída em JSON

Use a flag --json para imprimir respostas no formato JSON.

clickhousectl cloud --json service list
clickhousectl cloud --json service get <service-id>

clickhousectl detecta automaticamente contextos de agentes de codificação (Claude Code, Cursor, Codex, Gemini CLI, Goose, Devin e qualquer ferramenta que defina a variável de ambiente padrão AGENT) e envia JSON para stdout automaticamente, sem definir --json.

Códigos de saída

Os códigos de saída seguem as convenções da CLI gh:

Código	Significado
`0`	Sucesso
`1`	Erro (qualquer item não classificado abaixo)
`2`	Cancelado (interrompido pelo usuário)
`4`	Autenticação necessária (sem credenciais, 401/403, gravações apenas via OAuth)

Skills

Instale o pacote oficial ClickHouse Agent Skills em ClickHouse/agent-skills.

# Padrão: modo interativo para humanos, escolha o escopo e depois os agentes
clickhousectl skills

# Não interativo: instala em todas as pastas de agentes locais do projeto suportadas
clickhousectl skills --all

# Não interativo: instala apenas nos agentes detectados
clickhousectl skills --detected-only

# Não interativo: instala em todas as pastas de agentes globais suportadas
clickhousectl skills --global --all

# Não interativo: instala em agentes locais do projeto específicos
clickhousectl skills --agent claude --agent codex

Flags não interativas

Flag	Descrição
`--agent <name>`	Instala Skills para um agente específico (pode ser repetido)
`--global`	Usa o escopo global; se omitido, o escopo do projeto é usado
`--all`	Instala Skills para todos os agentes compatíveis
`--detected-only`	Instala Skills para os agentes compatíveis detectados no sistema

Autoatualização

clickhousectl pode se autoatualizar para o lançamento mais recente:

# Update to the latest version
clickhousectl update

# Check for updates without installing
clickhousectl update --check

A CLI também verifica atualizações em segundo plano (no máximo uma vez a cada 24 horas) e exibe um aviso quando há uma versão mais recente disponível.

Telemetria

clickhousectl coleta telemetria de uso anônima para nos ajudar a entender como a CLI é usada. Ela é ativada por padrão, mas nada é enviado antes de você ser informado: na primeira execução, a CLI exibe um aviso explicando o que é coletado e como desativar a telemetria, sem enviar nada. A coleta só começa nas execuções subsequentes, portanto você sempre tem a oportunidade de desativá-la antes que qualquer dado seja coletado. Cada evento contém apenas:

O comando executado (por exemplo, local start) e os nomes das flags usadas — nunca os valores das flags, argumentos posicionais ou qualquer outra entrada fornecida pelo usuário. Portanto, consultas, nomes de tabelas, credenciais e caminhos de arquivos nunca são coletados.
O código de saída (por exemplo, 0, 1, 2, 4) e o resultado (por exemplo, ok, error, cancelled)
Para comandos digitados incorretamente, a sugestão de “você quis dizer” exibida pela CLI — registrada somente quando corresponde exatamente ao nome de um comando ou flag existente, portanto nunca pode conter o que você digitou
A versão do clickhousectl, o SO, a arquitetura e se a CLI foi invocada por um agente de IA (e qual agente) ou em CI

A telemetria é totalmente anônima: nenhum dado pessoal é coletado, e não há identificadores de dispositivo ou instalação. Para desativar a telemetria:

Execute clickhousectl telemetry disable (para reativar, use enable; para verificar, use status)
Defina a variável de ambiente DO_NOT_TRACK=1

Defina CHCTL_TELEMETRY_DEBUG=1 para imprimir o payload exato em stderr sem enviar nada.

​Instalação

​Instalação rápida

​Requisitos

​Local

​Instalando e gerenciando versões do ClickHouse

​Armazenamento dos binários do ClickHouse

​Iniciando um projeto

​Executar consultas

​Como criar e gerenciar servidores ClickHouse

​Arquivos de configuração personalizados para servidores locais

​Diretório local de dados do projeto

​Executando o Postgres local

​Autenticação

​API key/segredo da API (recomendado)

​Login com OAuth

​Status da autenticação e logout

​Como depurar qual fonte de credenciais foi usada

​Cloud

​Organizações

​Serviços

​Opções de criação do serviço

​Modos de autenticação da Query API

​Gerenciamento de endpoints de consulta

​Gerenciamento de Private Endpoint

​Configuração do Backup

​Serviços Postgres

​Opções de criação do serviço Postgres

​Backups

​ClickPipes

​Criando ClickPipes

​Membros

​Convites

​Chaves

​Atividade

​Saída em JSON

​Códigos de saída

​Skills

​Flags não interativas

​Autoatualização

​Telemetria

Instalação

Instalação rápida

Requisitos

Local

Instalando e gerenciando versões do ClickHouse

Armazenamento dos binários do ClickHouse

Iniciando um projeto

Executar consultas

Como criar e gerenciar servidores ClickHouse

Arquivos de configuração personalizados para servidores locais

Diretório local de dados do projeto

Executando o Postgres local

Autenticação

API key/segredo da API (recomendado)

Login com OAuth

Status da autenticação e logout

Como depurar qual fonte de credenciais foi usada

Cloud

Organizações

Serviços

Opções de criação do serviço

Modos de autenticação da Query API

Gerenciamento de endpoints de consulta

Gerenciamento de Private Endpoint

Configuração do Backup

Serviços Postgres

Opções de criação do serviço Postgres

Backups

ClickPipes

Criando ClickPipes

Membros

Convites

Chaves

Atividade

Saída em JSON

Códigos de saída

Skills

Flags não interativas

Autoatualização

Telemetria