@snapback/cli

v3.0.1

Published

18 days ago

CLI tool for managing SnapBack snapshots and file protection

0High
0Medium
0Low

snapback cli file-protection snapshots backup

AI coding agents—Cursor, Claude Code, GitHub Copilot, Windsurf—are incredible until they're not. One hallucinated change cascades into hours of debugging. Git doesn't help because you haven't committed yet. And the faster you vibe-code, the faster mistakes compound.

SnapBack makes your codebase smarter every session. Day 1: Detection. Day 30: Patterns. Day 90: Prediction.

Why SnapBack?

| The Problem | The Solution | |-------------|--------------| | AI makes a bad change | Automatic snapshots before risky edits | | You don't notice until later | Risk analysis flags dangerous patterns | | Git history is clean (no commits yet) | One-click recovery with snap undo | | Same mistake happens again | Learning loop auto-promotes patterns | | Works in Cursor but not VS Code | Editor-agnostic protection |

Key Metrics

⚡ <100ms snapshot creation (tested on 10K file repo, MacBook Pro M1, SSD)
🎯 89% AI change detection accuracy (internal benchmark, Q4 2025)
🔒 Privacy-first — code never leaves your machine
🧠 Self-improving — learns from your mistakes automatically

Getting Started

SnapBack has two primary interfaces:

🎨 VS Code Extension (Recommended)

The extension provides the best experience with automatic snapshots, visual recovery UI, and real-time risk indicators.

ext install MarcelleLabs.snapback-vscode

Or search "SnapBack" in the VS Code Extensions marketplace.

💻 CLI Tool

For terminal workflows, CI/CD integration, and MCP server setup:

# Install globally
npm install -g @snapback/cli
# or
pnpm add -g @snapback/cli

# Or run without installing
npx @snapback/cli <command>

Quick Start

# Interactive setup wizard (recommended for first-time users)
snap wizard

# Or quick init
snap init

# Analyze a file for risk
snap analyze src/auth.ts

# Create a snapshot before risky changes
snap snapshot -m "Before auth refactor"

# Pre-commit validation
snap check --all

# Something went wrong? Recover instantly
snap undo

Integration with AI Tools & Editors

SnapBack supports two protocol layers for maximum compatibility:

MCP Integration (AI Assistants)

Model Context Protocol for AI assistants like Claude, Cursor, and Windsurf.

Supported AI Tools:

Claude Desktop - .claude/mcp.json or ~/.claude.json
Qoder - .qoder-mcp-config.json
Cursor, Windsurf, cline, Gemini, Roo Code - mcpServers format

Quick Setup:

# Auto-detect and configure all AI tools
snap tools configure

# Or configure specific tools
snap tools configure --cursor
snap tools configure --claude
snap tools configure --windsurf

ACP Integration (Editor Agents)

Agent Communication Protocol for editor-native agents in Zed, JetBrains, and Neovim.

Supported Editors:

Zed - ~/.config/zed/settings.json (agent_servers)
JetBrains AI Assistant - ~/.config/jetbrains/ai-assistant.json
Neovim - Coming soon

Quick Setup:

# Auto-configure for Zed
snap acp configure --zed

# Auto-configure for JetBrains
snap acp configure --jetbrains

# Or configure all detected editors
snap acp configure --all

Manual Setup:

# View configuration examples
snap acp info

# Start ACP server manually
snap acp serve

# Or start with workspace path and verbose logging
snap acp serve --workspace /path/to/project --verbose

How it works: The snap acp serve command starts a JSON-RPC 2.0 server over stdin/stdout that your editor communicates with. No network required - fully local.

Compatibility Matrix

| Integration Layer | Protocol | Editors/Tools | |-------------------|----------|---------------| | VS Code Extension | Extension API | VS Code, Cursor, VSCodium, Code Server | | MCP | JSON-RPC over stdio | Claude Desktop, Qoder, Windsurf, cline, Gemini, Roo Code | | ACP | JSON-RPC 2.0 + Content-Length | Zed, JetBrains, Neovim |

Total: 13 tools/editors across 3 protocol layers.

Manual Setup

If you prefer manual configuration or the auto-setup doesn't work, add this to your AI tool's MCP config:

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "-y",
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "/absolute/path/to/your/project"
      ],
      "env": {
        "SNAPBACK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Using Global Install

{
  "mcpServers": {
    "snapback": {
      "command": "snap",
      "args": [
        "mcp",
        "--stdio",
        "--workspace",
        "/absolute/path/to/your/project"
      ],
      "env": {
        "SNAPBACK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 3: Using Node Directly

{
  "mcpServers": {
    "snapback": {
      "command": "node",
      "args": [
        "/absolute/path/to/node_modules/@snapback/cli/dist/index.js",
        "mcp",
        "--stdio",
        "--workspace",
        "/absolute/path/to/your/project"
      ],
      "env": {
        "SNAPBACK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config File Locations

| Tool | Config Path | |------|-------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.windsurf/mcp.json | | Continue | ~/.continue/config.json |

Workspace Requirements

The MCP server requires at least one of these markers in your project:

.git/ directory
package.json file
.snapback/ directory

Verify Setup

# Check which tools are configured
snap tools status

# Validate configurations
snap tools validate

# Repair broken configs
snap tools repair

Available MCP Tools

Once configured, your AI assistant uses the V2 4-tool surface — a session-oriented API designed for agentic coding loops:

| Tool | When to call | What it returns | |------|-------------|----------------| | snap_begin | Start of every task | Intelligence briefing: past learnings, active warnings, session lineage | | snap_pulse | Mid-session check | Read-only vitals: pulse level, risk pressure, trajectory | | snap_learn | Any discovery | Captures a pattern, gotcha, or decision for future sessions | | snap_end | Task complete | Ceremony: outcome recorded, carry-forward context for next session |

The agentic workflow (runs automatically in your AI assistant):

snap_begin({ task: "refactor auth module" })
  → briefing with learnings, warnings, risk context

  [... agent works ...]

snap_pulse()  // optional mid-session check
  → pulse: elevated, pressure: 42%, trajectory: stable

snap_learn({ insight: "always snapshot before token refresh logic" })

snap_end({ outcome: "completed", summary: "..." })
  → ceremony: files changed, patterns captured, context for next session

The full surface (check, advise, safe_to_write, refactoring intelligence, learning intelligence) is also available for advanced workflows — see MCP documentation →.

How It Compares

vs. Git Stash

| Feature | Git Stash | SnapBack | |---------|-----------|----------| | Automatic snapshots | ❌ Manual | ✅ On save | | AI change detection | ❌ | ✅ Cursor, Copilot, Claude | | Risk analysis | ❌ | ✅ Per-file scoring | | Recovery UX | 😬 Arcane | ✅ snap undo |

vs. Cursor's Built-in Checkpoints

| Feature | Cursor | SnapBack | |---------|--------|----------| | Works in any editor | ❌ | ✅ | | Risk scoring | ❌ | ✅ | | Learning from mistakes | ❌ | ✅ | | CLI access | ❌ | ✅ | | MCP integration | ❌ | ✅ |

vs. Static Analysis (SonarQube, CodeClimate)

| Feature | Static Analysis | SnapBack | |---------|-----------------|----------| | Local-first | ❌ Cloud | ✅ | | AI source detection | ❌ | ✅ | | Recovery/snapshots | ❌ | ✅ | | Personal learning | ❌ | ✅ |

Commands

Core Commands

| Command | Description | |---------|-------------| | snap init | Initialize .snapback/ in your workspace | | snap snapshot | Create a snapshot of current state | | snap analyze <file> | Risk analysis for a file | | snap check | Pre-commit validation | | snap list | List all snapshots | | snap undo | Revert the last destructive operation | | snap status | Show workspace status | | snap fix | Fix common issues |

Authentication Commands

| Command | Description | |---------|-------------| | snap login | OAuth login flow | | snap logout | Clear credentials | | snap whoami | Show current user |

Intelligence Commands

| Command | Description | |---------|-------------| | snap context [task] | Pre-task briefing: relevant patterns, warnings, risk context (CLI equivalent of snap_begin) | | snap validate <file> | Run 7-layer validation pipeline | | snap validate --all | Validate all staged files | | snap stats | Show learning statistics | | snap metrics [file] | File momentum scores — which files are highest-churn / highest-risk | | snap sync | Collect signals and fit momentum scoring normalizers | | snap refresh [--since] | Incremental signal update |

Learning Commands

| Command | Description | |---------|-------------| | snap learn record | Record a new learning | | snap learn list | List recorded learnings | | snap patterns report | Report a violation (auto-promotes at 3×) | | snap patterns summary | Show violation patterns |

Protection Commands

| Command | Description | |---------|-------------| | snap protect add <file> | Add file to protection list | | snap protect remove <file> | Remove from protection | | snap protect list | List protected files | | snap session start | Start a coding session | | snap session end | End current session (with learnings and validation) | | snap session end -l "learning" | End session and capture learnings | | snap session end --ceremony | End with validation (quick/standard/comprehensive) | | snap session end --outcome completed | End with outcome status | | snap watch | Continuous file watching |

MCP & Tools Commands

| Command | Description | |---------|-------------| | snap mcp --stdio | Start MCP server for AI assistant integration | | snap tools configure | Auto-setup MCP for detected AI tools | | snap tools configure --cursor | Configure for Cursor only | | snap tools configure --claude | Configure for Claude Desktop only | | snap tools configure --windsurf | Configure for Windsurf only | | snap tools configure --npm | Use npx mode (recommended for npm users) | | snap tools configure --dev | Use local development mode | | snap tools status | Check MCP configuration status | | snap tools validate | Validate MCP configurations | | snap tools repair | Repair broken MCP configurations |

Daemon & Service Commands

| Command | Description | |---------|-------------| | snap daemon start [--detach] | Start SnapBack daemon (CLI↔Extension coordination) | | snap daemon stop | Stop SnapBack daemon | | snap daemon status | Check daemon status | | snap daemon restart | Restart daemon | | snap daemon ping | Verify daemon is responsive | | snap service start [--daemon] | Start local service (shared state for multi-client) | | snap service stop | Stop local service | | snap service status | Check service status | | snap service logs [--follow] | Stream service logs | | snap service install | Register as system service | | snap service uninstall | Unregister system service |

Workspace Baseline Commands

| Command | Description | |---------|-------------| | snap baseline scan | Scan workspace and build intelligence baseline | | snap baseline status | Show baseline freshness and coverage | | snap baseline show | Display current baseline data | | snap baseline invalidate | Force baseline rebuild on next scan |

Utility Commands

| Command | Description | |---------|-------------| | snap wizard | Interactive first-run setup | | snap doctor | Diagnostics and health check | | snap doctor --fix | Auto-fix detected issues | | snap upgrade [--check|--canary] | Update CLI or check for new version | | snap config list | List configuration values | | snap config get <key> | Get a specific config value | | snap config set <key> <value> | Set a configuration value | | snap alias list | List command shortcuts | | snap alias set <name> <cmd> | Create a command alias | | snap interactive | Guided TUI workflow |

The 7-Layer Validation Pipeline

When you run snap validate or snap check, SnapBack analyzes your code across seven layers:

| Layer | What It Checks | |-------|----------------| | Syntax | Bracket matching, semicolons | | Types | any usage, @ts-ignore, non-null assertions | | Tests | Vague assertions, 4-path coverage | | Architecture | Layer boundaries, service bypass | | Security | Hardcoded secrets, eval() | | Dependencies | Deprecated packages | | Performance | console.log, sync I/O, await in loops |

# Validate a single file
snap validate src/auth.ts

# Validate all staged files (quiet mode for CI)
snap validate --all --quiet

# JSON output for automation
snap validate --all --json

Auto-Promotion: Learning from Mistakes

SnapBack tracks violations and automatically promotes patterns:

| Occurrence | Action | |------------|--------| | 1× | Stored in violations.jsonl | | 3× | Auto-promoted to workspace-patterns.json | | 5× | Marked for automated detection |

# Report a violation manually
snap patterns report

# View promotion status
snap patterns summary

World-Class CLI UX

SnapBack implements best practices from GitHub CLI, Vercel CLI, and Stripe CLI.

Smart Error Messages

╭───────────────────────────────────────────────────╮
│ [ERR_NOT_INIT] Workspace Not Initialized          │
│                                                   │
│ This workspace hasn't been set up for SnapBack   │
│                                                   │
│ 💡 Suggestion:                                    │
│    Initialize SnapBack in this directory         │
│                                                   │
│ 📋 Try running:                                   │
│    $ snap init                                    │
╰───────────────────────────────────────────────────╯

Typo Detection

$ snap statis
╭────────────────────────────────────────╮
│ Unknown command: statis                │
│                                        │
│ Did you mean:                          │
│   $ snap status                        │
│   $ snap stats                         │
╰────────────────────────────────────────╯

Command Aliases

# Create shortcuts
snap alias set st status
snap alias set ss snapshot

# Use them
snap st
snap ss -m "checkpoint"

Dry-Run Mode

snap init --dry-run
# Shows what will be created without making changes

snap tools configure --dry-run
# Shows what MCP config would be written

Shell Completions

# Bash
eval "$(snap completion bash)"

# Zsh
eval "$(snap completion zsh)"

# Fish
snap completion fish | source

Completion scripts are also available at:

resources/completions/snap.bash
resources/completions/snap.zsh
resources/completions/snap.fish

Pre-Commit Hook Integration

Git Hook

#!/bin/sh
# .git/hooks/pre-commit
npx @snapback/cli check --snapshot --quiet

Lefthook

# .lefthook.yml
pre-commit:
  commands:
    snapback:
      run: npx @snapback/cli check --all --quiet

GitHub Actions

- name: Validate code
  run: npx @snapback/cli validate --all --json > validation.json

- name: Check for risky changes
  run: npx @snapback/cli check --quiet

Configuration

Workspace Structure

After snap init:

your-project/
├── .snapback/
│   ├── config.json              # Workspace config
│   ├── vitals.json              # Health metrics
│   ├── constraints.md           # Your rules (optional)
│   ├── patterns/
│   │   ├── violations.jsonl     # Tracked violations
│   │   └── workspace-patterns.json
│   └── learnings/
│       └── user-learnings.jsonl
└── .snapbackrc                  # CLI config

`.snapbackrc` Options

{
  "protectionLevel": "warn",
  "autoSnapshot": true,
  "riskThreshold": 5.0,
  "ignorePaths": ["node_modules", "dist", ".git"]
}

Diagnostics

$ snap doctor

🏥 SnapBack Diagnostics

  ✓ Node.js version      v20.10.0
  ✓ CLI installation     v1.0.11 (latest)
  ✓ Global directory     ~/.snapback/ exists
  ✓ Authentication       Logged in as @user
  ✓ Workspace            .snapback/ initialized
  ✓ MCP tools            3 tools configured
  ✓ Git repository       Clean
  ✓ Network              API reachable

  All checks passed!

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Issues found (validation failed, risky changes) |

Related Packages

Open Source (npm)

| Package | Description | |---------|-------------| | @snapback-oss/sdk | Production-ready SDK for code safety systems | | @snapback-oss/contracts | Type definitions and schemas | | @snapback-oss/infrastructure | Storage and logging utilities | | @snapback-oss/events | Event definitions and handlers |

VS Code Extension

| Package | Description | |---------|-------------| | MarcelleLabs.snapback-vscode | VS Code extension with visual UI |

Get an API Key

Unlock Pro features like checkpoint creation and restoration:

👉 console.snapback.dev/app/settings/api-keys

License

Apache-2.0