Installazione

Pathrule CLI è l'interfaccia di Pathrule pensata per il terminale. È pubblicata su npm come @pathrule/cli con licenza Apache-2.0 ed esegue il server MCP locale, il supervisore degli hook e la cache locale per gli agenti che guidi da una shell. Questa pagina spiega come installarla, accedere, collegare un repository e i tuoi client IA, usarla senza account e rimuoverla di nuovo da un progetto. Tutti i comandi sono elencati nel riferimento dei comandi.

Requisiti

• macOS, Linux o Windows.
• Node.js 20.11.1 o successivo. La CLI controlla la versione a ogni esecuzione e, se è più vecchia, si ferma con un messaggio chiaro.
• Una shell moderna: zsh, bash o fish, oppure PowerShell su Windows.
• Un assistente di programmazione IA che supporti MCP. Pathrule CLI collega Claude Code, Codex, Cursor, Windsurf e GitHub Copilot. Non è necessario per l'installazione, ma ti servirà per verificare il flusso degli hook.

Installazione

npm (macOS, Linux, Windows)

npm è il metodo di installazione su tutti e tre i sistemi operativi. Richiede Node.js 20.11.1 o successivo.

npm install -g @pathrule/cli

Su Windows esegui il comando da PowerShell. Pathrule registra automaticamente un comando hook compatibile con Windows, quindi gli stessi comandi pathrule funzionano esattamente come in una shell Unix.

Per aggiornare, esegui la stessa installazione con @latest:

npm install -g @pathrule/cli@latest

Una volta al giorno, un'esecuzione interattiva controlla se c'è una release più recente e stampa un avviso di una riga con questo comando. Indica sempre e solo una versione più recente della tua. pathrule update esegue lo stesso controllo su richiesta, e pathrule config set update.policy manual disattiva il controllo giornaliero.

Download diretto

Non esistono un installer autonomo né una formula per gestori di pacchetti. Installa Pathrule CLI tramite npm su tutti i sistemi operativi.

Verifica

pathrule --version

La CLI stampa la sua versione ed esce con codice zero. Se il comando non viene trovato, assicurati che la cartella di installazione globale di npm sia nel PATH e riapri la shell.

Accesso

L'uso con Cloud richiede un account. La configurazione locale salta l'accesso; vedi Usarla senza account. Per impostazione predefinita pathrule login accede con un codice monouso. Lo stesso comando funziona sul tuo computer, via SSH e su una macchina headless o un runner di CI.

Flusso con codice dispositivo

pathrule login

La CLI stampa un codice monouso. Su una macchina con browser apre la pagina di approvazione con il codice già inserito: lì accedi al tuo account Pathrule e approvi. Su una macchina headless o via SSH, apri l'URL stampato su qualsiasi dispositivo, inserisci il codice e approva. Il terminale completa l'accesso da solo, e la tua password non vi transita mai.

Passa --no-open per impedire del tutto alla CLI di aprire un browser: stampa invece l'URL. Le guide meno recenti usano pathrule login --device-code, che è ancora accettato ed esegue questo stesso flusso.

Flusso PKCE nel browser

pathrule login --browser-callback

Questo comando accede con GitHub in un browser sulla stessa macchina e restituisce la sessione al terminale tramite un callback sulla tua macchina, protetto con PKCE. Se il tuo account usa l'autenticazione a due fattori, la CLI ti chiede il codice. In questo caso servono un terminale interattivo e un browser. Quando il callback non è utilizzabile, la CLI lo segnala e prosegue con il flusso con codice dispositivo; con --no-open o in uno script usa il flusso con codice dispositivo fin dall'inizio.

pathrule whoami mostra l'account con cui hai effettuato l'accesso. pathrule logout disconnette la CLI, e pathrule logout --all disconnette anche le altre interfacce di Pathrule su questa macchina, come l'estensione per VS Code.

Collegare un workspace

Il workspace è l'unità a cui Pathrule associa i contenuti. La CLI collega sempre la cartella in cui la esegui, quindi spostati prima nel repository. Non esiste un'opzione che accetti un percorso.

La procedura guidata fa tutto in un'unica esecuzione:

cd ~/repos/my-team
pathrule setup

pathrule setup inizia chiedendoti di scegliere tra Pathrule Cloud e Local. Cloud è il punto di partenza gestito consigliato, con account, organizzazioni e intelligenza condivisa. Local funziona su questa macchina e non richiede alcun account. Il setup collega il workspace e i client IA che scegli. Su un Mac con Apple Silicon propone anche il modello on-device opzionale, che puoi saltare.

Il setup Cloud può collegare un workspace esistente o crearne uno per questa cartella. Il runtime locale distribuisce poi i contenuti tramite la configurazione e gli hook dei client supportati.

Per procedere un passo alla volta:

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

pathrule workspace attach accetta il nome esatto del workspace o il suo id. Senza argomenti collega il tuo workspace corrente. Per iniziare invece con un nuovo workspace, pathrule init ne crea uno con il nome della cartella e lo collega in un solo passaggio, mentre pathrule init my-team o pathrule workspace create my-team fanno lo stesso con il nome che indichi. I workspace provengono dalla tua organizzazione corrente: pathrule org list mostra le tue organizzazioni e pathrule org use <slug> ti fa passare a un'altra.

Dopo il collegamento, ogni volta che esegui un client IA in questa cartella o in una sottocartella, il runtime sa quale workspace deve fornire i contenuti.

In uno script, pathrule setup riceve le risposte come opzioni e ha bisogno di --yes per agire:

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

Collegare i client IA

pathrule setup ti chiede quali client IA usi, li installa e ricorda la scelta per questo workspace. Per collegarne uno a mano:

pathrule install cursor
pathrule sync

pathrule install accetta claude, cursor, codex, windsurf o copilot, e senza un client li installa tutti e cinque. Scrive la voce del server MCP di Pathrule nella configurazione a livello utente di quel client e lascia intatti tutti gli altri server. GitHub Copilot riceve due voci, una per la Copilot CLI e una per VS Code. pathrule uninstall <client> rimuove di nuovo la voce.

pathrule sync scrive nel repository i file letti dai tuoi client e aggiorna l'indice locale degli hook. Eseguilo nella cartella a cui è collegato il workspace, dopo il collegamento e ogni volta che vuoi allineare quei file al workspace. Scrive per i client IA scelti per questo workspace in pathrule setup. Se non ne è stato scelto nessuno, scrive per i client i cui file Pathrule sono già presenti nel repository, e per Claude Code se non ce n'è nessuno. pathrule sync --skills copia le skill del workspace nelle cartelle delle skill dei tuoi client.

Cosa scrive Pathrule nel repository

Pathrule scrive nei punti che ciascun client legge già, quindi non serve configurare nulla di nuovo nel client.

Pathrule contrassegna ciò che scrive: i suoi file di istruzioni riportano un banner Pathrule, e tutto ciò che aggiunge a un tuo file si trova all'interno di un blocco contrassegnato. Quando un file di istruzioni come CLAUDE.md o AGENTS.md contiene già contenuti tuoi, Pathrule salva la tua versione come backup prima di scrivere, oppure scrive all'interno del suo blocco contrassegnato e lascia intatto il resto del file. Una cartella .pathrule nella radice del repository conserva il registro di Pathrule dei file che gestisce, insieme a quei backup. Le skill sincronizzate con pathrule sync --skills finiscono nella cartella delle skill di ciascun client, ad esempio .claude/skills/, e quando il repository ha un .gitignore, Pathrule aggiunge una sezione commentata che tiene quelle cartelle fuori da git finché non la elimini.

Fuori dal repository, pathrule install scrive le voci MCP nella configurazione a livello utente di ciascun client, e la CLI conserva sessione, cache e script degli hook nella tua home di Pathrule, per impostazione predefinita ~/.pathrule.

Per vedere cosa gestisce Pathrule in una cartella senza modificare nulla, esegui pathrule doctor, che elenca ogni file gestito con l'interfaccia e la versione che lo hanno scritto. Le pagine dei singoli client approfondiscono: Claude Code, Codex, Cursor, Windsurf e GitHub Copilot.

Usarla senza account

Pathrule CLI può anche funzionare interamente sulla tua macchina, senza account e senza cloud. All'interno del progetto:

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

pathrule init --local crea un workspace locale per la cartella corrente. pathrule setup --local fa lo stesso, poi installa la voce MCP locale per tutti i client IA, o per uno solo con --target <client>, installa gli hook e scrive i file del repository, il tutto senza accedere. Il tuo agente scrive memorie, regole e skill tramite gli strumenti MCP di Pathrule, e tu le leggi e le cerchi dal terminale con --local, ad esempio pathrule memory list --local. Consulta Lavorare senza account per tutti i comandi locali e Core open source per sapere cosa include l'edizione locale.

Configurazione solo open source

Pathrule CLI è di per sé open source con licenza Apache-2.0, e la modalità locale la esegue senza account e senza alcun servizio cloud. Il modello on-device che il setup propone su un Mac con Apple Silicon è opzionale: rifiutalo quando il setup te lo chiede, oppure rimuovilo in seguito con pathrule intelligence remove. Tutto ciò che non ha bisogno del modello continua a funzionare senza. Core open source elenca cosa è open source oggi e cosa è proprietario.

Verificare i collegamenti

Il doctor è l'unico comando che conferma la configurazione da cima a fondo. Si limita a leggere e non modifica mai nulla.

pathrule doctor

Controlla che:

• Tu abbia effettuato l'accesso e che siano selezionati un'organizzazione e un workspace.
• La cartella corrente sia quella a cui è collegato il workspace.
• Ogni client IA abbia installata la voce MCP di Pathrule.
• I file gestiti da Pathrule in questa cartella siano in ordine, con l'interfaccia e la versione che hanno scritto ciascuno. Un file scritto da un'altra interfaccia o da una versione più recente viene segnalato.

Quando qualcosa richiede attenzione, doctor indica il comando successivo, ad esempio pathrule login o pathrule attach <workspace>. pathrule doctor --json restituisce il report completo per uno script, che copre anche la versione di Node.js e segnala una voce MCP il cui comando di avvio non è aggiornato, ed esce con un codice diverso da zero quando un controllo fallisce. Una voce non aggiornata si corregge con pathrule repair, che riscrive le voci di Pathrule nelle configurazioni dei client, lascia intatti tutti gli altri server e riscrive i file del repository.

Rimuovere Pathrule da un progetto

Parti dal piano di sola lettura, eseguito dal repository:

pathrule eject

Elenca i file di proprietà di Pathrule e le sezioni gestite, compreso l'eventuale ripristino dei tuoi contenuti precedenti. Esamina il piano, poi applicalo in modo esplicito:

pathrule eject --apply

Per una cartella collegata a Cloud, pathrule detach scollega la cartella locale senza eliminare il workspace Cloud. Anche l'estensione per VS Code può scollegare la propria cartella.

Le integrazioni native hanno una propria configurazione registrata. Usa pathrule integrations remove <agent> per rimuoverne una. Le voci MCP basate sulle impostazioni installate con pathrule install si rimuovono con pathrule uninstall <client>. Queste operazioni preservano le impostazioni e i server dei client che non riguardano Pathrule.

Cosa leggere dopo

• Riferimento dei comandi per tutti i comandi e le opzioni.
• Guida rapida per scrivere la tua prima memoria e vedere l'hook in azione.
• Come funzionano gli hook per il modello che spiega cosa verifica doctor.
• Panoramica di MCP per gli strumenti che l'assistente chiama una volta avviato il runtime.