rollback

Restaura um harness ao estado anterior à sua instalação registrada.

SinopseCopy Anchor Link

apothem rollback --harness NAME|all [--install-id ULID | --last] [--yes]
                 [--project PATH]
                 [--quiet|-q] [--verbose|-v]
                 [--format plain|json] [--json] [--no-color]

rollback devolve cada harness selecionado ao estado em que ele estava antes da passagem de instalação registrada — a mais recente por padrão, ou a indicada por --install-id. Percorrendo o registro do ledger dessa instalação, da alteração mais recente para a mais antiga, ele:

• restaura cada arquivo e cada diretório que a instalação sobrescreveu a partir do backup que a instalação capturou, no caminho registrado (um diretório que a instalação substituiu é restaurado exatamente, sem os arquivos que a instalação adicionou a ele);
• remove cada arquivo e cada diretório que a instalação criou e recoloca qualquer caminho do layout legado que a instalação tenha removido;
• remove os armazenamentos de dados compartilhados (memory, contexts, learning) que a instalação criou, a menos que outro harness instalado ainda os use;
• remove os diretórios que a instalação criou, assim que estiverem vazios.

Um arquivo ou uma pasta no seu diretório pessoal que outras instalações também usam (uma pasta de skills, ou ~/.config/apothem/) é tratado como os armazenamentos de dados compartilhados: o rollback o mantém enquanto outra instalação ainda o lista, e o restaura ou remove somente para a última instalação que o usa. Uma pasta que esta instalação encontrou já existente (uma segunda ferramenta instalada depois da primeira) sai com a última instalação que a usa quando quem a criou foi uma instalação que desde então deixou de usá-la, de modo que reverter todas as ferramentas não deixa nada para trás. Quando o registro de uma instalação que poderia usar a pasta não pode ser lido, o rollback para com um erro antes de alterar qualquer coisa e não grava nenhum registro rollback; repare o registro e execute-o novamente.

Tudo o que o rollback remove ou substitui é primeiro copiado para a raiz de backup do Apothem (~/.apothem/backups/), de modo que o próprio rollback pode ser desfeito manualmente. Em seguida, o rollback anexa um registro rollback ao ledger do harness. Reverter uma instalação mais antiga restaura ou remove apenas os destinos que essa instalação mais antiga registrou e descarta todas as instalações posteriores a ela das instalações ativas do ledger, na mesma raiz. Os arquivos que uma instalação posterior adicionou fora desses destinos permanecem no lugar.

O ledger mantém os 10 registros de instalação mais recentes por raiz de instalação (com os backups que eles referenciam); uma instalação mais antiga não pode mais ser revertida por id e relata rollback.no_record. apothem backups prune reduz esse limite sob demanda e nunca remove o backup a partir do qual a instalação mais recente restaura.

Os registros gravados por um lançamento do Apothem anterior à adição desse comportamento não listam quais arquivos a instalação criou; reverter um registro desse tipo restaura apenas os arquivos sobrescritos.

A confirmação é solicitada por harness, a menos que --yes seja fornecido. Quando nenhum prompt é possível — --format json (o texto do prompt corromperia o documento JSON único) ou um shell não interativo (sem TTY) —, o comando recusa de antemão com um erro estruturado rollback.confirmation_required (saída 1), a menos que --yes seja fornecido. --install-id e --last selecionam a passagem de instalação e são mutuamente exclusivos.

Um rollback com --harness all é deliberadamente exaustivo: ele cobre todos os harnesses registrados, incluindo os que o exclude_harnesses do perfil pula durante a instalação. Restaurar o estado anterior à instalação é uma operação de limpeza, então ele alcança registros que uma instalação anterior mais ampla possa ter deixado. Um harness sem nenhuma instalação registrada falha como uma linha "outcome": "error" em results (consulte a saída JSON), e a execução continua com os demais harnesses. Em seguida, o comando sai com código 1 quando nada foi revertido, ou com código 2 (resultado parcial) quando pelo menos um destino foi revertido e uma falha também foi registrada.

OpçõesCopy Anchor Link

Saída JSONCopy Anchor Link

O exemplo é o envelope de um único harness nomeado. Com --harness all, harness é all, output_path é null, e results traz as linhas de cada harness selecionado.

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

Cada alvo restaurado ou removido aparece em results com "operation": "rollback" e um outcome de created ou updated (e em files_written); a message informa se o caminho foi restaurado ou removido. Uma restauração com falha (por exemplo, um backup que foi excluído) é "outcome": "error". Uma instalação que não registrou nenhuma alteração é relatada com "outcome": "skipped". Quando não existe nenhum registro de instalação correspondente para um único harness nomeado, o comando relata um erro rollback.no_record com "status": "error". Com --harness all, um harness sem nenhum registro correspondente é, em vez disso, uma linha "outcome": "error" em results.

ExemplosCopy Anchor Link

apothem rollback --harness claude-code --last
apothem rollback --harness claude-code --install-id 01J9Z… --yes
apothem rollback --harness cursor --project . --last --json

Códigos de saídaCopy Anchor Link

Veja tambémCopy Anchor Link

• apothem install — instala uma configuração de harness
• apothem update — reinstala a partir do perfil compartilhado atual
• apothem uninstall — remove uma configuração de harness
• apothem status — relata o estado de instalação, de verificação e de desvio