clickhousectl

Documentação do clickhousectl, a CLI do ClickHouse: local e na nuvem

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 ...

​

Login com OAuth

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.

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

# Create a service
clickhousectl cloud postgres create \
  --name my-pg \
  --region us-east-1 \
  --size m7i.2xlarge \
  --pg-version 17 \
  --ha-type sync

# 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>

# Read replicas 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 (obrigatório)
--size	Tamanho da instância, por exemplo m7i.2xlarge (obrigatório)
--provider	provedor de Cloud (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 [e-mail] --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.