CLI reference

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.

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

Global flags

These shape a session and can be passed to perch or 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.

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

Running work

Session and help

Account

Steering the work

Memory, usage, and skills

Delegating work

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.

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, Kimi, MiniMax, DeepSeek, Qwen, or Gemma 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

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 never leaves your machine, which is why this one is CLI only.

perch byolm set http://localhost:11434/v1 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

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. You add them in .perch/mcp.json, and connected tools then appear alongside the built-in ones. See MCP servers.

The agent browser is desktop only, so browser work is not available in the CLI. If you need it from a terminal-driven workflow, run that part in the desktop app.

Next steps

Personas→

Two voices, one engine. Same tools and same tasks, different register.

Troubleshooting→

The handful of things that go wrong, and the fixes.