Referencia de la CLI
Referencia de la CLI de Apothem — todos los subcomandos e indicadores.
La CLI apothem es la interfaz principal del operador para gestionar el perfil
compartido y los adaptadores de entorno.
Indicadores globales
| Indicador | Descripción |
|---|---|
--version | Imprime la versión de Apothem y sale |
--help | Imprime la ayuda del comando |
Subcomandos
apothem install
Instala un adaptador de entorno a partir del perfil compartido.
apothem install --harness <name|all> [--profile PATH] [--project PATH] [--dry-run] [--clean|--fresh] [--yes]| Opción | Descripción |
|---|---|
--harness <name> | Nombre del adaptador de entorno (consulta los valores canónicos más abajo). Obligatorio. |
--profile PATH | Ruta al YAML del perfil compartido. Por defecto, ~/.config/apothem/profile.yaml. |
--project PATH | Raíz del proyecto para los entornos con alcance de proyecto. |
--dry-run | Previsualiza la instalación sin escribir archivos. |
--clean, --fresh | Borrón y cuenta nueva opcional: respalda y elimina el estado de la instalación anterior (~/.claude, ~/.codex, ~/.agents, ~/.config/apothem) antes de instalar. |
--yes | Omite la confirmación por destino durante una eliminación con borrón y cuenta nueva (obligatorio para las ejecuciones no interactivas de --clean). |
Valores canónicos de --harness:
antigravity
claude-code
codebuddy
codex
cursor
gemini-cli
github-copilot
glm
hermes
kimi-code
kiro
open-claw
opencode
qwen-code
trae
windsurf
zedUsa --harness all --project <path> para seleccionar el conjunto completo del
registro. La lista exclude_harnesses del perfil se respeta durante la selección
por lotes de instalación/actualización.
apothem update
Vuelve a derivar la configuración nativa de un adaptador de entorno a partir del perfil compartido actual.
apothem update --harness <name|all> [--profile PATH] [--project PATH] [--dry-run]| Opción | Descripción |
|---|---|
--harness <name> | Nombre del adaptador de entorno. Obligatorio. |
--profile PATH | Ruta al YAML del perfil compartido. |
--project PATH | Raíz del proyecto para los entornos con alcance de proyecto. |
--dry-run | Previsualiza la actualización sin escribir archivos. |
update vuelve a materializar la salida del entorno. No actualiza el propio
motor de Apothem; actualiza el motor por el canal con el que lo instalaste
(el flujo /plugin, npx, o los scripts de instalación y actualización), como
se describe en Actualización.
apothem uninstall
Elimina la configuración nativa de un adaptador de entorno.
apothem uninstall --harness <name|all> [--project PATH] [--yes]| Opción | Descripción |
|---|---|
--harness <name> | Nombre del adaptador de entorno. Obligatorio. |
--project PATH | Raíz del proyecto para los entornos con alcance de proyecto. |
--yes | Omite el aviso de confirmación. |
apothem verify
Verifica que los destinos gestionados de un adaptador de entorno estén presentes y sean válidos.
apothem verify --harness <name|all> [--profile PATH] [--project PATH]| Opción | Descripción |
|---|---|
--harness <name> | Nombre del adaptador de entorno o all. Obligatorio. |
--profile PATH | YAML del perfil compartido contra el que se comprueba la fidelidad. Sin esta opción, la comprobación es puramente estructural. |
--project PATH | Raíz del proyecto para los entornos con alcance de proyecto. |
Sin --profile, la comprobación es estructural: cada destino gestionado debe
estar presente y ser válido. Con --profile, también exige fidelidad, de modo
que una instalación que existe pero se ha desviado de ese perfil no supera
verify — úsala para confirmar que un perfil concreto está instalado fielmente.
El código de salida es 0 cuando el entorno se verifica (y, con --profile, es
fiel a él), y 1 cuando falta un destino o no es válido, o cuando se pasa
--profile y la instalación se ha desviado.
apothem status
Informa el estado de instalación, de verificación y de desviación de cada entorno registrado.
apothem status [--profile PATH] [--project PATH]| Opción | Descripción |
|---|---|
--profile PATH | Perfil compartido que se usa como referencia de desviación. Un perfil predeterminado ilegible degrada la desviación a unknown en lugar de abortar el barrido. |
--project PATH | Raíz del proyecto para los entornos con alcance de proyecto. Sin esta opción, esos entornos informan needs-project. |
Cada fila combina un indicador installed con un indicador verified, y ambos
se combinan en el estado de desviación:
| Estado | Significado |
|---|---|
absent | Apothem no se ha instalado en este entorno. |
in-sync | Instalado y coincide con el perfil de referencia. |
drift | Instalado, pero ya no coincide — corrígelo con apothem update. |
unknown | Instalado, pero no se pudo leer el perfil de referencia. |
needs-project | Se informó de un entorno con alcance de proyecto sin --project, por lo que no se puede resolver su destino. |
installed responde a «¿Apothem se instaló aquí?», no a «¿este entorno está
presente en la máquina?». Se basa en los propios artefactos de Apothem — el
bloque gestionado dentro de un ancla de instrucciones y el contenido bajo el
subárbol .apothem/ propiedad de Apothem —, nunca en un archivo propiedad del
proveedor que el entorno escribe para sí mismo. Un entorno cuyo directorio de
configuración existe pero que Apothem nunca tocó informa absent, y uno que se
ha desinstalado informa absent aunque sigan existiendo los directorios
vaciados.
apothem profile
Gestiona el perfil compartido de Apothem.
apothem profile show [--profile PATH]
apothem profile init [--profile PATH] [--force]
apothem profile set <key> <value> [--profile PATH]
apothem profile edit [--profile PATH]| Subcomando | Descripción |
|---|---|
profile init | Crea un andamiaje de perfil mínimo válido según el esquema. |
profile show | Imprime el perfil resuelto como JSON en stdout. Con --json, el documento empieza por schema_version. |
profile set <key> <value> | Establece un campo del perfil. El valor se guarda como cadena literal: las palabras sueltas no se convierten, de modo que no sigue siendo "no" y 1.0 sigue siendo una cadena; hacen excepción true/false y la entrada explícita de listas y mapas [...] / {...}. El perfil ensamblado se valida contra el esquema antes de escribirse. |
profile edit | Abre el perfil en $EDITOR (recurre al valor predeterminado de la plataforma). |
La opción --profile PATH apunta cada subcomando a un archivo de perfil
alternativo. Por defecto, ~/.config/apothem/profile.yaml.
apothem harnesses
Lista e inspecciona los adaptadores de entorno registrados.
apothem harnesses list
apothem harnesses show <name>| Subcomando | Descripción |
|---|---|
harnesses list | Imprime una tabla de cada adaptador registrado con su indicador de estado de instalación y su ruta de salida. |
harnesses show <name> | Imprime el nombre, el estado de instalación y la ruta de salida de un adaptador. |
apothem doctor
Ejecuta diagnósticos del sistema para la instalación de Apothem.
apothem doctorImprime la versión de Apothem, el intérprete de Python, la plataforma, la ruta del perfil resuelto y una tabla de estado de instalación por entorno. El código de salida es 1 cuando falla cualquier comprobación: un perfil no válido, un entorno instalado que no supera la verificación, un comando de hook registrado que no puede arrancar, un adaptador que no puede cargarse o sondearse, o un historial de instalación ilegible. Un entorno que no está instalado se informa, pero no es un fallo, y las notas informativas no cambian el código de salida.
Referencia generada de comandos e indicadores
| Command | Flags | Description |
|---|---|---|
apothem backups prune | --dry-run, --format, --harness, --json, --keep, --no-color, --quiet, -q, --verbose, -v | Delete backup sets and install records beyond the newest N per harness. Keeps the newest N backup sets under ~/.apothem/backups/ for each selected harness, and the newest N install records per install root in its ledger under ~/.apothem/state/. A backup set that a kept record, or the latest install record of any install root, still references is never deleted, so rollback of the latest install still restores. |
apothem completion | — | Print a shell-completion script for SHELL to stdout. Supported shells: bash, zsh, fish, powershell. Every script is generated by Click's env-var completion protocol — PowerShell through the completion class registered above, since Click ships none natively. Enabling completion is opt-in: this command only prints the script — pipe or append it to the shell's completion file yourself (see --help). |
apothem diff | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Preview the pending configuration changes for a single harness. |
apothem doctor | --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Check the installed harnesses and the shared profile; exit 1 on any failure. Reports the engine version, Python, and platform; validates a present shared profile against the packaged schema; and, for every installed harness, runs the adapter's verify and starts each hook command the install registered with a no-op payload. A harness that is not installed is reported but is not a failure, so a machine with one healthy harness passes. Project-scope harnesses are checked when --project names their root. |
apothem harnesses list | --format, --json, --no-color, --quiet, -q, --verbose, -v | List all registered harness adapters. |
apothem harnesses show | --format, --json, --no-color, --quiet, -q, --verbose, -v | Show details for a specific harness adapter. |
apothem install | --clean, --fresh, --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Install a harness adapter configuration. |
apothem migrate-workspace | --dry-run, --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Migrate a legacy per-harness workspace into the shared .apothem layout. The base is the resolved --project root when supplied, otherwise the current working directory (the project-local default). Per-harness memory/contexts/learning stores union-merge into the shared store; a conflicting record is skipped, never overwritten; a legacy .plans tree moves under .apothem/plans; every consumed source is backed up first. The migration is idempotent. |
apothem profile edit | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Open the shared profile in the system editor. |
apothem profile init | --force, --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Create a schema-valid shared profile scaffold. |
apothem profile set | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Set a key in the shared profile. KEY is a dotted path that descends into the nested profile structure (identity.name, preferences.style, enforcement.sprints, harnesses.<harness>.preferences.style); a single key with no dot sets a top-level node. VALUE is stored as a literal string — bare words are not coerced (no stays "no", 2024-01-01 and 1.0 stay strings) — except true/false (the boolean enforcement flags) and explicit [...]/{...} list/map input. The fully-assembled profile is validated against the packaged schema BEFORE writing; an invalid set is refused with the standard diagnostic and the profile on disk is unchanged. |
apothem profile show | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Display the current shared profile. |
apothem quickstart | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Guided first run: ensure a profile, preview the writes, then install. Walks a new operator through the canonical path in one linear flow — create a starter profile if none exists (with a personalize nudge), preview the files each harness will write (project root vs your home directory), confirm, then install with the grouped capability-note output — and ends with the recommended next commands. --yes runs the whole sequence non-interactively; --format json emits one structured summary of every step. It composes the install building blocks; it does not duplicate them. Without --harness it asks which harness to install, so the first run writes one harness's configuration rather than all of them; all is an explicit choice. A run that cannot ask fails with a usage error before anything is written. |
apothem rollback | --format, --harness, --install-id, --json, --last, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Restore a harness to the state before its recorded install. |
apothem status | --format, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Report install, verify, and drift state for every registered harness. |
apothem uninstall | --format, --harness, --json, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Remove a harness adapter configuration. |
apothem update | --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Re-install a harness adapter configuration from the current profile. |
apothem verify | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Verify a harness adapter installation. Without --profile the check is structural: every managed target must be present and valid. With --profile the check additionally requires profile fidelity, so a present-but-drifted install fails verify — answering "is THIS profile faithfully installed?" rather than merely "does it exist?". |
Referencia
Registro navegable de clases de artefacto con rutas y disposiciones en disco para reglas, comandos, skills, trabajadores delegados, hooks, servidores MCP, ajustes y output-styles.
Campos del perfil
Referencia generada desde la fuente para cada campo del esquema del perfil compartido de Apothem.