> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
sprite org auth
```

If you're not logged in or encounter issues:

```bash theme={null}
# 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:

```bash theme={null}
sprite org list
```

Output:

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

To switch organizations:

```bash theme={null}
sprite org auth --org my-team
```

## Token Management

You can also create and manage tokens at [sprites.dev/account](https://sprites.dev/account).

### Viewing Your Token

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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```bash theme={null}
# Add another organization
sprite org auth --org my-team
```

### Switching Organizations

```bash theme={null}
# 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:

```bash theme={null}
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

```bash theme={null}
sprite org logout --org my-team
```

### Remove All Credentials

```bash theme={null}
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:

```bash theme={null}
# 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](https://sprites.dev/account).

### GitHub Actions Example

```yaml theme={null}
- 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:

```bash theme={null}
export SPRITE_ORG="my-org"           # Override the default organization
export SPRITES_API_URL="https://api.sprites.dev"  # Override API endpoint
```

## Troubleshooting

### "Not authenticated" Error

```bash theme={null}
# 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:

```bash theme={null}
# 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:

1. Look for the URL printed in the terminal
2. Copy and paste it into your browser
3. Complete authentication
4. Return to the terminal

### Permission Errors

If you get permission errors after authentication:

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

## Security Best Practices

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Commands Reference" icon="terminal" href="/sprites/cli/commands">
    Full CLI documentation and command examples
  </Card>

  <Card title="Quickstart" icon="rocket" href="/sprites/quickstart">
    Create your first Sprite in minutes
  </Card>
</CardGroup>