restore

Restore (restore [--dry-run] [path])

Copies from a backup source back onto this machine. Interactive and conservative: it adds and (only with consent) overwrites, and it never deletes anything that exists only locally. Whichever source resolves below, restore only ever reads from it: it never writes back to the source, and never pushes anywhere. With --dry-run it goes exactly as far as the plan (step 3) and stops: nothing is applied, no question is asked, and any temp extraction directory is cleaned up. Useful for checking what a restore would do, especially against the GitHub mirror, which may be weeks ahead of or behind this machine.

The mirror tree and the name-to-target derivation rules live in ${CLAUDE_PLUGIN_ROOT}/docs/layout.md; read it before building the plan. To converge this machine with a different machine's mirror, use merge (${CLAUDE_PLUGIN_ROOT}/commands/merge.md) instead: restore maps a mirror back onto the machine it came from (or a replacement for it), merge reconciles two machines' divergent state.

Resolve the source

• <path> given: a zip made by zip <path>, or its already-extracted folder. If <path> is a file (a .zip), extract it into a fresh temp directory (mktemp -d) and use that as the source root; if it is already a directory, use it directly. Verify the source root contains at least one machines/<hostname>/ subtree; if not, say so and stop. No GitHub involved at all: no clone, no gh, no network, and no need for /backup setup to have ever run.
• <path> is a gist URL (https://gist.github.com/...): a share bundle made by share (${CLAUDE_PLUGIN_ROOT}/commands/share.md). Fetch it with gh gist view <id> --raw (or --files), read the bundle.zip.base64 file, base64-decode it to a temp .zip, extract that into a fresh temp directory (mktemp -d), and use it as the source root exactly like a local zip. Requires gh authenticated; no /backup setup needed. The gist's ONBOARDING.md is context for a human, not part of the restore; mention it in the report so the user reads it. A share bundle carries no config/ and only the thread's curated stores, so the plan will naturally be narrow; that is expected.
• No <path>: a configured backup target. Two kinds can be configured, and both may be at once (see docs/object-storage.md):
  • GitHub mirror (~/.claude/memory-backup/ is a clone with an origin). If it is not configured, this is probably the disaster-recovery path: ask for the backup repo (owner/name), verify it exists, and clone it into place first. Otherwise git pull --ff-only so the mirror is current. The source root is the clone.
  • Object storage (~/.claude/memory-backup-obstore.json exists). Read bucket/prefix/endpoint/region/profile from it and materialize the mirror into a fresh temp directory (mktemp -d) with ${CLAUDE_PLUGIN_ROOT}/scripts/obstore-pull.sh --dest <tmp> --bucket .... That temp directory is then the source root, handled exactly like an extracted zip: read-only, and cleaned up at the end (step 4) or on any early stop, since this run created it.
  • Both configured: ask via AskUserQuestion which to restore from (they can differ: the bucket may be ahead of or behind the git mirror). Only one configured: use it without asking.