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ámetroDescripciónEjemplo
(predeterminado)Modo interactivo, interfaz TUI de terminalpi
-p, --printModo Print, imprime el resultado y salepi -p "resumir código"
--mode jsonModo JSON, todos los eventos se emiten como líneas JSONpi --mode json -p "resumen"
--mode rpcModo RPC, protocolo JSONL en stdin/stdoutpi --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ámetroDescripciónEjemplo
--provider nameEspecifica el proveedor de IApi --provider anthropic
--model patternID de modelo; admite formatos provider/id y :thinkingpi --model openai/gpt-4o
pi --model sonnet:high
--api-key keyPasa 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 levelNivel de razonamiento: off/minimal/low/medium/high/xhigh/maxpi --thinking high
--models patternsLista de modelos separada por comas; limita el ciclo de Ctrl+Ppi --models "claude-*,gpt-4o"
--list-modelsLista todos los modelos disponiblespi --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ámetroDescripciónEjemplo
-c, --continueContinúa la sesión más recientepi -c
-r, --resumeExamina y selecciona sesiones históricaspi -r
--session path|idUsa el archivo de sesión o UUID especificadopi --session abc123
--fork path|idCrea una nueva sesión bifurcada desde la sesión especificadapi --fork abc123
--session-dir dirDirectorio 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-sessionModo temporal, no guarda la sesiónpi --no-session
-n, --name nameEstablece el nombre mostrado de la sesiónpi --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ámetroDescripciónEjemplo
-t, --tools listHerramientas especificadas mediante lista blanca, separadas por comaspi --tools read,bash,edit,write
-xt, --exclude-tools listDeshabilita las herramientas especificadas, separadas por comaspi --exclude-tools bash
-nbt, --no-builtin-toolsDeshabilita todas las herramientas integradas, conservando las herramientas de extensiónpi --no-builtin-tools
-nt, --no-toolsDeshabilita todas las herramientas, modo de conversación purapi --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ámetroDescripciónEjemplo
-e, --extension sourceCarga una extensión; se puede repetirpi -e ./my-ext.ts -e npm:@foo/bar
--no-extensionsDeshabilita el descubrimiento automático de extensionespi --no-extensions
--skill pathCarga un Skill; se puede repetirpi --skill ./my-skill
--no-skillsDeshabilita el descubrimiento automático de Skillspi --no-skills
--prompt-template pathCarga una plantilla de prompt; se puede repetirpi --prompt-template ./review.md
--no-prompt-templatesDeshabilita el descubrimiento automático de plantillaspi --no-prompt-templates
--theme pathCarga un tema; se puede repetirpi --theme ./my-theme.json
--no-themesDeshabilita el descubrimiento automático de temaspi --no-themes
-nc, --no-context-filesDeshabilita la carga de AGENTS.md/CLAUDE.mdpi -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ámetroDescripciónEjemplo
--system-prompt textReemplaza el prompt del sistema predeterminadopi --system-prompt "Eres un experto en Python"
--append-system-prompt textAñade al prompt del sistemapi --append-system-prompt "Responde en chino"
--tui-modeModo de interfaz, como fullscreen; si no se especifica, se usa el modo regular.pi --tui-mode fullscreen
--use-themeCarga el tema especificado; solo tiene efecto para esta ejecución, sin modificar la configuración.pi --use-theme "dark-plus"
--verboseFuerza la visualización de información detallada de iniciopi --verbose
-a, --approveConfía en los archivos locales del proyecto para esta ejecuciónpi -a
-na, --no-approveNo confía en los archivos locales del proyecto para esta ejecuciónpi -na
--Separador; el contenido posterior se pasa al prompt tal cualpi -- @notes.md resumir esta nota
-h, --helpMuestra información de ayudapi -h
-v, --versionMuestra el número de versiónpi -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.

SubcomandoDescripció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 listLista los paquetes de extensión instalados
pi updateActualiza pi y los paquetes de extensión; admite --self, --all, --models, --extensions, --extension <source>
pi configHabilita 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.

VariableFunciónEjemplo
ANTHROPIC_API_KEYMé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_PROXYEspecifica un servidor proxy para las solicitudes de APIhttp://127.0.0.1:7890
NO_PROXYLista blanca de proxy; los hosts que coinciden no pasan por el proxy.localhost,127.0.0.1
COLORTERMUno 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