CLI Reference

Backup, restore, verify, and migrate your AI identity from the command line.

$ 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
  stats                   Show usage statistics about your snapshots
  doctor                  Health-check snapshots: decrypt, unpack, verify chains
  inspect <id>           Decrypt and summarize a snapshot without restoring
  diff <a> <b>            Compare two snapshots side-by-side
  search <query>          Search across all snapshots
  export                  Export an encrypted agent container
  import <file>           Import an encrypted agent container
  container               Manage encrypted agent state containers (export, import)
  verify <file>           Verify a .savestate container and list metadata
  prune                   Drop old snapshots by retention policy (dry-run)
  antibodies              Manage failure antibodies (list, add, preflight, stats)
  schedule                Configure automatic backup schedule (Pro/Team)
  migrate                 Migration wizard between platforms
  trust                   Inspect Trust Kernel state, audit trail, and denylist
  team                    Team management: members, invites, audit log (Team)
  eval                    Memory quality evaluation (quality, report)
  login                   Authenticate with SaveState cloud
  logout                  Remove the saved cloud API key
  cloud                   Cloud storage commands (Pro/Team)
  mcp                     MCP server: serve, status, export, import
  context                 Preflight context compilation for agent runs
  memory                  Manage multi-tier memory (L1/L2/L3) for long-running agents
  slo                     Memory freshness SLO monitoring (status, report, config)
  acl                     Manage active commitments (propose, verify, gate, list)
  identity                Manage agent identity (show, init, set, schema)
  integrity               Memory Integrity Grid (status, seed, incidents)
  trace                   Inspect Askable Echoes trace runs (list, show, export)
  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 [options]

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

Flag	Description
`--json`	Emit init status as JSON. Skips the spinner and passphrase prompt. Useful for scripting.

$ savestate init --json

💡 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"`). Must be a single non-empty snapshot label (no commas).
`-t, --tags <tags>`	Comma-separated tags for organization (e.g., `"backup,weekly"`). Must be one or more non-empty snapshot tags (comma-separated).
`--tag <entry...>`	Record a structured state entry as `type:key=value` (repeatable). Types: `decision`, `preference`, `error`, `api_response`, `custom`. Distinct from `-t, --tags`. Must be type:key=value with type one of: decision, preference, error, api_response, custom.
`--meta <entry...>`	Additional metadata for `--tag` entries as `key=value` (repeatable). Applied to every state entry on this snapshot. Must be key=value with a non-empty key and value.
`-a, --adapter <adapter>`	Force a specific adapter instead of auto-detection. Must be one of: clawdbot, claude-code, claude-web, openai-assistants, chatgpt, gemini, cursor, windsurf.
`-s, --schedule <interval>`	Set up auto-snapshot schedule (e.g., `6h`, `1d`). Must be a duration like `1h`, `6h`, `12h`, or `1d` up to 7 days. (Pro)
`--full`	Force a full snapshot, skipping incremental delta detection
`--json`	Emit the snapshot result as JSON. Encrypts the archive. Skips the spinner. When SaveState is not initialized, emits a missing summary (found, adapter, snapshotId, timestamp, platform; omits extra fields). When no adapter can be detected, emits a missing summary (found, adapter, snapshotId, timestamp, platform; omits extra fields). Useful for scripting.

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

# Record structured state entries
$ savestate snapshot --tag decision:api_provider=openai --tag preference:theme=dark --meta confidence=high

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

# Scriptable snapshot metadata
$ savestate snapshot --json --full

# Scriptable JSON when no adapter can be detected
$ savestate snapshot --json

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
`[snapshot-id]`	Snapshot to restore. Optional; defaults to `latest`. Must be a single non-empty snapshot id (or `latest`).
`--to <platform>`	Restore to a different platform (cross-platform migration). Must be one of: clawdbot, claude-code, claude-web, openai-assistants, chatgpt, gemini, cursor, windsurf.
`--dry-run`	Show what would be restored without making any changes
`--include <categories>`	Only restore specific categories: `identity`, `memory`, `conversations` (comma-separated). Must be one or more of: identity, memory, conversations.
`--json`	Emit the restore result as JSON. Decrypts the archive. Skips the spinner. When SaveState is not initialized, emits a missing summary (found, snapshotId, timestamp, platform, hasIdentity; omits extra fields). When the snapshot is missing, emits a missing summary (found, snapshotId, timestamp, platform, hasIdentity; omits extra fields). Useful for scripting.

Examples

# Restore latest snapshot
$ savestate restore latest

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

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

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

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

# Scriptable JSON result
$ savestate restore latest --json --dry-run

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

`savestate list`

List all snapshots with metadata. Alias: savestate ls. Reads the snapshot index only — it does not decrypt archives. Requires savestate init.

$ savestate list [options]

Flag	Description
`--json`	Emit snapshot records as JSON, newest first. Does not decrypt archives. When SaveState is not initialized, emits a missing summary (found, total, storage; omits extra fields). Useful for scripting.
`--limit <n>`	Maximum number of snapshots to show (default 50)
`--since <date>`	Only snapshots taken after this date (ISO 8601, e.g. `2026-04-01`)
`--until <date>`	Only snapshots taken before this date. Must be an ISO 8601 date.
`--adapter <id>`	Only snapshots from this adapter. Must be one of: clawdbot, claude-code, claude-web, openai-assistants, chatgpt, gemini, cursor, windsurf.
`--tag <tag>`	Only snapshots tagged with this label. Must be a single non-empty snapshot tag (no commas).

# Recent snapshots
$ savestate list --limit 5

# Claude Code snapshots since April
$ savestate list --adapter claude-code --since 2026-04-01

# Tagged backups as JSON
$ savestate ls --tag weekly --json | jq '.[0]'

# Scripting
$ savestate list --json

`savestate stats`

Show usage statistics about your snapshots: total count, storage size, adapter mix, cadence, and top tags. Reads the snapshot index only — it does not decrypt archives.

$ savestate stats [options]

Flag	Description
`--json`	Emit usage statistics as JSON. Does not decrypt archives. When SaveState is not initialized, emits a missing summary (found, total, totalBytes, first, latest, storage; omits extra fields). Useful for scripting.

# Human-readable summary
$ savestate stats

# Scripting
$ savestate stats --json

# Scriptable JSON when SaveState is not initialized
$ savestate stats --json

`savestate doctor`

Health-check every snapshot in the index. Decrypts each archive, unpacks the manifest, verifies content checksums, and walks incremental chains end-to-end. Reports a per-snapshot status table and a summary. Exits non-zero if any snapshot is unhealthy, so it can be wired into cron.

$ savestate doctor [options]

Flag	Description
`--json`	Emit per-snapshot diagnosis as JSON. Decrypts archives. When SaveState is not initialized, emits a missing summary (found, total, healthy, unhealthy; omits extra fields). Useful for scripting.
`--adapter <id>`	Only check snapshots from this adapter. Must be one of: clawdbot, claude-code, claude-web, openai-assistants, chatgpt, gemini, cursor, windsurf.
`--limit <n>`	Only check the N most recent snapshots. Must be a positive integer up to 1000.

# Check every snapshot
$ savestate doctor

# Scripting
$ savestate doctor --json

# Scriptable JSON when SaveState is not initialized
$ savestate doctor --json

# Restrict to recent Claude Code snapshots
$ savestate doctor --adapter claude-code --limit 5 --json

`savestate inspect`

Decrypt and summarize a snapshot without restoring it. Use this to browse history and confirm what a backup contains before running savestate restore. Requires a single non-empty snapshot id, savestate init, and a passphrase.

$ savestate inspect <snapshot-id> [options]

Flag	Description
`<snapshot-id>`	Snapshot to decrypt and summarize. Must be a single non-empty snapshot id (or `latest`).
`--json`	Emit the snapshot summary as JSON. Decrypts the archive. When SaveState is not initialized, emits a missing summary (found, id, timestamp, platform, hasIdentity; omits extra fields). When the snapshot is missing, emits a missing summary (found, id, timestamp, platform, hasIdentity; omits extra fields). Useful for scripting.

Pass latest to inspect the most recent snapshot. Output includes id, timestamp, platform, adapter, size, optional label/tags, and content counts (memories, conversations, knowledge, tools, skills, identity).

# Summarize the latest snapshot
$ savestate inspect latest

# Scripting
$ savestate inspect latest --json

# Scriptable JSON summary
$ savestate inspect ss-2026-01-26T09-30-00-b7c1m4 --json

`savestate diff`

Compare two snapshots and see what changed across identity, memory, conversations, and tools. Requires savestate init and a passphrase. Decrypts both archives.

$ savestate diff <snapshot-a> <snapshot-b> [options]

Flag	Description
`--json`	Emit identity and state diffs as JSON. Decrypts both archives. When SaveState is not initialized, emits a missing summary (found, snapshotA, snapshotB, hasChanges; omits extra fields). When a snapshot is missing, emits a missing summary (found, snapshotA, snapshotB, hasChanges; omits extra fields). Useful for scripting.

# Human-readable summary
$ 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

# Scripting
$ savestate diff ss-2026-01-25 ss-2026-01-27 --json

`savestate search`

Search across all snapshots without restoring them. Find that conversation from months ago. Searches memory entries, conversations, identity files, and knowledge documents. Returns results ranked by relevance with context snippets. Requires a non-empty query, savestate init, and a passphrase.

$ savestate search <query> [options]

Flag	Description
`<query>`	Search text. Must be a non-empty query.
`--type <type>`	Filter by type: `memory`, `conversation`, `identity`, or `knowledge` (comma-separated)
`--limit <n>`	Maximum number of results (default 20). Must be a positive integer up to 1000.
`--snapshot <id>`	Search within a specific snapshot instead of every archive
`--json`	Output ranked results as JSON. When SaveState is not initialized, emits a missing summary (found, query, snapshot, count; omits extra fields). When the snapshot is missing, emits a missing summary (found, query, snapshot, count; omits extra fields). Useful for scripting.

# Search every snapshot
$ savestate search "cocktail recommendations"

# Conversations only, cap results
$ savestate search "cocktail recommendations" --type conversation --limit 5

# One snapshot
$ savestate search "system prompt" --snapshot ss-2026-01-26T09-30-00-b7c1m4

# Scriptable JSON results
$ savestate search "cocktail recommendations" --json

# Scriptable JSON when the snapshot is missing
$ savestate search "cocktail recommendations" --snapshot missing --json

`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`). Must be a non-empty key=value pair.
`--json`	Emit the current config as JSON. Omits the saved cloud API key. When SaveState is not initialized, emits a missing summary (found, version, storage, defaultAdapter; omits extra fields). Useful for scripting.

# View current config
$ savestate config

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

# Scriptable config (API key omitted)
$ savestate config --json

# Scriptable JSON when SaveState is not initialized
$ savestate config --json

`savestate adapters`

List all available platform adapters and their detection status.

$ savestate adapters [options]

Flag	Description
`--json`	Output adapter records as JSON. When SaveState is not initialized, emits a missing summary (found, total; omits extra fields). Useful for scripting.

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

# Scriptable JSON records
$ savestate adapters --json

# Scriptable JSON when SaveState is not initialized
$ savestate adapters --json

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

`savestate export`

Export agent state to an encrypted .savestate container. Loads and encrypts the selected components, then writes the archive. A missing output directory is rejected before encrypting. An existing output file is refused unless --force is set.

$ savestate export -a <id> -o <file> [options]

Flag	Description
`-a, --agent <id>`	Agent ID to export. Must be a single non-empty agent id.
`-o, --output <file>`	Output file path (default: `agent.savestate`). Must be a single non-empty path. A missing parent directory, directory path, or empty path is rejected before writing.
`--dry-run`	Encrypt and print export metadata without writing. An existing output file can still be previewed without `--force`.
`--force`	Overwrite an existing output file
`--include <paths>`	Only pack named state paths (`personality`, `memory`, `tools`, `preferences`, `conversation_history`)
`--exclude <paths>`	Skip named state paths from the packed set
`-p, --passphrase <pass>`	Passphrase for encryption, or `SAVESTATE_PASSPHRASE` / prompt. An empty value is rejected before encrypting.
`-k, --keyfile <path>`	Keyfile instead of a passphrase. An empty path, missing file, directory, or file with no contents is rejected before encrypting.
`--description <text>`	Optional human-readable description stored in the manifest. Must be a non-empty description.
`--json`	Emit the export result as JSON. Encrypts the archive. Skips progress output. When the output directory is missing, emits a missing summary (found, output, written, agent; omits extra fields). Useful for scripting.

# Preview without writing
$ savestate export -a my-agent -o agent.savestate --dry-run

# Overwrite an existing archive
$ savestate export -a my-agent -o agent.savestate --force

# Scriptable export metadata
$ savestate export -a my-agent -o agent.savestate --json --dry-run

# Missing output directory
$ savestate export -a my-agent -o missing-dir/agent.savestate --json

`savestate import`

Import agent state from an encrypted .savestate container. Decrypts, verifies, and restores. The input file must be a single non-empty path. A missing input path is rejected before decrypting. A missing --target parent directory is rejected before restoring. An existing target file is refused unless --force is set.

$ savestate import <file> [options]

Flag	Description
`--dry-run`	Decrypt and print import metadata without restoring. An existing target file can still be previewed without `--force`.
`-p, --passphrase <pass>`	Passphrase for decryption, or `SAVESTATE_PASSPHRASE` / prompt. An empty value is rejected before decrypting.
`-k, --keyfile <path>`	Keyfile instead of a passphrase. An empty path, missing file, directory, or file with no contents is rejected before decrypting.
`--target <dir>`	Write restored agent state to this directory. Must be a single non-empty path. A missing parent directory is rejected before restoring.
`--force`	Overwrite an existing target file
`--include <paths>`	Only restore named state paths
`--exclude <paths>`	Skip named state paths while restoring
`--merge`	Merge with existing state (default: replace)
`--json`	Emit the import result as JSON. Decrypts the archive. Skips progress output. When the input file is missing, emits a missing summary (found, input, restored, agent; omits extra fields). Useful for scripting.

# Preview without restoring
$ savestate import agent.savestate --dry-run

# Restore into a directory, replacing an existing target file
$ savestate import agent.savestate --target ./restored --force

# Scriptable import metadata
$ savestate import agent.savestate --json --dry-run

# Missing input file
$ savestate import missing.savestate --json

`savestate verify`

Verify integrity of a .savestate container. Checks the magic header, manifest, checksum, and (when a key is provided) decryptability. Prints packed components and payload metadata. An empty, whitespace-only, missing, or directory file path is rejected before reading.

$ savestate verify <file> [options]

Flag	Description
`-p, --passphrase <pass>`	Passphrase used to decrypt the container. An empty or whitespace-only value is rejected before decrypting.
`-k, --keyfile <path>`	Keyfile instead of a passphrase. An empty path, missing file, directory, or file with no contents is rejected before decrypting.
`--json`	Emit the full verify result as JSON. Decrypts the archive when a key is provided. When the input file is missing, emits a missing summary (found, input, valid, agent; omits extra fields). Useful for scripting.

On a valid file, output includes agent id, created timestamp, format version, optional description, components, excluded paths, checksum, size, content type, payload name, encryption algorithm, and key derivation.

If the container decrypts but has no agent_state payload, verify still prints the metadata it can read from the manifest — including Content-Type, checksum, size, components, and encryption details — then reports the file as corrupted.

# Verify with a passphrase
$ savestate verify agent.savestate --passphrase "secret"

# Scripting
$ savestate verify agent.savestate --json

# Missing input file
$ savestate verify missing.savestate --json

# Verify with a keyfile and JSON
$ savestate verify agent.savestate --keyfile ./key.bin --json

`savestate prune`

Drop old snapshots according to a retention policy. Dry-run is the default: nothing is deleted unless --apply is set. Specify --keep-last, --older-than, or both.

$ savestate prune [options]

Flag	Description
`--keep-last <n>`	Keep the N most recent snapshots. Must be a positive integer up to 1000.
`--older-than <date>`	Drop snapshots older than this date. Must be an ISO 8601 date.
`--apply`	Actually delete. Without this flag, prune only prints the plan
`--json`	Emit the prune plan as JSON. Useful for scripting. Dry-run is the default unless `--apply` is set. When SaveState is not initialized, emits a missing summary (found, dryRun, keepCount, dropCount; omits extra fields).

The newest snapshot is never pruned. A snapshot that is the only one for its adapter is held back for chain safety.

# Preview which snapshots would be dropped
$ savestate prune --keep-last 10

# Delete snapshots older than a cutoff
$ savestate prune --older-than 2026-01-01 --apply

# Scripting
$ savestate prune --keep-last 10 --json

# Scriptable JSON when SaveState is not initialized
$ savestate prune --json

`savestate antibodies`

Manage failure antibodies: reusable rules that match a tool, error, or path and suggest a safe action. Subcommands: list, add, preflight, stats.

$ savestate antibodies <subcommand> [options]

Flag	Description
`--json`	Emit antibody list, preflight, stats, and an add summary (id, risk, safe action, and confidence) as JSON. List output is a stable rule summary (id, risk, intervention, active, confidence, hits, overrides, and safe action). When SaveState is not initialized, `list --json` emits a missing summary (found, total, shown; omits extra fields) and `add --json` emits a missing summary (found, added, id; omits extra fields). Preflight output is a stable summary (blocked, elapsed, semantic, and warnings with rule id, risk, intervention, confidence, safe action, and reasons). When SaveState is not initialized, `preflight --json` emits a missing summary (found, blocked, elapsedMs, semanticUsed; omits extra fields). Stats output is a stable summary (counts plus per-rule hits and overrides). When SaveState is not initialized, `stats --json` emits a missing summary (found, totalRules, activeRules, retiredRules, totalHits, totalOverrides; omits extra fields). Omits extra fields. Useful for scripting.
`--all`	Include retired rules in `list`
`--tool <name>`	Tool name for `add` / `preflight`. Must be a single non-empty tool name.
`--error-code <code>`	Error code in the rule trigger or preflight context. Must be a single non-empty error code.
`--path-prefix <prefix>`	Path prefix in the rule trigger. Must be a single non-empty path prefix.
`--path <path>`	Path in preflight context. Must be a single non-empty path.
`--tags <tags>`	Comma-separated tags for `add` / `preflight`. Must be one or more non-empty antibody tags (comma-separated).
`--risk <level>`	Risk level: low, medium, high, or critical
`--safe-action <type>`	Safe action for a manual rule
`--confidence <0..1>`	Rule confidence
`--id <id>`	Rule ID when adding manually. Must be a single non-empty rule id.
`--semantic`	Enable the semantic matcher stub on `preflight`

# List active rules
$ savestate antibodies list

# Scripting
$ savestate antibodies list --json

# Add a rule for a tool/error pair
$ savestate antibodies add --tool write --error-code EACCES --risk high --safe-action check_permissions --json

# Scriptable JSON when SaveState is not initialized
$ savestate antibodies add --json

# Check whether a planned action matches a rule
$ savestate antibodies preflight --tool write --path ./secret.env --json

# Scriptable JSON when SaveState is not initialized
$ savestate antibodies preflight --json

# Hit counts and overrides
$ savestate antibodies stats --json

`savestate schedule`

Configure automatic backup schedule. Enabling a schedule requires Pro or Team and a logged-in API key. Status and disable work without a subscription. Uses launchd on macOS and systemd user timers on Linux. With no flags, prints the current status.

$ savestate schedule [options]

Flag	Description
`-e, --every <interval>`	Backup interval (e.g., `1h`, `6h`, `12h`, `1d`). Must be a duration like 1h, 6h, 12h, or 1d up to 7 days. Requires Pro or Team
`-d, --disable`	Disable scheduled backups
`-s, --status`	Show schedule status (default when no other flag is set)
`--json`	Emit schedule status as JSON. Skips progress output. When SaveState is not initialized, emits a missing summary (found, enabled, running, supported; omits extra fields). Useful for scripting.

Run savestate login first. The job runs savestate snapshot --label auto on the interval.

# Show whether scheduled backups are enabled
$ savestate schedule

# Scriptable schedule status
$ savestate schedule --json

# Enable a 6-hour backup schedule
$ savestate schedule --every 6h

# Turn scheduled backups off
$ savestate schedule --disable

`savestate migrate`

Move AI identity between platforms (ChatGPT → Claude, Claude → Gemini, and so on). Requires savestate init first. With no flags, prompts for source and target. Source and target cannot be the same platform.

$ savestate migrate [options]

Flag	Description
`-f, --from <platform>`	Source platform to migrate from. Must be one of: chatgpt, claude, gemini, copilot.
`-t, --to <platform>`	Target platform to migrate to. Must be one of: chatgpt, claude, gemini, copilot.
`-s, --snapshot <id>`	Use an existing snapshot instead of creating a new one. Must be a single non-empty snapshot id.
`-l, --list`	List available platforms and their capabilities
`--json`	Emit the platform catalog as JSON with `--list`, or a compatibility report as JSON with `--dry-run` (source, target, feasibility, summary, items, and recommendations; omits source refs). When SaveState is not initialized, emits a missing summary (found, source, target, feasibility; omits extra fields). Skips the wizard banner. Useful for scripting.
`--dry-run`	Show a compatibility report without making changes
`--review`	Inspect items needing manual attention without migrating
`--resume`	Resume an interrupted migration
`-i, --include <types>`	Only migrate specific types: `instructions`, `memories`, `conversations`, `files`, `customBots` (comma-separated). Must be one or more of: instructions, memories, conversations, files, customBots.
`--force`	Skip the confirmation prompt before writing
`-v, --verbose`	Show detailed progress
`--no-color`	Disable colorized output

        # List platforms the wizard can migrate between
$ savestate migrate --list

# Scriptable platform catalog
$ savestate migrate --list --json

# Preview ChatGPT → Claude without writing anything
$ savestate migrate --from chatgpt --to claude --dry-run

# Scriptable compatibility report
$ savestate migrate --from chatgpt --to claude --dry-run --json

# Missing summary when SaveState is not initialized
$ savestate migrate --json

# Inspect items that need manual attention
$ savestate migrate --from chatgpt --to claude --review

# Memories only, skip confirmation
$ savestate migrate --from chatgpt --to claude --include memories --force

# Resume an interrupted migration
$ savestate migrate --resume

# Run the migration
$ savestate migrate --from chatgpt --to claude

# Reuse an existing snapshot instead of creating a new one
$ savestate migrate --from chatgpt --to claude --snapshot ss-2026-01-26T09-30-00-b7c1m4

`savestate trust`

Inspect Trust Kernel state, the promotion audit trail, and the WriteGate denylist. Subcommands: status, audit, and deny (add, remove, list). See the Trust Kernel docs for the state machine.

$ savestate trust <subcommand> [options]

Flag	Description
`--json`	Emit Trust Kernel metrics as JSON on `status`, audit events as JSON (entry id, states, actor, and reason) on `audit`, denylist entries as JSON (pattern, reason, actor, and epoch) on `deny list`, a deny-remove summary (pattern and removed count) on `deny remove`, or a deny-add summary (pattern, reason, and actor) on `deny add`. When no denylist entry matches, `deny remove` emits a missing summary (found, pattern, removed; omits extra fields). Omits event metadata. Useful for scripting.
`--limit <n>`	Number of recent events for `audit` (default 50). Must be a positive integer up to 1000.
`-r, --reason <reason>`	Why a pattern is denylisted on `deny add`. Must be a non-empty reason.
`-b, --by <actor>`	Who is adding the denylist entry (defaults to `cli`). Must be a single non-empty actor id.

# Entries by state/scope and denylist size
$ savestate trust status --json

# Recent promotion and rejection events
$ savestate trust audit --limit 20 --json

# Scripting
$ savestate trust audit --json

# Block a pattern at the WriteGate
$ savestate trust deny add secret.env --reason "contains credentials" --json

# Unblock a pattern
$ savestate trust deny remove secret.env --json

# List denylist entries
$ savestate trust deny list --json

`savestate team`

Team management for the Team tier: membership, invites, and the audit log. Subcommands: status, members, invite, and audit. Requires savestate login. A 402 response means the account is not on Team — upgrade at savestate.dev/#pricing.

$ savestate team <subcommand> [options]

Flag	Description
`-r, --role <role>`	Invite role: `admin`, `member`, or `viewer` (default `member`). Must be one of: admin, member, viewer.
`--json`	Emit team status as JSON (id, name, and role), members as JSON (email, role, and invite timestamps), invite as JSON (invited email, role, and invite timestamps), or audit as JSON (id, action, actor, resource, and timestamp). Omits event metadata. When team status is missing, emits a missing summary (found, id, name, role; omits extra fields). When team members are missing, emits a missing summary (found, name, total, shown; omits extra fields). When a team invite is missing, emits a missing summary (found, email, role; omits extra fields). When the team or audit log is missing, `audit --json` emits a missing summary (found, teamId, count, nextCursor; omits extra fields). Useful for scripting.
`--since <date>`	Audit entries after this date. Must be an ISO 8601 date.
`--until <date>`	Audit entries before this date. Must be an ISO 8601 date.
`--format <format>`	Audit output: `csv` or `json` (default `json`). Must be one of: csv, json.

# Your team name, id, and role
$ savestate team status --json

# Members and pending invites
$ savestate team members --json

# Invite a viewer
$ savestate team invite user@example.com --role viewer --json

# Stream the audit log as CSV
$ savestate team audit --since 2026-01-01 --format csv

# Scripting
$ savestate team audit --json

`savestate eval`

Run memory quality benchmarks and print the last report. Subcommands: quality and report. Requires savestate init. Suites load from .savestate/benchmarks/ (JSON files). Results are saved to .savestate/eval-results.json. Reports precision, recall, F1, stale-hit rate, constraint retention, and confidence.

$ savestate eval <subcommand> [options]

Flag	Description
`--threshold <0..1>`	Confidence threshold for pass/fail on `quality` (default 0.7). Must be a number between 0 and 1.
`--suite <name>`	Run only a specific benchmark suite. Must be a single non-empty name (no commas or spaces).
`-v, --verbose`	Show per-test metrics
`--json`	Emit quality and report results as JSON. When SaveState is not initialized, `quality` emits a missing summary (found, suite, suiteCount, passed, total, passRate; omits extra fields). When the named suite is missing, `quality` emits a missing summary (found, suite, suiteCount, passed, total, passRate; omits extra fields). When SaveState is not initialized, `report` emits a missing summary (found, suiteCount, passed, total, passRate; omits extra fields). When no report exists, `report` emits a missing summary (found, suiteCount, passed, total, passRate; omits extra fields). Useful for scripting.

# Run every benchmark suite
$ savestate eval quality

# One suite, stricter threshold, JSON
$ savestate eval quality --suite recall --threshold 0.9 --json

# Last saved report with per-test metrics
$ savestate eval report --verbose

# Scripting
$ savestate eval report --json

`savestate login`

Authenticate with SaveState cloud. Requires savestate init first. Prompts for an API key unless you pass --key. Keys start with ss_live_ — get yours at savestate.dev/account. The key is validated against the API and saved locally so cloud features (schedule, cloud push/pull, team) unlock.

$ savestate login [options]

Flag	Description
`-k, --key <api-key>`	API key (or enter interactively). Must be a single non-empty API key.
`--json`	Emit the login result as JSON. Skips the spinner. When SaveState is not initialized, emits a missing summary (found, authenticated, email, tier; omits extra fields). Useful for scripting.

# Prompt for the key
$ savestate login

# Pass the key on the command line
$ savestate login --key ss_live_...

# Scriptable login
$ savestate login --key ss_live_... --json

# Scriptable JSON when SaveState is not initialized
$ savestate login --json

`savestate logout`

Remove the saved cloud API key from local config. Does not revoke the key on the server. Reports if you were not logged in.

$ savestate logout [options]

Flag	Description
`--json`	Emit logout status as JSON. Skips progress output. When SaveState is not initialized, emits a missing summary (found, loggedOut, hadKey; omits extra fields). Useful for scripting.

# Remove the saved cloud API key
$ savestate logout

# Scriptable logout status
$ savestate logout --json

`savestate cloud`

Push, pull, list, and delete encrypted snapshots in SaveState cloud storage. Requires Pro or Team and a logged-in API key (savestate login). Snapshots stay encrypted; the CLI uploads .saf.enc files through the API. Default push/pull is the latest snapshot unless you pass --id or --all.

$ savestate cloud <subcommand> [options]

Flag	Description
`--id <id>`	Specific snapshot ID (prefix match allowed). Must be a single non-empty snapshot id.
`--all`	Process all snapshots instead of the latest
`-f, --force`	Overwrite existing local files on pull, or skip delete confirmation
`--json`	Emit the cloud list as JSON, a push summary (uploaded count and snapshot ids) on `push`, pull results on `pull`, or delete results on `delete`. When SaveState is not initialized, `push` emits a missing summary (found, id, pushed, failed; omits extra fields). When SaveState is not initialized, `list` emits a missing summary (found, total, shown; omits extra fields). When SaveState is not initialized, `pull` emits a missing summary (found, id, pulled, failed, skipped; omits extra fields). When SaveState is not initialized, `delete` emits a missing summary (found, id, deleted, failed; omits extra fields). When the snapshot ID is missing, `push` emits a missing summary (found, id, pushed, failed; omits extra fields), `pull` emits a missing summary (found, id, pulled, failed, skipped; omits extra fields), and `delete` emits a missing summary (found, id, deleted, failed; omits extra fields). Skips the spinner and delete confirmation. Useful for scripting.

# List snapshots in cloud storage
$ savestate cloud list

# Scriptable cloud inventory
$ savestate cloud list --json

# Push the latest local snapshot
$ savestate cloud push

# Scriptable cloud push
$ savestate cloud push --json

# Pull a specific snapshot, overwriting the local file
$ savestate cloud pull --id ss-2026-01-26 --force

# Scriptable pull summary
$ savestate cloud pull --json

# Delete one cloud snapshot without the confirm prompt
$ savestate cloud delete --id ss-2026-01-26 --force

# Scriptable cloud delete
$ savestate cloud delete --id ss-2026-01-26 --json

`savestate mcp`

MCP server commands for Claude Code, Cursor, Codex, and other MCP clients. Subcommands: serve, status, export, and import. Stdio is the default transport. Client JSON snippets are on the MCP Server guide. export and import require savestate init.

$ savestate mcp <subcommand> [options]

Flag	Description
`-p, --port <port>`	HTTP port for `serve` (default 3333; HTTP mode is not implemented yet). Must be an integer from 1 to 65535.
`--stdio`	Use stdio transport (default, recommended for MCP clients)
`--no-stdio`	Request HTTP transport instead of stdio (not implemented yet)
`-a, --agent <id>`	Agent ID for `export` (default `default`) or target agent for `import`. Must be a single non-empty agent id.
`-o, --output <path>`	Passport output path for `export`. Must be a single non-empty path.
`--include-snapshots`	Include snapshot metadata in the exported passport
`-i, --input <path>`	Passport file to import (required for `import`). Must be a single non-empty path.
`--merge`	Merge imported memories with existing ones instead of replacing
`--json`	Emit MCP status as JSON on `status`, export summary (agent, output path, memory/snapshot counts) on `export`, or import summary (input path, source/target agents, memory/snapshot counts) on `import`. When SaveState is not initialized, `status --json` emits a missing summary (found, initialized, enabled; omits extra fields). When SaveState is not initialized, `export` emits a missing summary (found, agent, output, memories, snapshots, written; omits extra fields). When the agent has no memories or snapshots, `export` emits a missing summary (found, agent, output, memories, snapshots, written; omits extra fields). When SaveState is not initialized, `import` emits a missing summary (found, input, importedMemories, totalMemories, snapshots; omits extra fields). When the passport file is missing, `import` emits a missing summary (found, input, importedMemories, totalMemories, snapshots; omits extra fields). Skips progress output. Useful for scripting.

# Start the MCP server (stdio)
$ savestate mcp serve

# Config, tools, and client snippet
$ savestate mcp status

# Scriptable MCP status
$ savestate mcp status --json

# Export a memory passport
$ savestate mcp export --agent my-agent --include-snapshots

# Scriptable export summary
$ savestate mcp export --agent my-agent --json

# Import a passport into another agent
$ savestate mcp import --input passport.json --agent other-agent --merge

# Scriptable import summary
$ savestate mcp import --input passport.json --json

`savestate context`

Preflight context compilation for agent runs. Subcommands: compile, explain, validate, and config. compile builds a RunBrief for an agent and task within a token budget (default 4000). explain prints the inclusion trace for a compiled run. validate checks a RunBrief JSON file. config shows scoring weights and budget allocation.

$ savestate context <subcommand> [options]

Flag	Description
`-a, --agent <id>`	Agent ID for `compile` (required). Must be a single non-empty agent id.
`-t, --task <intent>`	Task intent for `compile` (required). Must be a non-empty task intent.
`-b, --budget <tokens>`	Token budget for `compile` (default 4000). Must be a positive integer up to 1000000.
`-f, --file <path>`	Path to a RunBrief JSON file for `validate`. Must be a single non-empty path.
`--weights`	Show scoring weights on `config`
`--budget`	Show budget allocation on `config`
`--json`	Emit compile, explain, validate, and config results as JSON. Explain omits score breakdowns. Validate includes valid flag, errors, warnings, and coverage. When the RunBrief file is missing, `validate` emits a missing summary (found, file, valid, errors, warnings; omits extra fields). Skips progress output. Useful for scripting.

# Compile a RunBrief
$ savestate context compile --agent my-agent --task "summarize inbox"

# Explain why candidates were included
$ savestate context explain run_abc123 --json

# Validate a saved brief
$ savestate context validate --file brief.json

# Show scoring weights and budget split
$ savestate context config --weights --budget

# Scripting
$ savestate context compile --agent my-agent --task "summarize inbox" --json
$ savestate context explain run_abc123 --json
$ savestate context validate --file brief.json --json
$ savestate context config --json

`savestate memory`

Manage multi-tier memory (L1/L2/L3) for long-running agents. Subcommands: list, promote, demote, pin, unpin, apply-policies, config, explain, edit, delete, rollback, expire, and log. Requires savestate init. Prompts for the archive passphrase unless SAVESTATE_PASSPHRASE is set.

$ savestate memory <subcommand> [options]

Flag	Description
`-t, --tier <tier>`	Filter `list` by tier (L1, L2, L3)
`-p, --pinned`	Show only pinned memories on `list`
`-l, --limit <n>`	Maximum number of memories to show on `list` (default 20)
`-s, --snapshot <id>`	Snapshot to inspect or modify (default: latest). Must be a single non-empty snapshot id.
`--json`	Emit list, explain, log, config, promote, demote, pin, unpin, apply-policies, edit, delete, rollback, and expire results as JSON. Omits previous content. Config includes tier limits and policy names. When the snapshot is missing, `list` emits a missing summary (found, snapshot, total, shown; omits extra fields), `config` emits a missing summary (found, snapshot, version, defaultTier; omits extra fields), and `apply-policies` emits a missing summary (found, snapshot, applied, changeCount; omits extra fields). Promote, demote, and apply-policies include from/to tiers. When the memory is missing, `promote` emits a missing summary (found, id, from, to; omits extra fields) and `demote` emits a missing summary (found, id, from, to; omits extra fields). Pin and unpin include pinned status. When the memory is missing, `pin` emits a missing summary (found, id, pinned; omits extra fields) and `unpin` emits a missing summary (found, id, pinned; omits extra fields). When the memory is missing, `log` emits a missing summary (found, id, events; omits extra fields). Edit includes edited version. When the memory is missing, `edit` emits a missing summary (found, id, version; omits extra fields). Delete includes deleted status. When the memory is missing, `delete` emits a missing summary (found, id, deleted; omits extra fields). Rollback includes rolled-back status. When the memory is missing, `rollback` emits a missing summary (found, id, rolledBack; omits extra fields). Expire includes expired count and IDs. When the namespace is missing, `expire` emits a missing summary (found, namespace, applied, expiredCount; omits extra fields). Explain includes retrieval scores and summaries. When no memories match, `explain` emits a missing summary (found, query, shown; omits extra fields). Skips table output. Useful for scripting.
`--dry-run`	Preview `apply-policies` and `expire` without writing
`-t, --to <tier>`	Target tier on `promote` (default L1) and `demote` (default L3). Promote must be one of: L1, L2; demote target (Must be one of: L2, L3).
`-r, --reason <reason>`	Required reason on `delete`; optional on `edit`. Must be a non-empty reason.
`-n, --namespace <ns>`	Namespace (`org:app:agent[:user]`) for `explain` and `expire`. Must be a single non-empty namespace.
`-c, --content <content>`	New content on `edit`. Must be non-empty memory content.
`-t, --tags <tags>`	Comma-separated tags on `explain` (filter) and `edit` (replace). Must be one or more non-empty memory tags (comma-separated).
`-i, --importance <n>`	New importance score (0-1) on `edit`. Must be a number between 0 and 1.
`--actor <id>`	Actor ID for the audit trail on `edit`, `delete`, and `rollback` (default `cli-user`). Must be a single non-empty actor id.
`-v, --version <n>`	Required version to restore on `rollback`. Must be a positive integer up to 1000.

# List memories in L1
$ savestate memory list --tier L1

# Pinned memories only
$ savestate memory list --pinned --limit 5

# Promote a memory to faster access
$ savestate memory promote mem-123 --to L1 --json

# Demote a memory to archival
$ savestate memory demote mem-123 --to L3 --json

# Pin a memory
$ savestate memory pin mem-123 --json

# Unpin a memory
$ savestate memory unpin mem-123 --json

# Preview policy demotions as JSON
$ savestate memory apply-policies --json --dry-run

# Edit content and importance
$ savestate memory edit mem-123 --content "Updated preference" --importance 0.9 --reason "correction" --json

# Soft-delete a memory
$ savestate memory delete mem-123 --reason "stale" --json

# Rollback to a previous version
$ savestate memory rollback mem-123 --version 2 --json

# Preview TTL expiry without applying
$ savestate memory expire --namespace org:app:agent --json --dry-run

# Audit history for one memory
$ savestate memory log mem-123 --json

# Scripting
$ savestate memory list --json
$ savestate memory list --snapshot ss-missing --json
$ savestate memory config --json
$ savestate memory config --snapshot ss-missing --json
$ savestate memory apply-policies --json
$ savestate memory apply-policies --snapshot ss-missing --json
$ savestate memory edit mem-123 --content "Updated preference" --json
$ savestate memory delete mem-123 --reason "stale" --json
$ savestate memory rollback mem-123 --version 2 --json
$ savestate memory expire --namespace org:app:agent --json
$ savestate memory expire --namespace org:missing --json
$ savestate memory explain "inbox preference" --json

`savestate slo`

Memory freshness SLO monitoring. Subcommands: status, report, and config. status evaluates namespace compliance against freshness, relevance, recall, and cross-session targets. report prints a period summary (default 7 days). config shows or updates SLO thresholds. Enable monitoring with savestate slo config --set enabled=true.

$ savestate slo <subcommand> [options]

Flag	Description
`-n, --namespace <ns>`	Namespace (`org:app:agent[:user]`) for `status` (default `default:default:default`). Must be a single non-empty namespace.
`-p, --period <duration>`	Report window for `report` (e.g. `7d`, `30d`; default 7 days). Must be a duration like 24h, 7d, or 1w up to 365 days.
`--set <key=value>`	Set a config value on `config` (e.g. `enabled=true`). Must be a non-empty key=value pair.
`--json`	Emit status, report, and config as JSON. When monitoring is disabled, `status` emits a missing summary (found, enabled, namespace, compliant, violations; omits extra fields) and `report` emits a missing summary (found, enabled, reportId, totalQueries, namespaces; omits extra fields). Useful for scripting.

# Check compliance for a namespace
$ savestate slo status --namespace org:app:agent

# Period report as JSON
$ savestate slo report --period 7d --json

# Enable monitoring and raise max age
$ savestate slo config --set enabled=true
$ savestate slo config --set freshness.max_age_hours=720

# Scripting
$ savestate slo status --json
$ savestate slo status --namespace org:missing --json
$ savestate slo report --period 7d --json
$ savestate slo report --json
$ savestate slo config --json

`savestate acl`

Manage Active Commitment Layer (ACL) commitments that gate high-impact agent actions. Subcommands: propose, verify, gate, and list. propose records a commitment with type, criticality, description, and proposer. verify approves or rejects a proposed commitment. gate checks whether an action type is allowed. list prints all commitments.

$ savestate acl <subcommand> [options]

Flag	Description
`-t, --type <type>`	Commitment type for `propose`: `customer_promise`, `ticket_status_change`, `escalation_closure`, or `account_tool_write`. Must be one of: customer_promise, ticket_status_change, escalation_closure, account_tool_write.
`-c, --criticality <level>`	Criticality for `propose`: `c1`, `c2`, or `c3`. Must be one of: c1, c2, c3.
`-d, --description <text>`	Description of the commitment for `propose`. Must be a non-empty commitment description.
`-p, --proposer <id>`	ID of the proposing agent for `propose`. Must be a single non-empty proposer id.
`-e, --expires-in <minutes>`	Minutes until expiration on `propose` (positive integer up to 10080)
`-i, --id <id>`	Commitment ID for `verify`. Must be a single non-empty commitment id.
`-v, --verifier <id>`	ID of the verifier for `verify`. Must be a single non-empty verifier id.
`-a, --approve`	Approve the commitment on `verify` (default is reject)
`-a, --action <type>`	Action type to check on `gate`. Must be one of: customer_promise, ticket_status_change, escalation_closure, account_tool_write.
`--json`	Emit commitments or gate status as JSON. Omits the audit trail. When no commitment exists, `verify` emits a missing summary (found, id, state, verifier; omits extra fields). Useful for scripting.

# Propose a customer promise
$ savestate acl propose --type customer_promise --criticality c3 --description "Refund within 24h" --proposer agent-1

# Approve a proposed commitment
$ savestate acl verify --id <commitment-id> --verifier reviewer-1 --approve

# Check whether an action is allowed
$ savestate acl gate --action customer_promise

# List all commitments
$ savestate acl list

# Scripting
$ savestate acl list --json

$ savestate acl verify --id cmt-missing --verifier reviewer-1 --json

`savestate identity`

Manage the workspace agent identity document at .savestate/identity.json. Subcommands: show, init, set, and schema. show prints the current identity. init <name> creates one if missing. set <field> <value> updates a core field or metadata.<key>. schema prints the JSON schema. Requires savestate init.

$ savestate identity <subcommand> [args...] [options]

Flag Description

--json Emit an init summary as JSON on init (created, alreadyExists, path, name, version; omits tool config). When SaveState is not initialized, init emits a missing summary (found, created, alreadyExists, path, name, version; omits extra fields). Emit a set summary as JSON on set (updated, field, name, version; omits tool config). When SaveState is not initialized, set emits a missing summary (found, updated, field, name, version; omits extra fields). Emit identity as JSON on show (omits tool config). When SaveState is not initialized, show emits a missing summary (found, name, version, schemaVersion; omits extra fields). When no identity exists, show emits a missing summary (found, name, version, schemaVersion; omits extra fields). When no identity exists, set emits a missing summary (found, updated, field, name, version; omits extra fields). Emit a schema summary as JSON on schema (id, title, type, required fields, property names/types, additionalProperties; omits descriptions and nested tool config). When SaveState is not initialized, schema emits a missing summary (found, id, title, type; omits extra fields). Skips the spinner. Useful for scripting.

Flag	Description
`--json`	Emit an init summary as JSON on `init` (created, alreadyExists, path, name, version; omits tool config). When SaveState is not initialized, `init` emits a missing summary (found, created, alreadyExists, path, name, version; omits extra fields). Emit a set summary as JSON on `set` (updated, field, name, version; omits tool config). When SaveState is not initialized, `set` emits a missing summary (found, updated, field, name, version; omits extra fields). Emit identity as JSON on `show` (omits tool config). When SaveState is not initialized, `show` emits a missing summary (found, name, version, schemaVersion; omits extra fields). When no identity exists, `show` emits a missing summary (found, name, version, schemaVersion; omits extra fields). When no identity exists, `set` emits a missing summary (found, updated, field, name, version; omits extra fields). Emit a schema summary as JSON on `schema` (id, title, type, required fields, property names/types, additionalProperties; omits descriptions and nested tool config). When SaveState is not initialized, `schema` emits a missing summary (found, id, title, type; omits extra fields). Skips the spinner. Useful for scripting.

# Create a local identity
$ savestate identity init MyAgent

# Show the current identity
$ savestate identity show

# Update a core field or nested metadata key
$ savestate identity set tone professional
$ savestate identity set goals '["Help users"]'
$ savestate identity set metadata.customKey "custom value"

# Print the identity JSON schema
$ savestate identity schema --json

# Scripting
$ savestate identity show --json
$ savestate identity set tone professional --json
$ savestate identity schema --json
$ savestate identity init MyAgent --json

`savestate integrity`

Memory Integrity Grid: detect and contain memory poisoning with honeyfact seeding, tripwire monitoring, and quarantine. Subcommands: status, seed, rotate, incidents, incident, quarantine, release, config, test, and clear. Requires savestate init.

$ savestate integrity [subcommand] [args...] [options]

Flag	Description
`--json`	Emit a rotation summary as JSON on `rotate` (rotated, valid, created/retired counts, tenant, TTL, rotatedAt; omits honeyfact contents). When SaveState is not initialized, `rotate` emits a missing summary (found, rotated, valid, createdCount, retiredCount; omits extra fields). Emit a seed summary as JSON on `seed` (count, tenant, TTL, seededAt; omits honeyfact contents). When SaveState is not initialized, `seed` emits a missing summary (found, count; omits extra fields). Emit a quarantine summary as JSON on `quarantine` (success, approval, target, action, reason, eventId, error; omits event metadata). When SaveState is not initialized, `quarantine` emits a missing summary (found, success, eventId; omits extra fields). Emit a release summary as JSON on `release` (success, approval, target, action, reason, eventId, error; omits event metadata). When no quarantine entry exists, `release` emits a missing summary (found, targetId, success, eventId; omits extra fields). Emit a config summary as JSON on `config` (enabled, honeyfact count/TTL, tripwire threshold/fuzzy, containment policy/auto-escalate; omits nested objects). When SaveState is not initialized, `config` emits a missing summary (found, enabled; omits extra fields). Emit a clear summary as JSON on `clear` (cleared count, tenant; omits honeyfact contents). When SaveState is not initialized, `clear` emits a missing summary (found, cleared; omits extra fields). Emit a test summary as JSON on `test` (triggered, duration, event count/ids/confidence/source, incident id/severity; omits matched content). When SaveState is not initialized, `test` emits a missing summary (found, triggered, eventCount, incidentId; omits extra fields). Emit incident records as JSON on `incidents` and `incident` (omits event match context). When SaveState is not initialized, `incidents` emits a missing summary (found, total, shown; omits extra fields). When SaveState is not initialized, `incident` emits a missing summary (found, id, status, eventCount; omits extra fields). When no incident exists, `incident` emits a missing summary (found, id, status, eventCount; omits extra fields). Status output is a stable summary (enabled, policy, honeyfact counts, incident counts, and containment counts). When SaveState is not initialized, `status` emits a missing summary (found, enabled, policy, honeyfacts, incidents; omits extra fields). Omits extra fields. Skips the banner. Useful for scripting.
`--tenant <id>`	Tenant ID (default: `default`). Must be a single non-empty tenant id.
`--count <n>`	Number of honeyfacts to seed. Must be a positive integer up to 1000.
`honeyfact.ttl_days`	Honeyfact TTL in days on `config`. Must be a positive integer up to 365.
`honeyfact.count`	Honeyfact seed count on `config`. Must be a positive integer up to 1000.
`tripwire.threshold`	Tripwire fuzzy match threshold on `config`. Must be a number between 0 and 1.
`--status <status>`	Filter incidents by status. Must be one of: open, investigating, contained, resolved, false_positive.
`enabled`	Enable the Memory Integrity Grid on `config`. Must be true or false.
`tripwire.fuzzy_enabled`	Tripwire fuzzy matching on `config`. Must be true or false.
`containment.auto_escalate`	Auto-escalate critical incidents on `config`. Must be true or false.
`--status <status>`	Filter incidents by status. Must be one of: open, investigating, contained, resolved, false_positive.
`--force`	Required on `clear`
`--reason <text>`	Reason for quarantine or release. Must be a non-empty reason.
`--user <id>`	Actor for `quarantine` and `release` (default `cli`). Must be a single non-empty user id (no commas).
When SaveState is not initialized, `release` emits a missing summary (found, targetId, success, eventId; omits extra fields).

# Show honeyfact, incident, and containment status
$ savestate integrity status

# Plant honeyfact memories
$ savestate integrity seed --count 10

# List detected incidents
$ savestate integrity incidents

# Scripting
$ savestate integrity status --json
$ savestate integrity rotate --json
$ savestate integrity seed --count 10 --json
$ savestate integrity quarantine mem-123 --json
$ savestate integrity release mem-123 --json
$ savestate integrity clear --force --json
$ savestate integrity test "canary text" --json
$ savestate integrity incidents --json
$ savestate integrity incident inc-123 --json
$ savestate integrity config --json

# Quarantine a memory or agent
$ savestate integrity quarantine mem-123 --reason "tripwire hit" --user reviewer-1

`savestate trace`

Inspect Askable Echoes trace runs: an append-only ledger of tool calls, results, checkpoints, and errors. Subcommands: list, show, and export. Requires savestate init. Runs are stored under .savestate/traces.

$ savestate trace <subcommand> [options]

Flag	Description
`--json`	Emit run and event summaries as JSON on `list` and `show`. When SaveState is not initialized, `list` emits a missing summary (found, total, shown; omits extra fields and event payloads). When SaveState is not initialized, `show` emits a missing summary (found, runId, adapter, eventCount; omits extra fields and event payloads). When no run exists, `show` emits a missing summary (found, runId, adapter, eventCount; omits extra fields and event payloads). Emit an export summary as JSON on `export` (format, run, run/event counts, run ids/adapters/timestamps/tags; omits event payloads and on-disk file paths). When SaveState is not initialized, `export` emits a missing summary (found, format, run, runCount, eventCount; omits extra fields, run lists, event payloads, and on-disk file paths). When `--run` names a missing run, `export` emits a missing summary (found, format, run, runCount, eventCount; omits extra fields, run lists, event payloads, and on-disk file paths). Useful for scripting.
`--format <format>`	Export format on `export` (only `jsonl` is supported). Must be one of: jsonl.
`--run <id>`	Export only a specific run ID (default: all runs). Must be a single non-empty run id.

# List trace runs
$ savestate trace list

# Show events for one run
$ savestate trace show run-123 --json

# Export every run as JSONL
$ savestate trace export --format jsonl

# Export one run
$ savestate trace export --run run-123

# Scripting
$ savestate trace list --json
$ savestate trace export --json
$ savestate trace export --run run-123 --json

`savestate container`

Manage encrypted agent state containers. Subcommands: export and import. Same encryption, path selection, and dry-run behavior as the top-level savestate export / savestate import commands, with required --out / --in flags instead of optional --output or a positional file.

$ savestate container <subcommand> [options]

Flag	Description
`-a, --agent <id>`	Required on `export`. Agent ID to pack. Must be a single non-empty agent id.
`-o, --out <file>`	Required on `export`. Output `.savestate` path. Must be a single non-empty path.
`-i, --in <file>`	Required on `import`. Input `.savestate` path. Must be a single non-empty path.
`--dry-run`	Preview without writing or restoring
`--force`	Overwrite an existing export file or import target file
`--include <paths>`	Only pack or restore named state paths (`personality`, `memory`, `tools`, `preferences`, `conversation_history`)
`--exclude <paths>`	Skip named state paths
`-p, --passphrase <pass>`	Passphrase, or `SAVESTATE_PASSPHRASE` / prompt
`-k, --keyfile <path>`	Keyfile instead of a passphrase
`--description <text>`	Optional manifest description on `export`. Must be a non-empty description.
`--target <dir>`	Write restored agent state to this directory on `import`
`--merge`	Merge with existing state on `import` (default: replace)
`--replace`	Replace existing state on `import`
`--json`	Emit export or import results as JSON. Encrypts on `export`, decrypts on `import`. Skips progress output. Useful for scripting.

# Preview an export without writing
$ savestate container export -a my-agent -o agent.savestate --dry-run

# Restore into a directory, replacing an existing target file
$ savestate container import --in agent.savestate --target ./restored --force

# Scripting
$ savestate container export -a my-agent -o agent.savestate --json --dry-run

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.

← Previous Getting Started Next → Platform Adapters