Referência da CLI
Referência da CLI do Apothem — sinopse, opções e códigos de saída de cada comando da interface de linha de comando apothem.
A interface de linha de comando apothem gerencia as configurações de
adaptadores de harness a partir do perfil compartilhado. Cada página abaixo
documenta um subcomando: sua sinopse, suas opções, seu comportamento e seus
códigos de saída.
Cada um dos comandos install, update e uninstall também aceita um alias na
forma contínua (installing, updating, uninstalling) idêntico ao comando
base em sinalizadores e comportamento. A atualização e a desinstalação pelos
canais de instalação — o plugin do Claude Code, npx e os scripts instaladores
de uma única etapa — são documentadas nos guias de instalação
Atualização e Desinstalação,
e não pelos próprios aliases.
Comandos
| Comando | Descrição |
|---|---|
| quickstart | Primeira execução guiada: garante um perfil, mostra uma prévia das gravações e depois instala. |
| install | Instala a configuração de um adaptador de harness a partir do perfil compartilhado (alias: installing). |
| update | Reinstala a configuração de um adaptador de harness a partir do perfil compartilhado atual (alias: updating). |
| uninstall | Remove a configuração de um adaptador de harness (alias: uninstalling). |
| rollback | Restaura um harness ao estado anterior à sua instalação registrada. |
| backups | Poda os backups de instalação e o histórico do ledger que o Apothem mantém (backups prune). |
| verify | Verifica a instalação de um adaptador de harness. |
| status | Relata o estado de instalação, de verificação e de desvio de cada harness registrado. |
| diff | Mostra uma prévia das alterações de configuração pendentes de um único harness. |
| harnesses | Lista e inspeciona os adaptadores de harness registrados. |
| profile | Gerencia o perfil compartilhado do Apothem. |
| migrate-workspace | Migra um espaço de trabalho legado por harness para o layout compartilhado .apothem. |
| doctor | Executa diagnósticos do sistema para a instalação do Apothem. |
| completion | Emite um script de autocompletar de shell que pode ser carregado com source (bash, zsh, fish, powershell). |
Contrato da saída JSON
Todo comando, exceto completion (que emite um script de shell), aceita
--json (abreviação de --format json) e, nesse caso, grava exatamente um
documento JSON em stdout. Cada documento começa com uma
chave schema_version de nível superior, um inteiro que hoje vale 1:
{"schema_version": 1, "status": "success", "command": "verify", "...": "..."}- Estabilidade. Dentro de uma mesma
schema_version, as mudanças são aditivas: uma nova chave pode aparecer, mas nenhuma chave é renomeada ou removida e nenhum valor muda de tipo. Qualquer outra mudança incrementaschema_version. - Artefatos versionados.
profile show --jsonemite o próprio perfil, então suaschema_versioné a versão do schema do perfil (também1hoje). - Uma exceção.
harnesses list --jsonemite um array JSON (um objeto por harness), como sempre fez, então não tem uma chave de nível superior para carregar a versão. Envolvê-lo em um objeto quebraria os parsers existentes; até que um incremento de versão faça isso, trate seu formato comoschema_version1. - Erros. As falhas esperadas usam o mesmo formato de documento com
"status": "error"e um objetoerrorque carregacode,field,reasonefix.
Códigos de saída
Todos os comandos usam o mesmo pequeno conjunto de códigos de saída; cada página lista os que o comando pode retornar.
| Código | Significado |
|---|---|
| 0 | Sucesso |
| 1 | Falha esperada: um erro de validação, de perfil, de harness, de projeto ou de adaptador |
| 2 | Resultado parcial: um lote gravou ou removeu algo antes de uma falha (somente os comandos cuja página o lista) |
| 64 | Erro de uso: uma opção ou um comando desconhecido, uma opção obrigatória ausente ou um valor de opção inválido |
Um erro de uso nunca toca o sistema de arquivos. Com --json (ou
--format json), ele imprime um documento de erro com "code": "cli.usage"
em vez do texto de uso simples, para que a automação consiga distinguir um
sinalizador digitado errado de uma gravação parcial.
Para os comandos slash e a visão geral da CLI de nível mais alto, consulte as páginas de referência Visão geral da CLI e Comandos slash.
Disciplina de planos — Memória de trabalho efêmera e local ao projeto
Gerencie a memória de trabalho efêmera e local ao projeto em .apothem/plans/ (uma árvore legada .plans/ é atualizada via apothem migrate-workspace) com esquema de frontmatter, transições de ciclo de vida, promoção para ADR e aplicação por meio de hooks e validadores.
quickstart
Referência da CLI para o comando guiado de primeira execução apothem quickstart.