Getting Started

Install SaveState, take your first snapshot, and restore your AI identity in under a minute.

The same clean-install steps are on the developers setup guide.

Installation

SaveState is published as @savestate/cli. The unscoped package name savestate is not on npm, so npx savestate returns E404. Homebrew and the shell installer are also available.

npm (recommended)

$ npm install -g @savestate/cli

Or run a single command without a global install. The binary name inside the package is still savestate:

$ npx @savestate/cli init

Homebrew

$ brew tap savestatedev/tap
$ brew install savestate

Shell installer (macOS & Linux)

$ curl -fsSL https://savestate.dev/install.sh | sh

This auto-detects your platform (macOS arm64/x64, Linux arm64/x64) and installs the appropriate binary. Falls back to npm if no binary is available.

Initialize

From the project directory, set SAVESTATE_PASSPHRASE and initialize. The passphrase is required. It must be at least 8 characters. SaveState derives the AES-256-GCM key from it and does not store the passphrase.

init does not prompt when stdin is not a terminal. Without SAVESTATE_PASSPHRASE, snapshot and restore then fail with No passphrase available. An interactive terminal prompts only if the variable is unset.

$ 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!

That writes .savestate/config.json in the project and sets storage.options.path to ~/.savestate. The encrypted archive is <snapshot-id>.saf.enc in that directory. The project also gets .savestate/index.json, which lists those archives. The "Detected platform" line appears when an adapter matches (here, a CLAUDE.md or .claude/ directory).

Save and restore one project

Worked example: a Claude Code project that contains CLAUDE.md. After init, with SAVESTATE_PASSPHRASE still set, save the project:

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

SaveState detects the platform (see Adapters) and stores identity files, memory, conversations, and tools in the encrypted archive.

Snapshot options

# Add a label and tags
$ npx @savestate/cli snapshot --label "Before migration" --tags "backup,pre-update"

# Force a specific adapter
$ npx @savestate/cli snapshot --adapter clawdbot

# Force a full snapshot (skip incremental)
$ npx @savestate/cli snapshot --full

Listing Snapshots

$ npx @savestate/cli list
📋 Snapshots
   Storage: local

  ID                             Date                  Adapter      Label        Size
  ss-2026-10-20T13-43-36-6w3qby  Oct 20, 13:43         claude-code  first      1.2 KB

  1 snapshot

Columns are ID, Date, Adapter, Label, and Size. Date is local time. Id, label, and size come from the snapshot you saved.

Restoring

Change or delete CLAUDE.md, then put the saved copy back. SAVESTATE_PASSPHRASE must still be set to the same value:

$ 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 had changed is kept as CLAUDE.md.bak. Restore a specific id with npx @savestate/cli restore <id>. Move the archive to another adapter with --to, for example npx @savestate/cli restore latest --to claude.

Next Steps

Connect the MCP server in Claude Code and Cursor: How to connect SaveState's MCP server to Claude Code and Cursor. Restore after a crash: How to Restore SaveState After a Crash.

Subscribe

Pro is $9/month. Encrypted portable memory you can snapshot, restore, search, and migrate from the CLI. Card today. No waitlist.

Subscribe to Pro — $9/mo Team is $29/month

After you pay, your API key is emailed. Then savestate login. Card today — no waitlist.