Referencia CLI

El CLI de pillbox está diseñado para operadores humanos y tareas de configuración. El agente interactúa con Pillbox mediante el servidor MCP, no el CLI.

`pillbox status`

Muestra el estado global: ruta del binario, bases de datos global y local, bottle activo, servidor HTTP, servidor MCP y skill.

Comandos serve

`pillbox serve`

Muestra el estado del servicio si está instalado. Si no está instalado, muestra un aviso con el comando para instalarlo.

`pillbox serve install [--port N]`

Registra el servidor HTTP como servicio del sistema y habilita el arranque automático al iniciar el equipo. Puerto por defecto: 4242.

pillbox serve install
pillbox serve install --port 8080

También añade pillbox.local al fichero hosts del sistema para acceder por nombre en lugar de localhost. Requiere permisos de escritura en el fichero hosts (sudo en Linux/macOS, administrador en Windows); si no los tiene, el servicio se instala igualmente y el acceso queda disponible en http://localhost:<puerto>.

`pillbox serve uninstall`

Elimina el servicio del sistema y la entrada pillbox.local del fichero hosts. En Windows, requiere una terminal elevada (Administrador).

`pillbox serve start`

Arranca el servicio. El servicio debe estar instalado previamente con pillbox serve install.

`pillbox serve stop`

Detiene el servicio.

`pillbox serve status`

Muestra si el servidor está corriendo y la URL de acceso.

Comandos bottle

`pillbox bottle init`

Asistente interactivo para inicializar un bottle en el directorio actual.

Pide un nombre para mostrar (por defecto: nombre del directorio)
Pide el alcance: local o global
Crea la base de datos y ejecuta las migraciones
Si es local y está en un repositorio git: ofrece añadir .pillbox/ al .gitignore

`pillbox bottle status`

Estado del bottle en el directorio actual.

`pillbox bottle list [-l N]`

Lista todos los bottles registrados en la base de datos global. Por defecto: 20.

pillbox bottle list
pillbox bottle list -l 50

`pillbox bottle migrate <global|local>`

Mueve las prescripciones y pills de un bottle entre las bases de datos local y global. Pide confirmación y actualiza el scope del bottle automáticamente.

global: mueve el bottle del directorio actual a la base de datos global y elimina el archivo de base de datos local (.pillbox/pillbox.db).

local: muestra un listado interactivo de bottles globales; mueve el seleccionado a la base de datos local y lo elimina del global. Falla si el directorio ya tiene un bottle local.

pillbox bottle migrate global    # local → global (elimina el archivo de BD local)
pillbox bottle migrate local     # global → local (elimina el bottle del global)

`pillbox bottle delete <slug>`

Elimina un bottle del registro global. Requiere escribir el slug para confirmar — la operación no se puede deshacer.

pillbox bottle delete mi-proyecto

El comando muestra el nombre, slug y ruta de la base de datos del bottle antes de pedir confirmación.

`pillbox bottle repair <slug>`

Actualiza la ruta de la base de datos de un bottle desvinculado — uno cuyo archivo .pillbox/pillbox.db ya no existe en la ubicación registrada (por ejemplo, después de mover un proyecto a un nuevo directorio).

pillbox bottle repair mi-proyecto

Pide la nueva ruta absoluta al archivo pillbox.db. La ruta debe existir y ser un archivo; si no existe, el comando termina con error sin hacer cambios.

`pillbox bottle vinculate [directorio]`

Registra una base de datos local existente en el registro global del usuario actual. Útil cuando un segundo usuario del sistema necesita acceder a un bottle creado por otro usuario en la misma máquina — por ejemplo, cuando dos usuarios comparten un directorio de proyecto.

directorio es opcional y usa el directorio de trabajo actual por defecto.

pillbox bottle vinculate                           # vincula el bottle del directorio actual
pillbox bottle vinculate /home/alice/mi-proyecto   # vincula el bottle en la ruta indicada

El comando lee el bottle de <directorio>/.pillbox/pillbox.db y lo añade a ~/.pillbox/pillbox.db. La operación es idempotente — ejecutarla dos veces reporta “ya vinculado” sin error.

Condiciones de error:

.pillbox/pillbox.db no encontrado en la ruta resuelta — sale con código 1
La ruta resuelta es la propia base de datos global (enlace circular) — sale con código 1
La base de datos local no contiene ningún bottle — sale con código 1

Comandos prescription

`pillbox prescription open "<título>"`

Abre una nueva prescription (sesión de trabajo) para el bottle actual.

pillbox prescription open "Implementar login OAuth"

Es posible tener múltiples prescriptions abiertas simultáneamente en el mismo bottle.

`pillbox prescription list [-l N] [--archived-limit N]`

Lista las prescriptions más recientes del bottle actual. Por defecto: 10.

Flag	Descripción
`-l`, `--limit N`	Máximo de prescriptions activas a mostrar (por defecto: 10)
`--archived-limit N`	Máximo de prescriptions archivadas a mostrar; `0` oculta la sección

pillbox prescription list
pillbox prescription list -l 25
pillbox prescription list --archived-limit 0

`pillbox prescription show <id> [-l N] [--archived-limit N]`

Muestra el detalle completo de una prescription y todas sus pills. Acepta el UUID completo o un prefijo corto (≥ 8 caracteres). Por defecto muestra 20 pills; usa -l para cambiar el límite.

Flag	Descripción
`-l`, `--limit N`	Máximo de pills a mostrar (por defecto: 20)
`--archived-limit N`	Máximo de pills archivadas a mostrar; `0` oculta la sección

pillbox prescription show abc123ef
pillbox prescription show abc123ef -l 50

`pillbox prescription close`

Cierra la prescription abierta del bottle actual.

`pillbox prescription reopen <id>`

Reabre una prescription cerrada (limpia ended_at). Acepta el UUID completo o un prefijo corto (≥ 8 caracteres). Idempotente — si la prescription ya está abierta, finaliza con éxito sin cambios.

pillbox prescription reopen abc123ef

Comandos pill

`pillbox pill show <id>`

Muestra el detalle completo de una pill por su UUID. Acepta el UUID completo o un prefijo corto. Funciona aunque la pill esté archivada.

pillbox pill show abc123ef

Comandos capsule

`pillbox capsule list [-l N] [--archived-limit N]`

Lista las capsules globales — activas primero, archivadas (soft-deleted) en una sección separada al final. Por defecto: 50.

Flag	Descripción
`-l`, `--limit N`	Máximo de capsules activas a mostrar (por defecto: 50)
`--archived-limit N`	Máximo de capsules archivadas a mostrar; `0` oculta la sección

pillbox capsule list
pillbox capsule list -l 100
pillbox capsule list --archived-limit 0

`pillbox capsule show <id>`

Muestra el detalle completo de una capsule por UUID, incluyendo si está archivada. Acepta el UUID completo o un prefijo corto.

pillbox capsule show abc123ef

Comandos MCP

`pillbox mcp install`

Descarga el servidor MCP desde la última release de GitHub y lo instala en ~/.pillbox/mcp/. Requiere Node.js ≥ 18. Detecta todos los providers instalados (claude, opencode) y registra la entrada MCP en cada uno de ellos.

`pillbox mcp uninstall [--provider <nombre>]`

Elimina el directorio del servidor MCP y su entrada de todos los providers detectados. Usa --provider para apuntar a un provider específico.

Flag	Descripción
`--provider <nombre>`	Provider del que desinstalar (`claude` u `opencode`). Si se omite, pregunta interactivamente.

`pillbox mcp status`

Muestra el estado de instalación del servidor MCP y la ayuda de uso.

Comandos skill

`pillbox skill install`

Descarga la skill de Claude Code desde la última release de GitHub. Detecta todos los providers instalados e instala la skill en cada uno de ellos.

`pillbox skill uninstall [--provider <nombre>]`

Elimina el directorio de la skill para el provider indicado. Usa --provider para apuntar a un provider específico.

Flag	Descripción
`--provider <nombre>`	Provider del que desinstalar (`claude` u `opencode`). Si se omite, pregunta interactivamente.

`pillbox skill status`

Muestra el estado de instalación de la skill y la ayuda de uso.

Comandos de idioma

`pillbox lang`

Muestra el idioma actual y las opciones disponibles.

`pillbox lang set <código>`

Establece el idioma del CLI. Se guarda en ~/.pillbox/lang.

pillbox lang set es
pillbox lang set en

Códigos soportados: es, en, de, it, pt, fr.

Orden de detección del idioma: ~/.pillbox/lang → variable de entorno PILLBOX_LANG → idioma del sistema → fallback es.

`pillbox update`

Auto-actualiza el binario de Pillbox desde la última release de GitHub. Compara la versión actual con la última disponible y pide confirmación antes de descargar y reemplazar el binario.

pillbox update

`pillbox uninstall`

Eliminación interactiva de los componentes de Pillbox. Pregunta antes de cada paso: servidor MCP, skill, base de datos global, binario.

Variables de entorno

Variable	Descripción
`PILLBOX_LANG`	Sobreescribe la detección de idioma (ej. `PILLBOX_LANG=en`)
`PILLBOX_VERSION`	Versión a instalar (usada por `install.sh`)
`PILLBOX_INSTALL_DIR`	Directorio de instalación del binario
`RUST_LOG`	Nivel de log del servidor (ej. `RUST_LOG=info pillbox serve start`)