rollback

하니스를 기록된 설치 이전의 상태로 복원합니다.

개요Copy 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은 선택한 각 하니스를 기록된 설치 패스(기본값은 가장 최근 패스, 또는 --install-id로 지정한 패스) 이전의 상태로 되돌립니다. 해당 설치의 원장 기록을 가장 최근 변경부터 차례로 처리하면서 다음을 수행합니다.

• 설치가 덮어쓴 모든 파일과 디렉터리를 설치가 캡처한 백업에서 기록된 경로로 복원합니다(설치가 교체한 디렉터리는 설치가 그 안에 추가한 파일 없이 정확히 복원됩니다).
• 설치가 만든 모든 파일과 디렉터리를 제거하고, 설치가 정리하며 없앤 레거시 레이아웃 경로를 되돌려 놓습니다.
• 설치가 만든 공유 데이터 저장소(memory, contexts, learning)를 제거합니다. 단, 설치된 다른 하니스가 아직 사용 중이면 제거하지 않습니다.
• 설치가 만든 디렉터리가 비게 되면 해당 디렉터리를 제거합니다.

다른 설치도 사용하는 홈 디렉터리의 파일이나 폴더(스킬 폴더, 또는 ~/.config/apothem/)는 공유 데이터 저장소처럼 취급됩니다. rollback은 다른 설치가 아직 그것을 나열하는 동안에는 유지하며, 그것을 사용하는 마지막 설치에 대해서만 복원하거나 제거합니다. 이 설치가 이미 자리에 있는 것으로 발견한 폴더(첫 번째 도구 다음에 설치된 두 번째 도구)는, 그 이후 그 폴더를 놓아 준 설치가 그 폴더를 만들었다면 그 폴더를 사용하는 마지막 설치와 함께 사라지므로, 모든 도구를 롤백하면 아무것도 남지 않습니다. 폴더를 사용할 수 있는 설치의 기록을 읽을 수 없으면, rollback은 어떤 것도 바꾸기 전에 오류와 함께 중단되며 rollback 기록을 쓰지 않습니다. 기록을 복구한 다음 다시 실행하세요.

rollback이 제거하거나 교체하는 모든 대상은 먼저 Apothem 백업 루트 (~/.apothem/backups/)에 복사되므로, 롤백 자체도 수동으로 되돌릴 수 있습니다. rollback은 이어서 하니스 원장에 rollback 기록을 추가합니다. 이전 설치를 롤백하면 그 설치가 기록한 대상만 복원하거나 제거하며, 같은 루트의 원장 활성 설치에서 그 이후의 모든 설치를 제외합니다. 이후 설치가 그 대상 바깥에 추가한 파일은 그대로 남습니다.

원장은 설치 루트마다 가장 최근의 설치 기록 10개(그리고 그 기록이 참조하는 백업)를 보관합니다. 그보다 오래된 설치는 더 이상 id로 롤백할 수 없으며 rollback.no_record를 보고합니다. apothem backups prune은 요청 시 이 한도를 낮추며, 최신 설치가 복원 원본으로 삼는 백업은 절대 제거하지 않습니다.

이 동작이 추가되기 전의 Apothem 릴리스가 작성한 기록에는 설치가 어떤 파일을 만들었는지 나열되어 있지 않습니다. 그런 기록을 롤백하면 덮어쓴 파일만 복원됩니다.

--yes를 제공하지 않으면 하니스마다 확인을 요청합니다. 프롬프트를 띄울 수 없는 경우, 즉 --format json(프롬프트 텍스트가 단일 JSON 문서를 손상시킴) 또는 비대화형 셸(TTY 없음)에서는 --yes를 제공하지 않는 한 명령이 구조화된 rollback.confirmation_required 오류(종료 코드 1)와 함께 처음부터 거부합니다. --install-id와 --last는 설치 패스를 선택하며 상호 배타적입니다.

--harness all 롤백은 의도적으로 빠짐없이 동작합니다. 등록된 모든 하니스를 대상으로 하며, 프로필의 exclude_harnesses가 설치 중에 건너뛰는 하니스도 포함합니다. 설치 전 상태로 되돌리는 것은 정리 작업이므로, 이전에 더 넓은 범위로 수행된 설치가 남겼을 수 있는 기록까지 다룹니다. 기록된 설치가 없는 하니스는 results에 "outcome": "error" 행으로 실패로 기록되며(JSON 출력 참조), 실행은 나머지 하니스로 계속됩니다. 그런 다음 롤백된 대상이 없으면 명령은 1로 종료하고, 대상이 하나 이상 롤백되었고 실패도 함께 기록된 경우에는 2(부분 결과)로 종료합니다.

옵션Copy Anchor Link

JSON 출력Copy Anchor Link

이 예시는 이름이 지정된 단일 하니스에 대한 응답 구조입니다. --harness all에서는 harness가 all이고, output_path는 null이며, results에는 선택된 모든 하니스의 행이 담깁니다.

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

복원되거나 제거된 각 대상은 "operation": "rollback"과 created 또는 updated인 outcome으로 results에 나타납니다(files_written에도 나타남). message는 해당 경로가 복원되었는지 제거되었는지를 알려 줍니다. 실패한 복원(예: 백업이 삭제된 경우)은 "outcome": "error"입니다. 변경 사항을 기록하지 않은 설치는 "outcome": "skipped"로 보고됩니다. 이름을 지정한 단일 하니스에 일치하는 설치 기록이 없으면 명령은 "status": "error"와 함께 rollback.no_record 오류를 보고합니다. --harness all에서는 일치하는 기록이 없는 하니스가 대신 results의 "outcome": "error" 행이 됩니다.

예시Copy Anchor Link

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

종료 코드Copy Anchor Link

함께 보기Copy Anchor Link

• apothem install — 하니스 구성을 설치합니다
• apothem update — 현재 공유 프로필에서 다시 설치합니다
• apothem uninstall — 하니스 구성을 제거합니다
• apothem status — 설치, 검증, 드리프트 상태를 보고합니다