tavva/sprite-cli

Sprite CLI (sprite)

Command-line interface for Sprites - persistent, hardware-isolated Linux microVMs for safe code execution. Sprites maintain filesystem and memory between runs, wake instantly from hibernation, and charge per-second of compute.

Quick Reference

sprite login                     # Authenticate with Fly.io
sprite logout                    # Remove configuration
sprite create [name]             # Create a new sprite
sprite use <name>                # Activate sprite for current directory
sprite use --unset               # Remove sprite association
sprite list                      # List all sprites (alias: ls)
sprite destroy [-f] <name>       # Remove a sprite
sprite exec <command>            # Run command in sprite (alias: x)
sprite exec -file src:dst <cmd>  # Upload file before execution
sprite console                   # Open interactive shell (alias: c)
sprite checkpoint create [-c]    # Save current state
sprite checkpoint list           # List checkpoints (alias: ls)
sprite checkpoint info <id>      # Show checkpoint details
sprite checkpoint delete <id>    # Remove checkpoint (alias: rm)
sprite restore [version-id]      # Restore from checkpoint
sprite proxy <port>              # Forward local port to sprite
sprite url update --auth <type>  # Set URL access (public/default)
sprite api <path> [curl-opts]    # Make authenticated API calls
sprite upgrade                   # Update CLI to latest version

Global Options

Available with any command:

• --debug[=<file>] - Enable debug logging
• -o, --org <name> - Specify organization
• -s, --sprite <name> - Specify sprite
• -h, --help - Display help

Common Tasks

Create and Use a Sprite

# Create a new sprite
sprite create my-dev-env

# Activate sprite for current directory (creates .sprite file)
sprite use my-dev-env

# Now commands run in this sprite context
sprite exec npm install

Execute Commands

# Run a single command
sprite exec ls -la

# Short alias
sprite x python script.py

# With environment variables
sprite exec -e API_KEY=secret ./run.sh

# Upload a file before execution (source:dest format)
sprite exec -file ./local-file.txt:/tmp/local-file.txt cat /tmp/local-file.txt

# Run with TTY (for interactive commands)
sprite exec -t vim file.txt

Interactive Shell

# Open shell (auto-detects bash/zsh/fish/tcsh/ksh)
sprite console

# Short alias
sprite c

Checkpoint Management

# Save current state with comment
sprite checkpoint create -c "Before risky changes"

# List all checkpoints
sprite checkpoint list

# View checkpoint details
sprite checkpoint info <version-id>

# Restore to a checkpoint
sprite restore <version-id>

# Delete a checkpoint
sprite checkpoint delete <version-id>

Port Forwarding

# Forward local port 3000 to sprite port 3000
sprite proxy 3000

# Forward local 8080 to sprite 3000
sprite proxy 8080:3000

# Multiple ports
sprite proxy 3000 5432 6379

URL Access Control

# Make sprite publicly accessible
sprite url update --auth public

# Require authentication (default)
sprite url update --auth default

Authentication

Initial Setup

# Interactive login via Fly.io
sprite login

# Or with pre-generated token
sprite auth setup --token <token>

Organization Management

# List configured tokens
sprite org list

# Add API token to organization
sprite org auth

# Remove all tokens
sprite org logout

# Toggle keyring storage
sprite org keyring enable
sprite org keyring disable

Configuration

• Global config: ~/.sprites/sprites.json
• Local context: .sprite file in project directory

The .sprite file stores organization and sprite selection, similar to .nvmrc or .python-version.

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Command not found
• 126 - Command cannot execute
• 127+ - Command/signal termination

Additional Resources

For complete CLI documentation including all options:

• references/cli-reference.md - Full command reference with all flags