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 Sprites Go SDK exposes the Sprite’s filesystem through an FS interface that extends the standard io/fs package. You can use it directly with any Go code that accepts fs.FS, such as fs.WalkDir, while also having access to write operations that the standard library interfaces do not cover.

​
Getting an FS handle

Filesystem() returns an FS rooted at /. All relative paths are resolved from the filesystem root.
fsys := sprite.Filesystem()

​
The FS interface

FS satisfies several standard Go filesystem interfaces and adds write operations: 
type FS interface {
    fs.FS         // Open(name string) (fs.File, error)
    fs.StatFS     // Stat(name string) (fs.FileInfo, error)
    fs.ReadFileFS // ReadFile(name string) ([]byte, error)
    fs.ReadDirFS  // ReadDir(name string) ([]DirEntry, error)

    // Write operations
    WriteFile(name string, data []byte, perm fs.FileMode) error
    Mkdir(name string, perm fs.FileMode) error
    MkdirAll(path string, perm fs.FileMode) error
    Remove(name string) error
    RemoveAll(path string) error
    Rename(oldname, newname string) error
    Copy(src, dst string) error
    Chmod(name string, mode fs.FileMode) error

    // Context variants for long operations
    WriteFileContext(ctx context.Context, name string, data []byte, perm fs.FileMode) error
    RemoveContext(ctx context.Context, name string) error
    RemoveAllContext(ctx context.Context, path string) error
    CopyContext(ctx context.Context, src, dst string) error
    ChmodContext(ctx context.Context, name string, mode fs.FileMode) error
}
Because FS satisfies fs.FS, fs.StatFS, fs.ReadFileFS, and fs.ReadDirFS, you can pass a Sprite FS value anywhere those interfaces are accepted — including fs.WalkDir.

​
Reading files

​
Read a file’s bytes

data, err := fsys.ReadFile("config/app.toml")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(data))

​
Stat a file

info, err := fsys.Stat("config/app.toml")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("size=%d mode=%s\n", info.Size(), info.Mode())

​
List a directory

entries, err := fsys.ReadDir("logs")
if err != nil {
    log.Fatal(err)
}
for _, entry := range entries {
    fmt.Println(entry.Name(), entry.IsDir())
}

​
Walk the directory tree

Because FS satisfies fs.FS, you can use the standard library’s fs.WalkDir: 
err := fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
    if err != nil {
        return err
    }
    fmt.Println(path)
    return nil
})

​
Writing files

WriteFile creates or overwrites the named file. Pass the file permissions as a fs.FileMode. Parent directories are created automatically. 
content := []byte("hello from Go\n")
err := fsys.WriteFile("output/result.txt", content, 0644)
if err != nil {
    log.Fatal(err)
}
For large uploads or when you need cancellation support, use the context variant: 
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

err := fsys.WriteFileContext(ctx, "output/result.txt", content, 0644)
WriteFile always sets mkdirParents=true on the server request, so intermediate directories are created implicitly. You do not need to call MkdirAll before writing a file.

​
Creating directories

Creates a single directory. The parent directory must already exist.
err := fsys.Mkdir("output", 0755)

​
Deleting files and directories

Removes a single file or an empty directory.
err := fsys.Remove("output/old.log")
Use the context variant for cancellable operations:
err := fsys.RemoveContext(ctx, "output/old.log")
RemoveAll is irreversible. There is no recycle bin or undo on the Sprite filesystem.

​
Moving and copying

​
Rename (move)

err := fsys.Rename("output/draft.txt", "output/final.txt")
Rename works for both files and directories and can move across paths within the same filesystem.

​
Copy

Copy duplicates a file or directory. Directories are copied recursively. 
err := fsys.Copy("config/defaults.toml", "config/app.toml")
For large copies, use the context variant: 
err := fsys.CopyContext(ctx, "data/large-dataset", "data/large-dataset-backup")

​
Changing permissions

err := fsys.Chmod("scripts/deploy.sh", 0755)
Use the context variant when targeting many files or large directory trees: 
err := fsys.ChmodContext(ctx, "scripts/deploy.sh", 0755)

​
Complete example

The following example deploys a configuration file, verifies it was written, and then cleans up an old log directory: 
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    client := sprites.New("your-auth-token")
    sprite := client.Sprite("my-sprite")
    ctx := context.Background()

    fsys := sprite.FilesystemAt("/app")

    // Write a config file
    config := []byte(`{"debug": false, "port": 8080}`)
    if err := fsys.WriteFile("config.json", config, 0644); err != nil {
        log.Fatal(err)
    }

    // Verify it was written
    info, err := fsys.Stat("config.json")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Written: %s (%d bytes)\n", info.Name(), info.Size())

    // List the app directory
    entries, err := fsys.ReadDir(".")
    if err != nil {
        log.Fatal(err)
    }
    for _, e := range entries {
        fmt.Println(e.Name())
    }

    // Remove a stale log directory
    if err := fsys.RemoveAllContext(ctx, "logs/old"); err != nil {
        log.Fatal(err)
    }
}

​
Context variants reference

Every write operation that may be slow has a Context variant. Use these whenever you need timeout or cancellation support. 
WriteFileContext(ctx context.Context, name string, data []byte, perm fs.FileMode) error
Uploads data to the named path. Respects context cancellation.
RemoveContext(ctx context.Context, name string) error
Removes a file or empty directory with context support.
RemoveAllContext(ctx context.Context, path string) error
Recursively removes a path. Respects context cancellation.
CopyContext(ctx context.Context, src, dst string) error
Copies a file or directory tree. Always copies recursively.
ChmodContext(ctx context.Context, name string, mode fs.FileMode) error
Changes the permissions of the named file or directory.

Build docs developers (and LLMs) love

Get started for freeTalk to us