CLI Reference

Eight commands. Full control over your AI backups.

$ savestate --help

Time Machine for AI. Backup, restore, and migrate your AI identity.

Commands:
  init                    Initialize encryption & storage config
  snapshot                Capture current AI state to encrypted archive
  restore [snapshot-id]   Restore from snapshot (default: latest)
  list                    List all snapshots with metadata
  diff <a> <b>            Compare two snapshots side-by-side
  search <query>          Search across all snapshots
  config                  View or edit configuration
  adapters                List available platform adapters

`savestate init`

Initialize SaveState in the current directory. Creates a .savestate/ directory containing your encryption configuration and storage settings.

$ savestate init

This command:

Prompts for a passphrase (used to derive your encryption key via scrypt)
Creates .savestate/config.json with default local storage
Sets up the snapshot index file

💡 You can also use global config at ~/.savestate/config.json — local project config takes priority.

`savestate snapshot`

Capture the current AI state and save it as an encrypted archive.

$ savestate snapshot [options]

Flag	Description
`-l, --label <label>`	Human-readable label for this snapshot (e.g., `"Before migration"`)
`-t, --tags <tags>`	Comma-separated tags for organization (e.g., `"backup,weekly"`)
`-a, --adapter <adapter>`	Force a specific adapter instead of auto-detection (e.g., `clawdbot`, `claude-code`)
`-s, --schedule <interval>`	Set up auto-snapshot schedule (e.g., `6h`, `1d`) (Pro)
`--full`	Force a full snapshot, skipping incremental delta detection

Examples

# Basic snapshot with auto-detection
$ savestate snapshot

# Labeled + tagged
$ savestate snapshot --label "Pre-update backup" --tags "important,v2"

# Force the Claude Code adapter
$ savestate snapshot --adapter claude-code

# Force full snapshot (ignore incrementals)
$ savestate snapshot --full

# Schedule auto-backups every 6 hours (Pro)
$ savestate snapshot --schedule 6h

By default, snapshots are incremental — only changes since the last snapshot are stored. Use --full to force a complete capture. See Incremental Snapshots for details.

`savestate restore`

Restore your AI state from a snapshot. Defaults to the latest if no ID is specified.

$ savestate restore [snapshot-id] [options]

Flag	Description
`--to <platform>`	Restore to a different platform (cross-platform migration)
`--dry-run`	Show what would be restored without making any changes
`--include <categories>`	Only restore specific categories: `identity`, `memory`, `conversations` (comma-separated)

Examples

# Restore latest snapshot
$ savestate restore latest

# Restore a specific snapshot
$ savestate restore ss-2026-01-26T09-30-00-b7c1m4

# Migrate to Claude
$ savestate restore latest --to claude

# Restore only memory files
$ savestate restore latest --include memory

# Preview without changing anything
$ savestate restore latest --dry-run

ℹ️ Existing files are backed up with a .bak extension before being overwritten.

`savestate list`

List all snapshots with metadata. Alias: savestate ls.

$ savestate list [options]

Flag	Description
`--json`	Output as JSON (useful for scripting)
`--limit <n>`	Maximum number of snapshots to show

$ savestate list --limit 5
$ savestate ls --json | jq '.[0]'

`savestate diff`

Compare two snapshots and see what changed.

$ savestate diff <snapshot-a> <snapshot-b>

Outputs a summary of added, removed, and modified content across identity, memory, conversations, and tools.

$ savestate diff ss-2026-01-25 ss-2026-01-27
Changes between ss-2026-01-25 and ss-2026-01-27:
  + 3 files added
  ~ 5 files modified
  - 1 file removed

`savestate search`

Search across all snapshots without restoring them. Find that conversation from months ago.

$ savestate search <query>

Searches across memory entries, conversations, identity files, and knowledge documents. Returns results ranked by relevance with context snippets.

$ savestate search "cocktail recommendations"

`savestate config`

View or edit your SaveState configuration.

$ savestate config [options]

Flag	Description
`--set <key=value>`	Set a configuration value (e.g., `storage.type=s3`)
`--json`	Output current config as JSON

# View current config
$ savestate config

# Set storage to S3
$ savestate config --set "storage.type=s3"

# Export config as JSON
$ savestate config --json

`savestate adapters`

List all available platform adapters and their detection status.

$ savestate adapters
ID                  NAME                  PLATFORM          DETECTED
clawdbot            Clawdbot              clawdbot          ✓
claude-code         Claude Code           claude-code       ✗
claude-web          Claude Web (claude.ai) claude-web        ✗
openai-assistants   OpenAI Assistants     openai-assistants  ✗
chatgpt             ChatGPT               chatgpt           ✗
gemini              Google Gemini         gemini            ✗

Detection is automatic based on the current directory and environment. See Platform Adapters for details on what each adapter captures.

← Previous Getting Started Next → Platform Adapters