# Perch CLI

Run Perch from a terminal without installing the Desktop app.

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