install

Instala la configuración de un adaptador de entorno a partir del perfil compartido.

SinopsisCopy Anchor Link

apothem install --harness NAME|all [--profile PATH] [--dry-run]
                 [--clean|--fresh] [--yes] [--project PATH]
                 [--quiet|-q] [--verbose|-v]
                 [--format plain|json] [--json] [--no-color]

Carga y valida el perfil compartido, selecciona un adaptador por su nombre o el conjunto all de todo el registro, valida el plan de materialización y escribe la configuración nativa del entorno junto con las cohortes de soporte. Los adaptadores de alcance de proyecto requieren --project PATH.

El alias en forma continua apothem installing (que también se acepta como apothem Installing) se resuelve en el mismo manejador.

Primera ejecución sin perfilCopy Anchor Link

Cuando se omite --profile y no existe ningún perfil en la ruta predeterminada (~/.config/apothem/profile.yaml), install escribe primero allí el perfil inicial, imprime Created a starter profile at <path> y continúa. El perfil inicial lleva campos de identidad de marcador de posición, así que la instalación imprime también la nota de identidad de marcador de posición; personaliza el perfil y luego ejecuta update para aplicarlo. Con --json, la creación se informa como una entrada de warnings con "operation": "profile_created".

• --dry-run nunca escribe el perfil: la vista previa usa el perfil inicial en memoria e informa "operation": "profile_scaffold_preview".
• Un --profile PATH explícito que no existe nunca se crea; el comando sale con 1 y profile.not_found.

Vista previa del radio de impactoCopy Anchor Link

install --harness all se despliega en alcances mixtos: los adaptadores de alcance de proyecto escriben bajo la raíz --project proporcionada, mientras que los adaptadores de alcance de usuario escriben bajo tu directorio personal, fuera de esa raíz. Antes de que la instalación escriba cualquier archivo, el comando imprime los destinos concretos agrupados bajo dos encabezados: los que están dentro de la raíz del proyecto y los que están bajo tu directorio personal. Un tercer encabezado lista las carpetas compartidas de tu directorio personal que escriben los adaptadores de alcance de proyecto, fuera de --project: la carpeta de skills y ~/.config/apothem/ (consulta Carpetas en tu directorio personal). La única excepción es --clean: su paso de partida limpia se ejecuta antes de esta vista previa, escribe una copia de seguridad y elimina los destinos anteriores, tal como se describe más abajo.

Cuando la selección escribe fuera de la raíz del proyecto, ya sea en la carpeta de un adaptador con raíz en el directorio personal o en una carpeta compartida, una confirmación interactiva protege las escrituras con raíz en el directorio personal. --yes, una shell no interactiva (sin TTY), --dry-run y --format json proceden cada uno sin preguntar. Solo --dry-run no escribe nada; --format json omite la vista previa y la solicitud de confirmación, pero aun así realiza las escrituras. Rechazar la solicitud del directorio personal aborta antes de las escrituras de la instalación. Con --clean, el paso de borrón y cuenta nueva se ejecuta primero bajo su propia confirmación por destino: escribe una copia de seguridad en ~/.apothem/backups y elimina los destinos que confirma. Esas eliminaciones y la copia de seguridad se mantienen cuando se rechaza la solicitud de instalación.

Carpetas en tu directorio personalCopy Anchor Link

Siete adaptadores de alcance de proyecto escriben las skills de Apothem, y las reglas y plantillas que citan las skills, en carpetas de tu directorio personal:

cursor, github-copilot, windsurf, zed  ->  ~/.agents/skills/ (codex writes it too)
codebuddy                               ->  ~/.codebuddy/skills/
kiro                                    ->  ~/.kiro/skills/
trae                                    ->  ~/.trae/skills/
all seven                               ->  ~/.config/apothem/rules/ and templates/ (codex uses them too)

• --project elige el archivo de reglas y el proyecto al que pertenece la instalación. No cambia adónde van las skills: una instalación con --project A y otra con --project B escriben las mismas carpetas.
• Cada instalación que nombra una carpeta escribe los mismos archivos. Una segunda instalación los encuentra e informa unchanged, y el orden en que instalas no importa.
• Las carpetas del directorio personal se escriben antes que nada en el proyecto. Si una escritura allí falla, la instalación del adaptador se detiene con el error y el proyecto queda sin cambios. El error nombra la ruta que estorba, por ejemplo un archivo llamado ~/.agents donde debería estar la carpeta.
• Cada carpeta de skill se escribe en una carpeta oculta .<name>.apothem-staging junto a ella y se renombra a su lugar cuando está completa, de modo que una escritura fallida o interrumpida nunca deja una carpeta de skill a medio escribir con su nombre definitivo. Vuelve a ejecutar la instalación para terminar; reemplaza cualquier carpeta de staging que haya quedado.
• Un enlace simbólico en una de estas carpetas o por encima de ella, como los que crean los gestores de dotfiles para ~/.config o ~/.agents, se sigue cuando lleva a algún lugar dentro de tu directorio personal. Un enlace que sale de tu directorio personal detiene la instalación con target escapes the allowed materialization root, y lo mismo ocurre con un enlace dentro de una carpeta de skill.
• La instalación no añade ningún archivo de skill ni de regla a tu repositorio. El proyecto recibe el archivo de reglas del adaptador, además de la carpeta de datos .apothem/ que crea toda instalación de proyecto.
• Una carpeta de skill que tiene el nombre de una skill de Apothem y que Apothem no escribió se omite. La instalación imprime una línea Warning: y el sobre de --format json lleva una entrada de warnings con "outcome": "warning" y "operation": "skill_conflict" que nombra la carpeta. Cámbiale el nombre a la carpeta o muévela y luego ejecuta update.
• Cada una de estas instalaciones, actualizaciones y ejecuciones en seco imprime una Note: que nombra las carpetas que escribe fuera de --project. En el sobre JSON es una entrada de warnings con "operation": "user_level_write" y una lista paths.

Notas sobre capacidadesCopy Anchor Link

Cada adaptador proyecta solo las capacidades que su entorno admite de forma nativa; las capacidades sin superficie nativa se informan, no se descartan en silencio. En modo plain, esto es una única nota agrupada por entorno (por ejemplo Note: <harness> - 9 capabilities not projected; pass --verbose for detail); con --verbose, cada capacidad imprime su propia línea de justificación. Cualquier otra advertencia del adaptador se imprime también en modo plain en su propia línea Warning:, por ejemplo la advertencia de Zed que nombra un archivo de instrucciones que el nuevo .rules oculta. El sobre de --format json siempre lleva la lista warnings completa, independientemente del nivel de detalle.

La instalación y la actualización también imprimen avisos como líneas Note:. Un aviso nunca cambia lo que escribe la instalación. Cuando una instalación escribe una raíz compartida, una ruta que otras herramientas también cargan (por ejemplo la carpeta de skills ~/.agents/skills/), la nota nombra esas herramientas, y pone entre paréntesis una herramienta que carga la ruta solo bajo una condición, por ejemplo Open-Claw (only under its default state directory). Una instalación que escribe una carpeta que otras instalaciones también escriben (el rol holder) indica que la carpeta se mantiene hasta que se desinstala la última instalación de Apothem que la usa, y nombra las instalaciones que la usan ahora. Cuando una instalación apunta a una herramienta que ya carga contenido de Apothem desde la raíz compartida de otra instalación, la nota nombra la instalación que lo colocó: el propietario registrado mientras siga usando la carpeta y, en caso contrario, la instalación más antigua que la use. En el sobre de --format json, cada aviso es una entrada de warnings con "outcome": "advisory" y "operation": "shared_root"; su role es owner, holder o reader, holders lista las instalaciones que usan la carpeta y owner_of_record nombra al propietario registrado.

Una instalación que registra hooks también imprime notas sobre el archivo de hooks. Un aviso hook_review nombra el paso que la herramienta necesita antes de ejecutar los hooks (un reinicio y una revisión, o confiar en el espacio de trabajo), o el riesgo de un archivo de hooks que un repositorio incluye en sus commits y que nombra el intérprete de esta máquina. Un aviso hook_import aparece para una herramienta que también ejecuta los hooks de los archivos de configuración de Claude Code, como los que escribe la instalación de Apothem para Claude Code, y nombra el interruptor propio de la herramienta para desactivar esa importación y lo que ese interruptor detiene además. Cada uno es una entrada de warnings con "outcome": "advisory", el harness, la path del archivo de hooks y un message.

Un comando de hook lleva la ruta del proyecto y la ruta del intérprete entre comillas dobles, que sh, Git Bash y PowerShell leen por igual. Una ruta que contiene $, un acento grave, una comilla doble o una barra invertida haría que el comando ejecutara un archivo distinto, así que la instalación (y --dry-run) se detiene con un error que nombra la ruta y no escribe nada; mueve o cambia el nombre del proyecto y vuelve a ejecutarla. Un espacio o un apóstrofo en una ruta no son problema.

Los servidores MCP del perfil reciben tres avisos, cada uno de los cuales nombra el campo del perfil:

El aviso de credenciales nunca imprime el valor que encontró. Un valor que contiene una referencia ${...} nunca se marca.

Configuraciones del operador con comentariosCopy Anchor Link

Algunas configuraciones de entorno son archivos que tú también editas, como settings.json, opencode.json (que puede ser JSONC), openclaw.json (JSON5) y config.yaml. La instalación fusiona sus claves en estos archivos y conserva cada clave que agregaste.

Una fusión reescribe el archivo como JSON o YAML simple, lo que eliminaría los comentarios, las comas finales y la sintaxis JSON5. Por eso:

• Cuando la fusión no cambiaría ningún valor (por ejemplo, porque tú mismo ya agregaste las claves de Apothem), el archivo se deja byte a byte como está.
• Cuando la fusión debe cambiar un valor en un archivo que lleva comentarios o sintaxis JSON5, o en un archivo que no se puede analizar en absoluto, la instalación no escribe nada para ese entorno y sale con 1 y el código de error config.unparseable. El campo fix nombra las claves que la instalación agregaría, de modo que puedas convertir el archivo a JSON o YAML simple, o agregar esas claves a mano y volver a ejecutar.
• Cuando una clave que la instalación rellena con un mapeo o una lista (por ejemplo skills.external_dirs en config.yaml) contiene en tu archivo un valor escalar, o la otra forma de contenedor, la instalación no escribe nada para ese entorno y sale con 1 y el mismo código de error, porque rellenar la clave descartaría tu valor. El error nombra la clave; cámbiala a la forma que nombra, o elimínala, y vuelve a ejecutar. Una clave que dejaste vacía (skills: sin nada debajo) se rellena.

OpcionesCopy Anchor Link

Salida JSONCopy Anchor Link

Cuando se proporciona --json (o --format json), se escribe un único documento JSON en stdout:

{
  "schema_version": 1,
  "status": "success",
  "command": "install",
  "action": "installed",
  "harness": "claude-code",
  "profile_path": "C:\\Users\\Example\\.config\\apothem\\profile.yaml",
  "project": null,
  "files_written": ["C:\\Users\\Example\\.claude\\settings.json"],
  "results": [],
  "warnings": [],
  "error": null,
  "output_path": "C:\\Users\\Example\\.claude\\settings.json"
}

Con --dry-run no se escribe nada y results lista cada ruta que la instalación escribiría, cada una con el resultado que tendría (created, updated o unchanged) y, para un archivo que tú también editas, el diff unificado en detail.diff — el mismo plan que muestra apothem diff:

{
  "schema_version": 1,
  "status": "dry_run",
  "command": "install",
  "action": "dry_run",
  "harness": "claude-code",
  "files_written": [],
  "results": [
    {
      "harness": "claude-code",
      "outcome": "created",
      "operation": "write_text",
      "path": "C:\\Users\\Example\\.claude\\settings.json",
      "message": "dry run: no filesystem changes made"
    }
  ],
  "warnings": [],
  "error": null
}

Cuando se proporciona --clean, el sobre lleva además un objeto clean que describe la fase de eliminación — la lista de disposiciones por destino, si la ejecución fue una vista previa y el directorio de copia de seguridad con marca de tiempo (null en una ejecución en seco):

{
  "clean": {
    "dry_run": true,
    "backup_dir": null,
    "targets": [
      {
        "path": "C:\\Users\\Example\\.claude",
        "present": true,
        "removed": false,
        "skipped_reason": null
      }
    ]
  }
}

Una ejecución en seco con limpieza previsualiza ambas fases en un único documento: la vista previa de la eliminación bajo clean y la vista previa de la escritura nueva bajo results.

Los errores de validación previstos usan el mismo sobre e incluyen un objeto de error:

{
  "schema_version": 1,
  "status": "error",
  "command": "install",
  "harness": "all",
  "files_written": [],
  "error": {
    "code": "project.required",
    "field": "project",
    "reason": "project-scope harnesses require --project: cursor, gemini-cli, github-copilot, kimi-code, windsurf, codebuddy, kiro, trae, zed, glm.",
    "fix": "Pass --project PATH or select only user-scope harnesses."
  }
}

EjemplosCopy Anchor Link

apothem install --harness claude-code
apothem install --harness claude-code --dry-run
apothem install --harness cursor --project . --profile ~/profile.yaml --json
apothem install --harness all --project . --dry-run --json
apothem installing --harness claude-code   # continuous-form alias
apothem Installing --harness claude-code   # capitalized variant

Códigos de salidaCopy Anchor Link

Véase tambiénCopy Anchor Link

• apothem installing — alias en forma continua de este comando (documentado aquí; la CLI acepta ambas formas)
• apothem update — vuelve a aplicar el perfil actual a un entorno
• apothem verify — confirma que el adaptador está activo
• Primeros pasos — guía de instalación completa