Referência da CLI
Referência da CLI do Apothem — todos os subcomandos e flags.
A CLI apothem é a interface principal do operador para gerenciar o perfil
compartilhado e os adaptadores de harness.
Flags globais
| Flag | Descrição |
|---|---|
--version | Imprime a versão do Apothem e sai |
--help | Imprime a ajuda do comando |
Subcomandos
apothem install
Instala um adaptador de harness a partir do perfil compartilhado.
apothem install --harness <name|all> [--profile PATH] [--project PATH] [--dry-run] [--clean|--fresh] [--yes]| Opção | Descrição |
|---|---|
--harness <name> | Nome do adaptador de harness (veja os valores canônicos abaixo). Obrigatório. |
--profile PATH | Caminho para o YAML do perfil compartilhado. Padrão: ~/.config/apothem/profile.yaml. |
--project PATH | Raiz do projeto para harnesses com escopo de projeto. |
--dry-run | Pré-visualiza a instalação sem gravar arquivos. |
--clean, --fresh | Recomeço do zero por adesão explícita: faz backup e remove o estado de instalação anterior (~/.claude, ~/.codex, ~/.agents, ~/.config/apothem) antes de instalar. |
--yes | Pula a confirmação por alvo durante uma remoção de recomeço do zero (obrigatório para execuções não interativas 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
zedUse --harness all --project <path> para selecionar o conjunto de todo o
registro. A lista exclude_harnesses do perfil é respeitada durante a seleção em
lote de instalação/atualização.
apothem update
Re-deriva a configuração nativa de um adaptador de harness a partir do perfil compartilhado atual.
apothem update --harness <name|all> [--profile PATH] [--project PATH] [--dry-run]| Opção | Descrição |
|---|---|
--harness <name> | Nome do adaptador de harness. Obrigatório. |
--profile PATH | Caminho para o YAML do perfil compartilhado. |
--project PATH | Raiz do projeto para harnesses com escopo de projeto. |
--dry-run | Pré-visualiza a atualização sem gravar arquivos. |
update rematerializa a saída do harness. Ele não atualiza o próprio motor do
Apothem; atualize o motor pelo canal com que você o instalou
(o fluxo /plugin, npx ou os scripts de instalação e atualização), conforme
descrito em Atualização.
apothem uninstall
Remove a configuração nativa de um adaptador de harness.
apothem uninstall --harness <name|all> [--project PATH] [--yes]| Opção | Descrição |
|---|---|
--harness <name> | Nome do adaptador de harness. Obrigatório. |
--project PATH | Raiz do projeto para harnesses com escopo de projeto. |
--yes | Pula a solicitação de confirmação. |
apothem verify
Verifica se os alvos gerenciados de um adaptador de harness estão presentes e válidos.
apothem verify --harness <name|all> [--profile PATH] [--project PATH]| Opção | Descrição |
|---|---|
--harness <name> | Nome do adaptador de harness ou all. Obrigatório. |
--profile PATH | YAML do perfil compartilhado contra o qual a fidelidade é verificada. Sem ele, a verificação é puramente estrutural. |
--project PATH | Raiz do projeto para harnesses com escopo de projeto. |
Sem --profile, a verificação é estrutural: todo alvo gerenciado deve estar
presente e válido. Com --profile, ela também exige fidelidade, de modo que uma
instalação que existe, mas se desviou desse perfil, falha no verify — use-o para
confirmar que um perfil específico está instalado fielmente.
O código de saída é 0 quando o harness é verificado (e, com --profile, fiel a
ele), e 1 quando um alvo está ausente ou inválido, ou quando --profile é
fornecido e a instalação se desviou.
apothem status
Relata o estado de instalação, de verificação e de desvio de cada harness registrado.
apothem status [--profile PATH] [--project PATH]| Opção | Descrição |
|---|---|
--profile PATH | Perfil compartilhado a usar como linha de base de desvio. Um perfil padrão ilegível rebaixa o desvio para unknown em vez de abortar a varredura. |
--project PATH | Raiz do projeto para harnesses com escopo de projeto. Sem ela, esses harnesses relatam needs-project. |
Cada linha associa uma flag installed a uma flag verified, e as duas se
combinam no estado de desvio:
| Estado | Significado |
|---|---|
absent | O Apothem não fez instalação neste harness. |
in-sync | Instalado e correspondente à linha de base do perfil. |
drift | Instalado, mas não corresponde mais — corrija com apothem update. |
unknown | Instalado, mas o perfil de linha de base não pôde ser lido. |
needs-project | Um harness com escopo de projeto foi relatado sem --project, de modo que seu destino não pode ser resolvido. |
installed responde "o Apothem instalou aqui?", não "este harness está presente
na máquina?". Ele se baseia nos próprios artefatos do Apothem — o bloco
gerenciado dentro de uma âncora de instruções e o conteúdo sob a subárvore
.apothem/ de propriedade do Apothem —, nunca em um arquivo de propriedade do
fornecedor que o harness grava para si mesmo. Um harness cujo diretório de
configuração existe, mas que o Apothem nunca tocou, relata absent, e um harness
que foi desinstalado relata absent mesmo que os diretórios esvaziados
permaneçam.
apothem profile
Gerencia o perfil compartilhado do 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 | Descrição |
|---|---|
profile init | Cria um esqueleto de perfil mínimo válido conforme o schema. |
profile show | Imprime o perfil resolvido como JSON no stdout. Com --json, o documento começa com schema_version. |
profile set <key> <value> | Define um campo do perfil. O valor é armazenado como uma string literal — palavras sem aspas não sofrem conversão de tipo, de modo que no continua "no" e 1.0 continua uma string —, exceto true/false e entradas explícitas de lista e mapa [...] / {...}. O perfil montado é validado conforme o schema antes de ser gravado. |
profile edit | Abre o perfil no $EDITOR (recorre ao padrão da plataforma). |
A opção --profile PATH aponta cada subcomando para um arquivo de perfil
alternativo. Padrão: ~/.config/apothem/profile.yaml.
apothem harnesses
Lista e inspeciona os adaptadores de harness registrados.
apothem harnesses list
apothem harnesses show <name>| Subcomando | Descrição |
|---|---|
harnesses list | Imprime uma tabela de cada adaptador registrado com sua flag de status de instalação e seu caminho de saída. |
harnesses show <name> | Imprime o nome, o estado de instalação e o caminho de saída de um adaptador. |
apothem doctor
Executa diagnósticos do sistema para a instalação do Apothem.
apothem doctorImprime a versão do Apothem, o interpretador Python, a plataforma, o caminho do perfil resolvido e uma tabela de status de instalação por harness. O código de saída é 1 quando qualquer verificação falha: um perfil inválido, um harness instalado que não passa na verificação, um comando de hook registrado que não consegue iniciar, um adaptador que não pôde ser carregado ou sondado, ou um ledger ilegível. Um harness que não está instalado é relatado e não constitui uma falha, e notas informativas não alteram o código de saída.
Referência gerada de comandos e flags
| 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?". |
Referência
Registro navegável de classes de artefato com caminhos e disposições em disco para regras, comandos, skills, trabalhadores delegados, hooks, servidores MCP, configurações e output-styles.
Campos do perfil
Referência gerada a partir da fonte para cada campo do esquema do perfil compartilhado do Apothem.