Pathrule CLI

Pathrule CLI is the installation and terminal surface for Pathrule. It is published on npm as @pathrule/cli under the Apache-2.0 license, runs on macOS, Linux and Windows, and hosts the local MCP server, the local cache and the hook supervisor in your shell. It connects Claude Code, Codex, Cursor, Windsurf and GitHub Copilot, and it fits SSH, headless and standalone terminal workflows.

The content and MCP contract stay shared across clients, while delivery follows what each client is given. Claude Code and Codex get hooks that include a prompt hook, so context arrives before the agent acts, plus their repository files. Cursor, Windsurf and GitHub Copilot get Pathrule's MCP entry and reach the same knowledge through its MCP tools.

What Pathrule CLI owns

• Editions. Every folder is served by Pathrule Cloud or Pathrule Local. On a new install the device default is Pathrule Cloud; pathrule setup --local makes a folder Local, and pathrule config set default-mode changes the default for new folders. See Local or Cloud.
• Sign-in. A one-time device code, which works the same on your own computer, over SSH and on any headless machine.
• Workspace attach. Attach the folder you run it in to a workspace, so the runtime can resolve your AI session's working directory. pathrule setup does it as part of setting the folder up, and pathrule init creates or reuses the folder's workspace.
• AI client install and sync. Writes Pathrule's MCP entry into Claude Code, Codex, Cursor, Windsurf and GitHub Copilot. pathrule sync writes the hook configuration and knowledge files Claude Code reads, and Codex's when the repository has Codex files.
• Removal. pathrule eject previews project cleanup and pathrule eject --apply applies it. Remove native integrations through pathrule integrations remove <agent> and MCP entries through pathrule uninstall <client>. See Remove Pathrule from a project.
• No account needed. pathrule setup --local runs a folder on a local store with no sign-in and no cloud. See Work without an account.
• MCP server. Runs locally and is the surface your assistant speaks to. One MCP entry serves every folder, and each call is answered from the edition of the folder it is about.
• Hook supervisor. Registers the hooks of Claude Code, and of Codex when the repository has Codex files, and delivers the path-scoped context for the folder the agent is working in.
• Your working preferences. pathrule me lists, explains, re-scopes and forgets what User Intelligence holds about you, learned from your own words and kept on your machine.
• Knowledge in the terminal. pathrule search, list and read work in Local and Cloud. The CLI does not write knowledge in either edition: your agent writes through MCP, and Local knowledge is edited in the Local Console.
• Doctor and status. pathrule status shows which edition and workspace serve the folder. pathrule doctor is a single read-only command that checks the folder's edition, your sign-in and folder attachment in a Cloud folder, each AI client's MCP entry, and the files Pathrule manages in the folder. pathrule install rewrites out-of-date entries.
• Scripting. Nearly every command takes --json for stable, machine readable output.

Every command and option is in the command reference.

Happy path

npm i -g @pathrule/cli
cd ~/repos/my-project
pathrule setup
pathrule doctor

On a new install pathrule setup sets the folder up on Pathrule Cloud. It offers to sign you in, uses the folder's workspace, an existing workspace with the folder's name or a new one named after the folder, writes the MCP entry for every AI client, and writes the files Claude Code and Codex read. To choose the workspace yourself, run pathrule workspace attach my-project in the folder, or pathrule init my-project to create one with that name. Both act on the current folder, and neither takes a path option. pathrule org use my-team switches the organization new workspaces go to.

After this, Claude Code or Codex opened in ~/repos/my-project receives the Pathrule context for its first prompt. Cursor, Windsurf and GitHub Copilot reach it through Pathrule's MCP tools when the agent calls them.

Output modes

The CLI has two output modes that you switch between with --json.

• Human mode (default): Status lines marked ok, warn, error or info, with the next command to run where one applies. Prompts and browser windows appear only in an interactive terminal.
• JSON mode: One JSON object per command, for scripts, CI runners and automation. It always carries schema_version, ok, command and cwd, plus data on success or an error with a code and a message. eject does not support it, and it never prompts or opens a browser.

pathrule workspace list           # human
pathrule workspace list --json    # machine readable

A command exits non-zero when it did not do what you asked, so a CI step fails on it.

Commands that open the browser

A few flows are cloud only and open Pathrule Web in your default browser rather than reimplementing the console in the terminal.

pathrule billing
pathrule upgrade
pathrule team open

Each one prints the URL it opened. With --no-open it prints the URL without opening anything, so you can copy it from a remote shell. Plain pathrule team lists the organization's members in the terminal, and its pending invites when you are an owner or admin.

When to use Pathrule CLI

Use Pathrule CLI when you work over SSH, when you want to script Pathrule into a CI runner, when you want to try Pathrule with no account, or when you simply live in the terminal. To browse and edit knowledge inside your editor, add Pathrule for VS Code, which shares the same sign-in and hooks.

What to read next

• Install for install paths, the sign in flow, what Pathrule writes into a repository, and how to remove it.
• Command reference for every command and option.
• Pathrule for VS Code for the editor surface that shares the same identity and hooks.
• How hooks work for what the runtime hands to your assistant.