> ## 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 > Utilisez ClickHouse CLI pour gérer les services ClickHouse Cloud et les instances ClickHouse locales ClickHouse CLI (`clickhousectl`) est un outil de ligne de commande unifié permettant de gérer les ressources ClickHouse Cloud ainsi que le développement local avec ClickHouse. Il permet également de gérer les services [ClickHouse Cloud Postgres](/fr/products/managed-postgres/overview) et [ClickPipes](/fr/integrations/clickpipes). Cette page constitue une référence des commandes disponibles dans `clickhousectl` 0.4.2. Exécutez `clickhousectl --version` pour vérifier la version installée, et `clickhousectl --help` sur n'importe quelle commande pour obtenir la liste complète des flags.

Installation

```bash theme={null} curl https://clickhouse.com/cli | sh ``` Un alias `chctl` est également créé automatiquement pour plus de commodité. Pour mettre à jour une installation existante vers la dernière version : ```bash theme={null} clickhousectl update # self-update clickhousectl update --check # check for updates without installing ```

Gestion de Cloud

Authentifiez-vous auprès de ClickHouse Cloud et gérez vos services directement depuis la ligne de commande.

Authentification

```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 ``` Les clés API sont enregistrées dans `.clickhouse/credentials.json` (fichier local au projet, ignoré par git). Vous pouvez également utiliser des environment variables : ```bash theme={null} export CLICKHOUSE_CLOUD_API_KEY=your-key export CLICKHOUSE_CLOUD_API_SECRET=your-secret ``` Préséance des credentials, de la plus élevée à la plus faible : flags `--api-key`/`--api-secret`, credentials du projet dans `.clickhouse/credentials.json`, variables d'environnement (shell, puis `.env`), tokens OAuth issus de `cloud auth login`. Les tokens OAuth sont en lecture seule ; les commandes d'écriture (create, delete, start, stop, update, scale) nécessitent une authentification par clé API.

Services

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

Exécuter des requêtes

Exécutez du SQL sur un service Cloud via HTTP grâce à la Query API — sans binaire `clickhouse` local ni mot de passe de service. Un seul des paramètres `--id` ou `--name` doit être fourni, et il est obligatoire : ```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 ``` Avec l'authentification par clé API, les requêtes s'exécutent avec un accès en lecture et en écriture. La clé authentifiée est utilisée directement lorsque le query endpoint du service l'autorise déjà ; sinon, la première requête provisionne un query endpoint ainsi qu'une clé lecture/écriture propre au service, et enregistre cette clé dans `.clickhouse/credentials.json`. Passez `--no-auto-enable` pour échouer au lieu de provisionner. Avec OAuth, le SQL s'exécute sous votre utilisateur cloud avec un accès read-only (`SELECT` uniquement), et rien n'est provisionné. À savoir : * `service query` exécute une seule statement par requête. Le SQL multi-statements est rejeté par la Query API, quel que soit son mode de transmission — `--query`, `--queries-file` ou stdin — avec `Error: SQL error 62: Syntax error (Multi-statements are not allowed)`. Un `;` final sur une statement unique ne pose pas de problème. Pour les scripts, exécutez `clickhousectl local use latest` et utilisez plutôt `clickhouse client` sur le service. * `--query` et `--queries-file` sont mutuellement exclusifs (code de sortie 2). Stdin n'est lu que si aucun des deux n'est fourni. `--query` ne lit jamais stdin : rediriger ou envoyer des données par pipe en parallèle constitue donc une erreur bloquante plutôt qu'un no-op silencieux : `Error: --query cannot be combined with SQL or data on stdin.` Envoyez plutôt un `INSERT` et ses données sous forme d'un single stream — `printf 'INSERT INTO t FORMAT CSV\n' | cat - data.csv | clickhousectl cloud service query --id ` — ou lisez une statement complète depuis stdin avec `--queries-file -`. * L'output format par défaut est `PrettyCompact` sur un terminal et `TabSeparated` en cas de pipe. `--json` sélectionne `JSONEachRow` et ne peut pas être combiné avec `--format` (code de sortie 2). * Une clé API Query enregistrée que l'endpoint rejette avec un HTTP 401/403 n'est jamais remplacée automatiquement ; la CLI consulte l'enregistrement de management de la clé uniquement pour en indiquer la raison. Remplacez ce credential précis avec `clickhousectl cloud service repair-query-key `, qui supprime également la clé remplacée. Sur un service en cours d'exécution, la commande ne se termine avec le code 0 qu'une fois qu'une query de probe avec la nouvelle clé a réussi, résultat rapporté sous `verification` dans la sortie `--json`. Si la Query API rejette toujours la clé à la fin de la readiness window, la commande se termine avec le code 1, mais la réparation reste valide : ne la relancez pas, exécutez plutôt `cloud service query`. * La Query API expire après environ 30 secondes ; la statement continue de s'exécuter sur le service, mais le résultat est perdu. Au-delà de cette durée, exécutez `clickhousectl local use latest` afin de placer le `clickhouse` binary standard dans le `PATH`, puis connectez-vous avec `clickhouse client --host --secure --port 9440 --user default --password `.

Points de terminaison de service et configuration

```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` doit correspondre exactement à une heure pleine (`HH:00`) et est validé par la CLI avant tout appel à l'API. Cette option exige également que la période de sauvegarde soit de `24` ou `48` heures : passez `--backup-period-hours 24` ou `--backup-period-hours 48` dans la même commande, ou assurez-vous que l'une de ces deux valeurs est déjà enregistrée. Avec toute autre période enregistrée, la CLI refuse l'opération avant d'appeler l'API, avec le message `Error: the stored backup period is 12 hours, but --backup-start-time requires 24 or 48.` `--clear-backup-start-time` supprime un horodatage de début enregistré et lève cette restriction. Combinez cette option avec `--backup-period-hours` pour effacer l'horodatage de début et définir n'importe quelle période en un seul appel. Elle est incompatible avec `--backup-start-time`.

Sauvegardes

```bash theme={null} clickhousectl cloud backup list clickhousectl cloud backup get ``` Pour restaurer une sauvegarde, créez un nouveau service à partir de celle-ci : `clickhousectl cloud service create --name restored-service --backup-id `.

ClickPipes

Gérez les [ClickPipes](/fr/integrations/clickpipes) permettant d'ingérer des données dans un service Cloud. La plupart des commandes prennent l'ID du service comme premier argument. ```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 ``` À savoir : * `clickpipe create postgres` exige soit `--table-mapping ` (répétable, une table par flag), soit `--table-mapping-json ` ; les deux peuvent être combinés. La forme JSON reprend textuellement l'objet de mapping de tables de l'API et constitue le seul moyen de définir `excludedColumns`, `sortingKeys`, `partitionByExpr`, `partitionKey` et `tableEngine`. Notez que `partitionKey` partitionne le snapshot initial à des fins de parallélisme et n'a aucun lien avec le `PARTITION BY` de la table de destination, qui correspond à `partitionByExpr`. `--iam-role` est requis avec `--auth IAM_ROLE` et rejeté avec l'authentification basique, et `--replication-slot-name` n'est valide qu'avec `--replication-mode cdc_only`. * Les paramètres CDC de Postgres sont appliqués à la création du pipe : `--sync-interval-seconds`, `--pull-batch-size`, `--initial-load-parallelism`, `--snapshot-rows-per-partition`, `--snapshot-parallel-tables`, `--allow-nullable-columns`, `--enable-failover-slots` et `--delete-on-merge`. Seuls le sync interval et le pull batch size peuvent être modifiés par la suite ; les paramètres de snapshot et de chargement initial ne le peuvent pas. * `--role `, disponible sur toutes les sous-commandes `clickpipe create`, est répétable et sélectionne le rôle ClickHouse accordé à l'utilisateur de destination du pipe. Il remplace le rôle que cet utilisateur recevrait autrement : sans `--role`, l'utilisateur détient `clickpipes_system` et `default_role` ; avec `--role my_role`, il détient `clickpipes_system` et `my_role`. Le rôle doit pouvoir créer des tables dans la base de données de destination — un rôle en lecture seule fait échouer la création avec `Not enough privileges`. Les noms `clickpipes` et `clickpipes_system`, réservés par l'API, sont rejetés. * Le TLS et la vérification de certificat sont activés par défaut pour les sources Postgres. Une chaîne source approuvée publiquement ne nécessite aucun fichier CA ; pour une CA source privée ou auto-signée, transmettez son bundle PEM avec `--ca-certificate `. Pour une source ClickHouse Cloud Postgres, récupérez ce bundle avec `clickhousectl cloud postgres certs get`. La vérification du hostname s'appuie sur `--host`, sauf si `--tls-host ` la remplace. * Pour les pipes Kafka et Kinesis, `--auth` est déduit des flags de credential lorsqu'il est omis, et aucune authentification n'est envoyée si aucun flag de credential n'est fourni. * `clickpipe settings` couvre uniquement les paramètres d'ingestion des pipes de streaming (Kafka, Kinesis) et de stockage objet, et les paramètres propres à Kafka sont omis pour les pipes non Kafka. Les pipes CDC de bases de données (Postgres, MySQL, MongoDB, BigQuery) n'ont pas de paramètres d'ingestion : `settings get` sur l'un d'eux se termine avec le code 1 et renvoie vers `clickhousectl cloud clickpipe get `, où sont indiqués leur sync interval et leur pull batch size. * Un pipe ne peut utiliser qu'un reverse private endpoint ayant atteint le statut `Ready` ; un endpoint AWS PrivateLink reste en `PendingAcceptance` tant que la demande de connexion n'a pas été acceptée dans le compte propriétaire de la source. Les pipes Kafka référencent l'endpoint par son ID avec `--reverse-private-endpoint-id` (répétable) ; les pipes CDC Postgres et MySQL transmettent l'un des `dnsNames` de l'endpoint via `--host`. * Les pipes Google Cloud Pub/Sub sont en preview limitée : contactez le support pour activer la fonctionnalité pour votre organisation avant d'en créer un. `--service-account-file` prend le chemin d'une clé JSON de service account GCP, ou `-` pour lire la clé depuis stdin ; la clé n'est jamais acceptée en ligne, elle n'apparaît donc ni dans la liste des processus ni dans l'historique du shell.

Postgres services (beta)

Créez et gérez des services [ClickHouse Cloud Postgres](/fr/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 ``` À savoir : * `--provider` vaut `aws` par défaut ; `gcp` est également accepté, avec des tailles de machine GCP telles que `c4-standard-4`. `--size` est validé par la Cloud API et non par la CLI : une taille non prise en charge n'est donc rejetée qu'au niveau du server. * Les changements de rôle sont à cohérence à terme, et l'API accuse réception de `promote` et `switchover` avant de les appliquer : un code de sortie 0 ne suffit donc pas à confirmer que le rôle a changé. Ces deux commandes acceptent `--wait`, qui interroge la cible jusqu'à ce qu'elle signale le nouveau rôle, ainsi que `--wait-timeout ` (300 par défaut) pour borner cette interrogation. L'ancien primary peut continuer à signaler `isPrimary=true` pendant plusieurs minutes : vérifiez donc avec `clickhousectl cloud postgres list --filter isPrimary=true` qu'un seul service est primary. * `postgres delete` fonctionne quel que soit l'état du service, y compris `running` : il n'est donc pas nécessaire de l'arrêter au préalable.

Organisations

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

Clés 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 ```

Membres et invitations

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

Journal d'activité

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

Sortie JSON

Utilisez l’option `--json` pour obtenir des réponses au format JSON depuis n’importe quelle commande cloud : ```bash theme={null} clickhousectl cloud service list --json ``` Les commandes `org prometheus` et `service prometheus` font exception : elles produisent toujours du texte d’exposition Prometheus brut et ignorent silencieusement `--json`.

Développement local

La CLI gère également les installations locales de ClickHouse, les serveurs locaux et les instances Postgres locales basées sur Docker. Consultez la page [clickhousectl (CLI)](/fr/get-started/setup/self-managed/clickhousectl) pour bien débuter avec le développement 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 ``` À savoir : * Les commandes `local` sont limitées au périmètre du projet : elles utilisent le répertoire `.clickhouse` du répertoire de travail courant exact et ne remontent jamais dans les répertoires parents. Placez-vous à la racine du projet avant de les exécuter. * `clickhousectl local use` crée également un lien symbolique `~/.local/bin/clickhouse`, ce qui rend directement accessibles les sous-commandes standard telles que `clickhouse client`, `clickhouse benchmark` et `clickhouse format`. Passez `--no-global` pour ne pas créer ce lien symbolique. * `local remove` exige une version installée exacte. Elle refuse de supprimer une version utilisée par un serveur en cours d'exécution dans un projet, quel qu'il soit, ou qui correspond à la valeur par défaut actuelle ; `--force` arrête ces serveurs et efface la valeur par défaut ainsi que le lien symbolique global. * Sans nom, `local server stop` arrête `default` s'il existe, sinon le seul serveur connu ; s'il existe plusieurs serveurs autres que `default`, un nom est demandé. Sans nom, `local server remove` ne sélectionne que le `default` existant — il ne devine jamais un serveur personnalisé. * `local client` accepte `-v`/`--version` pour choisir une version de client installée en mode hôte/port direct, admet `-q` de façon répétée pour plusieurs requêtes et accepte plusieurs chemins pour `--queries-file`. Combiner `--query` et `--queries-file` constitue une erreur d'utilisation. * `local postgres start` bloque jusqu'à ce que PostgreSQL accepte les connexions, dans la limite du nombre de secondes défini par `--wait-timeout` (60 par défaut, 600 au maximum). Si `--port` est omis, le port 5432 est utilisé s'il est libre, sinon un port est sélectionné automatiquement ; un port explicitement demandé mais déjà occupé est rejeté.

Autres commandes

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

Prérequis

* MacOS (aarch64, x86\_64) ou Linux (aarch64, x86\_64) * Les commandes Cloud nécessitent une [clé API ClickHouse Cloud](/fr/products/cloud/features/admin-features/api/openapi) pour l'accès en écriture ; la connexion OAuth est en lecture seule * `clickhousectl local postgres` nécessite Docker