Instalação

O Pathrule CLI é a superfície do Pathrule pensada para o terminal. Ele é publicado no npm como @pathrule/cli sob a licença Apache-2.0 e executa o servidor MCP local, o supervisor de hooks e o cache local para os agentes que você usa a partir de um shell. Esta página explica como instalá-lo, entrar na sua conta, conectar um repositório e seus clientes de IA, usá-lo sem conta e removê-lo de um projeto depois. Todos os comandos estão listados na referência de comandos.

Requisitos

• macOS, Linux ou Windows.
• Node.js 20.11.1 ou mais recente. O CLI verifica a versão a cada execução e, se ela for mais antiga, para com uma mensagem clara.
• Um shell moderno: zsh, bash ou fish, ou PowerShell no Windows.
• Um assistente de programação com IA que fale MCP. O Pathrule CLI conecta Claude Code, Codex, Cursor, Windsurf e GitHub Copilot. Ele não é obrigatório para a instalação, mas você vai querer um para verificar o fluxo dos hooks.

Instalação

npm (macOS, Linux, Windows)

O npm é o caminho de instalação nos três sistemas operacionais. Ele exige Node.js 20.11.1 ou mais recente.

npm install -g @pathrule/cli

No Windows, execute pelo PowerShell. O Pathrule registra automaticamente um comando de hook compatível com Windows, então os mesmos comandos pathrule funcionam ali exatamente como em um shell Unix.

Para atualizar, execute a mesma instalação com @latest:

npm install -g @pathrule/cli@latest

Uma vez por dia, uma execução interativa verifica se há uma versão mais nova e exibe um aviso de uma linha com esse comando. O aviso só aparece para uma versão mais nova que a sua. pathrule update faz a mesma verificação quando você quiser, e pathrule config set update.policy manual desativa a verificação diária.

Download direto

Não existe instalador avulso nem fórmula para gerenciador de pacotes. Instale o Pathrule CLI pelo npm em qualquer sistema operacional.

Verificação

pathrule --version

O CLI exibe a versão e termina com código zero. Se o comando não for encontrado, confira se o local de instalação global do npm está no seu PATH e abra o shell de novo.

Entrar na conta

O uso com Cloud exige uma conta. A configuração local dispensa a entrada; veja Usar sem conta. Por padrão, pathrule login faz a entrada com um código de uso único. O mesmo comando funciona no seu computador, via SSH e em uma máquina sem interface gráfica ou em um runner de CI.

Fluxo de código de dispositivo

pathrule login

O CLI exibe um código de uso único. Em uma máquina com navegador, ele abre a página de aprovação com o código já preenchido: entre na sua conta Pathrule ali e aprove. Em uma máquina sem interface gráfica ou via SSH, abra a URL exibida em qualquer dispositivo, digite o código e aprove. O terminal conclui a entrada sozinho, e sua senha nunca passa por ele.

Use --no-open para que o CLI não abra navegador nenhum. Nesse caso, ele exibe a URL. Guias mais antigos usam pathrule login --device-code, que continua sendo aceito e executa esse mesmo fluxo.

Fluxo PKCE no navegador

pathrule login --browser-callback

Esse comando faz a entrada com GitHub em um navegador na mesma máquina e devolve a sessão ao terminal por meio de um callback na sua própria máquina, protegido com PKCE. Se sua conta usa autenticação de dois fatores, o CLI pede o código. Aqui é preciso ter um terminal interativo e um navegador. Quando não dá para usar o callback, o CLI avisa e segue com o fluxo de código de dispositivo; com --no-open ou em um script, ele usa o fluxo de código de dispositivo desde o início.

pathrule whoami mostra com qual conta você entrou. pathrule logout desconecta o CLI, e pathrule logout --all também desconecta as outras superfícies do Pathrule nesta máquina, como a extensão do VS Code.

Vincular um espaço de trabalho

O espaço de trabalho é a unidade à qual o Pathrule vincula o conteúdo. O CLI sempre vincula a pasta em que você o executa, então entre no repositório primeiro. Não existe opção que receba um caminho.

O fluxo guiado faz tudo de uma vez:

cd ~/repos/my-team
pathrule setup

O pathrule setup começa pedindo que você escolha Pathrule Cloud ou Local. Cloud é o início gerenciado recomendado, com contas, organizações e inteligência compartilhada. Local roda nesta máquina e não exige conta. O setup conecta o espaço de trabalho e os clientes de IA que você escolher. Em um Mac com Apple Silicon, ele também oferece o modelo no dispositivo, que é opcional e pode ser ignorado.

O setup com Cloud pode vincular um espaço de trabalho existente ou criar um para esta pasta. Em seguida, o runtime local entrega o conteúdo por meio da configuração e dos hooks dos clientes suportados.

Para fazer passo a passo:

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

pathrule workspace attach recebe o nome exato do espaço de trabalho ou o id dele. Sem argumento, ele vincula seu espaço de trabalho atual. Para começar um espaço de trabalho novo, pathrule init cria um com o nome da pasta e o vincula em um único passo, e pathrule init my-team ou pathrule workspace create my-team fazem o mesmo com o nome que você indicar. Os espaços de trabalho vêm da sua organização atual: pathrule org list mostra as suas e pathrule org use <slug> troca de organização.

Depois do vínculo, sempre que você executar um cliente de IA nesta pasta ou abaixo dela, o runtime sabe de qual espaço de trabalho deve servir o conteúdo.

Em um script, o pathrule setup recebe as respostas como opções e precisa de --yes para agir:

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

Conectar seus clientes de IA

O pathrule setup pergunta quais clientes de IA você usa, instala esses clientes e guarda a escolha para este espaço de trabalho. Para conectar um manualmente:

pathrule install cursor
pathrule sync

pathrule install recebe claude, cursor, codex, windsurf ou copilot e, sem cliente, instala os cinco. Ele grava a entrada do servidor MCP do Pathrule na configuração de nível de usuário do próprio cliente e não mexe em nenhum outro servidor que esteja lá. O GitHub Copilot recebe duas entradas, uma para o Copilot CLI e outra para o VS Code. pathrule uninstall <client> remove a entrada.

pathrule sync grava no repositório os arquivos que seus clientes leem e atualiza o índice local de hooks. Execute-o na pasta à qual o espaço de trabalho está vinculado, depois do vínculo e sempre que quiser que esses arquivos acompanhem o espaço de trabalho. Ele grava para os clientes de IA escolhidos para este espaço de trabalho no pathrule setup. Quando nenhum foi escolhido, grava para os clientes cujos arquivos do Pathrule já estão no repositório e, se não houver nenhum, para o Claude Code. pathrule sync --skills copia as skills do espaço de trabalho para as pastas de skills dos seus clientes.

O que o Pathrule grava no seu repositório

O Pathrule grava nos lugares que cada cliente já lê, então não é preciso configurar nada novo no cliente.

O Pathrule marca o que grava: seus arquivos de instruções trazem um banner do Pathrule, e tudo o que ele adiciona a um arquivo seu fica dentro de um bloco marcado. Quando um arquivo de instruções como CLAUDE.md ou AGENTS.md já tem conteúdo seu, o Pathrule salva sua versão como backup antes de gravar, ou grava dentro do bloco marcado e deixa o resto do arquivo intacto. Uma pasta .pathrule na raiz do repositório guarda o registro do Pathrule sobre os arquivos que ele gerencia, junto com esses backups. As skills sincronizadas com pathrule sync --skills vão para a pasta de skills de cada cliente, como .claude/skills/, e, quando o repositório tem um .gitignore, o Pathrule adiciona uma seção comentada que mantém essas pastas fora do git até você apagá-la.

Fora do repositório, pathrule install grava as entradas MCP na configuração de nível de usuário de cada cliente, e o CLI guarda a sessão, o cache e o script de hook na sua pasta pessoal do Pathrule, que por padrão é ~/.pathrule.

Para ver o que o Pathrule gerencia em uma pasta sem alterar nada, execute pathrule doctor, que lista cada arquivo gerenciado com a superfície e a versão que o gravou. As páginas de cada cliente trazem mais detalhes: Claude Code, Codex, Cursor, Windsurf e GitHub Copilot.

Usar sem conta

O Pathrule CLI também roda inteiramente na sua máquina, sem conta e sem nuvem. Dentro do projeto:

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

pathrule init --local cria um espaço de trabalho local para a pasta atual. pathrule setup --local faz o mesmo e, em seguida, instala a entrada MCP local para todos os clientes de IA, ou para um só com --target <client>, instala os hooks e grava os arquivos do repositório, tudo sem entrar em conta nenhuma. Seu agente grava memórias, regras e skills pelas ferramentas MCP do Pathrule, e você as lê e pesquisa pelo terminal com --local, por exemplo pathrule memory list --local. Veja Trabalhar sem conta para todos os comandos locais e Núcleo de código aberto para saber o que a edição local inclui.

Configuração somente com código aberto

O próprio Pathrule CLI é código aberto sob Apache-2.0, e o modo local o executa sem conta e sem serviço em nuvem. O modelo no dispositivo que o setup oferece em um Mac com Apple Silicon é opcional: recuse quando o setup perguntar ou remova depois com pathrule intelligence remove. Tudo o que não depende do modelo continua funcionando sem ele. A página Núcleo de código aberto lista o que é código aberto hoje e o que é proprietário.

Verificar a configuração

O doctor é o único comando que confirma a configuração de ponta a ponta. Ele só lê; nunca altera nada.

pathrule doctor

Ele verifica:

• Se você entrou na conta e se há uma organização e um espaço de trabalho selecionados.
• Se a pasta atual é aquela à qual o espaço de trabalho está vinculado.
• Se cada cliente de IA tem a entrada MCP do Pathrule instalada.
• Os arquivos que o Pathrule gerencia nesta pasta, com a superfície e a versão que gravou cada um. Um arquivo gravado por outra superfície ou por uma versão mais nova é sinalizado.

Quando algo precisa de atenção, o doctor indica o próximo comando, como pathrule login ou pathrule attach <workspace>. pathrule doctor --json devolve o relatório completo para uso em scripts, que também cobre a versão do Node.js e sinaliza uma entrada MCP cujo comando de inicialização está desatualizado, e termina com código diferente de zero quando alguma verificação falha. Uma entrada desatualizada é corrigida com pathrule repair, que reescreve as entradas do Pathrule nas configurações dos seus clientes, não mexe em nenhum outro servidor e grava de novo os arquivos do repositório.

Remover o Pathrule de um projeto

Comece pelo plano somente leitura, a partir do repositório:

pathrule eject

Ele lista os arquivos que pertencem ao Pathrule e as regiões gerenciadas, incluindo a recuperação do seu conteúdo anterior, se houver. Revise esse plano e aplique-o explicitamente:

pathrule eject --apply

No caso de uma pasta vinculada ao Cloud, pathrule detach desconecta a pasta local sem apagar o espaço de trabalho no Cloud. A extensão do VS Code também pode desvincular a pasta dela.

As integrações nativas têm uma configuração própria registrada. Use pathrule integrations remove <agent> para remover uma delas. As entradas MCP baseadas em configuração instaladas com pathrule install podem ser removidas com pathrule uninstall <client>. Essas operações preservam as configurações e os servidores dos clientes que não têm relação com o Pathrule.

O que ler em seguida

• Referência de comandos para todos os comandos e opções.
• Início rápido para gravar sua primeira memória e ver o hook disparar.
• Como os hooks funcionam para entender o modelo que explica o que o doctor está verificando.
• Visão geral do MCP para conhecer as ferramentas que o assistente chama quando o runtime está no ar.