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
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.
~/.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
.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 :
--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 comme18-alpine ; les nouvelles instances utilisent la version 18 par défaut.
.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).
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
~/.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 :.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 :- Les indicateurs
--api-keyet--api-secret .clickhouse/credentials.json- Les variables d’environnement exportées
- Les variables définies dans le fichier
.envdu répertoire courant - Les jetons OAuth globaux
--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 :
--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 doncget jusqu’à ce que la ressource atteigne l’état souhaité.
Services
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 :
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_adminsi 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 afficheBinding the authenticated API key to the Query API endpoint for service '<name>'...sur stderr. Passez--no-auto-enablepour que la commande échoue plutôt.
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é.
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 :
--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 :
--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 :
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.
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é :
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
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 :
--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
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 :
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 :
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 :--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
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é
-- 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 :
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.