CLI Authentication

Sprites uses your Fly.io account for authentication. This guide covers setting up authentication and managing API tokens.

Quick Setup

The simplest way to authenticate:

sprite org auth

This opens a browser window to authenticate with Fly.io. Once complete, you’re ready to use Sprites.

Authentication Flow

1. Authenticate with Fly.io

If you’re already logged into flyctl, the Sprites CLI can use your existing session:

sprite org auth

If you’re not logged in or encounter issues:

# First, ensure you're logged into fly
fly auth logout
fly auth login

# Verify your flyctl session works
fly apps list

# Then authenticate with Sprites
sprite org auth

2. Select an Organization

If you belong to multiple Fly.io organizations, select one:

sprite org list

Output:

Organizations:
  personal (current)
  my-team
  another-org

To switch organizations:

sprite org auth --org my-team

Token Management

You can also create and manage tokens at sprites.dev/account.

Viewing Your Token

Your Sprites API token is stored securely. To view it:

# If using keyring storage, disable it first
sprite org keyring disable

# Then check the config file
cat ~/.sprites/sprites.json

The token is used for API and SDK authentication.

Token Storage

By default, tokens are stored in your system keyring for security. You can switch to file-based storage:

# Disable keyring (stores token in config file)
sprite org keyring disable

# Re-enable keyring storage
sprite org keyring enable

Config File Structure

When using file-based storage, ~/.sprites/sprites.json contains:

{
  "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": {}
        }
      }
    }
  }
}

Multiple Organizations

Adding Organizations

Add tokens for multiple organizations:

# Add another organization
sprite org auth --org my-team

Switching Organizations

# List organizations
sprite org list

# Use a specific org for a command
sprite -o my-team list

# Set default organization
sprite org auth --org my-team

Per-Directory Organization

Use different organizations in different directories:

cd ~/projects/team-project
sprite use --org my-team my-sprite

cd ~/projects/personal
sprite use --org personal my-personal-sprite

The organization is saved in the local .sprite file.

Logging Out

Remove a Single Organization

sprite org logout --org my-team

Remove All Credentials

sprite logout

This removes all stored tokens and configuration.

CI/CD Authentication

For CI/CD or automated environments, use sprite auth setup --token to configure authentication:

# Set up authentication from a token (no browser needed)
sprite auth setup --token "my-org/token-id/secret"

You can generate tokens at sprites.dev/account.

GitHub Actions Example

- name: Install Sprites CLI
  run: |
    curl -fsSL https://sprites.dev/install.sh | bash
    echo "$HOME/.local/bin" >> $GITHUB_PATH

- name: Setup Sprites auth
  run: sprite auth setup --token "$SPRITES_TOKEN"
  env:
    SPRITES_TOKEN: ${{ secrets.SPRITES_TOKEN }}

- name: Use Sprites
  run: sprite list

Environment Variables

After authentication is configured, you can use environment variables to override settings:

export SPRITE_ORG="my-org"           # Override the default organization
export SPRITES_API_URL="https://api.sprites.dev"  # Override API endpoint

Troubleshooting

”Not authenticated” Error

# Re-authenticate
sprite org auth

# If that fails, reset and try again
fly auth logout
fly auth login
sprite org auth

Token Not Found

If the CLI can’t find your token:

# Check if using keyring
sprite org keyring disable

# Verify token exists
cat ~/.sprites/sprites.json | grep api_token

# Re-authenticate if needed
sprite org auth

Browser Doesn’t Open

If the authentication browser doesn’t open automatically:

Look for the URL printed in the terminal
Copy and paste it into your browser
Complete authentication
Return to the terminal

Permission Errors

If you get permission errors after authentication:

Verify your Fly.io account has access to the organization
Check that your flyctl session is valid: fly apps list
Try re-authenticating: sprite org auth

Security Best Practices

Use keyring storage (default) for interactive use
Use sprite auth setup --token for CI/CD pipelines with tokens stored as secrets
Never commit .sprites/ or .sprite files to version control
Rotate tokens periodically by re-authenticating
Use organization-specific tokens rather than personal tokens in shared environments

Getting Started

Concepts

CLI Reference

Integrations

CLI Authentication

Quick Setup

Authentication Flow

1. Authenticate with Fly.io

2. Select an Organization

Token Management

Viewing Your Token

Token Storage

Config File Structure

Multiple Organizations

Adding Organizations

Switching Organizations

Per-Directory Organization

Logging Out

Remove a Single Organization

Remove All Credentials

CI/CD Authentication

GitHub Actions Example

Environment Variables

Troubleshooting

”Not authenticated” Error

Token Not Found

Browser Doesn’t Open

Permission Errors

Security Best Practices

Next Steps

Commands Reference

Quickstart

​Quick Setup

​Authentication Flow

​1. Authenticate with Fly.io

​2. Select an Organization

​Token Management

​Viewing Your Token

​Token Storage

​Config File Structure

​Multiple Organizations

​Adding Organizations

​Switching Organizations

​Per-Directory Organization

​Logging Out

​Remove a Single Organization

​Remove All Credentials

​CI/CD Authentication

​GitHub Actions Example

​Environment Variables

​Troubleshooting

​”Not authenticated” Error

​Token Not Found

​Browser Doesn’t Open

​Permission Errors

​Security Best Practices

​Next Steps

Commands Reference

Quickstart

Quick Setup

Authentication Flow

1. Authenticate with Fly.io

2. Select an Organization

Token Management

Viewing Your Token

Token Storage

Config File Structure

Multiple Organizations

Adding Organizations

Switching Organizations

Per-Directory Organization

Logging Out

Remove a Single Organization

Remove All Credentials

CI/CD Authentication

GitHub Actions Example

Environment Variables

Troubleshooting

”Not authenticated” Error

Token Not Found

Browser Doesn’t Open

Permission Errors

Security Best Practices

Next Steps