Quickstart

This guide shows you how to install the CLI, create your first Sprite, and start running commands. By the end, you’ll have a working environment that sticks around between runs, serves traffic over HTTP, and wakes up automatically when you need it.

Install the CLI

Install with our install script (macOS/Linux):

curl -fsSL https://sprites.dev/install.sh | sh

This auto-detects your platform, downloads the binary with checksum verification, and installs to ~/.local/bin.

For Windows or manual installation, see CLI Installation or download from GitHub Releases.

Verify installation:

sprite --help

Authenticate

Sprites uses your Fly.io account for authentication:

sprite org auth

This opens a browser window to authenticate with Fly.io.

If authentication fails, try running fly auth logout followed by fly auth login first, then retry sprite org auth.

Create Your First Sprite

sprite create my-first-sprite

This creates a new Sprite with default configuration, running and ready to accept commands.

Set it as your active Sprite to avoid adding -s my-first-sprite to every command:

sprite use my-first-sprite

Run Commands

Execute commands in your Sprite:

# Run a simple command
sprite exec echo "Hello, Sprites!"

# Run multiple commands
sprite exec "cd /tmp && ls -la"

# Open an interactive shell
sprite console

Explore the Environment

Sprites come pre-configured with common development tools:

# Check available runtimes
sprite exec "node --version && python3 --version && go version"

# Install packages
sprite exec "pip install requests"

# Clone a repository
sprite exec "git clone https://github.com/your/repo.git"

Persistence in Action

Your Sprite’s filesystem persists between commands:

# Create a file
sprite exec "echo 'Hello' > /home/sprite/greeting.txt"

# Later, it's still there
sprite exec "cat /home/sprite/greeting.txt"

View Your Sprite’s URL

Every Sprite has a unique HTTP URL:

sprite url

Manage Sprites

# List all sprites
sprite list

# Destroy when done
sprite destroy my-first-sprite

---

Using the SDKs

Beyond the CLI, you can create and manage Sprites programmatically:

JavaScript

import { SpritesClient } from '@fly/sprites';

const client = new SpritesClient(process.env.SPRITE_TOKEN);

const sprite = await client.createSprite('my-sprite');

// Execute a command
const result = await sprite.execFile('python', ['-c', "print('hello')"]);
console.log(result.stdout);

// Stream output from long-running commands
const cmd = sprite.spawn('bash', ['-c', 'for i in {1..10}; do date +%T; sleep 0.5; done']);
for await (const line of cmd.stdout) {
  process.stdout.write(line);
}

await sprite.delete();

Go

package main

import (
    "context"
    "fmt"
    "io"
    "os"

    sprites "github.com/superfly/sprites-go"
)

func main() {
    ctx := context.Background()
    client := sprites.New(os.Getenv("SPRITE_TOKEN"))

    sprite, _ := client.CreateSprite(ctx, "my-sprite", nil)
    defer client.DeleteSprite(ctx, "my-sprite")

    // Execute a command
    cmd := sprite.Command("python", "-c", "print('hello')")
    output, _ := cmd.Output()
    fmt.Println(string(output))

    // Stream output from long-running commands
    cmd = sprite.Command("bash", "-c", "for i in {1..10}; do date +%T; sleep 0.5; done")
    stdout, _ := cmd.StdoutPipe()
    cmd.Start()
    io.Copy(os.Stdout, stdout)
    cmd.Wait()
}

---

Next Steps

• Working with Sprites - Find out about sessions, ports, persistence, and everything beyond the basics
• Core concepts: Lifecycle - Take a deeper dive into Sprites core concepts, beginning with Lifecyle and Persistence
• Billing and Cost Optimization - Learn how Sprites are billed, estimate your costs, and try cost optimization strategies