Sprite CLI

Sprite CLI

External CLI for managing Sprite environments from outside a sprite.

Installation

If sprite command is not found, install it:

curl https://sprites.dev/install.sh | bash

After installation, the user must authenticate manually:

Run sprite login to authenticate with your Fly.io account.

Do not run sprite login automatically - prompt the user to run it themselves.

Quick Reference

sprite list                              # List all sprites
sprite create <name>                     # Create sprite (user must request)
sprite destroy -s <name> -force          # Destroy sprite (see safety note)
sprite use <name>                        # Set sprite context for directory
sprite exec -s <name> -- <cmd>           # Run command in sprite
sprite console -s <name>                 # Interactive shell
sprite checkpoint create -s <name>       # Create checkpoint
sprite checkpoint list -s <name>         # List checkpoints
sprite restore -s <name> <id>            # Restore checkpoint
sprite proxy <port>                      # Forward ports
sprite url -s <name>                     # Show sprite URL
sprite api -s <name> <path>              # API call (curl wrapper)

Sprites

List

sprite list
sprite ls

Create (requires explicit user request)

sprite create my-sprite
sprite create -o myorg my-sprite

Destroy

sprite destroy -s my-sprite -force

Safety rule: Only destroy sprites you created in the current session. If asked to destroy a sprite you didn't create, tell the user the command instead:

To destroy that sprite, run: sprite destroy -s <name> -force

Use (set context)

sprite use my-sprite          # Creates .sprite file
sprite use --unset            # Remove context

Executing Commands

Single command

sprite exec -s my-sprite -- ls -la
sprite x -s my-sprite -- npm start

With proper quoting for shell commands

sprite exec -s my-sprite -- bash -c 'echo "hello" > /tmp/file.txt'

Interactive console

sprite console -s my-sprite
sprite c -s my-sprite

Checkpoints

Checkpoints are fast (~300ms). Use frequently.

sprite checkpoint create -s my-sprite
sprite checkpoint list -s my-sprite
sprite checkpoint ls -s my-sprite
sprite restore -s my-sprite <checkpoint-id>

Create with comment via API:

sprite api -s my-sprite /checkpoint -X POST -d '{"comment":"before refactor"}'

Services (Remote)

Manage long-running services on a sprite via sprite exec + sprite-env:

List services

sprite exec -s my-sprite -- sprite-env services list

Create service

# Basic service
sprite exec -s my-sprite -- sprite-env services create myapp --cmd python3 --args app.py

# With HTTP port (for web services)
sprite exec -s my-sprite -- sprite-env services create web --cmd python3 --args server.py --http-port 8080

# With dependencies
sprite exec -s my-sprite -- sprite-env services create api --cmd node --args server.js --needs postgres,redis

Options:

• --cmd <command> - Command to run (required)
• --args <a,b,c> - Comma-separated arguments
• --http-port <port> - HTTP port for proxy routing (only one service can have this)
• --needs <svc1,svc2> - Service dependencies
• --env <K=V,...> - Environment variables
• --dir <path> - Working directory
• --duration <time> - Log streaming duration (default: 5s)
• --no-stream - Don't stream logs after creation

Start/Stop/Restart

sprite exec -s my-sprite -- sprite-env services start myapp
sprite exec -s my-sprite -- sprite-env services stop myapp
sprite exec -s my-sprite -- sprite-env services restart myapp

Delete service

sprite exec -s my-sprite -- sprite-env services delete myapp

Send signal

sprite exec -s my-sprite -- sprite-env services signal myapp TERM
sprite exec -s my-sprite -- sprite-env services signal myapp HUP

View logs

Logs are at /.sprite/logs/services/<name>.log:

sprite exec -s my-sprite -- cat /.sprite/logs/services/myapp.log
sprite exec -s my-sprite -- tail -f /.sprite/logs/services/myapp.log

Port Forwarding

Forward local ports through sprite proxy:

sprite proxy 8080
sprite proxy 8080 3000 5432

URL Management

Each sprite has a unique URL. By default, URLs require authentication.

sprite url -s my-sprite                           # Show URL and auth status
sprite url update -s my-sprite --auth public      # Make public (user must request)
sprite url update -s my-sprite --auth sprite      # Require auth (default)

Note: Only make URLs public when the user explicitly requests it. Public URLs expose the HTTP service to the internet.

File Transfer

Use scripts/sprite-transfer.py to copy files between sprites or local:

# Local to sprite
python3 scripts/sprite-transfer.py ./local-file.txt my-sprite:/path/to/file

# Sprite to local
python3 scripts/sprite-transfer.py my-sprite:/path/to/file ./local-file.txt

# Sprite to sprite
python3 scripts/sprite-transfer.py sprite-a:/file sprite-b:/file

Direct API file operations

# Read file
sprite api -s my-sprite '/fs/read?path=/home/sprite/file.txt'

# Write file
echo "content" | sprite api -s my-sprite '/fs/write?path=/tmp/file.txt&mkdir=true' -X PUT --data-binary @-

# List directory
sprite api -s my-sprite '/fs/list?path=/home/sprite'

API Access

sprite api wraps curl with authentication:

sprite api -s my-sprite /checkpoints              # GET
sprite api -s my-sprite /exec -X POST             # POST
sprite api /sprites                               # Management API

See references/api.md for full API reference.

Debug Mode

sprite --debug exec -s my-sprite npm start
sprite --debug=/tmp/debug.log exec -s my-sprite npm start