Passer au contenu principal
clickhousectl (alias chctl) est la CLI officielle de ClickHouse, du développement local à ClickHouse Cloud. Elle s’adresse aussi bien aux utilisateurs dans un terminal qu’aux scripts et aux agents de code. Avec clickhousectl, vous pouvez :
  • Installer des versions locales de ClickHouse et passer de l’une à l’autre, lancer des serveurs locaux isolés et exécuter du SQL
  • Exécuter Postgres en local via Docker
  • Créer, configurer, mettre à l’échelle, sauvegarder et interroger des services ClickHouse Cloud
  • Créer, surveiller, configurer et restaurer des services ClickHouse Managed Postgres
  • Créer et exploiter des ClickPipes depuis le stockage d’objet, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB et BigQuery
  • Gérer les sources, tableaux de bord, alertes, webhooks, recherches enregistrées et rôles d’un service Managed ClickStack
  • Développer des UDF exécutables en local et les déployer sur ClickHouse Cloud
  • Gérer les membres de l’organisation, les invitations, les clés API et les rôles
  • Installer les ClickHouse agent skills officiels dans les agents de code
Cette page présente des exemples représentatifs. clickhousectl <command> --help fait référence pour chaque commande et chaque indicateur. L’aide de la plupart des commandes se termine par un bloc CONTEXT FOR AGENTS ; pour les commandes Cloud, elle indique également les autorisations requises pour l’API key. Pour des procédures pas à pas, suivez les liens vers les guides dans chaque section. Pour une vue d’ensemble centrée sur Cloud, consultez Interface en ligne de commande de ClickHouse.

Installation

clickhousectl fonctionne sous MacOS et Linux, sur architectures ARM64 et x86_64.
Le script installe ~/.local/bin/clickhousectl et crée l’alias chctl. Assurez-vous que ~/.local/bin figure dans votre PATH. Vous pouvez également l’installer à l’aide d’un gestionnaire de paquets : Seuls le script d’installation et npm créent l’alias chctl. Pour mettre à jour une installation existante, exécutez clickhousectl update (voir Mise à jour automatique).

Prérequis

  • Docker, uniquement pour Postgres en local
  • Pour les commandes Cloud, un compte ClickHouse Cloud. Les commandes de lecture fonctionnent avec une authentification OAuth via le navigateur (cloud auth login). La création ou la modification de ressources nécessite une API key. Consultez la section Authentification.

Local

Les commandes locales s’exécutent dans le répertoire courant. Chaque projet stocke les données de son serveur dans .clickhouse/, tandis que les binaires ClickHouse sont partagés globalement dans ~/.clickhouse/. La CLI ne parcourt pas les répertoires parents : exécutez donc les commandes locales depuis la racine de votre projet. Consultez le guide de développement local pour découvrir le flux de travail complet.

Installer et sélectionner des versions

local use installe la version si nécessaire, la définit comme version par défaut pour les prochains démarrages du serveur et crée un lien symbolique vers ~/.local/bin/clickhouse, afin que clickhouse client et clickhouse local soient accessibles depuis votre PATH. Passez --no-global pour ne pas créer le lien symbolique. Si un fichier ordinaire existe déjà à cet emplacement, il est laissé tel quel. local remove refuse de supprimer la version par défaut ou une version utilisée par un serveur en cours d’exécution, quel que soit le projet. --force arrête ces serveurs et supprime la version, puis réinitialise la version par défaut et supprime le lien symbolique.

Initialiser un projet

init est facultatif. Cette commande crée un répertoire .clickhouse/ ignoré par git pour les données d’exécution, ainsi que des squelettes SQL que vous pouvez commiter : clickhouse/ (tables/, materialized_views/, queries/, seed/, udfs/) et postgres/ (tables/, views/, functions/, queries/, seed/). Si vous la relancez, elle ne crée que les éléments manquants.

Lancer des serveurs locaux

Chaque serveur nommé dispose de ses propres données dans .clickhouse/servers/<name>/data/, qui sont conservées à l’arrêt du serveur pour le prochain démarrage. Sans nom, le premier serveur s’appelle default ; si default est déjà en cours d’exécution, un nouveau nom est généré. Les ports par défaut sont 8123 pour HTTP et 9000 pour TCP ; si ceux-ci sont déjà utilisés, des ports libres sont attribués. --version sélectionne une version pour ce démarrage uniquement, sans modifier la version par défaut. Un démarrage sans version spécifiée et sans version par défaut installe latest sans en faire la version par défaut ; exécutez d’abord local use latest pour la définir comme version par défaut.

Exécuter des requêtes SQL avec le client local

local client se connecte à un serveur nommé avec le même binaire ClickHouse que celui qui exécute ce serveur (nom par défaut : default). Les arguments placés après -- sont transmis tels quels à clickhouse client. La sortie et le code de sortie proviennent de clickhouse client, même en mode JSON ; définissez donc vous-même le format de sortie SQL dans vos scripts.

Configuration personnalisée du serveur

Placez une configuration XML ou YAML partielle dans ~/.clickhouse/configs/ et sélectionnez-la par son nom au démarrage d’un serveur :
Le fichier se superpose aux valeurs par défaut intégrées : il suffit donc d’y indiquer les paramètres que vous modifiez. Ce choix n’est pas mémorisé : un démarrage ultérieur sans --config supprime la surcouche. Les chemins des données et les ports gérés l’emportent toujours sur les valeurs de configuration.

Enregistrer les informations de connexion dans un fichier dotenv

dotenv lit les ports effectivement utilisés par le serveur en cours d’exécution et écrit CLICKHOUSE_HOST, CLICKHOUSE_PORT et CLICKHOUSE_HTTP_PORT, ainsi que l’utilisateur, le mot de passe et la base de données si vous les fournissez. Les autres lignes d’un fichier existant sont conservées. Chargez le fichier avec le chargeur dotenv de votre application ; ne passez jamais l’aperçu affiché à eval.

Postgres local

Postgres local s’exécute dans Docker : Docker doit donc être en cours d’exécution. Les versions 17 et 18 de Postgres sont prises en charge, y compris les étiquettes d’image comme 18-alpine ; les nouvelles instances utilisent la version 18 par défaut.
Une instance est identifiée par son nom et sa version majeure. Lorsque vous redémarrez une instance arrêtée, elle réutilise son port, son utilisateur, son mot de passe et sa base de données d’origine : les indicateurs de création sont donc sans effet lors d’une reprise. Un mot de passe aléatoire est généré si vous n’en fournissez pas. Le fichier .env.local contient le mot de passe ; veillez donc à l’exclure du contrôle de version.

UDFs locales

local udf déploie des UDF exécutables depuis clickhouse/udfs/<name>/ sur un serveur local. cloud udf téléverse ce même répertoire vers Cloud (voir UDFs dans Cloud).
Toutes les commandes, à l’exception de init, acceptent --server <name> (valeur par défaut : default). deploy valide udf.json de la même manière que Cloud. Sur un serveur en cours d’exécution, la commande recharge les fonctions et vérifie que la fonction a bien été chargée. L’environnement d’exécution native ne peut être déployé localement que sur des hôtes Linux amd64 ou arm64. Consultez le guide des fonctions définies par l’utilisateur.

Authentification

Les commandes Cloud utilisent l’un des deux types d’informations d’authentification suivants : Si vous n’avez pas encore de compte ClickHouse Cloud, clickhousectl cloud auth signup ouvre la page d’inscription dans votre navigateur.

Connexion avec OAuth

Cela ouvre votre navigateur pour le flux OAuth pour appareils. Les jetons sont enregistrés globalement dans ~/.clickhouse/tokens.json et rafraîchis automatiquement.
OAuth est en lecture seule. Pour créer ou modifier des ressources, connectez-vous avec une API key.

API key

Créez une API key disposant des rôles nécessaires à vos commandes, puis enregistrez-la. L’invite interactive permet d’éviter que le secret n’apparaisse dans l’historique de votre interpréteur de commandes :
La connexion vérifie la clé et affiche l’identité à laquelle elle est associée. Si l’API rejette la clé, celle-ci n’est pas enregistrée et la commande se termine avec le code de sortie 4. Si l’API est injoignable, la clé est tout de même enregistrée, avec un avertissement. Pour l’intégration continue et les autres processus automatisés, injectez la clé via votre gestionnaire de secrets plutôt que de l’enregistrer :
En développement, la CLI lit également ces variables depuis un fichier .env situé dans le répertoire courant. Veillez à exclure .env du contrôle de version.

Vérifier et effacer les identifiants

whoami fonctionne avec les deux types d’identifiants et renvoie le code de sortie 4 si les identifiants sont rejetés. status peut renvoyer le code de sortie 0 même si aucun identifiant n’est valide ; utilisez donc whoami pour vérifier l’accès. La déconnexion ne supprime pas les variables d’environnement et ne modifie pas le fichier .env.

Ordre de priorité des informations d’authentification

La première source disponible l’emporte :
  1. Les indicateurs --api-key et --api-secret
  2. .clickhouse/credentials.json
  3. Les variables d’environnement exportées
  4. Les variables définies dans le fichier .env du répertoire courant
  5. Les jetons OAuth globaux
Ajoutez --debug à n’importe quelle commande cloud pour afficher sur stderr la source d’informations d’authentification retenue ainsi que l’URL de l’API :

Sélectionner une organisation

Les commandes qui portent sur une organisation ne la sélectionnent automatiquement que si vos identifiants donnent accès à une seule organisation. Sinon, indiquez --org-id, ou --org-name suivi du nom exact :
La plupart des commandes portant sur des ressources acceptent un ID positionnel ou un --name exact. Consultez Authentification et accès pour en savoir plus sur les autorisations, les clés restreintes et le nettoyage à la déconnexion.

Cloud

Les commandes Cloud appellent l’API ClickHouse Cloud. Les requêtes de création et de mise à jour se terminent dès que l’API les accepte : interrogez donc get jusqu’à ce que la ressource atteigne l’état souhaité.

Services

Conservez le mot de passe initial affiché lors de la création : il n’est renvoyé qu’une seule fois. La commande de création rend la main avant la fin du provisionnement ; relancez donc get jusqu’à ce que l’état soit running. Si vous omettez --ip-allow, toutes les adresses IP sont autorisées (0.0.0.0/0). Les entrées sont au format IP_OR_CIDR=DESCRIPTION. Restaurez une sauvegarde dans un nouveau service avec --backup-id, ou déployez un service dans une infrastructure BYOC avec --byoc-id. Mettre à jour, mettre à l’échelle et configurer un service :
La mémoire par réplique est un multiple de 4 Go, avec un maximum de 120 Go pour les services non payants et de 356 Go pour les services payants, dans la limite de 50 répliques. Les limites de l’organisation et de l’entrepôt peuvent abaisser ces valeurs. La mise à l’échelle automatique horizontale nécessite que la fonctionnalité correspondante soit activée pour l’organisation. update ne modifie que les indicateurs que vous spécifiez. Les autres groupes de commandes de service sont settings (list, get, schema, set, unset), scaling-schedule, upgrade-window, replica-aware-routing (bêta), snapshot (bêta), private-endpoint, backup-config et prometheus. Consultez Créer et exploiter un Service Cloud.

API de requête

cloud service query exécute une instruction SQL via HTTP, sans nécessiter de binaire clickhouse local ni de mot de passe de service :
  • OAuth exécute la requête sous votre identity, avec un accès SQL en lecture seule. Rien n’est lié au service.
  • API key : lors du premier appel, clickhousectl ajoute votre API key au point de terminaison de l’API de requêtes du service et crée cet endpoint avec les rôles sql_console_admin si nécessaire. Les rôles, origines et autres liaisons de clés existants sont conservés, et aucune nouvelle clé n’est créée. Lorsque la CLI modifie l’endpoint, elle affiche Binding the authenticated API key to the Query API endpoint for service '<name>'... sur stderr. Passez --no-auto-enable pour que la commande échoue plutôt.
Une clé propre à un service, enregistrée par une version antérieure de la CLI, reste prioritaire pour ce service. Si l’API la rejette, cloud service repair-query-key <service-id> la remplace explicitement. L’API de requête n’accepte qu’un seul statement par requête. Elle peut expirer au bout d’environ 30 secondes alors que le SQL continue de s’exécuter : vérifiez donc le résultat avant de relancer une écriture. Utilisez clickhouse client pour les scripts à plusieurs statements, les chargements en masse et les requêtes longues. La liste d’autorisation d’adresses IP du service restreint les connexions directes, mais pas la route de l’API de requête qui passe par le proxy. Interroger un service inactif le réveille ; un service arrêté doit être démarré avec cloud service start. Gérez le point de terminaison de l’API de requêtes du service, les endpoints SQL nommés et les requêtes enregistrées :
query-endpoint create remplace les rôles de chaque clé associée à l’endpoint. Consultez Comportement du SQL et de l’API de requête.

Managed Postgres

cloud postgres permet de gérer ClickHouse Managed Postgres. Ces commandes sont en version bêta, et la prise en charge de GCP est en aperçu privé.
Les tailles AWS disponibles incluent m6gd.large, c6gd.xlarge et r6gd.xlarge. Sur GCP, passez --provider gcp avec une région GCP et une taille telle que c4-standard-lssd-4. Enregistrez le mot de passe et la chaîne de connexion renvoyés par create. Les réponses ultérieures de get ne renvoient jamais les identifiants : reset-password est le seul moyen d’en obtenir de nouveaux. Connectez-vous avec psql en utilisant sslmode=verify-full et le fichier de l’AC. Si vous omettez les indicateurs d’accès lors de la création, toutes les adresses IPv4 et IPv6 sont autorisées sur Postgres (5432) et PgBouncer (6432). Passez un --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION] par règle, ou --block-public-access pour n’appliquer aucune règle. Dès que vous spécifiez une règle, seules les règles indiquées s’appliquent. Surveillance et récupération :
cloud postgres query n’accepte que OAuth : la commande échoue donc tant qu’une source d’API key de priorité supérieure est active. metrics, slow-queries et prometheus couvrent la supervision. restore copie les règles d’accès IPv4 actuelles de la source sur le service restauré, sauf si vous passez --ip-allow ou --block-public-access. Les restaurations et les répliques sont renvoyées sans mot de passe. promote et switchover rendent la main dès que l’opération est acceptée ; après un promote, interrogez postgres get --json jusqu’à ce que la réplique indique isPrimary: true. Consultez le guide Managed Postgres.

ClickPipes

cloud clickpipe ingère des données depuis un stockage d’objet, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB et BigQuery. La création et la découverte du schéma nécessitent une API key et un service de destination en cours d’exécution. Chaque source dispose de sa propre sous-commande clickpipe create <source> ; exécutez-la avec --help pour afficher ses indicateurs. Chargez des fichiers depuis S3 à l’aide d’un rôle IAM. Commencez par découvrir le schéma, puis sélectionnez les colonnes :
Répliquez Postgres via CDC. Le certificat TLS est vérifié par défaut ; pour une source Managed Postgres, exportez son AC et transmettez-la :
--table-mapping crée des tables ReplacingMergeTree : lisez donc l’état courant avec FINAL WHERE _peerdb_is_deleted = 0. Un pipeline d’ingestion Kafka suit le même principe : exécutez clickpipe schema-discover kafka avec les mêmes indicateurs de source, puis transmettez les colonnes :
Par défaut, les pipelines d’ingestion BigQuery effectuent un snapshot. Pour la CDC, indiquez --replication-mode cdc, une --replication-method, ainsi qu’une colonne de watermark ou une fonction d’événements pour chaque table dans --table-mapping-json. Planifiez les synchronisations avec --sync-cron ou --sync-interval-seconds. Gérer les pipelines d’ingestion existants :
Les pipelines d’ingestion CDC doivent être à l’état Paused avant toute opération update : arrêtez le pipeline d’ingestion, interrogez get jusqu’à ce qu’il passe à l’état Paused, puis mettez-le à jour. Le service pouvant relancer le pipeline d’ingestion au cours de la mise à jour, n’exécutez start que si get affiche toujours Paused. L’option --start-paused est disponible pour le stockage d’objet, Kafka, Kinesis et Pub/Sub. Les autres groupes de commandes sont cdc-scaling, context get (disponibilité de la workload identity GCP et principal de sécurité) et reverse-private-endpoint. Consultez le guide ClickPipes et la référence de configuration ClickPipe.

ClickStack

cloud clickstack gère les sources, les tableaux de bord, les alertes, les webhooks, les recherches enregistrées et les rôles d’un service Managed ClickStack existant. Les ressources sont des fichiers JSON (--file, ou - pour stdin). Les lectures prennent en charge OAuth ; les écritures nécessitent une API key.
Chaque mise à jour de ClickStack remplace l’intégralité de la ressource. Enregistrez l’état actuel avec get --json et envoyez la définition complète, pas seulement les champs modifiés. Consultez le guide ClickStack.

UDFs dans Cloud

cloud udf gère les UDF exécutables au niveau de l’organisation, leurs versions et leurs associations aux services. deploy téléverse le répertoire que vous avez testé avec local udf, attend la fin de la construction, associe cette version au service, puis attend que son déploiement soit terminé :
Pour exécuter chaque étape vous-même, utilisez udf create, udf version create, udf attach (avec --wake pour un service inactif), udf detach et udf delete. Ces commandes rendent la main dès que la requête est acceptée ; interrogez ensuite udf get et udf attachment get pour suivre leur progression. Les lectures prennent en charge OAuth ; les écritures nécessitent une API key. Consultez le guide des fonctions définies par l’utilisateur.

Organisations et accès

Les sous-commandes cloud org acceptent --org-id, jamais un ID positionnel. org usage couvre une période de 31 jours au maximum. org propose également quota, balance, notification-types, role (rôles d’organisation personnalisés) et byoc (infrastructure BYOC). Les notifications sont en bêta. Gérez les membres, les invitations et les clés API :
Si vous omettez --ip-allow lors d’un key create, tout accès réseau est refusé, contrairement à la création d’un service. Le secret n’est affiché qu’une seule fois. key list ne renvoie qu’une seule page, sauf si vous passez --all. Lors d’un key update, les indicateurs omis conservent leurs paramètres, tandis que --clear-expiry, --clear-roles et --clear-ip-allow les suppriment.

Sauvegardes

La restauration crée toujours un nouveau service. cloud backup bucket (get, create, update, delete) configure votre propre bucket de sauvegarde (BYOB) à partir d’un fichier JSON spécifique au fournisseur. Consultez la section consacrée aux sauvegardes dans le guide du Service Cloud.

Sortie JSON

Les commandes qui renvoient des données structurées acceptent l’option --json, notamment les commandes locales, Cloud, skills, update et telemetry :
Lorsque la CLI détecte un agent de code (comme Claude Code, Cursor, Codex, Gemini CLI, Goose ou Devin, ou tout outil qui définit AI_AGENT), elle bascule automatiquement sur le JSON. Les clients SQL et natifs conservent leurs propres formats : cloud service query renvoie du JSONEachRow en mode JSON, et la sortie de local client est toujours au format natif. Les scripts qui analysent la sortie des requêtes doivent spécifier --format explicitement. En mode JSON, les erreurs d’exécution sont écrites sur stderr sous la forme d’un objet comportant un code stable et un message :
Basez votre logique conditionnelle sur error.code, et non sur le message. Les erreurs d’utilisation restent au format texte, avec le code de sortie 2. Consultez contrats d’automatisation et de sortie pour en savoir plus sur les formes de sortie et les codes d’erreur.

Codes de sortie

local client, local postgres client et les autres commandes qui délèguent à un client natif renvoient directement le code de sortie de ce client.

Compétences d’agent

Installez les ClickHouse agent skills officielles dans vos agents de code :
Par défaut, les compétences s’installent dans le projet en cours, ou dans votre répertoire personnel avec --global. Le répertoire partagé .agents/skills/ est toujours inclus. En l’absence de terminal, vous devez spécifier --agent, --all ou --detected-only. Exécutez clickhousectl skills --help pour obtenir la liste des noms d’agents pris en charge.

Mise à jour automatique

La CLI vérifie également en arrière-plan si des mises à jour sont disponibles, au plus une fois toutes les 24 heures, et affiche une notification lorsqu’une version plus récente est disponible.

Télémétrie

clickhousectl collecte des données d’utilisation anonymes afin d’orienter son développement. La première exécution affiche un avis et n’envoie aucune donnée ; la collecte débute lors d’une exécution ultérieure, sauf si vous la désactivez. Chaque événement contient :
  • Le chemin de la commande et les noms des indicateurs et arguments explicitement transmis, jamais leurs valeurs
  • Le résultat et le code de sortie
  • Pour une commande mal saisie, le nom de la commande ou de l’indicateur suggéré par la CLI, jamais ce que vous avez saisi
  • Pour les échecs à l’exécution, des catégories bornées : étape et type d’échec, un statut HTTP figurant dans une liste d’autorisation, ainsi que des catégories de nouvelle tentative, d’état de provisionnement et de durée
  • La version de la CLI, l’OS et l’architecture, l’exécution ou non en intégration continue, ainsi que l’agent de code détecté
Les valeurs des arguments, les requêtes SQL, les identifiants, les identifiants de ressources, les arguments placés après -- et les messages d’erreur ne sont jamais enregistrés. Aucun identifiant d’installation ou d’appareil n’est utilisé. Pour désactiver la collecte :
Définissez CHCTL_TELEMETRY_DEBUG=1 pour afficher la charge utile sur stderr sans rien envoyer. Pour en savoir plus, consultez la documentation sur la télémétrie.