Installation

Pathrule CLI est la surface de Pathrule pensée d'abord pour le terminal. Il est publié sur npm sous le nom @pathrule/cli, sous licence Apache-2.0, et fait tourner le serveur MCP local, le superviseur de hooks et le cache local pour les agents que vous pilotez depuis un shell. Cette page explique comment l'installer, vous connecter, connecter un dépôt et vos clients IA, l'utiliser sans compte, puis le retirer d'un projet. Toutes les commandes figurent dans la référence des commandes.

Prérequis

• macOS, Linux ou Windows.
• Node.js 20.11.1 ou plus récent. Le CLI vérifie la version à chaque exécution et s'arrête avec un message explicite si elle est trop ancienne.
• Un shell moderne : zsh, bash ou fish, ou PowerShell sous Windows.
• Un assistant de codage IA compatible MCP. Pathrule CLI connecte Claude Code, Codex, Cursor, Windsurf et GitHub Copilot. Ce n'est pas obligatoire pour l'installation, mais vous en aurez besoin pour vérifier le fonctionnement des hooks.

Installation

npm (macOS, Linux, Windows)

npm est la méthode d'installation sur les trois systèmes d'exploitation. Elle nécessite Node.js 20.11.1 ou plus récent.

npm install -g @pathrule/cli

Sous Windows, lancez cette commande depuis PowerShell. Pathrule enregistre automatiquement une commande de hook compatible Windows, si bien que les mêmes commandes pathrule y fonctionnent exactement comme dans un shell Unix.

Pour mettre à jour, relancez la même installation avec @latest :

npm install -g @pathrule/cli@latest

Une fois par jour, une exécution interactive vérifie s'il existe une version plus récente et affiche un avis d'une ligne avec cette commande. Cet avis ne mentionne jamais qu'une version plus récente que la vôtre. pathrule update effectue la même vérification à la demande, et pathrule config set update.policy manual désactive la vérification quotidienne.

Téléchargement direct

Il n'existe ni installeur autonome ni formule pour un gestionnaire de paquets. Installez Pathrule CLI via npm, quel que soit le système d'exploitation.

Vérification

pathrule --version

Le CLI affiche sa version et se termine avec le code zéro. Si la commande est introuvable, vérifiez que le répertoire d'installation globale de npm figure dans votre PATH, puis rouvrez le shell.

Connexion

L'utilisation de Cloud nécessite un compte. La configuration locale se passe de connexion ; voir Utiliser Pathrule sans compte. Par défaut, pathrule login vous connecte avec un code à usage unique. La même commande fonctionne sur votre propre ordinateur, via SSH et sur une machine sans interface graphique ou un runner de CI.

Flux par code d'appareil

pathrule login

Le CLI affiche un code à usage unique. Sur une machine équipée d'un navigateur, il ouvre la page d'approbation avec le code déjà renseigné : connectez-vous à votre compte Pathrule sur cette page et approuvez. Sur une machine sans interface graphique ou via SSH, ouvrez l'URL affichée sur n'importe quel appareil, saisissez le code et approuvez. Le terminal termine la connexion de lui-même, et votre mot de passe n'y transite jamais.

Passez --no-open pour empêcher le CLI d'ouvrir un navigateur. Il affiche alors l'URL. Les anciens guides utilisent pathrule login --device-code, qui est toujours accepté et lance ce même flux.

Flux PKCE via le navigateur

pathrule login --browser-callback

Cette commande vous connecte avec GitHub dans un navigateur sur la même machine, puis renvoie la session au terminal via un callback sur votre propre machine, sécurisé par PKCE. Si votre compte utilise l'authentification à deux facteurs, le CLI vous demande le code. Ce flux nécessite un terminal interactif et un navigateur. Quand le callback n'est pas utilisable, le CLI le signale et bascule sur le flux par code d'appareil ; avec --no-open ou dans un script, il utilise d'emblée le flux par code d'appareil.

pathrule whoami indique le compte avec lequel vous êtes connecté. pathrule logout déconnecte le CLI, et pathrule logout --all déconnecte aussi les autres surfaces Pathrule de cette machine, comme l'extension VS Code.

Rattacher un espace de travail

L'espace de travail est l'unité à laquelle Pathrule rattache le contenu. Le CLI rattache toujours le dossier depuis lequel vous le lancez : placez-vous donc d'abord dans le dépôt. Aucune option ne permet de passer un chemin.

La voie guidée fait tout en une seule exécution :

cd ~/repos/my-team
pathrule setup

pathrule setup commence par vous faire choisir Pathrule Cloud ou Local. Cloud est le point de départ géré recommandé, avec comptes, organisations et intelligence partagée. Local tourne sur cette machine et ne nécessite aucun compte. La configuration connecte l'espace de travail et les clients IA que vous choisissez. Sur un Mac Apple Silicon, elle propose aussi le modèle embarqué, facultatif, que vous pouvez ignorer.

La configuration Cloud peut rattacher un espace de travail existant ou en créer un pour ce dossier. Le runtime local assure ensuite la livraison via la configuration des clients pris en charge et les hooks.

Pour procéder étape par étape :

cd ~/repos/my-team
pathrule workspace list
pathrule workspace attach my-team

pathrule workspace attach prend le nom exact de l'espace de travail ou son identifiant. Sans argument, la commande rattache votre espace de travail actuel. Pour créer plutôt un nouvel espace, pathrule init en crée un portant le nom du dossier et le rattache en une seule étape, et pathrule init my-team ou pathrule workspace create my-team font de même avec le nom que vous indiquez. Les espaces de travail proviennent de votre organisation actuelle : pathrule org list affiche les vôtres et pathrule org use <slug> permet d'en changer.

Une fois le rattachement effectué, chaque fois que vous lancez un client IA dans ce dossier ou en dessous, le runtime sait quel contenu d'espace de travail servir.

Dans un script, pathrule setup reçoit ses réponses sous forme d'options et a besoin de --yes pour agir :

pathrule setup --workspace my-team --target all --yes

Connecter vos clients IA

pathrule setup vous demande quels clients IA vous utilisez, les installe et mémorise ce choix pour cet espace de travail. Pour en connecter un manuellement :

pathrule install cursor
pathrule sync

pathrule install accepte claude, cursor, codex, windsurf ou copilot, et sans client il installe les cinq. La commande écrit l'entrée du serveur MCP de Pathrule dans la configuration utilisateur propre à ce client, sans toucher aux autres serveurs qui s'y trouvent. GitHub Copilot reçoit deux entrées, une pour le Copilot CLI et une pour VS Code. pathrule uninstall <client> retire l'entrée.

pathrule sync écrit dans le dépôt les fichiers que lisent vos clients et rafraîchit l'index local des hooks. Lancez la commande dans le dossier auquel l'espace de travail est rattaché, après le rattachement et chaque fois que vous voulez aligner ces fichiers sur l'espace de travail. Elle écrit pour les clients IA choisis pour cet espace de travail dans pathrule setup. Si aucun n'a été choisi, elle écrit pour les clients dont les fichiers Pathrule sont déjà présents dans le dépôt, et pour Claude Code s'il n'y en a aucun. pathrule sync --skills copie les skills de l'espace de travail dans les dossiers de skills de vos clients.

Ce que Pathrule écrit dans votre dépôt

Pathrule écrit aux emplacements que chaque client lit déjà : rien de nouveau n'est donc à configurer côté client.

Pathrule marque ce qu'il écrit : ses fichiers d'instructions portent une bannière Pathrule, et tout ce qu'il ajoute à l'un de vos fichiers se trouve dans un bloc balisé. Quand un fichier d'instructions comme CLAUDE.md ou AGENTS.md contient déjà votre propre contenu, Pathrule sauvegarde votre version avant d'écrire, ou écrit dans son bloc balisé sans toucher au reste du fichier. Un dossier .pathrule à la racine du dépôt conserve la liste des fichiers gérés par Pathrule, ainsi que ces sauvegardes. Les skills synchronisés avec pathrule sync --skills vont dans le dossier de skills de chaque client, comme .claude/skills/, et si le dépôt contient un .gitignore, Pathrule y ajoute une section commentée qui exclut ces dossiers de git jusqu'à ce que vous la supprimiez.

Hors du dépôt, pathrule install écrit les entrées MCP dans la configuration utilisateur de chaque client, et le CLI conserve sa session, son cache et son script de hook dans votre répertoire Pathrule, ~/.pathrule par défaut.

Pour voir ce que Pathrule gère dans un dossier sans rien modifier, lancez pathrule doctor, qui liste chaque fichier géré avec la surface et la version qui l'ont écrit. Les pages consacrées aux clients vont plus loin : Claude Code, Codex, Cursor, Windsurf et GitHub Copilot.

Utiliser Pathrule sans compte

Pathrule CLI peut aussi tourner entièrement sur votre machine, sans compte ni cloud. Dans le projet :

cd ~/repos/my-project
pathrule setup --local

pathrule init --local crée un espace de travail local pour le dossier courant. pathrule setup --local fait de même, puis installe l'entrée MCP locale pour chaque client IA, ou pour un seul avec --target <client>, installe les hooks et écrit les fichiers du dépôt, le tout sans connexion. Votre agent écrit des mémoires, des règles et des skills via les outils MCP de Pathrule, et vous les consultez et les recherchez depuis le terminal avec --local, par exemple pathrule memory list --local. Consultez Travailler sans compte pour toutes les commandes locales et Cœur open source pour le contenu de l'édition locale.

Configuration exclusivement open source

Pathrule CLI est lui-même open source sous licence Apache-2.0, et le mode local le fait tourner sans compte ni service cloud. Le modèle embarqué que la configuration propose sur un Mac Apple Silicon est facultatif : refusez-le quand la configuration vous le demande, ou supprimez-le plus tard avec pathrule intelligence remove. Tout ce qui ne dépend pas du modèle continue de fonctionner sans lui. Cœur open source indique ce qui est open source aujourd'hui et ce qui est propriétaire.

Vérifier le câblage

Doctor est la commande unique qui confirme la configuration de bout en bout. Elle se contente de lire et ne modifie jamais rien.

pathrule doctor

Elle vérifie que :

• Vous êtes connecté, et une organisation et un espace de travail sont sélectionnés.
• Le dossier courant est bien celui auquel l'espace de travail est rattaché.
• L'entrée MCP de Pathrule est installée pour chaque client IA.
• Les fichiers gérés par Pathrule dans ce dossier sont listés avec la surface et la version qui ont écrit chacun d'eux. Un fichier écrit par une autre surface ou par une version plus récente est signalé.

Quand un point demande votre attention, doctor indique la commande suivante, comme pathrule login ou pathrule attach <workspace>. pathrule doctor --json renvoie le rapport complet pour un script, qui couvre aussi la version de Node.js et signale toute entrée MCP dont la commande de lancement est obsolète, et la commande se termine avec un code non nul quand une vérification échoue. Une entrée obsolète se corrige avec pathrule repair, qui réécrit les entrées de Pathrule dans les configurations de vos clients, ne touche à aucun autre serveur et réécrit les fichiers du dépôt.

Retirer Pathrule d'un projet

Commencez par afficher le plan, en lecture seule, depuis le dépôt :

pathrule eject

Il liste les fichiers appartenant à Pathrule et les zones gérées, y compris la restauration éventuelle de votre contenu antérieur. Relisez ce plan, puis appliquez-le explicitement :

pathrule eject --apply

Pour un dossier rattaché à Cloud, pathrule detach déconnecte le dossier local sans supprimer l'espace de travail Cloud. L'extension VS Code peut aussi détacher son dossier.

Les intégrations natives ont leur propre configuration enregistrée. Utilisez pathrule integrations remove <agent> pour en retirer une. Les entrées MCP installées dans les paramètres avec pathrule install se retirent avec pathrule uninstall <client>. Ces opérations préservent les paramètres et serveurs des clients qui ne concernent pas Pathrule.

Pour aller plus loin

• Référence des commandes pour toutes les commandes et options.
• Démarrage rapide pour écrire votre première mémoire et voir le hook se déclencher.
• Fonctionnement des hooks pour comprendre le modèle que doctor vérifie.
• Présentation du MCP pour les outils que l'assistant appelle une fois le runtime lancé.