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.

The Client type is the primary entry point for the Sprites Go SDK. It holds authentication credentials, HTTP transport configuration, and a pool of control connections to sprites. Create a client with sprites.New or sprites.NewClient, then use its methods to create, retrieve, list, and delete sprites, or obtain *Sprite handles for executing commands and proxying ports.

​
Constructors

​
New

func New(token string, opts ...Option) *Client
Creates a new client authenticated with the given token. Defaults to https://api.sprites.dev as the base URL with a 30-second HTTP timeout and a 2-second control connection initialization timeout. Accepts zero or more Option values to customize behavior.
​
token
string
required
Bearer token used to authenticate all API requests.
​
opts
...Option
Zero or more functional options. See Option functions below.
​
returns
*Client
A fully initialized client ready for use.
client := sprites.New(os.Getenv("SPRITE_TOKEN"))

​
NewClient

func NewClient(baseURL, token string) *Client
Alternative constructor that accepts an explicit base URL. Equivalent to calling New(token, WithBaseURL(baseURL)).
​
baseURL
string
required
Base URL for the Sprites API (e.g., "https://api.sprites.dev").
​
token
string
required
Bearer token used to authenticate all API requests.
​
returns
*Client
A fully initialized client.

​
CreateToken

func CreateToken(ctx context.Context, flyMacaroon, orgSlug, inviteCode string, apiURL ...string) (string, error)
Package-level function (no Client required) that exchanges a Fly.io macaroon token for a Sprites access token. Useful during initial setup. Forces HTTP/1.1 to avoid header-size limits on the Fly.io edge proxy.
​
ctx
context.Context
required
Context for the HTTP request.
​
flyMacaroon
string
required
A valid Fly.io authentication token, typically starting with "FlyV1".
​
orgSlug
string
required
Organization slug (e.g., "personal" or a named organization).
​
inviteCode
string
required
Invite code required by some organizations. Pass an empty string if not needed.
​
apiURL
...string
Optional override for the API base URL. Defaults to "https://api.sprites.dev".
​
token
string
The issued Sprites access token.
​
error
error
Non-nil if the request failed or the response did not contain a token.
token, err := sprites.CreateToken(ctx, os.Getenv("FLY_TOKEN"), "personal", "")
if err != nil {
    log.Fatal(err)
}
client := sprites.New(token)

​
Option functions

Options are passed to New to customize the client.

​
WithBaseURL

func WithBaseURL(url string) Option
Sets a custom base URL for all API requests. Trailing slashes are stripped automatically.
​
url
string
required
Base URL of the Sprites API.

​
WithHTTPClient

func WithHTTPClient(client *http.Client) Option
Replaces the default HTTP client. The provided client’s transport is wrapped to capture the Sprite-Version response header.
​
client
*http.Client
required
Custom HTTP client to use for all requests.

​
WithControlInitTimeout

func WithControlInitTimeout(d time.Duration) Option
Sets how long Sprite() and SpriteWithOrg() wait to establish an initial control connection before falling back to per-request WebSocket connections. Defaults to 2 seconds.
​
d
time.Duration
required
Maximum duration to wait for the control connection.

​
WithDisableControl

func WithDisableControl() Option
Prevents the SDK from using multiplexed control connections entirely. All exec and proxy operations use a fresh direct WebSocket connection per request.

​
Sprite handles

​
Sprite

func (c *Client) Sprite(name string) *Sprite
Returns a *Sprite handle for the named sprite without making a create API call. Attempts to establish a control connection during the call, blocking for up to controlInitTimeout. Use this when the sprite already exists.
​
name
string
required
Name of the sprite.
​
returns
*Sprite
A sprite handle bound to this client.
sprite := client.Sprite("my-sprite")
out, err := sprite.Command("echo", "hello").Output()

​
SpriteWithOrg

func (c *Client) SpriteWithOrg(name string, org *OrganizationInfo) *Sprite
Like Sprite, but attaches organization information to the returned handle. Useful when working with sprites that belong to a specific organization.
​
name
string
required
Name of the sprite.
​
org
*OrganizationInfo
required
Organization information to associate with the sprite.
​
returns
*Sprite
A sprite handle with organization context.

​
Sprite management

​
CreateSprite

func (c *Client) CreateSprite(ctx context.Context, name string, config *SpriteConfig) (*Sprite, error)
Creates a new sprite on the server and returns a handle to it. Pass nil for config to use default settings.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name for the new sprite.
​
config
*SpriteConfig
Optional resource configuration.
​
sprite
*Sprite
Handle for the newly created sprite.
​
error
error
Non-nil on failure.
sprite, err := client.CreateSprite(ctx, "my-sprite", &sprites.SpriteConfig{
    RamMB: 512,
    CPUs:  1,
})

​
CreateSpriteWithOrg

func (c *Client) CreateSpriteWithOrg(ctx context.Context, name string, config *SpriteConfig, org *OrganizationInfo, labels []string) (*Sprite, error)
Creates a new sprite with optional organization context and labels.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name for the new sprite.
​
config
*SpriteConfig
Optional resource configuration.
​
org
*OrganizationInfo
Optional organization context.
​
labels
[]string
Optional labels to attach to the sprite.
​
sprite
*Sprite
Handle for the newly created sprite.
​
error
error
Non-nil on failure.

​
GetSprite

func (c *Client) GetSprite(ctx context.Context, name string) (*Sprite, error)
Fetches current information about a sprite from the API and returns a populated *Sprite.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name of the sprite to retrieve.
​
sprite
*Sprite
Sprite with all fields populated from the API response.
​
error
error
Non-nil on failure, including when the sprite is not found.

​
GetSpriteWithOrg

func (c *Client) GetSpriteWithOrg(ctx context.Context, name string, org *OrganizationInfo) (*Sprite, error)
Like GetSprite, but attaches organization information to the returned handle.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name of the sprite to retrieve.
​
org
*OrganizationInfo
Organization context to associate with the sprite handle.
​
sprite
*Sprite
Sprite with all fields populated from the API response.
​
error
error
Non-nil on failure.

​
ListSprites

func (c *Client) ListSprites(ctx context.Context, opts *ListOptions) (*SpriteList, error)
Retrieves a single page of sprites. Use ListAllSprites for automatic pagination.
​
ctx
context.Context
required
Context for the HTTP request.
​
opts
*ListOptions
Pagination and filter options. Defaults to 100 results if nil.
​
list
*SpriteList
Page of results.
​
error
error
Non-nil on failure.

​
ListAllSprites

func (c *Client) ListAllSprites(ctx context.Context, prefix string) ([]*Sprite, error)
Retrieves all sprites matching an optional prefix, following pagination automatically.
​
ctx
context.Context
required
Context for the HTTP requests.
​
prefix
string
required
Name prefix filter. Pass an empty string to list all sprites.
​
sprites
[]*Sprite
All matching sprites with fields populated from the API.
​
error
error
Non-nil on failure.

​
ListAllSpritesWithOrg

func (c *Client) ListAllSpritesWithOrg(ctx context.Context, prefix string, org *OrganizationInfo) ([]*Sprite, error)
Like ListAllSprites, but attaches organization context to every returned sprite handle.
​
ctx
context.Context
required
Context for the HTTP requests.
​
prefix
string
required
Name prefix filter.
​
org
*OrganizationInfo
Organization context to associate with each sprite handle.
​
sprites
[]*Sprite
All matching sprites.
​
error
error
Non-nil on failure.

​
ListAllSpritesResult

func (c *Client) ListAllSpritesResult(ctx context.Context, prefix string, org *OrganizationInfo) (*ListResult, error)
Like ListAllSpritesWithOrg, but also returns aggregate organization stats captured from the first page of results.
​
ctx
context.Context
required
Context for the HTTP requests.
​
prefix
string
required
Name prefix filter.
​
org
*OrganizationInfo
Organization context to associate with each sprite handle.
​
result
*ListResult
Contains the sprite slice and org stats.
​
error
error
Non-nil on failure.

​
DeleteSprite

func (c *Client) DeleteSprite(ctx context.Context, name string) error
Deletes the named sprite.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name of the sprite to delete.
​
error
error
Non-nil on failure.

​
DestroySprite

func (c *Client) DestroySprite(ctx context.Context, name string) error
Alias for DeleteSprite.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name of the sprite to destroy.
​
error
error
Non-nil on failure.

​
UpgradeSprite

func (c *Client) UpgradeSprite(ctx context.Context, name string) error
Upgrades the named sprite to the latest available version.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name of the sprite to upgrade.
​
error
error
Non-nil on failure.

​
UpdateSprite

func (c *Client) UpdateSprite(ctx context.Context, name string, req *UpdateSpriteRequest) error
Updates sprite settings such as URL authentication and labels.
​
ctx
context.Context
required
Context for the HTTP request.
​
name
string
required
Name of the sprite to update.
​
req
*UpdateSpriteRequest
required
Update payload.
​
error
error
Non-nil on failure.

​
UpdateURLSettings

func (c *Client) UpdateURLSettings(ctx context.Context, spriteName string, settings *URLSettings) error
Updates the URL authentication settings for a sprite.
​
ctx
context.Context
required
Context for the HTTP request.
​
spriteName
string
required
Name of the sprite.
​
settings
*URLSettings
required
URL authentication settings to apply.
​
error
error
Non-nil on failure.

​
Version

​
FetchVersion

func (c *Client) FetchVersion(ctx context.Context, spriteName string) error
Makes a lightweight HEAD request to capture the sprite server’s version from the Sprite-Version response header. Called automatically before attach operations when the version is unknown. The sprite name is required because each sprite may run a different version.
​
ctx
context.Context
required
Context for the HTTP request.
​
spriteName
string
required
Name of the sprite whose version to fetch.
​
error
error
Non-nil on failure.

​
SpriteVersion

func (c *Client) SpriteVersion() string
Returns the server version string captured from the most recent API response, or an empty string if no response has been observed yet.
​
returns
string
Server version string, or "" if unknown.

​
Lifecycle

​
Close

func (c *Client) Close() error
Closes the client and all pooled control connections. Call this when the client is no longer needed to release resources.
​
error
error
Always nil in the current implementation.
client := sprites.New(token)
defer client.Close()

Build docs developers (and LLMs) love

Get started for freeTalk to us