CLI Reference

The SnapBack CLI (snap) provides command-line access to protection features, workspace management, and automation capabilities.

The CLI is included with the VS Code extension. For standalone use, install via npm: npm install -g @snapback/cli

Quick Start

snap init

Creates a .snapback/ directory with default configuration.

snap status

Shows protection status, recent snapshots, and workspace health.

snap watch

Starts continuous file watching for automatic snapshots.

Command Reference

Authentication Commands

# OAuth login flow
snap login

# Clear credentials
snap logout

# Show current user
snap whoami

Login initiates the OAuth flow in your browser. Credentials are stored securely in your system keychain.

Workspace Management

# Initialize .snapback/ directory
snap init

# Show workspace status
snap status

# Fix common issues
snap fix

# Run diagnostics
snap doctor

# Interactive first-time setup
snap wizard

Status shows:

Protection state (active/inactive)
Recent snapshot count
Storage usage
Any warnings or issues

Protection Commands

# Configure file protection
snap protect

# Manage coding sessions
snap session

# Continuous file watching
snap watch

# Create a snapshot
snap snapshot -m "Before refactoring"

# List snapshots
snap list

Session management:

# Start a named session
snap session start "Implement auth"

# End current session
snap session end

# List all sessions
snap session list

Intelligence Commands

These commands bring SnapBack’s learning capabilities to the CLI.

# Get context before starting work
snap context "add authentication" --keywords auth session

# Run validation pipeline
snap validate src/auth.ts

# Validate all staged files
snap validate --all

# Show learning statistics
snap stats

Context returns:

Related patterns from your codebase
Recent violations to avoid
Risk assessment for the task

Utility Commands

# Manage configuration
snap config list
snap config get apiUrl
snap config set apiUrl https://api.snapback.dev

# Create command aliases
snap alias set st status
snap alias list

# Undo last destructive operation
snap undo

# Self-update CLI
snap upgrade
snap upgrade --check

Core Commands

`snap analyze`

Analyze a file for AI-generated code risks.

snap analyze src/auth.ts

Output includes:

Risk score (0-10)
Risk level (low/medium/high)
Detected signals (bulk changes, unusual patterns, etc.)

`snap check`

Pre-commit hook to check for risky AI changes.

# Check staged files (default)
snap check

# Create snapshot if risky changes detected
snap check --snapshot

# Suppress output unless issues found
snap check --quiet

# Check all files (legacy mode)
snap check --all

Add snap check to your pre-commit hook to catch risky AI changes before committing.

`snap interactive`

Launch interactive mode with guided workflow.

snap interactive

Provides a menu-driven interface for:

Analyzing files
Creating snapshots
Listing snapshots

MCP Integration

Local MCP Server

Start the MCP server for AI assistant integration:

# Start MCP server (stdio transport)
snap mcp --stdio

# Configure MCP tools
snap tools

MCP Configuration

For Cursor, Claude Code, or other MCP-compatible tools:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "snapback": {
      "command": "snap",
      "args": ["mcp", "--stdio"],
      "type": "stdio"
    }
  }
}

Daemon Management

The SnapBack daemon provides background services for CLI/extension communication.

# Start daemon in background
snap daemon start --detach

# Check daemon status
snap daemon status

# Stop daemon
snap daemon stop

# Restart daemon
snap daemon restart

# Test daemon connectivity
snap daemon ping

Configuration

Configuration File

Create a .snapbackrc in your project root:

{
  "autoDecisionEngine": {
    "enabled": true,
    "riskThreshold": 60,
    "notifyThreshold": 40
  },
  "snapshot": {
    "maxPerFile": 100,
    "retentionDays": 30
  },
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.next/**"
  ]
}

Environment Variables

# API key for authenticated features
export SNAPBACK_API_KEY=your_api_key

# Custom storage path
export SNAPBACK_STORAGE_PATH=/custom/path

# Log level (debug | info | warn | error)
export SNAPBACK_LOG_LEVEL=info

Git Integration

Pre-commit Hook

Add SnapBack checking to your pre-commit workflow:

#!/bin/bash
# .git/hooks/pre-commit

# Check staged files for risky AI changes
snap check

if [ $? -ne 0 ]; then
  echo "SnapBack detected potential risks. Review before committing."
  echo "To bypass: git commit --no-verify"
  exit 1
fi

Learning System

Record learnings and manage patterns:

# Record a learning
snap learn "Always validate user input before processing"

# List patterns
snap patterns list

# Show learning stats
snap stats

Troubleshooting

Common Issues

Command not found

Ensure the CLI is installed globally: npm install -g @snapback/cli

Authentication errors

Run snap login to re-authenticate. Check network connectivity.

Debug Mode

Enable verbose logging for troubleshooting:

SNAPBACK_LOG_LEVEL=debug snap status

Getting Help

# Get help for any command
snap --help
snap status --help
snap session --help

Quick Start Guide - Get started with SnapBack
How Protection Works - Understand the AutoDecisionEngine
MCP Integration - AI assistant integration
VS Code Commands - Full extension command reference