Referencia de la CLI
Todos los comandos de la CLI de Perch, tanto los subcomandos de perch que ejecutas desde tu shell como los comandos de barra que usas dentro de una sesión interactiva.
La CLI de Perch es el operador completo en tu terminal. Usa el mismo motor y el mismo verificador de citas que la app de escritorio, y trabaja desde la carpeta en la que ya estás. Esta página es la referencia completa de comandos: los subcomandos de perch que ejecutas desde tu shell, los flags globales que definen una sesión y los comandos de barra que escribes una vez que Perch está en ejecución.
Instala e inicia sesión
npm install -g perchai-cli # Node 18+
perch login # opens a browser tab, saves your session
perch # start working in the current folderDos formas de ejecutarla
Hay dos modos, y la diferencia está en si te quedas en una sesión o lanzas una sola tarea y sales.
- Interactivo. Ejecuta
perchsin argumentos para abrir un chat en el directorio actual. Lee los archivos que hay ahí, recibe tareas en lenguaje sencillo y mantiene un hilo. Los comandos de barra (más abajo) lo dirigen mientras trabaja. - De una sola ejecución. Ejecuta
perch run "<task>"para realizar una sola tarea y volver. Agrega--jsonpara obtener una salida legible por máquina. Esta es la forma que usas en scripts o con pipes.
perch # interactive session in .
perch run "Check March invoices for duplicates." # one task, then exit
perch run "Draft the venue section" --persona quill --jsonComandos de shell
Comandos que ejecutas desde tu shell como perch <command>.
| Comando | Qué hace |
|---|---|
perch | Abre un chat interactivo de Perch en el directorio actual. |
perch login | Abre el inicio de sesión en el navegador y guarda la sesión de esta terminal. |
perch status | Muestra la autenticación guardada y el estado de la conexión con la app. |
perch logout | Borra la sesión de autenticación guardada de la CLI. |
perch skills [name] | Lista las skills principales de Perch o imprime el contenido de una skill. |
perch run "<task>" | Ejecuta una sola tarea en lenguaje natural a través del operador. |
perch ap evidence <folder> | Prepara la evidencia, los casos, las métricas y los artefactos gráficos de la auditoría de cuentas por pagar. |
perch ap packet <folder> | Genera el paquete y el informe completos de la auditoría de cuentas por pagar. |
perch test ap <folder> | Ejecuta evidence y packet, y emite un comprobante de aprobado o reprobado. |
perch byok use <provider> | off | Ejecuta los turnos de esta terminal con una clave en la nube guardada en tu cuenta, o vuelve a Perch. |
perch byok list | status | test | set | remove | Administra las claves de tu cuenta sin salir de la terminal. |
perch byolm set <url> <model> | Apunta Perch a tu propio modelo local (Ollama, LM Studio, llama.cpp). |
perch byolm status | clear | test | Muestra, quita o prueba el modelo local. |
Flags globales
Definen una sesión y se pueden pasar a perch o a perch run:
| Flag | Valores | Propósito |
|---|---|---|
--cwd <dir> | cualquier ruta | Trabaja desde una carpeta distinta de la actual. |
--permission <mode> | default, auto_review, take_the_wheel, plan | Define cuánto puede hacer Perch sin preguntar. Consulta Modos de permisos. |
--mode <mode> | ask, agents, plan | Define el modo del chat para la sesión. |
--persona <persona> | saffron, quill | Empieza con una voz. Consulta Personas. |
--model <tier> | standard, standard max, pro, pro max | Fija un nivel de Roost para la ejecución. |
--thinking <on|off> | on, off | Activa o desactiva el razonamiento extendido del modelo seleccionado. |
--thread <id> | id del hilo | Continúa un hilo específico (con perch run). |
--json | - | Emite una salida legible por máquina (con perch run). |
Comandos de barra
Una vez que estás en una sesión interactiva, escribe un comando de barra en el prompt. Mientras Perch trabaja, también puedes escribir texto para dirigirlo y presionar Enter; Ctrl-C detiene el turno actual y Ctrl-E expande los detalles.
Esta sección es la lista. Para saber cuándo usar cada uno y qué te devuelve, consulta Comandos de barra.
Ejecutar trabajo
| Comando | Qué hace |
|---|---|
/goal <objective> | Trabaja de forma autónoma hacia un objetivo a lo largo de varios turnos hasta que pasa una auditoría de finalización. |
/goal [status|pause|resume|clear] | Revisa o controla el objetivo activo. Sobrevive al cierre, así que /goal resume funciona en una sesión posterior. |
/verify [text] | Vuelve a verificar la última respuesta, o un texto pegado, contra tus fuentes indexadas. |
/verify --changed | Vuelve a verificar solo las afirmaciones cuyas fuentes cambiaron desde tu último /verify. |
Sesión y ayuda
| Comando | Qué hace |
|---|---|
/help | Muestra la lista completa de comandos. |
/status | Muestra el cwd, la autenticación, el modo, la persona, el permiso y el hilo. |
/context | Muestra el medidor de contexto y los detalles de la compactación. |
/clear | Borra la memoria de conversación local de esta sesión de terminal. |
/exit | Sale de la CLI de Perch. |
Cuenta
| Comando | Qué hace |
|---|---|
/login | Inicia sesión con OAuth en el navegador. |
/logout | Borra la autenticación guardada de la CLI. |
Dirigir el trabajo
| Comando | Qué hace |
|---|---|
/persona [saffron|quill] | Muestra o cambia la voz. Personas. |
/mode [ask|agents|plan] | Muestra o fija el modo del chat. |
/permission [mode] | Muestra o fija la autonomía para los siguientes turnos. Modos de permisos. |
/model [tier|name] | Muestra o fija tu modelo: un nivel de Roost o un modelo fijado exacto. Niveles de modelo. |
/thinking [on|off] | Muestra o activa y desactiva el razonamiento extendido del modelo seleccionado. |
/byok [provider|off] | Muestra o cambia la clave en la nube guardada con la que se ejecutan los turnos de esta terminal. Usar tu propia clave de API. |
/local-tools [on|off] | Muestra o activa y desactiva las herramientas locales de shell y de archivos. |
/cwd [dir] | Muestra o cambia el directorio de trabajo. |
/thread [new|id] | Muestra, reinicia o fija el id del hilo actual. |
/permissions es un alias
/permissions hace lo mismo que /permission; cualquiera de las dos formas funciona.Memoria, uso y skills
| Comando | Qué hace |
|---|---|
/memory-audit <text> | Comprueba si una nota se guardaría en la memoria y por qué. Memoria. |
/usage | Muestra tu uso incluido de Perch Tokens y el uso de esta sesión. |
/skills [name] | Lista las skills principales de Perch o muestra el contenido de una skill. |
Delegar trabajo
| Comando | Qué hace |
|---|---|
/delegate <task> | Le pasa una tarea acotada a un agente en segundo plano para que la ejecute de forma asíncrona, con revisión. |
/bg <task> | Forma abreviada de /delegate. |
Usa /delegate cuando una tarea es autónoma y prefieres seguir trabajando en lugar de verla ejecutarse. El agente trabaja en segundo plano y devuelve su resultado para que lo revises, así que los trabajos largos nunca bloquean la sesión.
Modos de permisos
Los modos de permisos controlan cuánto hace Perch antes de detenerse a preguntar. Elige uno con /permission dentro de una sesión o con --permission al iniciar.
Perch decide en dos pasos. Primero se aplica, al instante, un conjunto fijo de reglas: leer archivos, editar dentro de tu espacio de trabajo y ejecutar los comandos de build y de pruebas propios del proyecto se hacen sin más; los force push, las reescrituras del historial y los borrados masivos siempre se detienen para que decidas tú; y una lista de bloqueo de rutas sensibles (claves, credenciales, carpetas del sistema) se rechaza en todos los modos. Lo que queda es el conjunto más pequeño de acciones importantes que esas reglas no pueden resolver por sí solas, y la forma de manejar ese resto es lo que distingue a los modos.
| Modo | Qué se ejecuta sin preguntar |
|---|---|
| Default | Solo lecturas. Cada escritura, comando, envío y borrado te pide aprobación primero. |
| Auto Review | El trabajo reversible de riesgo bajo y medio se ejecuta solo. Cada acción importante más allá de eso la revisa un revisor aparte, que te pregunta solo cuando tiene dudas. |
| Take the Wheel | Todo, sin preguntar. |
| Plan | Solo lectura. Las herramientas que hacen cambios siguen bloqueadas hasta que apruebes un plan. |
Empieza con el modo estricto
Cómo decide Auto Review
Auto Review es el modo sin intervención que de todas formas mantiene una protección frente al trabajo importante. En lugar de pausarse en cada escritura o comando, envía cada uno que las reglas fijas no pudieron aprobar a un revisor aparte, que emite un veredicto antes de que se ejecute la acción:
- Las acciones permitidas se ejecutan, y el turno continúa sin interrumpirte.
- Las acciones bloqueadas no se ejecutan. A Perch se le indica que encuentre una forma más segura de lograr el objetivo, no que esquive el bloqueo, y sigue trabajando.
- Perch te pregunta cuando el revisor no puede decidir, cuando el mismo tipo de acción se bloquea varias veces seguidas o en las acciones de mayor riesgo, que nunca se revisan automáticamente: los force push y los borrados masivos siempre se detienen para que los confirmes.
El revisor ve tu solicitud y la acción que Perch está a punto de realizar, y nada más. No lee el contenido de los archivos ni la salida de los comandos, así que las instrucciones escondidas en una página web o en un documento no pueden convencerlo de aprobar algo. Si en algún momento el revisor no está disponible, Perch te pregunta en lugar de adivinar. Estas verificaciones consumen una pequeña parte de tu uso incluido, a cambio de un modo que trabaja sin supervisión sin trabajar a ciegas.
La línea que traza Auto Review está entre lo reversible y lo irreversible, no entre lo fácil y lo difícil. Editar un archivo que puedes deshacer es una categoría distinta de enviar un correo electrónico, y el revisor los trata así.
Niveles de modelo
/model y --model aceptan un nivel de Roost, que deja que Roost elija un modelo capaz para cada tarea con facturación estándar:
auto: deja que Roost elija.standard,standard max: trabajo del día a día.pro,pro max: las tareas más difíciles.
También puedes fijar un modelo exacto (por ejemplo, /model claude-opus-5.5 en Pro, o una versión específica de GLM, Kimi, MiniMax, DeepSeek o Qwen) cuando necesitas un modelo conocido de principio a fin. Ejecuta /model sin argumentos para ver la selección actual y la lista completa.
Usa tu propio modelo
Dos comandos, según en qué máquina se ejecute el modelo.
perch byok ejecuta los turnos con una clave en la nube guardada en tu cuenta. La clave se guarda cifrada en la cuenta, así que una clave que agregaste en la web ya está disponible aquí; la elección de la clave es por dispositivo.
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 RoostTambién puedes agregar y probar claves desde aquí, incluido tu propio endpoint compatible con OpenAI:
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 openaiperch byolm apunta Perch a un modelo que tú mismo ejecutas, como Ollama, LM Studio o llama.cpp, en lugar de Roost. El endpoint nunca sale de tu máquina, y por eso este comando es exclusivo de la CLI.
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 RoostLos turnos con cualquiera de los dos no se descuentan de tus Perch Tokens, y Perch no cambia en silencio a un modelo alojado si tu endpoint falla. Consulta Usar tu propia clave de API.
Conectar herramientas
La CLI se conecta a servidores MCP para tener capacidades más allá de la carpeta. Los agregas en .perch/mcp.json, y las herramientas conectadas aparecen junto a las integradas. Consulta Servidores MCP.
El navegador del agente es exclusivo de la app de escritorio, así que el trabajo con el navegador no está disponible en la CLI. Si lo necesitas en un flujo de trabajo basado en la terminal, ejecuta esa parte en la app de escritorio.
Próximos pasos
Comandos de barra
Cómo usar en la práctica cada comando de barra en Perch Terminal y la CLI, qué obtienes y cuándo conviene usar uno en lugar de simplemente pedir algo.
Usar tu propia clave de API
Ejecuta Perch con tu propia clave de modelo o tu propio endpoint, en cualquier plan, incluido el gratis. Configuración para Web, escritorio y CLI, y cómo se relaciona con tu uso incluido.