SaveContext CLI (sc)

The Rust-native command-line interface for SaveContext. This CLI is the primary implementation, with the MCP server delegating operations to it via a bridge pattern.

Installation

From Source (Development)

cd cli
cargo build --release
# Binary at target/release/sc

Add to PATH

# Option 1: Symlink to a directory in PATH
ln -sf "$(pwd)/target/release/sc" /usr/local/bin/sc

# Option 2: Add to shell profile
export PATH="$PATH:/path/to/savecontext/cli/target/release"

Architecture

AI Coding Tools (Claude Code, Cursor, Cline, etc.)
                    │
                    ▼
    ┌───────────────────────────────────────────┐
    │  MCP Server (TypeScript)                  │
    │  @savecontext/mcp                         │
    │               │                           │
    │               ▼                           │
    │  ┌─────────────────────────────────────┐  │
    │  │  CLI Bridge                         │  │
    │  │  server/src/cli/bridge.ts           │  │
    │  │  Delegates to Rust CLI              │  │
    │  └─────────────────────────────────────┘  │
    └───────────────────┬───────────────────────┘
                        │
                        ▼
    ┌───────────────────────────────────────────┐
    │  Rust CLI (`sc`)                          │
    │  45+ commands for sessions, issues,       │
    │  context, memory, plans, checkpoints      │
    │  Background embedding generation          │
    └───────────────────┬───────────────────────┘
                        │
                        ▼
    ┌───────────────────────────────────────────┐
    │  SQLite Database                          │
    │  ~/.savecontext/data/savecontext.db       │
    └───────────────────────────────────────────┘

The MCP server acts as a thin transport layer that receives tool calls from AI coding assistants and delegates them to the Rust CLI. This architecture provides:

• Single source of truth: All business logic lives in Rust
• Direct CLI access: Power users can use sc directly from terminal
• Background processing: Embedding generation happens asynchronously after save
• Performance: Native Rust execution for database operations

Quick Reference

Global Flags

--db <path>       # Custom database path (default: ~/.savecontext/data/savecontext.db)
--actor <name>    # Actor name for audit trail
--session <id>    # Active session ID
--json            # Output as JSON
--format <fmt>    # Output format: json, csv, table (default: table)
--silent          # Minimal output (IDs only for create/mutate)
--dry-run         # Preview mutations without writing
-v, -vv, -vvv    # Increase verbosity (info, debug, trace)
-q, --quiet       # Quiet mode
--no-color        # Disable colored output

Commands

Session Management

sc session start "Feature work" -d "Description"   # Start a session
sc session list                                     # List sessions
sc session list --status all                        # Include completed
sc session pause                                    # Pause current session
sc session resume <id>                              # Resume a session
sc session end                                      # End current session
sc session rename "New name"                        # Rename session
sc session delete <id>                              # Delete session
sc session add-path /path/to/project                # Add path to session
sc session remove-path /path/to/project             # Remove path from session

Context Items

sc save auth-decision "Using JWT tokens" -c decision -p high
sc get --query "authentication"                     # Semantic search
sc get --query "auth" --search-all-sessions         # Search all sessions
sc get --query "auth" --search-mode fast            # Fast mode (Model2Vec only)
sc get --key auth-decision                          # Get by key
sc get --category decision                          # Filter by category
sc update auth-decision --value "Updated reasoning"
sc delete auth-decision
sc tag add auth-decision -t important,security
sc tag remove auth-decision -t security

Issues

sc issue create "Fix login bug" -t bug -p 3         # Create issue
sc issue list                                       # List open issues
sc issue list --status all                          # Include closed
sc issue show SC-a1b2                               # Show details
sc issue update SC-a1b2 --status in_progress        # Update
sc issue complete SC-a1b2                           # Mark done
sc issue claim SC-a1b2                              # Assign to self
sc issue release SC-a1b2                            # Unassign
sc issue clone SC-a1b2                              # Clone issue
sc issue duplicate SC-a1b2 --of SC-c3d4             # Mark as duplicate
sc issue ready                                      # List ready issues
sc issue next-block -c 3                            # Claim next batch
sc issue complete SC-a1b2 --reason "Done"           # Complete with reason
sc issue count                                      # Count by status
sc issue count --group-by type                      # Count by type
sc issue stale                                      # Stale issues (7+ days)
sc issue stale --days 3                             # Stale issues (3+ days)
sc issue blocked                                    # Blocked issues + blockers
sc issue dep tree SC-a1b2                           # Dependency tree
sc issue dep tree                                   # Trees for all epics
sc issue label add SC-a1b2 -l frontend,urgent
sc issue dep add SC-a1b2 --depends-on SC-c3d4

Checkpoints

sc checkpoint create "pre-refactor" --include-git
sc checkpoint list
sc checkpoint show <id>
sc checkpoint restore <id>
sc checkpoint delete <id>
sc checkpoint add-items <id> -k key1,key2
sc checkpoint remove-items <id> -k key1

Memory (Persistent Across Sessions)

sc memory save test-cmd "npm test" -c command
sc memory get test-cmd
sc memory list
sc memory list -c config
sc memory delete test-cmd

Projects

sc project create /path/to/project -n "My Project"
sc project list
sc project show <id>
sc project update <id> --name "New Name"
sc project delete <id>

Plans

sc plan create "Q1 Features" -c "## Goals\n- Feature 1\n- Feature 2"
sc plan list
sc plan show <id>
sc plan update <id> --status completed
sc plan capture                                # Import plan from AI agent's plan file
sc plan capture --agent claude --max-age 60    # Specific agent, 60min max age

Embeddings

sc embeddings status                                # Check config
sc embeddings configure --provider ollama --enable
sc embeddings configure --provider huggingface --token <token>
sc embeddings backfill                              # Generate for existing items
sc embeddings test "Hello world"                    # Test connectivity

Sync (JSONL Export/Import)

sc sync status
sc sync export
sc sync import

Prime (Context Injection)

sc prime --compact                                  # Fixed-limit category buckets
sc prime --smart --compact                          # Ranked by relevance within token budget
sc prime --smart --compact --budget 2000            # Custom token budget
sc prime --smart --compact --query "auth"           # Semantic boost for topic
sc prime --smart --compact --decay-days 7           # Aggressive recency bias
sc prime --smart --json                             # JSON with scoring stats
sc prime --transcript                               # Include Claude Code transcripts

Smart prime flags:

Flag	Default	Description
--smart	off	Enable relevance-ranked selection
--budget <n>	4000	Token budget for context items
--query <text>	none	Semantic boost for a topic
--decay-days <n>	14	Temporal decay half-life in days

Scoring: temporal_decay * priority_weight * category_weight * semantic_boost

• Temporal decay: exponential (today=1.0, 7d=0.71, 14d=0.5, 28d=0.25)
• Priority: high=3.0, normal=1.0, low=0.5
• Category: decision=2.0, reminder=1.5, progress=1.0, note=0.5
• Semantic boost: 0.5x-2.5x based on cosine similarity to --query
• MMR diversity: penalizes near-duplicate items by embedding similarity

Other

sc init --global                                    # Initialize database
sc status                                           # Show session status
sc compaction                                       # Prepare for compaction
sc completions bash > ~/.bash_completion.d/sc      # Shell completions
sc version

Embedding Configuration

The CLI supports background embedding generation for semantic search. Configure via environment variables or the embeddings configure command:

Ollama (Recommended for Local)

# Uses nomic-embed-text by default
sc embeddings configure --provider ollama --enable

# Or with custom model
sc embeddings configure --provider ollama --model mxbai-embed-large --enable

HuggingFace (Cloud API)

sc embeddings configure --provider huggingface --token hf_xxx --enable

Environment Variables

export SC_EMBEDDINGS_PROVIDER=ollama    # or huggingface
export SC_EMBEDDINGS_MODEL=nomic-embed-text
export SC_EMBEDDINGS_ENDPOINT=http://localhost:11434
export HUGGINGFACE_TOKEN=hf_xxx         # For HuggingFace

Output Modes

JSON Output

All commands support --json for machine-readable output:

sc session list --json | jq '.sessions[0].name'
sc issue list --json | jq '.issues | length'
sc get --query "auth" --json | jq '.items[].key'

Auto-JSON (Non-TTY)

When stdout is piped, output is automatically JSON — no flag needed:

sc issue list | jq '.issues[].title'    # Auto-JSON (piped)
sc issue list                            # Human-readable (TTY)

Format Flag

sc issue list --format json    # JSON output
sc issue list --format csv     # CSV output (id,title,status,priority,type,assigned_to)
sc issue list --format table   # Human-readable table (default)

Silent Mode

For scripting — create/mutate commands print only the ID:

ID=$(sc issue create "Bug fix" --silent)
sc save my-key "value" --silent           # Prints: my-key
sc session start "work" --silent          # Prints: sess_xxxx

Dry Run

Preview mutations without writing to the database:

sc issue create "Test" --dry-run          # Would create issue: Test [task, priority=2]
sc issue create "Test" --dry-run --json   # {"dry_run":true,"action":"create_issue",...}

Error Handling

Structured Errors

Errors include machine-readable codes, hints, and recovery suggestions:

{
  "error": {
    "code": "ISSUE_NOT_FOUND",
    "message": "Issue not found: SC-xxxx",
    "retryable": false,
    "exit_code": 3,
    "hint": "Did you mean: SC-a1b2, SC-a1b3?"
  }
}

Structured JSON errors are automatic when piped (non-TTY) or with --json.

Exit Code Categories

Exit	Category	Action
0	Success	Continue
1	Internal	Report bug
2	Database	Check init/permissions
3	Not Found	Verify ID, check hint for suggestions
4	Validation	Fix input, retry
5	Dependency	Resolve dependency first
6-9	Other	See cli/AGENTS.md for full reference

For the complete error code table and retryable flags, see cli/AGENTS.md.

Intent Detection

The CLI auto-normalizes common synonyms, so you don't need to memorize canonical values:

• Status: done → closed, wip → in_progress, todo → open
• Type: defect → bug, story → feature, cleanup → chore
• Priority: critical → 4, high → 3, low → 1, P0-P4 accepted

Similar ID Suggestions

When an ID isn't found, the error includes suggestions for similar existing IDs.

Session Hints

When no active session is bound to your terminal, the error lists recent resumable sessions with their IDs, names, and statuses.

Shell Completions

# Bash
sc completions bash > ~/.bash_completion.d/sc

# Zsh
sc completions zsh > ~/.zfunc/_sc

# Fish
sc completions fish > ~/.config/fish/completions/sc.fish

# PowerShell
sc completions powershell > $PROFILE.d/sc.ps1

Development

# Build debug
cargo build

# Build release
cargo build --release

# Run tests
cargo test

# Run with verbose logging (or use -v/-vv flags)
RUST_LOG=debug cargo run -- session list
# Note: Debug output shows search pipeline stages, session/project resolution, and embedding operations

# Check lints
cargo clippy

License

AGPL-3.0 - See LICENSE for details.