> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # ClickHouse CLI > Use o ClickHouse CLI para gerenciar serviços do ClickHouse Cloud e ambientes locais de desenvolvimento com ClickHouse O ClickHouse CLI (`clickhousectl`) é uma ferramenta unificada de linha de comando para gerenciar recursos do ClickHouse Cloud e ambientes locais de desenvolvimento com ClickHouse. Ele também permite gerenciar os serviços do [ClickHouse Cloud Postgres](/pt-BR/products/managed-postgres/overview) e os [ClickPipes](/pt-BR/integrations/clickpipes). Esta página é uma referência do conjunto de comandos do `clickhousectl` 0.4.2. Execute `clickhousectl --version` para verificar a versão instalada e `clickhousectl --help` em qualquer comando para ver a lista completa de flags.

Instalação

```bash theme={null} curl https://clickhouse.com/cli | sh ``` Um alias `chctl` também é criado automaticamente para facilitar. Para atualizar uma instalação existente para a versão mais recente: ```bash theme={null} clickhousectl update # self-update clickhousectl update --check # check for updates without installing ```

Gerenciamento da Cloud

Autentique-se no ClickHouse Cloud e gerencie seus serviços diretamente via linha de comando.

Autenticação

```bash theme={null} # Log in with an API key (read/write access) clickhousectl cloud auth login --api-key --api-secret # Log in with the OAuth device flow (interactive; read-only access) clickhousectl cloud auth login # Show which credential source is active clickhousectl cloud auth status # Log out and clear saved credentials clickhousectl cloud auth logout # Create a new ClickHouse Cloud account clickhousectl cloud auth signup ``` As chaves de API são salvas em `.clickhouse/credentials.json` (local ao projeto, ignorado pelo git). Você também pode usar variáveis de ambiente: ```bash theme={null} export CLICKHOUSE_CLOUD_API_KEY=your-key export CLICKHOUSE_CLOUD_API_SECRET=your-secret ``` Precedência de credenciais, da maior para a menor: flags `--api-key`/`--api-secret`, credenciais do projeto em `.clickhouse/credentials.json`, variáveis de ambiente (shell e, em seguida, `.env`), tokens OAuth obtidos com `cloud auth login`. Os tokens OAuth são somente leitura; comandos de escrita (create, delete, start, stop, update, scale) exigem autenticação por chave de API.

Serviços

```bash theme={null} # List services clickhousectl cloud service list # Create a service clickhousectl cloud service create --name my-service \ --provider aws \ --region us-east-1 # Get service details clickhousectl cloud service get # Update service settings (name, IP allow list, tags, endpoints, ...) clickhousectl cloud service update --add-ip-allow 0.0.0.0/0 # Scale a service clickhousectl cloud service scale \ --min-replica-memory-gb 24 \ --max-replica-memory-gb 48 \ --num-replicas 3 # Start/stop a service clickhousectl cloud service start clickhousectl cloud service stop # Reset the default user password clickhousectl cloud service reset-password # Delete a service clickhousectl cloud service delete ```

Executando consultas

Execute SQL em um serviço Cloud via HTTP através da Query API — sem necessidade de um binário `clickhouse` local ou da senha do serviço. É obrigatório informar exatamente um entre `--id` e `--name`: ```bash theme={null} # Query by service ID or by name clickhousectl cloud service query --id -q 'SELECT 1' clickhousectl cloud service query --name my-service -q 'SELECT version()' # Run a query from a SQL file (use "-" for stdin), choosing an output format. # The file must hold a single statement clickhousectl cloud service query --id \ --queries-file report.sql --format JSONEachRow # With neither --query nor --queries-file, SQL is read from stdin echo 'SELECT 1' | clickhousectl cloud service query --id # Replace a stored Query API key that the endpoint rejects clickhousectl cloud service repair-query-key ``` Com autenticação por chave de API, as consultas são executadas com acesso de leitura e escrita. A chave de API autenticada é usada diretamente quando o query endpoint do service já a autoriza; caso contrário, a primeira consulta provisiona um query endpoint e uma chave de API de leitura/escrita por service, e armazena essa chave de API em `.clickhouse/credentials.json`. Passe `--no-auto-enable` para falhar em vez de provisionar. Com OAuth, o SQL é executado com seu usuário do cloud com acesso somente leitura (apenas `SELECT`), e nada é provisionado. O que você precisa saber: * `service query` executa uma única instrução por requisição. SQL com múltiplas instruções é rejeitado pela Query API, independentemente de como chega — `--query`, `--queries-file` ou stdin — com `Error: SQL error 62: Syntax error (Multi-statements are not allowed)`. Um `;` no final de uma única instrução não é problema. Para scripts, execute `clickhousectl local use latest` e use o `clickhouse client` contra o service. * `--query` e `--queries-file` são mutuamente exclusivos (código de saída 2). O stdin só é lido quando nenhum dos dois é informado. `--query` nunca lê o stdin, portanto redirecionar ou enviar dados por pipe junto com ele é um erro grave, e não um no-op silencioso: `Error: --query cannot be combined with SQL or data on stdin.` Em vez disso, envie um `INSERT` e seus dados como um único stream — `printf 'INSERT INTO t FORMAT CSV\n' | cat - data.csv | clickhousectl cloud service query --id ` — ou leia uma instrução inteira do stdin com `--queries-file -`. * O output format padrão é `PrettyCompact` em um terminal e `TabSeparated` quando há pipe. `--json` seleciona `JSONEachRow` e não pode ser combinado com `--format` (código de saída 2). * Uma chave de API da Query API armazenada que o endpoint rejeita com HTTP 401/403 nunca é substituída automaticamente; a CLI lê o registro de gerenciamento da chave de API apenas para informar o motivo. Substitua essa credencial específica com `clickhousectl cloud service repair-query-key `, que também exclui a chave de API substituída. Em um service em execução, o comando sai com 0 apenas quando uma consulta de teste com a nova chave de API é bem-sucedida, o que é reportado em `verification` na saída `--json`. Se a Query API ainda rejeitar a chave de API quando a janela de readiness terminar, o comando sai com 1, mas o reparo continua válido: não execute o comando novamente; execute `cloud service query` no lugar. * A Query API expira após cerca de 30 segundos; a instrução continua sendo executada no service, mas o resultado é perdido. Para algo mais demorado, execute `clickhousectl local use latest` para colocar o `clickhouse` binary padrão no `PATH` e conecte-se com `clickhouse client --host --secure --port 9440 --user default --password `.

Endpoints e configuração do service

```bash theme={null} # Query endpoints (used by the Query API) clickhousectl cloud service query-endpoint get clickhousectl cloud service query-endpoint create --role sql_console_admin clickhousectl cloud service query-endpoint delete # Private endpoints. --endpoint-id takes an AWS VPC endpoint ID, a GCP PSC # connection ID, or an Azure private endpoint Resource ID / resourceGuid clickhousectl cloud service private-endpoint get-config clickhousectl cloud service private-endpoint create --endpoint-id # Backup configuration clickhousectl cloud service backup-config get clickhousectl cloud service backup-config update --backup-period-hours 24 clickhousectl cloud service backup-config update \ --backup-start-time 02:00 --backup-period-hours 24 clickhousectl cloud service backup-config update --clear-backup-start-time # Prometheus metrics for a service (always raw Prometheus exposition text) clickhousectl cloud service prometheus ``` `--backup-start-time` deve ser exatamente na hora cheia (`HH:00`) e é validado pela CLI antes de qualquer chamada de API. Ele também exige que o período de backup seja de `24` ou `48` horas: passe `--backup-period-hours 24` ou `--backup-period-hours 48` no mesmo comando, ou tenha um desses dois valores já armazenado. Com qualquer outro período armazenado, a CLI recusa a operação antes de chamar a API, exibindo `Error: the stored backup period is 12 hours, but --backup-start-time requires 24 or 48.` `--clear-backup-start-time` remove o horário de início armazenado e suspende essa restrição. Combine-o com `--backup-period-hours` para limpar o horário de início e definir qualquer período em uma única chamada. Ele conflita com `--backup-start-time`.

Backups

```bash theme={null} clickhousectl cloud backup list clickhousectl cloud backup get ``` Para restaurar um backup, crie um novo service a partir dele: `clickhousectl cloud service create --name restored-service --backup-id `.

ClickPipes

Gerencie os [ClickPipes](/pt-BR/integrations/clickpipes) para ingestão de dados em um serviço do Cloud. A maioria dos comandos recebe o ID do serviço como primeiro argumento. ```bash theme={null} # List pipes and get details clickhousectl cloud clickpipe list clickhousectl cloud clickpipe get # Create a pipe. Sources: object-storage, kafka, kinesis, pubsub, # postgres, mysql, mongodb, bigquery clickhousectl cloud clickpipe create object-storage \ --name my-pipe \ --source-url 'https://bucket.s3.us-east-1.amazonaws.com/data/*.json' \ --format JSONEachRow \ --database default \ --table events # A Postgres pipe needs at least one --table-mapping or --table-mapping-json clickhousectl cloud clickpipe create postgres \ --name my-cdc-pipe \ --host pg.example.com \ --pg-database appdb \ --username replicator \ --password \ --table-mapping public.orders:orders \ --sync-interval-seconds 30 \ --ca-certificate ./source-ca.pem # Lifecycle clickhousectl cloud clickpipe start clickhousectl cloud clickpipe stop clickhousectl cloud clickpipe resync # CDC pipes only clickhousectl cloud clickpipe delete # Scaling and settings. scale requires at least one of # --replicas, --cpu-millicores, or --memory-gb clickhousectl cloud clickpipe scale --replicas 2 clickhousectl cloud clickpipe settings get clickhousectl cloud clickpipe settings update # Discover a source schema without creating a pipe (beta) clickhousectl cloud clickpipe schema-discover kafka [options] clickhousectl cloud clickpipe schema-discover kinesis [options] clickhousectl cloud clickpipe schema-discover object-storage [options] clickhousectl cloud clickpipe schema-discover pubsub [options] # Reverse private endpoints: AWS PrivateLink, Amazon MSK multi-VPC, # Google Private Service Connect clickhousectl cloud clickpipe reverse-private-endpoint list clickhousectl cloud clickpipe reverse-private-endpoint get clickhousectl cloud clickpipe reverse-private-endpoint create \ --type VPC_ENDPOINT_SERVICE \ --description 'kafka source' \ --vpc-endpoint-service-name clickhousectl cloud clickpipe reverse-private-endpoint update \ --custom-private-dns-mapping pg.internal.example.com clickhousectl cloud clickpipe reverse-private-endpoint delete ``` O que você precisa saber: * `clickpipe create postgres` exige `--table-mapping ` (repetível, uma tabela por flag) ou `--table-mapping-json `; os dois podem ser combinados. A forma JSON recebe o objeto de mapeamento de tabelas da API literalmente e é a única maneira de definir `excludedColumns`, `sortingKeys`, `partitionByExpr`, `partitionKey` e `tableEngine`. Observe que `partitionKey` particiona o snapshot inicial para fins de paralelismo e não tem relação com o `PARTITION BY` da destination table, que corresponde a `partitionByExpr`. `--iam-role` é obrigatório com `--auth IAM_ROLE` e rejeitado com autenticação básica, e `--replication-slot-name` só é válido com `--replication-mode cdc_only`. * As configurações de CDC do Postgres são aplicadas no momento da criação do pipe: `--sync-interval-seconds`, `--pull-batch-size`, `--initial-load-parallelism`, `--snapshot-rows-per-partition`, `--snapshot-parallel-tables`, `--allow-nullable-columns`, `--enable-failover-slots` e `--delete-on-merge`. Somente o sync interval e o pull batch size podem ser alterados depois; as configurações de snapshot e de carga inicial, não. * `--role ` em qualquer subcomando `clickpipe create` é repetível e define a role do ClickHouse concedida ao usuário de destino do pipe. Ela substitui a role que esse usuário receberia por padrão: sem `--role`, o usuário possui `clickpipes_system` e `default_role`; com `--role my_role`, possui `clickpipes_system` e `my_role`. A role precisa ser capaz de criar tabelas na destination database — uma role somente leitura faz a criação falhar com `Not enough privileges`. Os nomes `clickpipes` e `clickpipes_system`, reservados pela API, são rejeitados. * TLS e verificação de certificados vêm ativados por padrão para sources Postgres. Uma cadeia de origem publicamente confiável dispensa arquivo de CA; para uma CA de origem privada ou autoassinada, informe seu pacote PEM com `--ca-certificate `. Para uma source ClickHouse Cloud Postgres, obtenha esse pacote com `clickhousectl cloud postgres certs get`. A verificação de hostname usa `--host`, a menos que `--tls-host ` a sobrescreva. * Para pipes Kafka e Kinesis, `--auth` é inferido a partir das flags de credencial quando omitido, e nenhuma autenticação é enviada se nenhuma flag de credencial for fornecida. * `clickpipe settings` abrange apenas as configurações de ingestão de pipes de streaming (Kafka, Kinesis) e de armazenamento de objetos, e as configurações exclusivas do Kafka são omitidas para pipes que não sejam Kafka. Pipes de CDC de banco de dados (Postgres, MySQL, MongoDB, BigQuery) não têm configurações de ingestão: `settings get` em um deles sai com código 1 e aponta para `clickhousectl cloud clickpipe get `, que é onde o sync interval e o pull batch size deles são exibidos. * Um pipe só pode usar um reverse private endpoint que tenha atingido o status `Ready`; um endpoint AWS PrivateLink permanece em `PendingAcceptance` até que a solicitação de conexão seja aceita na conta proprietária da source. Pipes Kafka referenciam o endpoint pelo ID com `--reverse-private-endpoint-id` (repetível); pipes de CDC Postgres e MySQL passam um dos `dnsNames` do endpoint como `--host`. * Pipes do Google Cloud Pub/Sub estão em preview limitado: contate o suporte para habilitar o recurso na sua organização antes de criar um. `--service-account-file` recebe o caminho para uma chave JSON de service account do GCP, ou `-` para ler a chave do stdin; a chave nunca é aceita inline, portanto não aparece em listagens de processos nem no histórico do shell.

Postgres services (beta)

Crie e gerencie serviços do [ClickHouse Cloud Postgres](/pt-BR/products/managed-postgres/overview). ```bash theme={null} # List Postgres services, optionally filtering client-side. # Filter keys: state, region, name, provider, isPrimary clickhousectl cloud postgres list clickhousectl cloud postgres list --filter state=running --filter isPrimary=true # Create a Postgres service clickhousectl cloud postgres create \ --name my-pg \ --region us-east-1 \ --size m7i.2xlarge \ --pg-version 18 # Get service details clickhousectl cloud postgres get # Update a service clickhousectl cloud postgres update --size m7i.4xlarge --add-tag env=prod # Reset the password (exactly one of --password or --generate) clickhousectl cloud postgres reset-password --generate # Runtime configuration (postgresql.conf + PgBouncer) and CA certificates. # config patch takes exactly one of --set (repeatable) or --file clickhousectl cloud postgres config get clickhousectl cloud postgres config patch --set max_connections=500 clickhousectl cloud postgres config replace --file config.json clickhousectl cloud postgres certs get # Read replicas, failover, and point-in-time restore clickhousectl cloud postgres read-replica create --name replica-1 clickhousectl cloud postgres promote --wait clickhousectl cloud postgres switchover --wait clickhousectl cloud postgres restore --name restored --restore-target 2026-04-16T12:00:00Z # Restart a service clickhousectl cloud postgres restart # Delete a service clickhousectl cloud postgres delete ``` O que você precisa saber: * `--provider` usa `aws` como padrão; `gcp` também é aceito, com tamanhos de máquina do GCP como `c4-standard-4`. `--size` é validado pela Cloud API, e não pela CLI, portanto um tamanho sem suporte só é rejeitado no servidor. * Alterações de role são eventualmente consistentes, e a API confirma `promote` e `switchover` antes de aplicá-los, de modo que o código de saída 0, isoladamente, não garante que a role foi alterada. Ambos aceitam `--wait` para consultar periodicamente até que o target reporte a nova role, com `--wait-timeout ` (padrão 300) limitando esse polling. O primary anterior pode continuar reportando `isPrimary=true` por alguns minutos, portanto confirme com `clickhousectl cloud postgres list --filter isPrimary=true` que exatamente um service é primary. * `postgres delete` funciona a partir de qualquer state, inclusive `running`, ou seja, não é necessário parar o service antes.

Organizações

```bash theme={null} clickhousectl cloud org list clickhousectl cloud org get clickhousectl cloud org update --name new-name clickhousectl cloud org prometheus clickhousectl cloud org usage --from-date 2026-08-01 --to-date 2026-08-31 ```

Chaves de API

```bash theme={null} clickhousectl cloud key list clickhousectl cloud key get clickhousectl cloud key create --name ci-key --role-id clickhousectl cloud key update clickhousectl cloud key delete ```

Membros e convites

```bash theme={null} clickhousectl cloud member list clickhousectl cloud member get clickhousectl cloud member update --role-id clickhousectl cloud member remove clickhousectl cloud invitation list clickhousectl cloud invitation create --email dev@example.com --role-id clickhousectl cloud invitation get clickhousectl cloud invitation delete ```

Log de atividades

```bash theme={null} clickhousectl cloud activity list --from-date 2026-08-01 --to-date 2026-08-31 clickhousectl cloud activity get ```

Saída em JSON

Use a opção `--json` para obter respostas em formato JSON de qualquer comando de cloud: ```bash theme={null} clickhousectl cloud service list --json ``` Os comandos `org prometheus` e `service prometheus` são a exceção: eles sempre emitem o texto bruto de exposição do Prometheus e ignoram silenciosamente `--json`.

Desenvolvimento local

A CLI também gerencia instalações locais do ClickHouse, servidores locais e instâncias locais do Postgres em Docker. Consulte a página [clickhousectl (CLI)](/pt-BR/get-started/setup/self-managed/clickhousectl) para começar a trabalhar com desenvolvimento local. ```bash theme={null} # Manage installed ClickHouse versions. install also accepts stable, lts, # a partial version like 25.12, an exact version, or a Postgres image # selector like postgres@18 clickhousectl local install latest clickhousectl local list clickhousectl local use clickhousectl local which clickhousectl local remove # Scaffold a project (.clickhouse/ plus clickhouse/ and postgres/ directories) clickhousectl local init # Manage local server instances (data persists in .clickhouse/servers/) clickhousectl local server start [name] clickhousectl local server list # --global lists servers across projects clickhousectl local server stop [name] clickhousectl local server stop-all clickhousectl local server remove [name] clickhousectl local server configs # named overlays for `server start --config` clickhousectl local server dotenv # Connect to a running server with clickhouse-client clickhousectl local client -q 'SELECT 1;' clickhousectl local client --host db.example.com --port 9000 --version 25.12 # Local Postgres instances (requires Docker) clickhousectl local postgres start --name clickhousectl local postgres client clickhousectl local postgres stop [name] clickhousectl local postgres stop-all clickhousectl local postgres remove [name] clickhousectl local postgres dotenv ``` O que você precisa saber: * Os comandos `local` têm escopo de projeto: eles usam o diretório `.clickhouse` dentro do diretório de trabalho atual exato e nunca procuram em diretórios pai. Vá para a raiz do projeto antes de executá-los. * O `clickhousectl local use` também cria um link simbólico em `~/.local/bin/clickhouse`, o que disponibiliza diretamente os subcomandos padrão, como `clickhouse client`, `clickhouse benchmark` e `clickhouse format`. Passe `--no-global` para pular o link simbólico. * O `local remove` exige uma versão instalada exata. Ele se recusa a remover uma versão usada por um servidor em execução em qualquer projeto, ou que seja o padrão atual; `--force` interrompe esses servidores e limpa o padrão e o link simbólico global. * Sem um nome, o `local server stop` interrompe o `default`, se existir, e, caso contrário, o único servidor conhecido; havendo vários servidores diferentes do padrão, ele solicita um nome. O `local server remove` sem nome só seleciona um `default` existente — ele nunca adivinha um servidor personalizado. * O `local client` aceita `-v`/`--version` para escolher uma versão de cliente instalada no modo direto de host/porta, aceita `-q` repetido para múltiplas consultas e aceita vários caminhos em `--queries-file`. Combinar `--query` e `--queries-file` é um erro de uso. * O `local postgres start` bloqueia até que o PostgreSQL aceite conexões, limitado pelos segundos definidos em `--wait-timeout` (padrão 60, máximo 600). Se `--port` for omitido, ele usa a 5432 caso esteja livre e, caso contrário, seleciona uma porta automaticamente; uma porta solicitada explicitamente que já esteja ocupada é rejeitada.

Outros comandos

```bash theme={null} # Install the ClickHouse agent skills into supported coding agents clickhousectl skills --agent claude # Manage anonymous usage telemetry: command name, flag and argument names # (never their values). Opt out with DO_NOT_TRACK=1 clickhousectl telemetry status clickhousectl telemetry disable clickhousectl telemetry enable ```

Requisitos

* macOS (aarch64, x86\_64) ou Linux (aarch64, x86\_64) * Os comandos do Cloud exigem uma [chave de API do ClickHouse Cloud](/pt-BR/products/cloud/features/admin-features/api/openapi) para acesso de escrita; o login por OAuth é somente leitura * `clickhousectl local postgres` requer Docker