PerchAI
Using Perch

CLI reference

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 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 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 22 or newer
perch login                  # opens a browser tab, saves your session
perch                         # start working in the current folder

perch login signs in with Google or GitHub; perch login google or perch login github picks one. To update, run perch update. A CLI installed with npm install -g also installs a newer version on its own after an interactive session ends.

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>.

CommandWhat it does
perchOpen an interactive Perch chat in the current directory.
perch login [google|github]Open Google or GitHub sign-in and save this terminal's session.
perch statusShow the saved auth and app-connection status.
perch logoutClear the saved CLI auth session.
perch updateUpdate the Perch CLI to the newest version.
perch run "<task>"Run a single natural-language task through the operator.
perch acpRun Perch inside an app that supports the Agent Client Protocol, such as Zed, JetBrains, or T3 Code.
perch skills [name]List skills, or print one skill's body.
perch skills new <name>Scaffold a new skill under .perch/skills in the project. Add --personal to put it in ~/.perch/skills instead.
perch skills eject <name>Copy a built-in skill into .perch/skills so you can edit it.
perch skills disable|enable <name>Turn a built-in, user, or plugin skill off or on.
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 byok set <provider> --key <key>Save a cloud key and its models to your account.
perch byok use <provider> | offRun this terminal's turns on a saved cloud key, or go back to Perch.
perch byok list | status | test | removeManage the keys on your account without leaving the terminal.
perch byolm detectFind local models that are already running on this computer.
perch byolm use <model>Pick one of the detected models, no URL needed.
perch byolm set <url> <model>Point Perch at your own local model (Ollama, LM Studio, llama.cpp).
perch byolm status | clear | testShow, remove, or probe the local model.
perch byolm off | onStop or resume running turns on the saved local model.
perch sub connect | use | list | disconnectSign in with a provider plan on this device, run turns on it, or stop using it.

Flags

These shape a session. The first five work on both perch and perch run; the rest are for perch run only.

FlagValuesPurpose
--cwd <dir>any pathWork from a folder other than the current one.
--permission <mode>default, auto_review, take_the_wheel, planSet how much Perch can do without asking. See Permission modes.
--mode <mode>ask, agents, planSet the chat mode for the session.
--persona <persona>saffron, quillStart in a voice. See Personas.
--thread <id>thread idContinue a specific thread.
--model <tier>standard, standard 1m, pro, pro 1m, or a model namePick a Roost tier or pin a model for the run.
--effort <level>off, low, medium, high, xhigh, max, ultraSet how hard the model thinks. --thinking on and --thinking off still work as the older form.
--attach <path>file pathAttach a local file to the task. Repeat it for more files. -a is the short form.
--skill <id>skill idRun the task with a skill loaded. Repeat it for more skills.
--jsonnoneEmit machine-readable output.

In an interactive session you set the model and effort with /model and /effort instead of a flag.

Slash commands

Once you are in an interactive session, type a slash command at the prompt. Press / to search the list: type to filter, Tab completes, Enter runs. Type @ to mention a file in the folder, and Perch reads it before it replies.

While Perch is working, Enter adds your message to the task and Tab queues it for after. Esc on an empty input, or Ctrl-C, stops the current turn, and Ctrl-E expands details. /keys lists every composer shortcut.

This section is the list. For when to reach for each one and what it gives you back, see Slash commands.

Running work

CommandWhat it does
/goal <objective>Work autonomously toward an objective across turns until a completion audit passes.
/goal [status|pause|resume|clear]Inspect or control the active goal. It survives quitting, so /goal resume works in a later session.
/verify [text]Re-check the last answer, or pasted text, against your indexed sources.
/verify --changedRe-check only the claims whose sources moved since your last /verify.
/deepresearch <question>Research the web and your own files, then report with a claim ledger.
/flock <task>Split one task across a small team of agents. On Pro and Ultra. See Flock.
/schedule [what and when]Set up a routine that runs in the cloud on a schedule. /routines is the same. Shown on accounts with routines.

Undoing file changes

CommandWhat it does
/rewindList the messages in this chat whose file changes you can undo.
/rewind <n>Restore your files to how they were before message n on that list.
/undoRestore your files to how they were before the latest message that changed them.

Session and help

CommandWhat it does
/helpShow the full command list.
/keysShow the composer keyboard shortcuts.
/statusShow cwd, auth, mode, persona, permission, and thread.
/settingsOpen the settings screen: voice, permissions, models, memory, and your account. /config is the same.
/contextShow the context meter and compaction details.
/compactSummarize older turns to free up the context window.
/theme [auto|dark|light]Show or set the colors. auto matches your terminal's background.
/clearClear this terminal session's local conversation memory.
/exitLeave the Perch CLI. /quit is the same.

Account

CommandWhat it does
/login [google|github]Sign in with Google or GitHub.
/logoutClear saved CLI auth. Your browser sign-in is left alone.
/usageShow your Perch Token allowance and this session's usage.

Steering the work

CommandWhat it does
/persona [saffron|quill]Show or switch voice. Personas.
/mode [ask|agents|plan]Show or set the chat mode.
/permission [mode]Show or set autonomy for the next turns. Permission modes.
/permissions [clear|revoke <n>]View or revoke the commands and tools you allowed for this session.
/model [tier|name]Show or set your model: a Roost tier or an exact model pin. Bare /model opens the picker. Model tiers.
/effort [level]Show or set how hard the model thinks: off, low, medium, high, xhigh, max, or ultra.
/thinking [on|off]The older form of /effort: on sets high, off sets off.
/subagent-model [name|inherit]Set the model that spawned sub-agents use. inherit clears it.
/byok [provider [model]|off]Show, or switch, the saved cloud key and model this terminal's turns run on. Bring your own key.
/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.

/permission and /permissions are different

/permission sets the permission mode. /permissions lists the commands and tools you allowed with "allow for this session", and /permissions revoke <n> or /permissions clear takes them back.

Files, connectors, and skills

CommandWhat it does
/attach [path]Attach a local file to your next message, or list the attached ones. You can also drag or paste a file path into the composer.
/detach [name|#N]Take a file off your next message.
/connectors [add <url>]Choose where each connector runs (this computer, the cloud, or both), sign in, add, or remove one. /mcp is the same.
/skills [name]List Perch's core skills, or show one skill's body.

Delegating work

CommandWhat it does
/delegate <task>Hand a scoped task to a background agent. Its result arrives in this chat when it finishes.
/bg <task>Shorthand for /delegate.
/agents [id|stop id]List this chat's agents, print one agent's steps and report, or stop one.

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 does before it stops to ask. Set one with /permission in a session or --permission on launch.

Perch decides in two steps. A fixed set of rules runs first, instantly: reading files, editing inside your workspace, and running the project's own build and test commands just go; force pushes, history rewrites, and bulk deletions always stop for you; and a sensitive-path blocklist (keys, credentials, system folders) is refused in every mode. What is left is the smaller set of consequential actions those rules cannot settle on their own, and how that leftover is handled is what separates the modes.

ModeWhat runs without asking
DefaultReads only. Every write, command, send, and delete asks you first.
Auto ReviewReversible low- and medium-risk work runs on its own. Each consequential action beyond that is checked by a separate reviewer, which asks you only when it is unsure.
Take the WheelEverything, without asking.
PlanRead-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 run correctly.

How Auto Review decides

Auto Review is the hands-off mode that still keeps a guard in front of consequential work. Rather than pausing on every write or command, it sends each one the fixed rules could not clear to a separate reviewer, which reaches a verdict before the action runs:

  • Allowed actions run, and the turn continues without interrupting you.
  • Blocked actions do not run. Perch is told to find a safer way to reach the goal, not to route around the block, and keeps working.
  • Perch asks you when the reviewer cannot decide, when the same kind of action is blocked several times in a row, or for the highest-risk actions that are never reviewed automatically at all: force pushes and bulk deletions always stop for your confirmation.

The reviewer sees your request and the action Perch is about to take, and nothing else. It does not read file contents or command output, so instructions hidden inside a web page or a document cannot talk it into approving something. If the reviewer is ever unavailable, Perch asks you instead of guessing. These checks use a small part of your allowance, in return for a mode that runs unattended without running blind.

The line Auto Review draws is between reversible and irreversible, not between easy and hard. Editing a file you can undo is a different category from sending an email, and the reviewer treats them that way.

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 1m: everyday work. The 1m tiers use the long context window.
  • pro, pro 1m: the hardest tasks.

The older names standard max and pro max still work.

You can also pin an exact model (for example /model claude-opus-5.5 on Pro, or a specific GLM, Kimi, MiniMax, DeepSeek, or Qwen build) when you need a known model end to end. Run /model with no argument to open the picker, which shows the current selection, the Roost tiers, and every named model.

Bring your own model

Two commands, depending on whose machine the model runs on.

perch byok runs turns on a cloud key saved to your account. The key itself is stored on the account, encrypted, so a key added on the web is already available here; picking it is per device.

perch byok list                  # keys saved on your account
perch byok use openai            # run this terminal's turns on that key
perch byok status                # what turns are running on right now
perch byok off                   # go back to Roost

You can add and probe keys from here too, including your own OpenAI-compatible endpoint:

perch byok set openai --key sk-...
perch byok set custom --key sk-... --url https://api.example.com/v1 --model acme/model-x
perch byok test                  # one real request against the selected key
perch byok remove openai

perch byolm points Perch at a model you run yourself, such as Ollama, LM Studio, or llama.cpp, instead of Roost. The endpoint stays on your machine. The desktop app can use a local model too, under Settings › Models.

perch byolm detect                                    # find local models that are running
perch byolm use llama3.1                              # pick one of them, no URL needed
perch byolm set http://localhost:11434/v1 llama3.1   # or register one by URL
perch byolm test                                      # probe that it responds
perch byolm status                                    # show the current local model
perch byolm off                                       # pause it; perch byolm on resumes
perch byolm clear                                     # remove it and go back to Roost

Turns on either one are not counted against your Perch Tokens, and Perch will not quietly fall back to a hosted model if your endpoint fails. See Bring your own key.

Connecting tools

The CLI connects to MCP servers for capabilities beyond the folder. Run /connectors to see them, sign in, and add or remove one; /connectors add <url> adds a hosted server. Local entries live in ~/.perch/mcp.json, and a project can carry its own in .perch/mcp.json in its folder. Connected tools appear alongside the built-in ones. See MCP servers.

The CLI has a browser of its own. The first time a task needs one, Perch starts a headless Chrome, Edge, or Chromium that is already on your computer. If there is none, it asks before downloading Chrome for Testing. It runs in a separate, temporary profile and never uses your own browser profile, so it is not signed in to your accounts. For work inside apps you are signed in to, use the agent browser in the desktop app.

Git attribution

When Perch runs git commit for you, it adds two lines to the end of the commit message: Co-authored-by: Perch <agent@perchai.app> and Made-with: Perch.

Your own git identity decides who the commit author is. Perch fills in the author from the account you signed in with only when git has no user.email set.

To turn all of this off in the CLI, set the environment variable PERCH_GIT_ATTRIBUTION to off (0 and false work too). Perch then runs its git commands exactly as written: no commit lines, no author.

macOS and Linux. Run this in your terminal, and add the same line to ~/.zshrc (or ~/.bashrc if your shell is bash) to keep it off in new terminals:

export PERCH_GIT_ATTRIBUTION=off

Windows (PowerShell). For the current terminal only:

$env:PERCH_GIT_ATTRIBUTION = "off"

To keep it off, run this once. It applies to terminals you open afterwards, not the one you run it in:

setx PERCH_GIT_ATTRIBUTION off

Settings applies everywhere

The Settings → General switch in the desktop app and on the web is saved to your Perch account, so cloud runs, Slack and routines follow it too. In a terminal, PERCH_GIT_ATTRIBUTION=off turns attribution off whatever your account says.

Next steps