Manual de referencia de Pi Agent CLI
A continuación se muestra la referencia de los parámetros comunes de línea de comandos de Pi Agent.
Opciones de modo
Los siguientes parámetros controlan el modo de ejecución de Pi Agent; si no se especifican, se entra por defecto en la interfaz interactiva.
| Parámetro | Descripción | Ejemplo |
|---|---|---|
| (predeterminado) | Modo interactivo, interfaz TUI de terminal | pi |
| -p, --print | Modo Print, imprime el resultado y sale | pi -p "resumir código" |
| --mode json | Modo JSON, todos los eventos se emiten como líneas JSON | pi --mode json -p "resumen" |
| --mode rpc | Modo RPC, protocolo JSONL en stdin/stdout | pi --mode rpc |
| --export <entrada> [salida] | Exporta la sesión como HTML; la ruta de salida se puede omitir. | pi --export abc123 session.html |
Opciones de modelo
Los siguientes parámetros se usan para especificar el proveedor, el modelo y el nivel de razonamiento; son adecuados para cambios temporales sin modificar el archivo de configuración.
| Parámetro | Descripción | Ejemplo |
|---|---|---|
| --provider name | Especifica el proveedor de IA | pi --provider anthropic |
| --model pattern | ID de modelo; admite formatos provider/id y :thinking | pi --model openai/gpt-4o pi --model sonnet:high |
| --api-key key | Pasa directamente la API Key; tiene la máxima prioridad; el valor de ejemplo debe reemplazarse con tu propia Key. | pi --api-key sk-ant-api03-xxxx |
| --thinking level | Nivel de razonamiento: off/minimal/low/medium/high/xhigh/max | pi --thinking high |
| --models patterns | Lista de modelos separada por comas; limita el ciclo de Ctrl+P | pi --models "claude-*,gpt-4o" |
| --list-models | Lista todos los modelos disponibles | pi --list-models |
Opciones de sesión
Los siguientes parámetros determinan qué sesión se usa en esta ejecución y dónde se guardan los archivos de sesión.
| Parámetro | Descripción | Ejemplo |
|---|---|---|
| -c, --continue | Continúa la sesión más reciente | pi -c |
| -r, --resume | Examina y selecciona sesiones históricas | pi -r |
| --session path|id | Usa el archivo de sesión o UUID especificado | pi --session abc123 |
| --fork path|id | Crea una nueva sesión bifurcada desde la sesión especificada | pi --fork abc123 |
| --session-dir dir | Directorio personalizado de almacenamiento de sesiones; el directorio predeterminado es ~/.pi/agent/sessions/; este parámetro se usa para reemplazarlo temporalmente. | pi --session-dir .pi/sessions |
| --no-session | Modo temporal, no guarda la sesión | pi --no-session |
| -n, --name name | Establece el nombre mostrado de la sesión | pi --name "refactorizar módulo de autenticación" |
Opciones de herramientas
Los siguientes parámetros controlan el alcance de disponibilidad de las herramientas integradas; se usan para restringir permisos o para mantener una conversación pura.
| Parámetro | Descripción | Ejemplo |
|---|---|---|
| -t, --tools list | Herramientas especificadas mediante lista blanca, separadas por comas | pi --tools read,bash,edit,write |
| -xt, --exclude-tools list | Deshabilita las herramientas especificadas, separadas por comas | pi --exclude-tools bash |
| -nbt, --no-builtin-tools | Deshabilita todas las herramientas integradas, conservando las herramientas de extensión | pi --no-builtin-tools |
| -nt, --no-tools | Deshabilita todas las herramientas, modo de conversación pura | pi --no-tools |
Opciones de recursos
Los siguientes parámetros controlan la carga de extensiones, Skills, plantillas y temas; los parámetros con el prefijo --no- se usan para desactivar el descubrimiento automático.
| Parámetro | Descripción | Ejemplo |
|---|---|---|
| -e, --extension source | Carga una extensión; se puede repetir | pi -e ./my-ext.ts -e npm:@foo/bar |
| --no-extensions | Deshabilita el descubrimiento automático de extensiones | pi --no-extensions |
| --skill path | Carga un Skill; se puede repetir | pi --skill ./my-skill |
| --no-skills | Deshabilita el descubrimiento automático de Skills | pi --no-skills |
| --prompt-template path | Carga una plantilla de prompt; se puede repetir | pi --prompt-template ./review.md |
| --no-prompt-templates | Deshabilita el descubrimiento automático de plantillas | pi --no-prompt-templates |
| --theme path | Carga un tema; se puede repetir | pi --theme ./my-theme.json |
| --no-themes | Deshabilita el descubrimiento automático de temas | pi --no-themes |
| -nc, --no-context-files | Deshabilita la carga de AGENTS.md/CLAUDE.md | pi -nc |
Otras opciones
Los siguientes parámetros sobrescriben comportamientos como el prompt del sistema, la confianza en el proyecto y la información de ayuda.
| Parámetro | Descripción | Ejemplo |
|---|---|---|
| --system-prompt text | Reemplaza el prompt del sistema predeterminado | pi --system-prompt "Eres un experto en Python" |
| --append-system-prompt text | Añade al prompt del sistema | pi --append-system-prompt "Responde en chino" |
| --tui-mode | Modo de interfaz, como fullscreen; si no se especifica, se usa el modo regular. | pi --tui-mode fullscreen |
| --use-theme | Carga el tema especificado; solo tiene efecto para esta ejecución, sin modificar la configuración. | pi --use-theme "dark-plus" |
| --verbose | Fuerza la visualización de información detallada de inicio | pi --verbose |
| -a, --approve | Confía en los archivos locales del proyecto para esta ejecución | pi -a |
| -na, --no-approve | No confía en los archivos locales del proyecto para esta ejecución | pi -na |
| -- | Separador; el contenido posterior se pasa al prompt tal cual | pi -- @notes.md resumir esta nota |
| -h, --help | Muestra información de ayuda | pi -h |
| -v, --version | Muestra el número de versión | pi -v |
-ay-naMutuamente excluyentes; en una misma ejecución solo se puede especificar uno de ellos.
El alcance de ambos se limita a esta ejecución; no se escribe en trust.json.
Subcomandos de pi
Además de los parámetros de inicio, pi ofrece un conjunto de subcomandos para gestionar paquetes de extensión y su propia actualización.
| Subcomando | Descripción |
|---|---|
| pi install <source> | Instala un paquete de extensión; con -l lo instala en el proyecto local. |
| pi remove <source> | Elimina un paquete de extensión instalado |
| pi uninstall <source> | Alias de remove, con el mismo efecto |
| pi list | Lista los paquetes de extensión instalados |
| pi update | Actualiza pi y los paquetes de extensión; admite --self, --all, --models, --extensions, --extension <source> |
| pi config | Habilita o deshabilita los diversos recursos proporcionados por el paquete de extensión. |
Variables de entorno relacionadas
Las siguientes variables de entorno afectan la autenticación, la red y el comportamiento del terminal; pueden usarse como configuración complementaria a los parámetros de línea de comandos.
| Variable | Función | Ejemplo |
|---|---|---|
| ANTHROPIC_API_KEY | Método alternativo de autenticación de Anthropic; se usa cuando no se ha iniciado sesión mediante la suscripción /login. | sk-ant-api03-xxxx |
| HTTP_PROXY / HTTPS_PROXY | Especifica un servidor proxy para las solicitudes de API | http://127.0.0.1:7890 |
| NO_PROXY | Lista blanca de proxy; los hosts que coinciden no pasan por el proxy. | localhost,127.0.0.1 |
| COLORTERM | Uno de los valores de referencia para la detección automática de truecolor; si la detección falla, se puede forzar con PI_TRUE_COLOR=1 o configurando terminal.trueColor. | truecolor |
Para proxies de uso prolongado, se recomienda escribirlos en~/.pi/agent/settings.jsondehttpProxy。
Esta configuración solo tiene efecto en el archivo de configuración global; si se escribe en el nivel de proyecto,.pi/settings.jsonno tiene efecto.
Parámetros de archivo
Uso@Prefijo para referenciar archivos:
$ pi @prompt.md "回答这个问题" $ pi -p @screenshot.png "图中有什么" $ pi @src/code.ts @src/test.ts "对比这两个文件"
Tomando el segundo comando como ejemplo, la salida es similar a:
La imagen muestra una captura de pantalla de una página de inicio de sesión, que incluye un campo de entrada de nombre de usuario, un campo de entrada de contraseña y un botón de inicio de sesión.Otras extensiones