Developers
Docs GitHub npm

Developer setup

A clean install: one passphrase, one snapshot, one restore.

These commands work on a machine that does not already have SaveState installed. Longer reference: Getting Started.

Install

The npm package is @savestate/cli. There is no unscoped savestate package, so npx savestate init fails with npm E404. After a global install, the binary name is savestate.

Terminal 
$ npm install -g @savestate/cli
# or, without a global install:
$ npx @savestate/cli --version

Set SAVESTATE_PASSPHRASE

SAVESTATE_PASSPHRASE is required before you snapshot or restore. It must be at least 8 characters. SaveState derives the AES-256-GCM key from it and does not write the passphrase to disk.

init does not prompt when stdin is not a terminal. If the variable is unset, a later snapshot in that same non-interactive shell exits with No passphrase available. Set SAVESTATE_PASSPHRASE environment variable or run in an interactive terminal. An interactive terminal prompts only when the variable is missing.

Terminal 
$ export SAVESTATE_PASSPHRASE="your-passphrase"
$ npx @savestate/cli init
✔ Created .savestate/ directory
✔ Detected platform: Claude Code
  Your snapshots will be encrypted with a passphrase.
  You can also set SAVESTATE_PASSPHRASE env var.
✓ SaveState initialized!

Run this in the project you want to capture. A directory with CLAUDE.md or .claude/ is detected as Claude Code. Init still succeeds if nothing is detected; pass --adapter on snapshot in that case. Config lands in .savestate/config.json. init sets storage.options.path to ~/.savestate, and the encrypted archive is <snapshot-id>.saf.enc there. .savestate/index.json in the project lists it.

Important: If you lose the passphrase, snapshots cannot be decrypted. There is no password reset.

Save the project

With the passphrase still exported, take one snapshot. This example is a Claude Code project:

Terminal 
$ npx @savestate/cli snapshot --label first
✔ Full snapshot created!
  ID:         ss-2026-10-17T13-23-14-tcb4ee
  Adapter:    Claude Code
  Type:       full
  Label:      first
  Storage:    local
  Status:     Encrypted & stored
$ npx @savestate/cli list

list prints the new snapshot id. Keep that shell's SAVESTATE_PASSPHRASE for the restore.

Restore it

Edit or delete CLAUDE.md, then restore the latest snapshot:

Terminal 
$ npx @savestate/cli restore latest
✔ Restore complete!
  Identity:      restored
  Memory:        0 entries restored
  Conversations: 0 indexed
  Your AI state has been restored.
  Existing files were backed up with .bak extension.

CLAUDE.md matches the snapshot again. The file you changed is kept as CLAUDE.md.bak. Use npx @savestate/cli restore <id> for a specific snapshot.

Next