Uso de Pi

Esta página recopila detalles de uso diario que no caben en la página de inicio rápido.

Modo interactivo

La interfaz tiene cuatro áreas principales:

• Encabezado de inicio - atajos, archivos de contexto cargados, plantillas de prompt, skills y extensiones
• Mensajes - mensajes del usuario, respuestas del asistente, llamadas a herramientas, resultados de herramientas, notificaciones, errores y UI de extensiones
• Editor - donde escribes; el color del borde indica el nivel de pensamiento actual
• Pie - directorio de trabajo, nombre de sesión, uso de tokens/caché, coste, uso de contexto y modelo actual

El editor puede sustituirse temporalmente por UI integrada como /settings o por UI personalizada de extensiones.

Funciones del editor

Función	Cómo
Referencia de archivo	Escribe @ para buscar archivos del proyecto con coincidencia difusa
Autocompletado de rutas	Pulsa Tab para completar rutas
Entrada multilínea	Shift+Enter, o Ctrl+Enter en Windows Terminal
Imágenes	Pega con Ctrl+V, Alt+V en Windows, o arrastra al terminal
Comando shell	!command se ejecuta y envía la salida al modelo
Comando shell oculto	!!command se ejecuta sin enviar la salida al modelo
Editor externo	Ctrl+G abre $VISUAL o $EDITOR

Consulta Keybindings para todos los atajos y la personalización.

Comandos con barra

Escribe / en el editor para abrir el autocompletado de comandos. Las extensiones pueden registrar comandos personalizados, las skills están disponibles como /skill:name y las plantillas de prompt se expanden con /templatename.

Comando	Descripción
/login, /logout	Gestionar credenciales OAuth o de clave API
/model	Cambiar modelos
/scoped-models	Activar/desactivar modelos para el ciclo Ctrl+P
/settings	Nivel de pensamiento, tema, entrega de mensajes, transporte
/resume	Elegir entre sesiones anteriores
/new	Iniciar una sesión nueva
/name <name>	Establecer el nombre visible de la sesión
/session	Mostrar archivo de sesión, ID, mensajes, tokens y coste
/tree	Saltar a cualquier punto de la sesión y continuar desde ahí
/fork	Crear una sesión nueva a partir de un mensaje de usuario anterior
/clone	Duplicar la rama activa actual en una sesión nueva
/compact [prompt]	Compactar contexto manualmente, opcionalmente con instrucciones personalizadas
/copy	Copiar el último mensaje del asistente al portapapeles
/export [file]	Exportar sesión a HTML
/share	Subir como gist privado de GitHub con enlace HTML compartible
/reload	Recargar atajos, extensiones, skills, prompts y archivos de contexto
/hotkeys	Mostrar todos los atajos de teclado
/changelog	Mostrar historial de versiones
/quit	Salir de pi

Cola de mensajes

Puedes enviar mensajes mientras el agente sigue trabajando:

• Enter encola un mensaje de dirección, entregado cuando el turno actual del asistente termina de ejecutar sus llamadas a herramientas.
• Alt+Enter encola un mensaje de seguimiento, entregado cuando el agente termina todo el trabajo.
• Escape aborta y restaura los mensajes en cola al editor.
• Alt+Up recupera los mensajes en cola al editor.

En Windows Terminal, Alt+Enter es pantalla completa por defecto. Remápalo como se describe en Terminal setup si quieres que pi reciba el atajo.

Configura la entrega en Settings con steeringMode y followUpMode.

Sesiones

Las sesiones se guardan automáticamente en ~/.pi/agent/sessions/, organizadas por directorio de trabajo.

pi -c                  # Continuar la sesión más reciente
pi -r                  # Explorar y seleccionar una sesión
pi --no-session        # Modo efímero; no guardar
pi --name "my task"    # Establecer nombre visible de sesión al iniciar
pi --session <path|id> # Usar un archivo de sesión o ID de sesión específico
pi --fork <path|id>    # Bifurcar una sesión en un archivo de sesión nuevo

Comandos de sesión útiles:

• /session muestra el archivo e ID de la sesión actual.
• /tree navega el árbol de sesión en el archivo y puede resumir ramas abandonadas.
• /fork crea una sesión nueva a partir de un mensaje de usuario anterior.
• /clone duplica la rama activa actual en un archivo de sesión nuevo.
• /compact resume mensajes antiguos para liberar contexto.

Consulta Sessions y Compaction para más detalles.

Archivos de contexto

Pi carga AGENTS.md o CLAUDE.md al iniciar desde:

• ~/.pi/agent/AGENTS.md para instrucciones globales
• directorios padre, subiendo desde el directorio de trabajo actual
• el directorio actual

Usa archivos de contexto para convenciones del proyecto, comandos, reglas de seguridad y preferencias. Desactiva la carga con --no-context-files o -nc.

Archivos de system prompt

Sustituye el system prompt por defecto con:

• .pi/SYSTEM.md para un proyecto
• ~/.pi/agent/SYSTEM.md de forma global

Añade al prompt por defecto sin reemplazarlo con APPEND_SYSTEM.md en cualquiera de las ubicaciones.

Confianza del proyecto

Al iniciar en modo interactivo, pi pregunta antes de confiar en una carpeta de proyecto que contiene ajustes, recursos o .agents/skills locales del proyecto y no tiene una decisión guardada para la carpeta o una carpeta padre en ~/.pi/agent/trust.json. Confiar en un proyecto permite a pi cargar .pi/settings.json y recursos .pi, instalar paquetes del proyecto faltantes y ejecutar extensiones del proyecto.

Antes de la decisión de confianza, pi carga solo archivos de contexto, extensiones de usuario/globales y extensiones CLI -e para que puedan manejar el evento project_trust. Las extensiones locales del proyecto, extensiones gestionadas por paquetes del proyecto y ajustes del proyecto se cargan solo después de confiar en el proyecto. Esta división también aplica al cambiar a una sesión de un cwd distinto cuya confianza no se haya resuelto en el proceso actual.

Los modos no interactivos (-p, --mode json y --mode rpc) no muestran un aviso de confianza. Sin una decisión de confianza guardada aplicable, usan defaultProjectTrust de la configuración global: ask (predeterminado) y never ignoran esos recursos del proyecto, mientras always los confía. Pasa --approve/-a o --no-approve/-na para anular la confianza del proyecto en una ejecución.

Si no aplica ninguna extensión o decisión guardada, defaultProjectTrust controla el comportamiento de respaldo. Establécelo en "ask", "always" o "never" en ~/.pi/agent/settings.json, o cámbialo con /settings.

pi config y los comandos de paquetes usan el mismo flujo de confianza del proyecto, excepto que pi update nunca pregunta. Pasa --approve para confiar en ajustes locales del proyecto en un comando o --no-approve para ignorarlos.

Usa /trust en modo interactivo para guardar una decisión de confianza del proyecto para sesiones futuras, incluida la confianza en la carpeta padre inmediata. Solo escribe en ~/.pi/agent/trust.json; la sesión actual no se recarga, así que reinicia pi para que los cambios surtan efecto.

Exportar y compartir sesiones

Usa /export [file] para escribir una sesión en HTML.

Usa /share para subir un gist privado de GitHub con un enlace HTML compartible.

Si usas pi para trabajo open source y quieres publicar sesiones para investigación de modelos, prompts, herramientas y evaluación, consulta badlogic/pi-share-hf. Publica sesiones en datasets de Hugging Face.

Referencia CLI

pi [options] [@files...] [messages...]

Comandos de paquetes

pi install <source> [-l]     # Instalar paquete, -l para local del proyecto
pi remove <source> [-l]      # Eliminar paquete
pi uninstall <source> [-l]   # Alias de remove
pi update [source|self|pi]   # Actualizar solo pi, o una fuente de paquete
pi update --all              # Actualizar pi y paquetes; reconciliar refs git fijadas
pi update --extensions       # Actualizar solo paquetes; reconciliar refs git fijadas
pi update --self             # Actualizar solo pi
pi update --extension <src>  # Actualizar un paquete
pi list                      # Listar paquetes instalados
pi config                    # Activar/desactivar recursos de paquetes

Estos comandos gestionan paquetes pi y pi update puede actualizar la instalación del CLI de pi. Para desinstalar pi mismo, consulta Quickstart. pi config y los comandos de paquetes del proyecto aceptan --approve/--no-approve para confiar o ignorar ajustes locales del proyecto en un comando. pi update nunca pregunta por confianza del proyecto.

Consulta Pi Packages para fuentes de paquetes y notas de seguridad.

Modos

Flag	Descripción
default	Modo interactivo
-p, --print	Imprimir respuesta y salir
--mode json	Emitir todos los eventos como líneas JSON; consulta JSON mode
--mode rpc	Modo RPC por stdin/stdout; consulta RPC mode
--export <in> [out]	Exportar una sesión a HTML

En modo print, pi también lee stdin canalizado y lo fusiona en el prompt inicial:

cat README.md | pi -p "Summarize this text"

Opciones de modelo

Opción	Descripción
--provider <name>	Proveedor, como anthropic, openai o google
--model <pattern>	Patrón o ID de modelo; admite provider/id y :<thinking> opcional
--api-key <key>	Clave API, anulando variables de entorno
--thinking <level>	off, minimal, low, medium, high, xhigh
--models <patterns>	Patrones separados por comas para el ciclo Ctrl+P
--list-models [search]	Listar modelos disponibles

Opciones de sesión

Opción	Descripción
-c, --continue	Continuar la sesión más reciente
-r, --resume	Explorar y seleccionar una sesión
--session <path|id>	Usar un archivo de sesión o UUID parcial específico
--fork <path|id>	Bifurcar un archivo de sesión o UUID parcial en una sesión nueva
--session-dir <dir>	Directorio personalizado de almacenamiento de sesiones
--no-session	Modo efímero; no guardar
--name <name>, -n <name>	Establecer nombre visible de sesión al iniciar

Opciones de herramientas

Opción	Descripción
--tools <list>, -t <list>	Lista de permitidos de herramientas integradas, de extensión y personalizadas
--exclude-tools <list>, -xt <list>	Desactivar herramientas integradas, de extensión y personalizadas específicas
--no-builtin-tools, -nbt	Desactivar herramientas integradas pero mantener extensiones/personalizadas
--no-tools, -nt	Desactivar todas las herramientas

Herramientas integradas: read, bash, edit, write, grep, find, ls.

Opciones de recursos

Opción	Descripción
-e, --extension <source>	Cargar una extensión desde ruta, npm o git; repetible
--no-extensions	Desactivar descubrimiento de extensiones
--skill <path>	Cargar una skill; repetible
--no-skills	Desactivar descubrimiento de skills
--prompt-template <path>	Cargar una plantilla de prompt; repetible
--no-prompt-templates	Desactivar descubrimiento de plantillas de prompt
--theme <path>	Cargar un tema; repetible
--no-themes	Desactivar descubrimiento de temas
--no-context-files, -nc	Desactivar descubrimiento de AGENTS.md y CLAUDE.md

Combina --no-* con flags explícitos para cargar exactamente lo que necesitas, ignorando ajustes. Ejemplo:

pi --no-extensions -e ./my-extension.ts

Otras opciones

Opción	Descripción
--system-prompt <text>	Reemplazar prompt por defecto; archivos de contexto y skills se siguen añadiendo
--append-system-prompt <text>	Añadir al system prompt
--verbose	Forzar inicio detallado
-a, --approve	Confiar en archivos locales del proyecto en esta ejecución
-na, --no-approve	Ignorar archivos locales del proyecto en esta ejecución
-h, --help	Mostrar ayuda
-v, --version	Mostrar versión

Argumentos de archivo

Antepone @ a los archivos para incluirlos en el mensaje:

pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"

Ejemplos

# Interactivo con prompt inicial
pi "List all .ts files in src/"

# No interactivo
pi -p "Summarize this codebase"

# No interactivo con stdin canalizado
cat README.md | pi -p "Summarize this text"

# Sesión única con nombre
pi --name "release audit" -p "Audit this repository"

# Modelo distinto
pi --provider openai --model gpt-4o "Help me refactor"

# Modelo con prefijo de proveedor
pi --model openai/gpt-4o "Help me refactor"

# Modelo con abreviatura de nivel de pensamiento
pi --model sonnet:high "Solve this complex problem"

# Limitar ciclo de modelos
pi --models "claude-*,gpt-4o"

# Modo solo lectura
pi --tools read,grep,find,ls -p "Review the code"

# Desactivar una extensión o herramienta integrada manteniendo el resto
pi --exclude-tools ask_question

Variables de entorno

Variable	Descripción
PI_CODING_AGENT_DIR	Anular directorio de configuración; predeterminado ~/.pi/agent
PI_CODING_AGENT_SESSION_DIR	Anular directorio de almacenamiento de sesiones; anulado por --session-dir
PI_PACKAGE_DIR	Anular directorio de paquetes, útil para rutas store de Nix/Guix
PI_OFFLINE	Desactivar operaciones de red al iniciar, incluidas comprobaciones de actualización, de paquetes y telemetría de instalación/actualización
PI_SKIP_VERSION_CHECK	Omitir la comprobación de actualización de versión de Pi al iniciar. Evita la petición de última versión a pi.dev
PI_TELEMETRY	Anular telemetría de instalación/actualización y cabeceras de atribución de proveedor: 1/true/yes o 0/false/no. No desactiva las comprobaciones de actualización
PI_CACHE_RETENTION	Establecer en long para caché de prompt extendida donde se admita
VISUAL, EDITOR	Editor externo para Ctrl+G

Principios de diseño

Pi mantiene el núcleo pequeño y delega el comportamiento específico del flujo de trabajo en extensiones, skills, plantillas de prompt y paquetes.

Intencionalmente no incluye MCP integrado, subagentes, ventanas emergentes de permisos, modo plan, tareas pendientes ni bash en segundo plano. Puedes construir o instalar esos flujos como extensiones o paquetes, o usar herramientas externas como contenedores y tmux.

Para la justificación completa, lee la entrada del blog.