Skip to content
Pathrule

docs

Command reference

Every Pathrule CLI command, what it does and the options that matter, from editions, sign-in and workspace setup to knowledge, diagnostics and account-free local use.

On this page

Every command in Pathrule CLI, grouped the way pathrule help groups them. Each entry says what the command does and which options matter. For a first setup, start with Install.

pathrule <command> [subcommand] [arguments] [options]
pathrule help

pathrule help lists the commands this install has. There is no help page per command: pathrule <command> --help prints the same list, so the options are on this page.

Editions and the device default

Every folder you use Pathrule in is served by one edition: Pathrule Cloud, with your account, or Pathrule Local, on this machine with no account. Which one serves a folder is decided in this order, and the deepest folder decides, so a project nested inside another keeps its own:

  1. The folder's own choice, recorded when you run pathrule setup or pathrule init there.
  2. Otherwise, the workspace that already serves it: its Local workspace, or the Pathrule Cloud workspace attached to it on this machine.
  3. Otherwise, the device default.

The device default is Pathrule Cloud on a new install. It is Pathrule Local when you chose Local, or in a build that names no Pathrule Cloud, such as one built from source. It decides only for folders that have no edition of their own.

pathrule config get default-mode
pathrule config set default-mode local

config get default-mode prints the default and where it comes from, for example default-mode=cloud (default for a new install). config set default-mode cloud or config set default-mode local changes what new folders use. It never changes a folder that already has its own edition, and it says how many folders on this machine keep theirs. It needs no account.

pathrule setup and pathrule init are the only commands that change a folder's edition, see Change a folder's edition. Every other command follows the folder:

  • sync, search, memory, rule, skill and instrument events work on the Cloud workspace in a Cloud folder and on the Local workspace in a Local folder. --local or --cloud on these commands no longer picks an edition for one run: one that contradicts the folder stops with exit code 64 and names the setup command that changes it.
  • There is no automatic fallback to Local. In a Cloud folder, being signed out, offline, without access, not attached, at a plan limit, or unable to load Pathrule Cloud is an error that says what to do. Nothing is served from a Local store instead, in the CLI, the MCP server, the hook or VS Code.
  • A folder that has both a Local workspace and an attached Cloud workspace, and no choice between them, is a conflict. Nothing guesses: commands stop and name pathrule setup --cloud and pathrule setup --local, and the hook delivers nothing there and says why.

The account commands (login, logout, whoami, org, workspace, attach, detach, open, activity, preflight, telemetry, billing, team, invite, upgrade and reactivate) are present whenever this machine uses Pathrule Cloud: the device default is Cloud, or a folder is a Cloud folder or attached to a Cloud workspace. On a machine that uses Pathrule Local everywhere, they answer Unknown command.

Global options

OptionWhat it does
--jsonPrints one machine-readable JSON object instead of human output. It also turns off color, prompts and browser windows.
--yesAccepts the confirmation that pathrule integrations and pathrule activity import ask for. Other commands do not read it.
--no-openNever opens a browser. A command that would open one prints the URL instead.
--no-colorPrints plain output with no color. Setting the NO_COLOR environment variable to 1 or true does the same.
--cloud, --localWith setup and init, choose the folder's edition. On commands that follow the folder, they state the edition you expect, and a mismatch stops. integrations reads them to choose the edition of a native integration.
--help, -hPrints the command list.
--version, -vPrints the CLI version.

When the CI environment variable is exactly true, the CLI also skips prompts, browser windows and the background update check, so a command never waits for input on a runner.

Options a command does not know

Most commands do not reject an option they do not recognise. They read it as a plain argument, which makes the command fail or act on the wrong target. pathrule workspace attach --path ~/repos/app looks for a workspace named --path, and pathrule install --client cursor stops because --client is not a client name. setup in a Local folder, integrations, instrument events and ui check their options and stop with exit code 64 on one they do not know. Use the options on this page.

JSON output

With --json, every reply is one JSON object with schema_version, ok, command and cwd, plus data when the command succeeded, or error with a code and a message when it did not. Some replies add next_steps with the commands to run next, and warnings. Nearly every command has a JSON form; eject and host run do not, so run them without it. With --json a command never prompts, so sign in with plain pathrule login, which shows you the code to approve.

Exit codes

  • 0: the command did what you asked.
  • 1: it failed. pathrule doctor exits 1 when a check fails, and pathrule status when the folder has a conflict or a Pathrule Cloud problem.
  • 2: pathrule integrations add, repair or remove stopped for your approval, or pathrule me got an unknown subcommand.
  • 64: a usage error, such as an unknown command or option, a missing argument, an unknown client name, --local or --cloud that contradicts the folder, or a setup that needs an answer it cannot ask for in a script.
  • 78: this Node.js is older than 22.14.0, or a part of the CLI this run needs, such as Pathrule Cloud, could not be loaded.
  • 130: you cancelled the prompt for an embeddings key.

Get started

CommandWhat it does
pathrule setupSets up the current folder's project in its edition: Pathrule Cloud by default on a new install, or Pathrule Local with --local. Run from a subfolder, it acts on the project root.
pathrule init [name]Creates or reuses the folder's workspace in its edition. With --cloud or --local it changes the edition, as setup does. It never resets, deletes or switches an existing project.
pathrule homeShows the project home for this folder: its workspace, edition, agents, knowledge and delivery. Plain pathrule in an interactive terminal does the same. It writes nothing.

setup and init take these options:

OptionWhat it does
--cloud, --localChoose the folder's edition. When it is the edition the folder already has, the same setup runs again and nothing is asked.
--scope project, --scope deviceWhen --cloud or --local differs from the folder's edition: change it for this project only, or change the device default. A script that changes a folder already set up needs one of them.
--transfer, --no-transferOn Pathrule Cloud: approve or decline the copy of this folder's Local knowledge to its Cloud workspace, in a script.
--target <client>setup only: write the MCP entry for one AI client instead of all of them: claude (or claude-code), cursor, codex, windsurf, copilot (or github-copilot), or all.
--workspace-name <name>setup in a Local folder: the name of a new Local workspace. The folder name is the default.
--import-instructionssetup in a Local folder: import the instruction file sections an existing Local workspace has never had, even when it already has content.

Cloud setup

In a Cloud folder, pathrule setup:

  1. Offers to sign you in, at a terminal, when you are not signed in. In a script, a signed-out setup stops with Not signed in and exit code 1.
  2. Uses the Pathrule Cloud workspace attached to the folder. Otherwise it uses an existing workspace with the folder's name, and says so in a line, or creates a workspace named after the folder in your current organization.
  3. Writes Pathrule's MCP entry for every AI client, or for one with --target <client>.
  4. Offers to copy the folder's Local knowledge when the folder has a Local workspace with knowledge, see Copy Local knowledge to Pathrule Cloud.
  5. Writes Claude Code's hooks and rule files, and Codex's files when the repository has them, and refreshes the hook index, as pathrule sync does.

pathrule init in a Cloud folder does the same without writing MCP entries, and pathrule init <name> uses that name instead of the folder's. A Cloud setup that does not finish leaves the folder on the edition it had before.

A Local setup is described in Work without an account.

Change a folder's edition

setup and init settle the folder's edition before they set it up:

  • With no --cloud or --local, the folder keeps its edition and nothing is asked. A new folder on a new install is set up on Pathrule Cloud.
  • With the edition the folder already has, the same setup runs again. Nothing changes and nothing is asked.
  • With the other edition, setup asks what to change, with exactly two answers:
    1. This project only (recommended, the default). It records this folder's choice. Other folders and the device default stay as they are.
    2. The device default. New folders use the new edition. Folders already set up keep theirs, this one too when it is already set up. A folder that is not set up yet follows the new default.

In a script, answer with --scope project or --scope device. A script that changes a folder already set up in the other edition, without either, stops with exit code 64 (setup_scope_required) and names both commands. A folder not set up yet changes no project's edition, so a script gets the default, this project only, and setup says so in a line:

pathrule setup --cloud --scope project
pathrule setup --local --scope device

Choosing a scope never approves a copy of knowledge. --cloud and --local together stop with exit code 64, and so does --transfer with --local. A folder in conflict is asked at a terminal which edition serves it, with no default; in a script, setup stops with exit code 64 (folder_edition_conflict).

When a folder changes edition:

  • Local to Cloud. The folder's Local workspace stays on this machine, unchanged and unused while the folder is a Cloud folder, and pathrule setup --local brings it back. Its knowledge can be copied to the Cloud workspace.
  • Cloud to Local. Nothing from Pathrule Cloud is copied to this machine, on any plan, Solo included. The Cloud workspace stays on Pathrule Cloud and stays attached here, unused. This machine's cached copy of it (the hook index and session caches) is removed, and the Claude Code rule files in .claude/rules/pathrule/ are written again from Local. The Local side starts with the folder's earlier Local workspace when this release kept it unused, otherwise empty.

Local or Cloud explains both directions in full.

Copy Local knowledge to Pathrule Cloud

When pathrule setup or pathrule init runs in a Cloud folder whose Local workspace holds knowledge, for example right after setup --cloud moved it from Local, it offers to copy that knowledge to the folder's Cloud workspace.

  • Preview first. It always prints how many memories, rules and skills there are and their size, the target workspace and organization, what is kept, what is lost or changed, what cannot be copied, and whether it fits your plan's limits. With --json the preview is in data.transfer.preview.
  • A separate approval. At a terminal it asks Copy these N items to "<workspace>"? [y/N], and only y copies. In a script, --transfer approves and --no-transfer declines; with neither, nothing is copied and a notice names pathrule setup --cloud --transfer. A no is remembered, and setup does not ask again unless you pass --transfer.
  • Safe to run again. A second run copies only what is missing, never overwrites an item edited in Pathrule Cloud since, and never changes the Local workspace.
  • An honest summary. It reports Copied X of N, what failed and why, what was not attempted because a plan limit stopped the copy, and the command to retry. Only a complete copy says everything is on Pathrule Cloud, and an incomplete one exits non-zero.

Activity is copied separately, with pathrule activity import --from-local.

Account and context

These commands are present when this machine uses Pathrule Cloud, see Editions and the device default.

CommandWhat it does
pathrule loginSigns in to Pathrule Cloud with a one-time code. The CLI prints the code and opens the approval page in your browser with the code filled in, or prints the URL to open on any device when there is no browser or you pass --no-open. --device-code, from older guides, runs the same flow.
pathrule logoutEnds the Pathrule Cloud session on this machine and removes it.
pathrule whoamiShows the signed-in account and when the session expires.
pathrule org listLists your organizations with your role and plan, and marks the current one with *. Plain pathrule org does the same.
pathrule org currentShows the current organization, your role in it and its plan.
pathrule org use <name-or-id>Makes an organization current, matched by its id or its exact name in any case.
pathrule org create <name>Creates an organization and makes it current.
pathrule workspace listLists the workspaces of the current organization, with the folder each one is attached at on this machine. Plain pathrule workspace does the same.
pathrule workspace currentShows the workspace attached to the folder you run it in, or says the folder is not attached.
pathrule workspace attach <name-or-id>Attaches the current folder to an existing workspace, matched by its id or its exact name, in the current organization first and then in your other organizations. pathrule workspace use is the same command. There is no path option: run it inside the folder.
pathrule workspace create [name]Creates a workspace in the current organization, named after the folder unless you give a name, and attaches the current folder to it.
pathrule workspace detachRemoves the attachment that serves the current folder, together with this machine's cached copy of that workspace and its rendered knowledge files. Nothing is deleted on Pathrule Cloud.
pathrule workspace openOpens the Signals page of the folder's workspace in the Pathrule Cloud console.

There is no current workspace. memory, rule, skill, search and sync use the workspace attached to the folder you run them in. The current organization is the one you chose with org use, or your only one, and it is where new workspaces and invitations go.

Workspace setup

CommandWhat it does
pathrule attach <name-or-id>The same as workspace attach. Pathrule Cloud.
pathrule detachThe same as workspace detach. Pathrule Cloud.
pathrule open [target]Pathrule Cloud. Opens a page of the Cloud console, or prints its URL with --no-open. workspace (the default) and signals open the Signals page of this folder's workspace; org or app the console; billing, upgrade or reactivate billing; team or members the members page; settings and workspaces those pages.
pathrule activity import --from-localPathrule Cloud. Copies this folder's Pathrule Local activity into its Cloud workspace. It says first what leaves the machine, sends nothing with --dry-run, and asks before sending unless you pass --yes. --days <n> limits it to the last 1 to 180 days (180 by default), and --undo removes the copy. Running it again copies nothing twice.
pathrule install [client]Writes Pathrule's MCP server entry into an AI client's own user-level configuration and leaves every other server in it alone. The client is claude (or claude-code), cursor, codex, windsurf, copilot (or github-copilot), or all, which is the default. 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: the MCP server answers each call from the edition of the folder it is about.
pathrule uninstall [client]Removes Pathrule's MCP entry from that client's configuration, or from all five.
pathrule syncWrites the repository files for this folder and refreshes the hook index from its workspace. Run it in the folder or below it.
pathrule instrument eventsShows the runtime events an application reported to this folder's workspace, Local or Cloud. Narrow it with --path, --kind, --environment, --status, --verification, --group <id>, --limit <n> and --cursor <c>.
pathrule mcp runStarts Pathrule's MCP server over standard input and output. The entry pathrule install writes launches it, so your AI client runs it and you do not need to.

pathrule sync writes files for Claude Code always, and for Codex when the repository already has Codex files: an AGENTS.md, .codex/hooks.json or .codex/config.toml. It writes no files for Cursor, Windsurf or GitHub Copilot, which reach Pathrule through their MCP entry. Claude Code's hook entries in .claude/settings.json are refreshed on every sync, unless a Claude Code plugin from pathrule integrations delivers the hook. Install lists each file. To take Pathrule back out of a repository, see Remove Pathrule from a project.

In a Cloud folder, plain pathrule instrument, instrument status, instrument keys and instrument sdk open the workspace's Signals page in the Pathrule Cloud console, where its Signals status and ingest keys are. In a Local folder, plain pathrule instrument is instrument events.

Knowledge

CommandWhat it does
pathrule search <query>Searches memories, rules and skills in this folder's workspace. --type memory,rule narrows the kinds, --path /apps/api or a leading path narrows to a path, and --limit <n> caps the results, 20 by default and 100 at most.
pathrule memory listLists memories, most recently updated first. --path or a leading path narrows the list, so pathrule memory list /apps/api and pathrule /apps/api memory list are the same. --limit <n> caps it.
pathrule memory read <id-or-title>Prints a memory in full, found by its id or its exact title in any case.
pathrule rule list, pathrule rule readThe same for rules.
pathrule skill list, pathrule skill readThe same for skills.

The CLI does not write knowledge, in either edition: pathrule memory add, rule add and skill add are refused and change nothing. Your AI agent writes memories, rules and skills through Pathrule's MCP tools. In a Local folder you can also edit them in the Local Console with pathrule ui. For a Cloud workspace, the Pathrule Cloud console shows them.

Your working preferences

CommandWhat it does
pathrule me listLists what User Intelligence holds about how you work, both what is in use and what is not yet. Plain pathrule me does the same.
pathrule me explain <id>Shows one preference with the words of yours it rests on. The id is the short id me list prints.
pathrule me scope <id>Keeps a preference to the workspace you run it in. --everywhere lets it apply in every workspace.
pathrule me forget <id>Stops using a preference and keeps it as rejected, so the same evidence does not bring it back. --delete removes it entirely.

Local Console and agent integrations

CommandWhat it does
pathrule uiOpens the accountless Local Console for knowledge, activity and Local Signals, served on this machine until you press Ctrl+C. --port, --no-open and --json control how it opens.
pathrule integrationsInteractive setup of a native integration for Claude Code and Codex. Outside an interactive terminal, lists the setup.
pathrule integrations add claude codex --local --dry-runPreviews a native integration without writing. Choose --cloud for a Pathrule Cloud integration.
pathrule integrations listLists detected agents and recorded integrations.
pathrule integrations doctorRead-only checks of the installed integration.
pathrule integrations repairReapplies recorded Pathrule integrations.
pathrule integrations remove <agent>Removes the recorded integration.

add, repair and remove change something only after you confirm at a terminal or pass --yes. Without either, they print the plan, change nothing and exit with 2. Cursor has no native integration: connect it with pathrule install cursor.

See Local Console and Native agent integrations.

Remove project integration

pathrule eject shows a read-only plan for removing the files and managed regions Pathrule owns in the current repository. pathrule eject --apply carries it out after you review it. Eject does not have a --json form and is not listed in pathrule help. Native plugins are removed through pathrule integrations remove <agent>.

Diagnostics and maintenance

CommandWhat it does
pathrule statusShows the folder, its edition and why, the device default and where it comes from, and the workspace that serves the folder. Read-only.
pathrule doctorRuns read-only checks of this folder's edition, your sign-in and attachment in a Cloud folder, each AI client's MCP entry, the files Pathrule manages here, and updates. --bundle writes a redacted support file.
pathrule preflight [action]Pathrule Cloud. In an attached folder, answers that Pathrule Cloud checks every action against the workspace's plan when it runs, so nothing needs checking first.
pathrule telemetryPathrule Cloud. Confirms that this CLI sends no usage data.
pathrule config get <key>Reads a preference: default-mode or update.policy.
pathrule config set <key> <value>default-mode takes cloud or local. update.policy takes automatic (the default) or notify.
pathrule updateChecks for a newer verified release and, for an npm global install, installs it after the package matches the signed release manifest. For other installs it prints what to run. --check only checks, and --json only checks unless you add --apply.
pathrule embeddingsShows or chooses the embedding provider for semantic search in Pathrule Local: status, use local, use openai, use voyage, use cloudflare, off and reindex. With none, ranking is by keyword and nothing leaves the machine.
pathrule topicsShows or chooses the model that names knowledge topics in the Local Console: status, use, off.
pathrule index refreshRebuilds the hook index of a Local workspace from its store. The hook runs it in the background.
pathrule learning drainProcesses the evidence the hook captured into a Local workspace. The hook runs it in the background.
pathrule hostrun, start, status or stop the local host that Pathrule surfaces share. --idle-timeout <minutes> sets how long a started host waits.

Status of a folder

pathrule status reads and changes nothing. It shows:

  • the folder, its edition and why: this project's choice, its workspace, the device default, or the default for a new install;
  • the device default and where it comes from;
  • the workspace that serves the folder: a Local workspace with its id and folder, or a Cloud workspace with its name, id and the folder it is attached at;
  • a workspace of the other edition that is kept but not used, and a conflict;
  • with Pathrule Cloud, the signed-in account, when the session expires, and whether the Cloud workspace answers.
Pathrule status
  Folder:          /Users/you/repos/acme-shop
  Edition:         Pathrule Cloud (this project's choice)
  Device default:  Pathrule Cloud (the default for a new install)
  Workspace:       Pathrule Cloud workspace "acme-shop" (<id>), attached at /Users/you/repos/acme-shop

It exits 1 for a conflict or a Pathrule Cloud problem (not_signed_in, not_attached, no_access, cloud_unreachable or cloud_unavailable), and never for a folder that is only not set up yet. With --json, data holds folder, device_default, workspace, dormant, conflict and account.

Doctor

pathrule doctor starts with folder_edition: the edition serving this folder and why, the device default and the workspace. It fails on a conflict or on a Cloud folder this run cannot serve, and warns on a folder that is not set up yet. In a Cloud folder it adds whether you are signed in, whether this folder is attached, and whether what the hook delivered reaches the console; a Local folder is not warned for having no Cloud attachment. It also checks each AI client's MCP entry, the files Pathrule manages in this folder with the surface and version that wrote each one, and updates and compatibility. With Pathrule Cloud, it names the next command when something needs attention, such as pathrule login or pathrule attach <workspace>. With --json the report also covers the Node.js version and flags an MCP entry whose launch command is out of date. --bundle writes a support file with credentials and local paths redacted into your Pathrule home.

Updates

Once a day the CLI checks for a newer release in the background. With update.policy automatic, the default, it also installs an available update itself for an npm global install when no Pathrule MCP server or host is running. With notify it only tells you, and manual is read as notify. Neither policy turns the check off: PATHRULE_DISABLE_UPDATES=1 turns updates off, and NO_UPDATE_CHECK=1 or CI=true skips the background check. When this machine uses Pathrule Cloud, the policy is kept with your account, so setting it needs you to be signed in.

Telemetry

Pathrule's CLI, MCP server and VS Code extension send no usage data. No build Pathrule distributes carries an analytics key, so there is nothing to turn on, and nothing about your commands, code, knowledge or account leaves your machine for analytics. The telemetry command, present when this machine uses Pathrule Cloud, confirms it. Pathrule Cloud counts its own use on its servers, only for accounts whose holder opted in on the account page.

Team and billing

These commands are present when this machine uses Pathrule Cloud.

CommandWhat it does
pathrule teamLists the members of the current organization with their roles, and its pending invites when you are an owner or admin. pathrule team open opens Pathrule Web, where members are managed.
pathrule invite <email> [role]Invites a teammate to the current organization. The role is admin, member or viewer, given as the second argument or with --role, and member is the default. It says whether Pathrule Cloud e-mailed the invitation and prints the invite link, valid for 7 days.
pathrule billingOpens the organization's billing in Pathrule Web.
pathrule upgradeOpens billing to pick a plan.
pathrule reactivateOpens billing to reactivate the organization.

Help and version

CommandWhat it does
pathrule helpPrints the command list. pathrule help cli prints a short guide to the CLI, and with Pathrule Cloud pathrule help surfaces and pathrule help web describe the other surfaces.
pathrule versionPrints the CLI version, the same as --version.

Work without an account

Pathrule CLI runs a folder on Pathrule Local, a store on this machine, with no account and no cloud. Run this inside the project:

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

On a new install the device default is Pathrule Cloud, so --local is what makes this folder a Local folder. At a terminal, setup asks whether that is for this project only or for the device default; in a script, a new folder is set up for this project only, and --scope device changes the default instead. To make every new folder Local, run pathrule config set default-mode local once.

pathrule setup --local creates the folder's Local workspace, or reuses the one that already covers it, and imports the project's instruction files, such as CLAUDE.md and AGENTS.md, word for word. It then writes the MCP entry for every AI client, or for one with --target <client>, installs the hooks and writes the repository files for Claude Code, and for Codex when the repository has Codex files. --workspace-name <name> names a new workspace, and --import-instructions imports instruction sections an existing workspace has never had. Any other option, such as --org or --workspace, stops with exit code 64. pathrule init --local [name] creates or reuses the Local workspace only, with no hooks and no MCP entries.

In a Local workspace your AI agent writes memories, rules and skills through Pathrule's MCP tools, and you edit them in the Local Console with pathrule ui. From the terminal you read and search them; in a Local folder these commands work on the Local workspace with no flag:

pathrule memory list
pathrule rule read "No service key in browser code"
pathrule search "migrations"
pathrule sync

memory add, rule add and skill add are not available here either. See Open source core for what the local edition includes.

  • Install for the first setup, what Pathrule writes into a repository, and how to remove it.
  • Local or Cloud for editions, switching a folder and the copy of Local knowledge.
  • Pathrule CLI for what the CLI owns and when to use it.
  • User Intelligence for what pathrule me manages.