Perch AI

Every command in the Perch CLI — the perch subcommands you run from your shell, and the slash commands you use inside an interactive session.

The Perch CLI is the full operator in your terminal. It runs the same engine and citation checker as the desktop app, working from the folder you are already in. This page is the complete command reference: the perch subcommands you run from your shell, the global flags that shape a session, and the slash commands you type once Perch is running.

Install and sign in

npm install -g perchai-cli   # Node 18+
perch login                  # opens a browser tab, saves your session
perch                         # start working in the current folder

Two ways to run

There are two modes, and the difference is whether you stay in a session or fire one task and exit.

Interactive. Run perch with no arguments to open a chat in the current directory. It reads the files there, takes tasks in plain language, and keeps a thread. Slash commands (below) steer it while it works.
One-shot. Run perch run "<task>" to execute a single task and return. Add --json for machine-readable output. This is the form you script or pipe.

perch                                   # interactive session in .
perch run "Check March invoices for duplicates."   # one task, then exit
perch run "Draft the venue section" --persona quill --json

Shell commands

Commands you run from your shell as perch <command>.

Command	What it does
`perch`	Open an interactive Perch chat in the current directory.
`perch login`	Open browser sign-in and save this terminal's session.
`perch status`	Show the saved auth and app-connection status.
`perch logout`	Clear the saved CLI auth session.
`perch skills [name]`	List Perch's core skills, or print one skill's body.
`perch run "<task>"`	Run a single natural-language task through the operator.
`perch ap evidence <folder>`	Prepare AP-audit evidence, cases, metrics, and graph artifacts.
`perch ap packet <folder>`	Generate the full AP audit packet and report.
`perch test ap <folder>`	Run evidence + packet and emit a pass/fail receipt.
`perch byolm set <url> <model>`	Point Perch at your own local model (Ollama, LM Studio, llama.cpp).
`perch byolm status \| clear \| test`	Show, remove, or probe the local model.

Global flags

These shape a session and can be passed to perch or perch run:

Flag	Values	Purpose
`--cwd <dir>`	any path	Work from a folder other than the current one.
`--permission <mode>`	`default`, `auto_review`, `take_the_wheel`, `plan`	Set how much Perch can do without asking. See Permission modes.
`--mode <mode>`	`ask`, `agents`, `plan`	Set the chat mode for the session.
`--persona <persona>`	`saffron`, `quill`	Start in a working style. See Personas.
`--model <tier>`	`standard`, `standard max`, `pro`, `pro max`	Pin a Roost tier for the run.
`--thinking <on\|off>`	`on`, `off`	Toggle extended thinking for the selected model.
`--thread <id>`	thread id	Continue a specific thread (with `perch run`).
`--json`	—	Emit machine-readable output (with `perch run`).

Slash commands

Once you are in an interactive session, type a slash command at the prompt. While Perch is working you can also type steering text and press Enter; Ctrl-C stops the current turn and Ctrl-E expands details.

Session and help

Command	What it does
`/help`	Show the full command list.
`/status`	Show cwd, auth, mode, persona, permission, and thread.
`/context`	Show the context meter and compaction details.
`/clear`	Clear this terminal session's local conversation memory.
`/exit`	Leave the Perch CLI.

Account

Command	What it does
`/login`	Sign in through browser OAuth.
`/logout`	Clear saved CLI auth.

Steering the work

Command	What it does
`/persona [saffron\|quill]`	Show or switch working style. Personas.
`/mode [ask\|agents\|plan]`	Show or set the chat mode.
`/permission [mode]`	Show or set autonomy for the next turns. Permission modes.
`/model [tier\|name]`	Show or set your model — a Roost tier or an exact model pin. Model tiers.
`/thinking [on\|off]`	Show or toggle extended thinking for the selected model.
`/local-tools [on\|off]`	Show or toggle local shell and file tools.
`/cwd [dir]`	Show or change the working directory.
`/thread [new\|id]`	Show, reset, or set the current thread id.

/permissions is an alias

/permissions does the same thing as /permission — either spelling works.

Memory, usage, and skills

Command	What it does
`/memory-audit <text>`	Check whether a note would be saved to memory, and why. Memory.
`/usage`	Show your Perch Token allowance and this session's usage.
`/skills [name]`	List Perch's core skills, or show one skill's body.

Delegating work

Command	What it does
`/delegate <task>`	Hand a scoped task to a background agent for async execution with review.
`/bg <task>`	Shorthand for `/delegate`.

Use /delegate when a task is self-contained and you would rather keep working than watch it run. The agent executes in the background and returns its result for review, so long jobs never block the session.

Permission modes

Permission modes control how much Perch can do before it stops to ask. Set one with /permission in a session or --permission on launch.

Mode	Behavior
Default	Strict. Writes, commands, sends, deletes, and other irreversible actions require your approval.
Auto Review	Low- and medium-risk reversible work runs automatically. High-risk reversible actions and all irreversible ones still require approval.
Take the Wheel	Full autonomy. Perch can send, delete, modify files, and take irreversible real-world actions without asking first.
Plan	Read-only. Mutating tools stay blocked until you approve a plan.

Start strict

Default is the right mode for real work: nothing irreversible happens without you seeing it. Move to Auto Review once you trust the loop for a given folder, and reserve Take the Wheel for tasks you have already watched Perch do correctly.

Model tiers

/model and --model accept a Roost tier, which lets Roost pick a capable model for each task at standard billing:

auto — let Roost choose.
standard, standard max — everyday work.
pro, pro max — the hardest tasks.

You can also pin an exact model (for example a specific GLM, Gemini, Kimi, MiniMax, DeepSeek, or Qwen build) when you need a known model end to end. Exact pins bill at 2×. Run /model with no argument to see the current selection and the full list.

Bring your own model

perch byolm points Perch at a model you run yourself — Ollama, LM Studio, or llama.cpp — instead of Roost.

perch byolm set http://localhost:11434 llama3.1   # register a local model
perch byolm test                                   # probe that it responds
perch byolm status                                 # show the current local model
perch byolm clear                                  # go back to Roost

Connecting tools

The CLI connects to MCP servers for capabilities beyond the folder. It ships with CourtListener for legal research and Playwright for browser automation, and you can add your own in .perch/mcp.json. Connected tools appear alongside the built-in ones. See MCP servers.