CLI Commands Reference

Complete reference for all sprite CLI commands.

Global Options

These options work with any command:

Option	Description
`--debug[=<file>]`	Enable debug logging (logs to stdout if no file specified)
`-o`, `--org`	`<name>` Specify organization (can be used anywhere)
`-s`, `--sprite`	`<name>` Specify sprite (can be used anywhere)
`-h`, `--help`	Show this help message

Authentication Commands

`sprite login`

sprite login - Authenticate with Fly.io

sprite login [api-url] [options]

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
-h, --help Show - this help message

Examples:

sprite login
sprite login -o my-org
sprite login https://custom-api.sprites.dev

`sprite logout`

sprite logout - Remove Sprites configuration

sprite logout [options]

Options:

-h, --help Show - this help message

Examples:

sprite logout

`sprite org auth`

Add an API token

sprite org auth [api-url|alias] [-o <api>:<org>]

Aliases: sprite orgs, sprite organizations, sprite o

Options:

-h, --help - Show help for this command
-o, --o <string> - Organization to use (shorthand)
-o, --org <string> - Organization to use
-s, --s <string> - Sprite to use (shorthand)
-s, --sprite <string> - Sprite to use

Examples:

sprite org auth
sprite org auth https://custom-api.sprites.dev
sprite org auth prod
sprite org auth -o prod:my-org
sprite org auth -o staging:test-org
sprite org auth https://staging-api.sprites.dev -o staging:test-org

`sprite org list`

Show configured tokens

sprite org list [api-url|alias]

Options:

-h, --help - Show help for this command

`sprite org logout`

Remove all tokens

sprite org logout [options]

Options:

-f, --force - Skip confirmation prompt
-h, --help - Show help for this command

`sprite org keyring disable`

--- Org selector

sprite org keyring disable

`sprite org keyring enable`

--- Org selector

sprite org keyring enable

`sprite auth setup`

Set up authentication using a pre-generated token.

sprite auth setup --token <token>

Options:

-h, --help - Show help for this command
-t, --token <string> - Token in format: org-slug/org-id/token-id/token-value

Examples:

sprite auth setup --token "org-slug/org-id/token-id/token-value"

Sprite Management

`sprite create`

sprite create - Create a new sprite

sprite create [options] [sprite-name]

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
-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.

Examples:

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

`sprite use`

sprite use - Activate a sprite for the current directory

sprite use [options] [sprite-name]

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 use my-sprite
sprite use -o myorg dev-sprite
sprite use

`sprite list`

sprite list - List all sprites

sprite list [options]

Aliases: sprite ls

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
--prefix <prefix> - Filter sprites by name prefix
-h, --help Show - this help message

Lists all sprites in the selected organization. Use —prefix to filter sprites by name prefix.

Examples:

sprite list
sprite list -o myorg
sprite list --prefix dev

`sprite destroy`

sprite destroy - Destroy a sprite

sprite destroy [options] [sprite-name]

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
--force Skip - confirmation prompt
-h, --help Show - this help message

Examples:

sprite destroy mysprite
sprite destroy -o myorg mysprite
sprite destroy -s mysprite
sprite destroy --force

Command Execution

`sprite exec`

sprite exec - Execute a command in the sprite environment

sprite exec [options] <command> [args...]

Aliases: sprite x

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
-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. Use ‘sprite sessions’ to list, attach to, or kill running sessions.

Examples:

sprite exec ls -la
sprite exec -dir /app echo hello world
sprite exec -env KEY=value,FOO=bar env
sprite exec -tty /bin/bash
sprite exec -o myorg -s mysprite npm start

`sprite console`

sprite console - Open an interactive shell in the sprite environment

sprite console [options]

Aliases: sprite c

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
-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. Sessions can be detached and reattached using sprite exec -id.

Examples:

sprite console
sprite console -o myorg -s mysprite

Checkpoints

`sprite checkpoint create`

Create a new checkpoint

sprite checkpoint create

Options:

-c, --comment <string> - Optional comment to describe this checkpoint
-h, --help - Show help for this command

`sprite checkpoint list`

List all checkpoints

sprite checkpoint list [options]

Aliases: sprite checkpoint ls, sprite checkpoints ls

Options:

-h, --help - Show help for this command
-h, --history <string> - Filter by history version Include auto-generated checkpoints

`sprite checkpoint info`

Show information about a specific checkpoint

sprite checkpoint info <version-id>

Options:

-h, --help - Show help for this command

Examples:

sprite checkpoint info v2

`sprite checkpoint delete`

Delete a checkpoint (soft delete)

sprite checkpoint delete <version-id>

Aliases: sprite checkpoint rm

Options:

-h, --help - Show help for this command

Examples:

sprite checkpoint delete v3

`sprite restore`

sprite restore - Restore from a checkpoint version

sprite restore [options] <version-id>

Aliases: sprite checkpoint restore

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
-h, --help Show - this help message

Examples:

sprite restore v1
sprite restore -o myorg -s mysprite v2
See also:
sprite checkpoint --help    Full checkpoint documentation

Networking

`sprite proxy`

sprite proxy - Forward local ports through the remote server proxy

sprite proxy [options] <port1> [port2] ... or <local1:remote1> [local2:remote2] ...

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
-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.

Examples:

sprite proxy 8080
sprite proxy 3000 8080
sprite proxy 4005:4000
sprite proxy 3001:3000 8081:8080
sprite proxy -o myorg -s mysprite 8080

`sprite url`

sprite url - Manage sprite URL settings

sprite url                    Show sprite URL and auth setting sprite url update [options]   Update URL authentication settings URL Format: https://<sprite-name>-<org>.sprites.dev/ Authentication Modes: sprite     Allows access via browser to Sprite org members, and via org tokens (default) public     No authentication - anyone with URL can access Subcommands: update     Update URL authentication settings Update options: --auth <type>    Authentication type: 'public' or 'sprite'

Examples:

sprite url                         # Show current URL and auth setting
sprite url update --auth public    # Make URL publicly accessible
sprite url update --auth sprite    # Require org membership (default)
Accessing Authenticated URLs:
Visit the URL in your browser and log in with Fly.io, or use an org token:
curl -H "Authorization: Bearer $SPRITE_API_TOKEN" https://mysprite-myorg.sprites.dev/
Security Notes:
- Public URLs are accessible to anyone on the internet
- Never expose secrets, env vars, or sensitive data via HTTP
- Use 'public' only for demos, webhooks, or truly public services

`sprite url update`

Update URL authentication settings

sprite url update [options]

Options:

-a, --auth <string> - Authentication type: ‘public’ or ‘sprite’ (default)
-h, --help - Show help for this command
-o, --o <string> - Organization to use (shorthand)
-o, --org <string> - Organization to use
-s, --s <string> - Sprite to use (shorthand)
-s, --sprite <string> - Sprite to use

Changes the authentication requirement for the sprite’s URL. Use ‘public’ to make the URL accessible without authentication. Use ‘sprite’ to require org membership (default).

Examples:

sprite url update --auth public
sprite url update --auth sprite

Utility Commands

`sprite api`

sprite api - Make authenticated API calls with curl

sprite api [options] <path> [curl options]

Options:

-o, --org <name> - Specify organization
-s, --sprite <name> - Specify sprite
-h, --help Show - this help message

This command wraps curl to automatically add authentication headers. If a sprite is specified with -s, the path is relative to /v1/sprites/<sprite-name>/. If no sprite is specified, the path is relative to /v1/. Paths starting with /v1/sprites/ are always used as-is, ignoring any sprite context. All arguments after the path are passed directly to curl.

Examples:

sprite api -o myorg /sprites
sprite api -o myorg -s my-sprite /upgrade -X POST
sprite api -o myorg -s my-sprite /exec -X GET
sprite api -o myorg -s my-sprite /checkpoints

`sprite upgrade`

sprite upgrade - Upgrade the sprite client to the latest version

sprite upgrade [options]

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 upgrade                  # Upgrade to the latest version
sprite upgrade --check          # Check for available updates
sprite upgrade --force          # Force upgrade even if up to date
sprite upgrade --channel dev    # Switch to the dev channel
sprite upgrade --channel rc     # Switch to the rc channel

Exit Codes

Code	Meaning
0	Success
1	General error
2	Command not found
126	Command cannot execute
127	Command not found (in sprite)
128+	Command terminated by signal

Environment Variables

Variable	Description
`SPRITE_TOKEN`	API token override (legacy; falls back if no stored token)
`SPRITE_URL`	Direct sprite URL (for local/dev direct connections)
`SPRITES_API_URL`	API URL override (default: `https://api.sprites.dev`)

Configuration Files

Global Config

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

{
  "version": "1",
  "current_selection": {
    "url": "https://api.sprites.dev",
    "org": "personal"
  },
  "urls": {
    "https://api.sprites.dev": {
      "url": "https://api.sprites.dev",
      "orgs": {
        "personal": {
          "name": "personal",
          "keyring_key": "sprites-cli:<user-id>",
          "use_keyring": true,
          "sprites": {}
        }
      }
    }
  }
}

Local Context

.sprite (in project directory):

{
  "organization": "personal",
  "sprite": "my-project-sprite"
}

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

CLI Commands Reference

Global Options

Authentication Commands

sprite login

sprite logout

sprite org auth

sprite org list

sprite org logout

sprite org keyring disable

sprite org keyring enable

sprite auth setup

Sprite Management

sprite create

sprite use

sprite list

sprite destroy

Command Execution

sprite exec

sprite console

Checkpoints

sprite checkpoint create

sprite checkpoint list

sprite checkpoint info

sprite checkpoint delete

sprite restore

Networking

sprite proxy

sprite url

sprite url update

Utility Commands

sprite api

sprite upgrade

Exit Codes

Environment Variables

Configuration Files

Global Config

Local Context

Related Documentation

`sprite login`

`sprite logout`

`sprite org auth`

`sprite org list`

`sprite org logout`

`sprite org keyring disable`

`sprite org keyring enable`

`sprite auth setup`

`sprite create`

`sprite use`

`sprite list`

`sprite destroy`

`sprite exec`

`sprite console`

`sprite checkpoint create`

`sprite checkpoint list`

`sprite checkpoint info`

`sprite checkpoint delete`

`sprite restore`

`sprite proxy`

`sprite url`

`sprite url update`

`sprite api`

`sprite upgrade`