Perch CLI

Run Perch from a terminal without installing the Desktop app.

npm install -g perchai-cli
perch login
perch status
perch --cwd ~/Desktop/Project --permission take_the_wheel
perch run "Summarize this folder" --cwd .
perch ap packet ./01-ap

perch login opens your browser, completes OAuth through Perch, and saves the CLI session in the macOS Keychain or ~/.perch/cli-auth-session.json on other platforms.

Interactive Commands

Run perch, then use these commands inside the terminal chat:

• /help — show commands.
• /status — show cwd, auth, mode, persona, permission, and thread.
• /usage — show tokens and estimated cost for this session.
• /cwd [dir] — show or change the working directory.
• /permission [default|auto_review|take_the_wheel|plan] — show or change permission mode.
• /permissions [default|auto_review|take_the_wheel|plan] — alias for /permission.
• /mode [ask|agents|plan] — show or change chat mode.
• /persona [saffron|quill] — show or change persona.
• /context — show context meter and compaction details.
• /local-tools [on|off] — show or toggle local shell/file tools.
• /thread [new|id] — show, reset, or set the current thread id.
• /clear — clear local conversation memory for this terminal session.
• /login — sign in through browser OAuth.
• /logout — clear saved CLI auth.
• /exit — leave Perch CLI.