install

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

Sinopse

apothem install --harness NAME|all [--profile PATH] [--dry-run]
                 [--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 escreve a configuração nativa do harness mais as coortes de suporte. Adaptadores com escopo de projeto exigem --project PATH.

O alias na forma contínua apothem installing resolve para o mesmo manipulador.

Prévia do raio de impacto

install --harness all se ramifica em escopos mistos: os adaptadores com escopo de projeto escrevem sob a raiz --project fornecida, enquanto os adaptadores com escopo de usuário escrevem sob o seu diretório pessoal — fora dessa raiz. Antes de qualquer arquivo ser escrito, o comando imprime os destinos concretos agrupados sob dois títulos: aqueles dentro da raiz do projeto e aqueles sob o seu diretório pessoal.

Quando a seleção escreve fora da raiz do projeto, uma confirmação interativa protege as escritas com raiz no diretório pessoal. --yes, um shell não interativo (sem TTY), --dry-run e --format json prosseguem cada um sem perguntar; --dry-run e --format json não escrevem nada. Recusar o prompt aborta antes de qualquer arquivo ser escrito.

Notas sobre capacidades

Cada adaptador projeta apenas as capacidades que o seu harness suporta nativamente; as capacidades sem superfície nativa são relatadas, 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); sob --verbose cada capacidade imprime sua própria linha de justificativa. O envelope --format json sempre carrega o array warnings completo, independentemente do nível de detalhe.

Opções

Saída JSON

Quando --json (ou --format json) é fornecido, um único documento JSON é escrito em stdout:

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

Para --dry-run:

{
  "status": "dry_run",
  "command": "install",
  "action": "dry_run",
  "harness": "claude-code",
  "files_written": [],
  "results": [],
  "warnings": [],
  "error": null
}

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

{
  "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, windsurf.",
    "fix": "Pass --project PATH or select only user-scope harnesses."
  }
}

Exemplos

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   # lowercase variant

Códigos de saída

Veja também

• 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