Install

Pathrule CLI is the terminal first surface for Pathrule. It is published on npm as @pathrule/cli under the Apache-2.0 license, and it runs the local MCP server, the hook supervisor and the local cache for the agents you drive from a shell. This page covers installing it, setting up a repository on Pathrule Cloud or Pathrule Local, connecting your AI clients, and taking it out of a project again. Every command is listed in the command reference.

Requirements

• macOS, Linux, or Windows.
• Node.js 22.14.0 or newer. The CLI checks the version on every run and stops with a clear message on an older one.
• A modern shell: zsh, bash or fish, or PowerShell on Windows.
• An AI coding assistant that speaks MCP. Pathrule CLI writes its MCP entry for Claude Code, Codex, Cursor, Windsurf and GitHub Copilot, and its hooks for Claude Code and Codex. Optional for install, but you will want one to verify the hook flow.

Install

npm (macOS, Linux, Windows)

This guide installs with npm on all three operating systems. It needs Node.js 22.14.0 or newer.

npm install -g @pathrule/cli

On Windows, run this from PowerShell. Pathrule registers a Windows compatible hook command automatically, so the same pathrule commands work there exactly as they do in a Unix shell.

To upgrade, run pathrule update, which installs the newest verified release for an npm global install, or the same npm install with @latest:

pathrule update
npm install -g @pathrule/cli@latest

Once a day the CLI checks for a newer release in the background. Under the default update policy, automatic, it also installs an available update itself for an npm global install when no Pathrule MCP server or host is running. pathrule config set update.policy notify makes it only tell you, and PATHRULE_DISABLE_UPDATES=1 turns updates off. See Updates.

Verify

pathrule --version

The CLI prints its version and exits zero. If the command is not found, make sure the npm global install location is on your PATH and reopen the shell.

Sign in

Pathrule Cloud uses your account. Pathrule Local needs none; see Use it without an account. On a new install the device default is Pathrule Cloud, so pathrule login is available straight away, and pathrule setup offers to sign you in when you are not. pathrule login signs in with a one-time code. The same command works on your own computer, over SSH and on a headless box or CI runner.

Device code flow

pathrule login

The CLI prints a one-time code. On a machine with a browser it opens the approval page with the code already filled in: sign in to your Pathrule account there and approve. On a headless box or over SSH, open the printed URL on any device, enter the code and approve. The terminal finishes signing in on its own, and your password never passes through it.

Pass --no-open to keep the CLI from opening a browser at all. It prints the URL instead. Older guides use pathrule login --device-code, which is still accepted and runs this same flow.

pathrule whoami shows the account you are signed in as, and pathrule logout ends the session on this machine.

Attach a workspace

A workspace is the unit Pathrule scopes content to, and every folder is served by one edition: a Pathrule Cloud workspace or a Pathrule Local workspace. The CLI always acts on the folder you run it in, so change into the repository first. There is no option that takes a path.

cd ~/repos/my-team
pathrule setup

On a new install this sets the folder up on Pathrule Cloud, the device default. Setup offers to sign you in, uses the folder's Cloud workspace, or an existing workspace with the folder's name, or creates one named after the folder, then writes the MCP entry for every AI client and the hooks and repository files. For Pathrule Local, with no account, run pathrule setup --local instead; see Use it without an account. Local or Cloud explains how a folder's edition is chosen and how to switch it.

To choose the Cloud workspace yourself:

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

pathrule workspace attach takes the workspace's exact name or its id. To start a new workspace instead, pathrule init creates one named after the folder and attaches it in one step, and pathrule init my-team or pathrule workspace create my-team does the same with the name you give. Workspaces come from your current organization: pathrule org list shows yours and pathrule org use <name-or-id> switches.

After this, any time you run an AI client in this folder or below it, the runtime knows which workspace's content to serve. pathrule status shows which edition and workspace serve the folder.

In a script, setup never asks a question. Sign in beforehand with pathrule login. When --cloud or --local changes the edition of a folder already set up, say whether that is for this project only or for the device default; a folder not set up yet gets this project only:

pathrule setup --local --scope project

Connect your AI clients

pathrule setup writes Pathrule's MCP entry into every AI client it supports, or into one with --target <client>, on Pathrule Cloud and Pathrule Local alike. To connect one by hand:

pathrule install cursor

pathrule install takes claude, cursor, codex, windsurf or copilot, and with no client it installs all five. It writes Pathrule's MCP server entry into that client's own user-level configuration and leaves every other server there alone. GitHub Copilot gets two entries, one for the Copilot CLI and one for VS Code. The entry is the same whatever a folder's edition. pathrule uninstall <client> removes the entry again.

Claude Code and Codex also get hooks and repository files. pathrule sync writes them into the repository and refreshes the local hook index; run it in the folder whenever you want those files to catch up with the workspace. It writes for Claude Code always, and for Codex when the repository already has Codex files: an AGENTS.md, .codex/hooks.json or .codex/config.toml. Cursor, Windsurf and GitHub Copilot get the MCP entry only, and reach Pathrule through its MCP tools.

What Pathrule writes into your repository

Pathrule writes into the places Claude Code and Codex already read, so nothing new has to be configured in the client.

Without an installed hook, or with PATHRULE_SIGNATURE_MODE=off, the compiled knowledge goes into files instead: .claude/rules/pathrule-knowledge.md and a CLAUDE.md in each folder with knowledge for Claude Code, and the full protocol in AGENTS.md plus an AGENTS.md in each folder with knowledge for Codex.

Pathrule marks what it writes: its files carry a Pathrule banner, and anything it adds to a file of yours sits inside a marked block. When an instruction file such as AGENTS.md already holds your own content, Pathrule saves your version as a backup before it writes, or writes inside its marked block and leaves the rest of the file alone. A .pathrule folder at the repository root keeps Pathrule's record of the files it manages, .pathrule/managed-files.json, together with those backups. The .claude/rules/pathrule/ folder carries its own .gitignore, so your .gitignore is not edited.

Outside the repository, pathrule setup and pathrule install write the MCP entries into each client's user-level configuration, and the CLI keeps its session, cache and hook script in your Pathrule home, ~/.pathrule by default.

To see what Pathrule manages in a folder without changing anything, run pathrule doctor, which lists each managed file with the surface and version that wrote it. The client pages go deeper: Claude Code, Codex, Cursor, Windsurf and GitHub Copilot.

Use it without an account

Pathrule CLI also runs a folder entirely on your machine, with no account and no cloud. Inside the project:

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

pathrule setup --local makes the folder a Pathrule Local folder. It creates the folder's Local workspace, or reuses the one that covers it, and imports the project's instruction files. It then writes the MCP entry for every AI client, or for one with --target <client>, and installs the hooks and repository files, all without signing in. On a new install the device default is Pathrule Cloud, so setup asks whether Local is for this project only or for the device default; pathrule config set default-mode local makes every new folder Local. pathrule init --local creates the Local workspace only.

Your agent writes memories, rules and skills through Pathrule's MCP tools, you edit them in the Local Console with pathrule ui, and you read and search them from the terminal, for example with pathrule memory list. See Work without an account for every local command and Open source core for what the local edition includes.

Open-source-only setup

Pathrule CLI itself is open source under Apache-2.0, and Pathrule Local runs it with no account, no cloud service and no model on your machine. Open source core lists what is open source today and what is proprietary.

Verify the wiring

The doctor is the single command that confirms the setup end to end. It only reads; it never changes anything.

pathrule doctor

It checks:

• Which edition serves the current folder and why, the device default and the workspace, and whether the folder has a conflict between a Local and a Cloud workspace.
• In a Cloud folder, that you are signed in and that the current folder is the one the workspace is attached to.
• Each AI client has Pathrule's MCP entry installed.
• The files Pathrule manages in this folder, with the surface and version that wrote each one. A file written by another surface or a newer version is flagged.

In a Cloud folder, when something needs attention, doctor names the next command, such as pathrule login or pathrule attach <workspace>. pathrule doctor --json returns the full report for a script, which also covers the Node.js version and flags an MCP entry whose launch command is out of date, and it exits non-zero when a check fails. pathrule install rewrites an out-of-date entry and leaves every other server alone, and pathrule sync writes the repository files again.

Remove Pathrule from a project

Start with the read-only plan from the repository:

pathrule eject

It lists Pathrule-owned files and managed regions, including any recovery of your earlier content. Review that plan, then apply it explicitly:

pathrule eject --apply

For a Cloud folder attachment, pathrule detach disconnects the folder on this machine and removes this machine's cached copy of the workspace, without deleting anything on Pathrule Cloud. The VS Code extension can also unbind its folder.

Native integrations have their own recorded setup. Use pathrule integrations remove <agent> to remove one. MCP entries written by pathrule setup or pathrule install can be removed with pathrule uninstall <client>. These operations preserve unrelated client settings and servers.

What to read next

• Command reference for every command and option.
• Local or Cloud for how a folder's edition is chosen and switched.
• Quickstart to get your first memory delivered and watch the hook fire.
• How hooks work for the model that explains what doctor is verifying.
• MCP overview for the tools the assistant calls once the runtime is up.