rollback

Restore a harness to the state before its recorded install.

SynopsisCopy 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 returns each selected harness to the state it was in before the recorded install pass — the latest by default, or the one named by --install-id. Working through that install's ledger record, newest change first, it:

• restores every file and directory the install overwrote from the backup the install captured, at its recorded path (a directory the install replaced is restored exactly, without the files the install added to it);
• removes every file and directory the install created, and puts back any legacy-layout path the install swept away;
• removes the shared data stores (memory, contexts, learning) the install created, unless another installed harness still uses them;
• removes the directories the install created, once they are empty.

A file or folder in your home directory that other installs also use (a skills folder, or ~/.config/apothem/) is treated like the shared data stores: rollback keeps it while another install still lists it, and restores or removes it only for the last install that uses it. A folder this install found already in place (a second tool installed after the first) goes with the last install that uses it when an install that has since let go of it created it, so rolling back every tool leaves nothing behind. When an install's record that could use the folder cannot be read, rollback stops with an error before it changes anything and writes no rollback record; repair the record and run it again.

Everything rollback removes or replaces is first copied into the Apothem backup root (~/.apothem/backups/), so a rollback can itself be undone by hand. Rollback then appends a rollback record to the harness ledger. Rolling back an older install restores or removes only the targets that older install recorded, and drops every install after it from the ledger's active installs at the same root. Files a later install added outside those targets stay in place.

The ledger keeps the newest 10 install records per install root (with the backups they reference); an older install can no longer be rolled back by id and reports rollback.no_record. apothem backups prune lowers that bound on demand, and never removes the backup the latest install restores from.

Records written by an Apothem release before this behaviour was added do not list which files the install created; rolling back such a record restores the overwritten files only.

Confirmation is prompted per harness unless --yes is supplied. When no prompt is possible — --format json (prompt text would corrupt the single JSON document) or a non-interactive shell (no TTY) — the command refuses up front with a structured rollback.confirmation_required error (exit 1) unless --yes is supplied. --install-id and --last select the install pass and are mutually exclusive.

A --harness all rollback is deliberately exhaustive: it covers every registered harness, including any the profile's exclude_harnesses skips during install — restoring pre-install state is a cleanup operation, so it reaches records a previously broader install may have left. A harness with no recorded install fails as an "outcome": "error" row in results (see JSON output), and the run continues with the remaining harnesses. The command then exits 1 when nothing was rolled back, or 2 (partial result) when at least one target was rolled back and a failure was also recorded.

OptionsCopy Anchor Link

JSON outputCopy Anchor Link

The example is the envelope for a single named harness. Under --harness all, harness is all, output_path is null, and results carries the rows of every selected harness.

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

Each restored or removed target appears in results with "operation": "rollback" and an outcome of created or updated (and in files_written); the message says whether the path was restored or removed. A failed restore (for example, a backup that was deleted) is "outcome": "error". An install that recorded no changes is reported with "outcome": "skipped". When no matching install record exists for a single named harness, the command reports a rollback.no_record error with "status": "error". Under --harness all, a harness with no matching record is an "outcome": "error" row in results instead.

ExamplesCopy Anchor Link

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

Exit codesCopy Anchor Link

See alsoCopy Anchor Link

• apothem install — install a harness configuration
• apothem update — re-install from the current shared profile
• apothem uninstall — remove a harness configuration
• apothem status — report install, verify, and drift state