install

Instala a configuração de um adaptador de harness a partir do perfil compartilhado.

SinopseCopy 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]

Carrega e valida o perfil compartilhado, seleciona um adaptador nomeado ou o conjunto all de todo o registro, valida o plano de materialização e grava a configuração nativa do harness mais os cohorts de suporte. Os adaptadores com escopo de projeto exigem --project PATH.

O alias na forma contínua apothem installing (também aceito como apothem Installing) resolve para o mesmo manipulador.

Primeira execução sem um perfilCopy Anchor Link

Quando --profile é omitido e não existe nenhum perfil no caminho padrão (~/.config/apothem/profile.yaml), install primeiro grava ali o perfil inicial, imprime Created a starter profile at <path> e continua. O perfil inicial carrega campos de identidade com marcadores de posição, então a instalação também imprime a nota sobre a identidade com marcadores de posição; personalize o perfil e depois execute update para aplicá-lo. Com --json, a criação é relatada como uma entrada de warnings com "operation": "profile_created".

• --dry-run nunca grava o perfil: a prévia usa o perfil inicial em memória e relata "operation": "profile_scaffold_preview".
• Um --profile PATH explícito que não existe nunca é criado; o comando sai com o código 1 e profile.not_found.

Prévia do raio de impactoCopy Anchor Link

install --harness all se ramifica em escopos mistos: os adaptadores com escopo de projeto gravam sob a raiz informada em --project, enquanto os adaptadores com escopo de usuário gravam sob o seu diretório pessoal — fora dessa raiz. Antes que a instalação grave qualquer arquivo, o comando imprime os destinos concretos agrupados sob dois títulos: os que ficam dentro da raiz do projeto e os que ficam sob o seu diretório pessoal. Um terceiro título lista as pastas compartilhadas no seu diretório pessoal que os adaptadores com escopo de projeto gravam, fora de --project: a pasta de skills e ~/.config/apothem/ (consulte Pastas no seu diretório pessoal). A única exceção é --clean: a etapa de limpeza completa roda antes desta prévia e grava um backup e remove os destinos anteriores, como descrito abaixo.

Quando a seleção grava fora da raiz do projeto, seja na pasta de um adaptador com raiz no diretório pessoal ou em uma pasta compartilhada, uma confirmação interativa protege as gravações com raiz no diretório pessoal. --yes, um shell não interativo (sem TTY), --dry-run e --format json prosseguem, cada um, sem perguntar. Somente --dry-run não grava nada; --format json pula a prévia e o prompt de confirmação, mas ainda realiza as gravações. Recusar o prompt do diretório pessoal aborta a operação antes que a instalação grave. Com --clean, a etapa de recomeço limpo é executada primeiro, sob uma confirmação própria para cada destino: ela grava um backup em ~/.apothem/backups e remove os destinos que confirma. Essas remoções e o backup permanecem no lugar quando o prompt de instalação é recusado.

Pastas no seu diretório pessoalCopy Anchor Link

Sete adaptadores com escopo de projeto gravam as skills do Apothem, e as regras e os templates que as skills citam, em pastas no seu diretório pessoal:

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 seleciona o arquivo de regras e o projeto ao qual a instalação pertence. Ele não altera para onde vão as skills: uma instalação com --project A e outra com --project B gravam as mesmas pastas.
• Toda instalação que nomeia uma pasta grava os mesmos arquivos. Uma segunda instalação os encontra e relata unchanged, e a ordem em que você instala não importa.
• As pastas do diretório pessoal são gravadas antes de qualquer coisa no projeto. Se uma gravação ali falhar, a instalação do adaptador para com o erro e o projeto permanece inalterado. O erro nomeia o caminho que está obstruindo, por exemplo um arquivo chamado ~/.agents onde a pasta deveria estar.
• Cada pasta de skill é gravada em uma pasta oculta .<name>.apothem-staging ao lado dela e renomeada para o lugar quando concluída, de modo que uma gravação com falha ou interrompida nunca deixa uma pasta de skill gravada pela metade sob o seu nome final. Execute a instalação novamente para concluir; ela substitui uma pasta de staging que tenha sobrado.
• Um link simbólico em uma dessas pastas ou acima dela, como os que os gerenciadores de dotfiles criam para ~/.config ou ~/.agents, é seguido quando leva a algum lugar dentro do seu diretório pessoal. Um link que sai do seu diretório pessoal interrompe a instalação com target escapes the allowed materialization root, assim como um link dentro de uma pasta de skill.
• A instalação não adiciona nenhum arquivo de skill ou de regra ao seu repositório. O projeto recebe o arquivo de regras do adaptador, mais a pasta de dados .apothem/ que toda instalação de projeto cria.
• Uma pasta de skill que tem o nome de uma skill do Apothem e que o Apothem não gravou é ignorada. A instalação imprime uma linha Warning: e o envelope --format json carrega uma entrada de warnings com "outcome": "warning" e "operation": "skill_conflict" que nomeia a pasta. Renomeie ou mova a pasta e depois execute update.
• Toda instalação, atualização e simulação desse tipo imprime uma Note: que nomeia as pastas que grava fora de --project. No envelope JSON, ela é uma entrada de warnings com "operation": "user_level_write" e uma lista paths.

Notas sobre capacidadesCopy Anchor Link

Cada adaptador projeta apenas as capacidades que o seu harness suporta nativamente; as capacidades sem superfície nativa são relatadas, e não descartadas silenciosamente. No modo plain, isso é uma única nota agrupada por harness (por exemplo, Note: <harness> - 9 capabilities not projected; pass --verbose for detail); com --verbose, cada capacidade imprime sua própria linha de justificativa. Qualquer outro aviso de adaptador também é impresso em sua própria linha Warning: no modo plain, por exemplo o aviso do Zed que nomeia um arquivo de instruções que o novo .rules oculta. O envelope --format json sempre carrega o array warnings completo, independentemente do nível de detalhe.

A instalação e a atualização também imprimem avisos consultivos como linhas Note:. Um aviso consultivo nunca altera o que a instalação grava. Quando uma instalação grava em uma raiz compartilhada, um caminho que outras ferramentas também carregam (por exemplo, a pasta de skills ~/.agents/skills/), a nota nomeia essas ferramentas e coloca entre parênteses uma ferramenta que só carrega o caminho sob uma condição, por exemplo Open-Claw (only under its default state directory). Uma instalação que grava uma pasta que outras instalações também gravam (o papel holder) informa que a pasta permanece até que a última instalação do Apothem que a usa seja desinstalada e nomeia as instalações que a usam agora. Quando uma instalação tem como alvo uma ferramenta que já carrega conteúdo do Apothem a partir da raiz compartilhada de outra instalação, a nota nomeia a instalação que o colocou ali: o proprietário registrado enquanto ele ainda usa a pasta, caso contrário a instalação mais antiga que a usa. No envelope --format json, cada aviso consultivo é uma entrada de warnings com "outcome": "advisory" e "operation": "shared_root"; o seu role é owner, holder ou reader, holders lista as instalações que usam a pasta e owner_of_record nomeia o proprietário registrado.

Uma instalação que registra hooks também imprime notas sobre o arquivo de hooks. Um aviso consultivo hook_review nomeia a etapa de que a ferramenta precisa antes de executar os hooks (uma reinicialização e uma revisão, ou confiar no workspace), ou o risco de um arquivo de hooks que um repositório versiona e que nomeia o interpretador desta máquina. Um aviso consultivo hook_import aparece para uma ferramenta que também executa os hooks dos arquivos de configuração do Claude Code, como os que a instalação do Apothem para o Claude Code grava, e nomeia o próprio interruptor da ferramenta para desativar essa importação e o que o interruptor também interrompe. Cada um é uma entrada de warnings com "outcome": "advisory", o harness, o path do arquivo de hooks e uma message.

Um comando de hook mantém o caminho do projeto e o caminho do interpretador entre aspas duplas, que sh, o Git Bash e o PowerShell leem. Um caminho que contém $, um acento grave, uma aspa dupla ou uma barra invertida faria o comando executar um arquivo diferente, então a instalação (e --dry-run) para com um erro que nomeia o caminho e não grava nada; mova ou renomeie o projeto e execute novamente. Um espaço ou um apóstrofo em um caminho não causa problema.

Os servidores MCP do perfil recebem três avisos consultivos, cada um nomeando o campo do perfil:

O aviso consultivo de credencial nunca imprime o valor que encontrou. Um valor que contém uma referência ${...} nunca é sinalizado.

Configurações do operador com comentáriosCopy Anchor Link

Algumas configurações de harness são arquivos que você também edita, como settings.json, opencode.json (que pode ser JSONC), openclaw.json (JSON5) e config.yaml. A instalação mescla as próprias chaves nesses arquivos e mantém todas as chaves que você adicionou.

Uma mesclagem reescreve o arquivo como JSON ou YAML simples, o que descartaria comentários, vírgulas finais e a sintaxe JSON5. Por isso:

• Quando a mesclagem não alteraria nenhum valor (por exemplo, você mesmo já adicionou as chaves do Apothem), o arquivo é mantido byte a byte como está.
• Quando a mesclagem precisa alterar um valor em um arquivo que carrega comentários ou sintaxe JSON5, ou em um arquivo que nem sequer pode ser analisado, a instalação não grava nada para esse harness e sai com o código 1 e o código de erro config.unparseable. O campo fix nomeia as chaves que a instalação adicionaria, para que você possa converter o arquivo para JSON ou YAML simples, ou adicionar essas chaves à mão e executar novamente.
• Quando uma chave que a instalação preenche com um mapeamento ou uma lista (por exemplo, skills.external_dirs em config.yaml) contém um valor escalar, ou o outro formato de contêiner, no seu arquivo, a instalação não grava nada para esse harness e sai com o código 1 e o mesmo código de erro, porque preencher a chave descartaria o seu valor. O erro nomeia a chave; altere-a para o formato que ele nomeia, ou remova-a, e execute novamente. Uma chave que você deixou vazia (skills: sem nada abaixo dela) é preenchida.

OpçõesCopy Anchor Link

Saída JSONCopy Anchor Link

Quando --json (ou --format json) é fornecido, um único documento JSON é gravado em 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"
}

Com --dry-run, nada é gravado e results lista cada caminho que a instalação gravaria, cada um com o resultado que teria (created, updated ou unchanged) e, para um arquivo que você também edita, o diff unificado em detail.diff — o mesmo plano que apothem diff mostra:

{
  "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
}

Quando --clean é fornecido, o envelope carrega adicionalmente um objeto clean que descreve a fase de remoção — a lista de disposições por destino, se a execução foi uma prévia e o diretório de backup com carimbo de data e hora (null em uma execução de simulação):

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

Uma execução de simulação com limpeza mostra uma prévia das duas fases em um único documento: a prévia da remoção em clean e a prévia da nova gravação em results.

Os erros de validação esperados usam o mesmo envelope e incluem um objeto de erro:

{
  "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."
  }
}

ExemplosCopy 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 saídaCopy Anchor Link

Veja tambémCopy Anchor Link

• apothem installing — alias na forma contínua deste comando (documentado aqui; a CLI aceita ambas as formas)
• apothem update — reaplica o perfil atual a um harness
• apothem verify — confirma que o adaptador está ativo
• Primeiros passos — guia de instalação completo