# La CLI Pilot Source : https://pilot.braike.com/docs/cli Brancher Pilot MCP depuis le terminal avec la commande pilot. Connexion, inscription dans vos assistants, pont stdio, skills, appels d'outils et diagnostic. La CLI Pilot (`@braike/pilot`, commande `pilot`) branche Pilot MCP depuis votre terminal, sans copier de configuration à la main. Elle vous connecte par votre navigateur, inscrit le serveur Pilot dans vos assistants, sert de pont aux clients qui ne lancent que des programmes locaux, installe les skills, et interroge Pilot depuis un script. ## Installer [#installer] Il faut Node.js 20 ou plus. Sans rien installer, `npx` télécharge la CLI et la lance : ```bash title="Terminal" npx @braike/pilot setup ``` Pour garder la commande `pilot` sous la main, installez-la une fois pour toutes : ```bash title="Terminal" npm install -g @braike/pilot pilot --version ``` Les exemples de cette page écrivent `pilot` ; avec `npx`, remplacez `pilot` par `npx @braike/pilot`. ## En deux commandes [#demarrage] ```bash title="Terminal" npx @braike/pilot login npx @braike/pilot setup ``` `login` ouvre l'écran d'autorisation de Pilot dans votre navigateur ; `setup` trouve les assistants installés sur votre ordinateur et y inscrit Pilot. Redémarrez ensuite votre assistant et posez-lui une question. ## Les commandes [#commandes] ### `pilot login` [#login] Ouvre la connexion à Pilot dans votre navigateur (OAuth 2.1). Vous choisissez l'espace à partager et gardez le niveau **Lecture**, comme pour un assistant (voir [l'écran d'autorisation](/docs/brancher-son-assistant#autorisation)). La CLI garde ensuite le jeton reçu sur votre ordinateur. ```bash title="Terminal" pilot login pilot login --workspace pilot login --no-browser ``` `--workspace` verrouille l'autorisation sur un espace, comme l'adresse d'un espace. `--no-browser` affiche l'adresse à ouvrir au lieu d'ouvrir le navigateur, par exemple sur un serveur. ### `pilot logout` [#logout] Révoque l'accès de la CLI auprès de Pilot, puis efface les jetons gardés sur cet ordinateur. Sans `--workspace`, toutes les connexions de l'adresse. ```bash title="Terminal" pilot logout pilot logout --workspace ``` Quand Pilot ne peut pas répondre (indisponibilité, réseau), la connexion est gardée et la commande échoue, pour être relancée. `--force` l'oublie quand même sur cet ordinateur. ### `pilot status` [#status] Dit si la CLI est connectée, à quelle adresse, pour quel espace, à quel niveau, jusqu'à quand, et si elle peut renouveler le jeton seule. Elle n'affiche jamais de jeton, et rend le code 1 quand aucune connexion n'est utilisable. ```bash title="Terminal" pilot status ``` ### `pilot setup` [#setup] Inscrit le serveur Pilot dans les assistants trouvés sur votre ordinateur. Sans `--client`, la CLI l'inscrit dans chacun d'eux ; `--all` le dit explicitement. ```bash title="Terminal" pilot setup pilot setup --client cursor pilot setup --client claude-code --client vscode pilot setup --client cursor --dry-run pilot setup --client generic ``` | Option | Effet | | --- | --- | | `--client ` | Inscrit Pilot dans cet assistant seulement ; se répète. | | `--all` | Inscrit Pilot dans tous les assistants trouvés. | | `--workspace ` | Inscrit l'adresse d'un espace, `https://app.pilot.braike.com/mcp/`. | | `--transport remote` ou `stdio` | Adresse distante, ou pont local `pilot mcp` pour chaque assistant. | | `--name ` | Nomme l'entrée autrement que `pilot`, par exemple une entrée par espace. | | `--dry-run` | Montre le changement sans rien écrire, et le vrai fichier quand un lien y mène. | | `--force` | Écrit quand même dans les trois cas laissés à vous (voir plus bas). | Les assistants pris en charge, le nom à donner à `--client`, et ce que la CLI écrit : | Assistant | `--client` | Ce que la CLI écrit | | --- | --- | --- | | Claude Desktop | `claude-desktop` | le pont local, dans `claude_desktop_config.json` | | Claude Code | `claude-code` | `claude mcp add --transport http --scope user` quand la commande `claude` est installée, sinon `~/.claude.json` | | Cursor | `cursor` | `~/.cursor/mcp.json` | | VS Code | `vscode` | le fichier `mcp.json` de votre profil utilisateur | | VS Code Insiders | `vscode-insiders` | le même, dans le dossier `Code - Insiders` | | Windsurf (Devin Desktop) | `windsurf` | `~/.config/devin/mcp_config.json`, et `~/.codeium/windsurf/mcp_config.json` pour une installation d'avant le changement de nom | | Codex et l'application ChatGPT de bureau | `codex` | `~/.codex/config.toml` | | Gemini CLI | `gemini` | `~/.gemini/settings.json` | | Tout autre client MCP | `generic` | rien : la CLI affiche la configuration à copier | Un assistant qui parle MCP à distance reçoit l'adresse de Pilot et se connecte lui-même au premier usage, par le même écran d'autorisation : Claude Code avec `/mcp` (ou `claude mcp login pilot`), Codex avec `codex mcp login pilot`, Gemini CLI avec `/mcp auth pilot` ; Cursor, VS Code et Windsurf ouvrent la page d'autorisation au premier usage. La configuration de Claude Desktop ne garde que des serveurs locaux : il reçoit le pont `pilot mcp`, connecté par `pilot login`. Claude sur claude.ai et ChatGPT dans le navigateur se branchent depuis leur interface : voir [Brancher son assistant](/docs/brancher-son-assistant). Avant de modifier un fichier, la CLI en garde une copie datée dans `~/.config/pilot/backups/` ; relancée, elle ne crée pas de doublon. Seule l'entrée Pilot change : un fichier JSON est réécrit avec sa propre indentation, et dans le TOML de Codex seule la table de Pilot change. Trois cas vous sont laissés, sauf `--force` : - un fichier dont le vrai chemin, liens suivis, sort de votre dossier personnel et des dossiers de configuration (`XDG_CONFIG_HOME`, `APPDATA`, `LOCALAPPDATA`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR`) ; - une entrée du même nom qui n'est pas celle de Pilot : choisissez un autre nom avec `--name` ; - un fichier JSON avec des commentaires, que `--force` réécrit sans eux. ### `pilot remove` [#remove] Retire l'entrée Pilot de la configuration des assistants, sans toucher au reste. Une entrée du même nom qui n'est pas celle de Pilot reste en place, sauf `--force`. ```bash title="Terminal" pilot remove --client cursor pilot remove --all --dry-run ``` Options : `--client `, `--all`, `--name `, `--dry-run`, `--force`. ### `pilot mcp` [#mcp] Lance un serveur MCP local en stdio qui relaie le serveur distant de Pilot : c'est le pont des assistants qui ne savent lancer qu'un programme local. Dans la configuration d'un tel assistant : ```json title="Configuration d'un client stdio" { "mcpServers": { "pilot": { "command": "npx", "args": ["-y", "@braike/pilot", "mcp"] } } } ``` - **Identifiant** : la [clé d'accès](/docs/brancher-son-assistant#autres) de la variable `PILOT_API_KEY` quand elle est définie, sinon la connexion de `pilot login`, relue à chaque requête : une connexion faite ailleurs sert tout de suite. Le pont renouvelle le jeton avant qu'il expire. - **Sans connexion**, le pont ouvre lui-même la connexion à Pilot dans votre navigateur et répond une erreur à l'assistant le temps que vous vous connectiez ; réessayez ensuite. Quand aucun navigateur ne peut s'ouvrir (un serveur, `PILOT_NO_BROWSER`), chaque requête reçoit une erreur qui dit de lancer `npx @braike/pilot login`. - **Un espace précis** : `--workspace `, ou la variable `PILOT_WORKSPACE`. ### `pilot tools` [#tools] Liste les outils que Pilot vous sert, un par ligne. ```bash title="Terminal" pilot tools pilot tools --json | jq '.[].name' ``` ### `pilot call` [#call] Appelle un outil et affiche sa réponse. Un outil en erreur rend le code de sortie 1, pour les scripts. ```bash title="Terminal" pilot call pilot_data_freshness pilot call google_get_campaign_performance --arg customer_id=1234567890 --arg date_range=LAST_7_DAYS pilot call google_analytics_run_report --json-args '{"dateRanges":[{"startDate":"28daysAgo","endDate":"yesterday"}],"dimensions":["sessionDefaultChannelGroup"],"metrics":["sessions"]}' ``` `--arg cle=valeur` se répète et suit le type que déclare le schéma de l'outil : un nombre, un booléen, une liste ou un objet sont lus comme tels, le reste reste du texte. `--arg cle:=` passe une valeur JSON telle quelle. `--json-args` passe un objet, que les `--arg` complètent ou remplacent. Les outils et leurs paramètres sont sur [Les régies et leurs outils](/docs/regies). ### `pilot skills list` et `pilot skills install` [#skills] Liste le catalogue des [skills](/docs/skills) et les installe là où votre assistant les lit. ```bash title="Terminal" pilot skills list pilot skills install pilot skills install google-ads-account-audit --target claude-code pilot skills install --target claude --out ./archives pilot skills install --target ./.github/skills ``` | `--target` | Où | | --- | --- | | `claude-code` | `~/.claude/skills//` | | `codex` | `~/.agents/skills//`, lu par Codex et l'application ChatGPT de bureau | | `cursor` | `~/.cursor/skills//` | | `claude` | une archive `.zip` dans `--out` (par défaut le dossier courant), à téléverser dans Claude : **Customize**, **Skills**, **+**, **+ Create skill**, **Upload a skill** | | un chemin | ce dossier, par exemple `./.github/skills` pour VS Code | Sans nom de skill, la CLI installe tout le catalogue ; sans `--target`, elle installe dans chaque assistant trouvé parmi Claude Code, Codex et Cursor. Elle remplace le dossier d'une skill d'un bloc ; un dossier modifié à la main depuis son installation reste tel quel, sauf `--force`. `--dry-run` montre ce qui serait installé. La CLI lit le catalogue que publie cette documentation, `https://pilot.braike.com/skills/index.json`, et vérifie la taille et l'empreinte SHA-256 de chaque fichier avant d'écrire : un seul écart refuse la skill entière. ### `pilot doctor` [#doctor] Vérifie votre installation : version de Node.js, version de la CLI au regard de la dernière publiée, accès au réseau, découverte de la connexion de Pilot, validité de votre identifiant, et assistants configurés. Une version plus récente n'est qu'un avertissement, avec la commande de mise à jour. Une vérification en échec rend le code 1. Voir [Dépannage](#depannage). ```bash title="Terminal" pilot doctor ``` ### `pilot open` [#open] Ouvre la console de votre espace, la page **Claude et ChatGPT**, dans votre navigateur ; sans espace connu, la liste de vos espaces. `--no-browser` affiche l'adresse. ```bash title="Terminal" pilot open pilot open --workspace ``` `pilot --version` donne la version, `pilot help ` l'aide d'une commande. ## Options communes [#options] | Option | Effet | | --- | --- | | `--base-url ` | Adresse de Pilot (par défaut `https://app.pilot.braike.com`). La CLI refuse toute adresse qui n'est pas celle de Pilot. | | `--allow-local` | Accepte une adresse locale (`http://localhost:3000`), pour le développement seulement. | | `--json` | Sortie JSON, pour les scripts. | | `--lang fr` ou `en` | Langue des messages ; sinon `PILOT_LANG`, puis la langue de votre système. | | `--verbose` | Détail de ce que fait la CLI, sans jamais afficher de jeton, de clé ni de secret. | | `-h`, `--help` | Aide de la commande. | ## Variables d'environnement [#environnement] | Variable | Usage | | --- | --- | | `PILOT_API_KEY` | Une clé d'accès (`ulys_...`), employée par `mcp`, `tools`, `call` et `doctor` au lieu de la connexion. | | `PILOT_WORKSPACE` | L'espace, quand `--workspace` n'est pas donné. | | `PILOT_BASE_URL` | L'adresse de Pilot, quand `--base-url` n'est pas donné. | | `PILOT_CONFIG_DIR` | Le dossier de la CLI au lieu de `~/.config/pilot`. | | `PILOT_LANG` | `fr` ou `en`. | | `PILOT_NO_BROWSER` | `1` : n'ouvre jamais de navigateur (c'est aussi le cas sur une machine Linux sans écran). | | `PILOT_LOGIN_TIMEOUT_MS` | Durée d'attente de la connexion par le navigateur, en millisecondes (5 minutes par défaut). | | `npm_config_registry` | Le registre que `doctor` interroge pour la dernière version (par défaut celui de npm). | ## Codes de sortie [#codes-de-sortie] | Code | Sens | | --- | --- | | `0` | Réussite. | | `1` | Échec : un outil en erreur, aucune connexion utilisable pour `status`, une connexion gardée par `logout` faute de réponse de Pilot, un fichier laissé à vous par `setup` ou `remove`, une vérification de `doctor` en échec. | | `2` | Erreur d'usage : commande ou option inconnue, valeur manquante. | ## Sécurité [#securite] - **Vos jetons restent chez vous**, dans `~/.config/pilot/credentials.json` : un dossier que vous seul pouvez lire (droits 0700, fichier 0600), écrit d'un bloc. Des droits relâchés sont resserrés ; sous Windows, la protection de votre profil utilisateur s'applique. - **Un jeton ne part que vers l'adresse qui l'a émis.** Les métadonnées du serveur d'autorisation doivent nommer l'adresse choisie, et chacun de ses points d'accès lui appartenir, sinon la connexion est refusée. Les redirections ne sont jamais suivies. - **Seulement les adresses de Pilot**, en HTTPS ; une adresse locale seulement avec `--allow-local`. - **Connexion OAuth 2.1** : PKCE `S256` et `state` vérifié, retour sur `http://127.0.0.1` à un port choisi au hasard, client enregistré une fois puis réutilisé, indicateur de ressource. `pilot logout` révoque les jetons, et une nouvelle connexion révoque, quand elle le peut, le jeton qu'elle remplace. - **Rien d'affiché** : aucun jeton, aucune clé, aucun code ni secret, même avec `--verbose`. Les séquences de contrôle d'un texte venu d'un serveur sont retirées. - **Vos configurations protégées** : copie datée avant tout changement, seule l'entrée Pilot change, aucune écriture hors de vos dossiers ni sur l'entrée d'un autre sans `--force`, et `--dry-run` pour voir avant. - **Aucune dépendance** : le paquet ne s'appuie que sur Node.js, sans aucun autre paquet npm : aucun paquet tiers ne touche à vos jetons. ## Dépannage [#depannage] Lancez d'abord `pilot doctor` : chaque vérification en échec dit où chercher. La CLI exige Node.js 20 ou plus. Vérifiez avec `node --version`, puis mettez Node.js à jour. `pilot doctor` le signale avec la commande de mise à jour : `npm install -g @braike/pilot@latest`. Avec `npx`, la dernière version est prise toute seule. Reconnectez-vous avec `pilot login`. Si votre accès a été retiré dans la console, l'ancien jeton ne sert plus. `pilot status` dit si une connexion est encore utilisable. Le pont `pilot mcp` a ouvert la connexion dans votre navigateur : terminez-la, puis reposez votre question. Si aucune fenêtre ne s'est ouverte, lancez `npx @braike/pilot login`. Le message dit pourquoi : une entrée `pilot` qui n'est pas celle de Pilot (choisissez un autre nom avec `--name`), un fichier avec des commentaires, ou un fichier hors de vos dossiers. `--dry-run` montre le changement ; `--force` l'écrit quand même. Relancez `pilot setup --client `, en ajoutant `--dry-run` pour voir le changement, puis redémarrez l'assistant. `pilot remove --client ` retire l'inscription si vous voulez repartir de zéro. Vérifiez l'adresse : `https://app.pilot.braike.com`, avec `app.`. Derrière un proxy d'entreprise, demandez l'accès à `app.pilot.braike.com`. `--verbose` détaille la requête qui échoue, sans secret. `pilot tools` liste ce que Pilot vous sert. Une régie absente n'est pas connectée à l'espace, n'a aucun compte choisi, ou n'est pas comprise dans votre forfait : voir [Erreurs et dépannage](/docs/erreurs#depannage).