Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/superfly/sprites-go/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through installing the Sprites Go SDK, creating a client, and executing your first remote command. The whole flow mirrors the standard library’s os/exec package — if you have used exec.Command before, you already know most of the API.
1

Install the SDK

Add the module to your Go project with go get:
go get github.com/superfly/sprites-go
The module path is github.com/superfly/sprites-go but the package name is sprites. Import it with an alias to use the short package name in your code.
2

Import the package and create a client

Import sprites and call sprites.New with your auth token. The default base URL points to https://api.sprites.dev — you do not need to configure it for production use.
import sprites "github.com/superfly/sprites-go"

client := sprites.New("your-auth-token")
If you need a custom API endpoint, pass the WithBaseURL option:
client := sprites.New("your-auth-token",
    sprites.WithBaseURL("https://api.sprites.dev"))
See Authentication for how to obtain a token and for all available client options.
3

Get a sprite handle

Call client.Sprite with the name of your sprite. This returns a *Sprite handle immediately — it does not make a blocking network call to create the sprite.
sprite := client.Sprite("my-sprite")
The client attempts to establish a multiplexed control connection in the background. If the sprite is not reachable within the configured timeout (default 2 seconds), subsequent commands fall back to direct WebSocket connections per request.
4

Run a command and read its output

Call sprite.Command exactly as you would call exec.Command. The returned *Cmd supports the same methods:
output, err := sprite.Command("echo", "hello", "world").Output()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Output: %s", output)
Use cmd.Run() when you do not need to capture output, or cmd.CombinedOutput() to merge stdout and stderr into a single byte slice.
5

Set environment variables and working directory

Assign cmd.Env and cmd.Dir before calling Run, Start, or Output — the same fields as exec.Cmd:
cmd := sprite.Command("bash", "-c", "echo Hello $USER from $HOSTNAME")
cmd.Env = []string{"USER=sprite", "HOSTNAME=remote"}
cmd.Dir = "/tmp"

output, err := cmd.Output()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Greeting: %s", output)
Env entries must be in key=value form. Dir sets the working directory for the remote process.

​
Complete working example

The following program demonstrates a client with a custom base URL, a simple command, a command with piped stdin and a context timeout, and environment variable injection — all drawn from the SDK’s README: 
package main

import (
    "context"
    "fmt"
    "log"
    "strings"
    "time"

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

func main() {
    // Create client with authentication
    client := sprites.New("your-auth-token",
        sprites.WithBaseURL("https://api.sprites.dev"))

    // Get a sprite handle
    sprite := client.Sprite("my-sprite")

    // Example 1: Simple command with output
    output, err := sprite.Command("date").Output()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Current date: %s", output)

    // Example 2: Command with piped stdin and a 5-second timeout
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    cmd := sprite.CommandContext(ctx, "grep", "-i", "error")
    cmd.Stdin = strings.NewReader("Line 1\nError on line 2\nLine 3\nAnother ERROR\n")

    output, err = cmd.Output()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Grep results:\n%s", output)

    // Example 3: Environment variable injection
    cmd = sprite.Command("bash", "-c", "echo Hello $USER from $HOSTNAME")
    cmd.Env = []string{"USER=sprite", "HOSTNAME=remote"}

    output, err = cmd.Output()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Greeting: %s", output)
}

​
Handling exit errors

When a remote process exits with a non-zero status, Run, Output, and CombinedOutput return an *ExitError. Inspect it to get the exact exit code: 
cmd := sprite.Command("false")
err := cmd.Run()

if err != nil {
    if exitErr, ok := err.(*sprites.ExitError); ok {
        fmt.Printf("Command exited with code: %d\n", exitErr.ExitCode())
    } else {
        log.Fatal(err)
    }
}

​
Next steps

Authentication

Exchange a Fly.io macaroon for a sprite token and explore all client options.

Introduction

Read about all SDK capabilities: TTY, port forwarding, services, checkpoints, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us