Skip to main content
Complete reference for all sprite CLI commands.

Authentication Commands

sprite login

sprite login - Authenticate with Fly.io
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --force - Skip the “already logged in” confirmation prompt
  • -h, --help - Show this help message
Examples:

sprite logout

sprite logout - Remove Sprites configuration
Options:
  • -h, --help - Show this help message
Examples:

sprite org auth

sprite org auth - Add an API token
Aliases: sprite orgs, sprite organizations, sprite o Options:
  • -o, --org <name> - Specify organization
  • -h, --help - Show this help message
Examples:

sprite org list

sprite org list - Show configured tokens
Options:
  • -h, --help - Show this help message

sprite org logout

sprite org logout - Remove all tokens
Options:
  • --force - Skip confirmation prompt
  • -h, --help - Show this help message

sprite org keyring disable

sprite org keyring disable - Disable keyring usage
Options:
  • -h, --help - Show this help message
Examples:

sprite org keyring enable

sprite org keyring enable - Enable keyring usage
Options:
  • -h, --help - Show this help message

sprite auth setup

sprite auth setup - Set up authentication using a pre-generated token.
Options:
  • --token <token> - Token in format: org-slug/org-id/token-id/token-value
  • -h, --help - Show this help message
Examples:

sprite org set-default

sprite org set-default - Set the default organization
Options:
  • -h, --help - Show this help message
Examples:

sprite org keyring status

sprite org keyring status - Show current keyring status
Options:
  • -h, --help - Show this help message

sprite auth migrate

sprite auth migrate - Migrate token keys to URL-based format

sprite keyring

sprite keyring - Browse organization tokens stored in keyring
Options:
  • -h, --help - Show this help message
Opens an interactive TUI to browse organization tokens. Use arrow keys to navigate, Enter to view tokens. Press ‘v’ to show/hide the selected token value.
Examples:

Sprite Management

sprite create

sprite create - Create a new sprite
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --skip-console - Exit after creating instead of connecting to console
  • --label <label> - Label to apply to the sprite (can be repeated)
  • -h, --help - Show this help message
Creates a new sprite with the specified name. The sprite will be created in the selected organization. If sprite name is not provided, you will be prompted. Lifecycle:
  • Sprites pause when idle (no HTTP requests and no active sessions)
  • Services keep sprites alive and auto-restart on boot
  • Use checkpoints to save and restore filesystem state Related Commands: sprite list —help List your sprites sprite destroy —help Delete a sprite permanently sprite console —help Open an interactive shell
Examples:

sprite use

sprite use - Activate a sprite for the current directory
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --unset - Remove the .sprite file from current directory
  • -h, --help - Show this help message
Creates a .sprite file in the current directory to set the active sprite. This file will be used by other commands when no sprite is explicitly specified. Similar to ‘nvm use’ or ‘asdf local’ for version management. If no sprite name is provided, shows an interactive list to choose from.
Examples:

sprite list

sprite list - List all sprites
Aliases: sprite ls Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -w, --watch - Watch for live updates
  • --prefix <prefix> - Filter sprites by name prefix
  • --json - Output sprite and organization details as JSON
  • -h, --help - Show this help message
Lists all sprites in the selected organization. Use —prefix to filter sprites by name prefix. —json cannot be combined with —watch.
Examples:

sprite destroy

sprite destroy - Destroy a sprite
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --force - Skip confirmation prompt
  • -h, --help - Show this help message
Examples:

sprite info

sprite info - Show sprite info including URL and labels
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message
Examples:

sprite config

sprite config - Show or update sprite configuration
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message
Examples:

sprite config update

sprite config update - Update sprite configuration
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --url-auth <type> - URL authentication type: ‘public’ or ‘sprite’
  • --private-access <type> - Private URL access type: ‘admins’ or ‘org_users’
  • --label <label> - Label to apply to the sprite (can be repeated)
  • --clear-labels - Clear all existing labels before applying —label
  • -h, --help - Show this help message
Examples:

sprite file edit

sprite file edit - Edit a file in a sprite
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message

sprite file push

sprite file push - Copy local files into a sprite
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -p, --parents - Create missing parent directories on the remote
  • -r, --recursive - Recursively push a directory
  • -h, --help - Show this help message
Examples:

sprite file pull

sprite file pull - Copy files out of a sprite to the local machine
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -p, --parents - Create missing parent directories locally
  • -r, --recursive - Recursively pull a directory
  • -h, --help - Show this help message
Examples:

Command Execution

sprite exec

sprite exec - Execute a command in the sprite environment
Aliases: sprite x Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --dir <path> - Working directory for command
  • --tty - Allocate pseudo-TTY
  • --env <vars> - Environment variables (KEY=value,KEY2=value2)
  • --http-post - Use HTTP/1.1 POST instead of WebSockets (non-TTY only)
  • --stdin - Read and forward stdin (non-TTY only)
  • --no-stdin - Do not read or forward stdin (non-TTY only)
  • --no-port-forward - Disable automatic local port forwarding for ports opened by the command
  • --file <source:dest> - Upload file before exec (repeatable)
  • -h, --help - Show this help message
When using —tty, terminal environment variables (TERM, COLORTERM, LANG, LC_ALL) are automatically passed through from your local environment. Piped stdin continues to be forwarded when neither stdin flag is supplied, but this compatibility mode cannot reconnect safely after a connection loss. Use —stdin to make input forwarding explicit or —no-stdin to keep output-only commands reconnectable. Use ‘sprite sessions’ to list, attach to, or kill running sessions.
Examples:

sprite console

sprite console - Open an interactive shell in the sprite environment
Aliases: sprite c Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --no-port-forward - Disable automatic local port forwarding for ports opened by the console
  • -h, --help - Show this help message
Opens an interactive shell with a TTY allocated. Uses shell environment variables to determine which shell to use. Supported shells: bash, zsh, fish, tcsh, ksh. Falls back to bash if shell detection fails. Detach with Ctrl+\ to leave the session running in the background. Related Commands: sprite exec —help Run a command without an interactive shell sprite attach —help Reconnect to a detached session sprite sessions —help List and manage running sessions
Examples:

sprite attach

sprite attach - Attach to a running session
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --no-port-forward - Disable automatic local port forwarding for ports opened by the session
  • -h, --help - Show this help message
Examples:

sprite sessions list

sprite sessions list - List running exec sessions
Aliases: sprite s list Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message

sprite sessions attach

sprite sessions attach - Attach to a running exec session
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --no-port-forward - Disable automatic local port forwarding for ports opened by the session
  • -h, --help - Show this help message

sprite sessions kill

sprite sessions kill - Kill a running exec session
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --signal <signal> - Signal to send (default: TERM)
  • --timeout <duration> - Timeout before SIGKILL (default: 10s)
  • -h, --help - Show this help message

Checkpoints

sprite checkpoint create

sprite checkpoint create - Create a new checkpoint
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --comment <text> - Optional comment describing this checkpoint
  • -h, --help - Show this help message

sprite checkpoint list

sprite checkpoint list - List all checkpoints
Aliases: sprite checkpoint ls, sprite checkpoints ls Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • --history <version> - Filter by history version
  • --include-auto - Include auto-generated checkpoints
  • -h, --help - Show this help message

sprite checkpoint info

sprite checkpoint info - Show information about a specific checkpoint
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message
Examples:

sprite checkpoint delete

sprite checkpoint delete - Delete a checkpoint
Aliases: sprite checkpoint rm Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message
Examples:

sprite restore

sprite restore - Restore from a checkpoint version
Aliases: sprite checkpoint restore Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message
Examples:

Networking

sprite proxy

sprite proxy - Forward local ports through the remote server proxy
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -W, --stdio <[host]:port> - Forward stdin and stdout to host:port on the Sprite
  • --ssh - Emulate an SSH session with a Sprite over stdio, for use as an ssh ProxyCommand.
  • -h, --help - Show this help message
Each port will be forwarded from localhost to the remote environment. Use LOCAL:REMOTE syntax to map different local and remote ports. Multiple ports can be specified to forward multiple services simultaneously. If a port was auto-forwarded by a running sprite exec, stop that command or rerun it with --no-port-forward before using the same local port here. Related Commands: sprite url —help Manage the sprite’s always-on HTTP URL
Examples:

sprite url

sprite url - Manage sprite URL settings
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -h, --help - Show this help message
  • --auth <type> - Authentication type: ‘public’ or ‘sprite’
Examples:

sprite url update

sprite url update - Update URL authentication settings
Options:
  • -o, --org <name> - Specify organization
  • -s, --sprite <name> - Specify sprite
  • -a, --auth <type> - Authentication type: ‘public’ or ‘sprite’
  • -h, --help - Show this help message
Examples:

Utility Commands

sprite api

Error: api requires a path argument

sprite upgrade

sprite upgrade - Upgrade the sprite client to the latest version
Options:
  • --check - Check for updates without installing
  • --force - Force upgrade even if already up to date
  • --version <version> - Upgrade to a specific version
  • --channel <channel> - Release channel (release, rc, dev)
  • -h, --help - Show this help message
Examples:

sprite completion

completion - Generate shell completion scripts

Exit Codes

Environment Variables

Configuration Files

Global Config

~/.sprites/sprites.json (managed by the CLI; format may evolve):

Local Context

.sprite (in project directory):

Installation

Install the Sprites CLI on your platform

Authentication

Set up your Fly.io account and manage tokens

Working with Sprites

Beyond the basics guide

Checkpoints

Save and restore sprite state