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 Cmd type represents a command to be run on a sprite. Its API mirrors os/exec.Cmd for familiarity: set fields to configure the command, then call Run to execute it synchronously, Start/Wait for asynchronous control, or Output/CombinedOutput to capture output. Obtain a *Cmd by calling sprite.Command or sprite.CommandContext. You can also attach to an existing session with sprite.AttachSession.

​
Fields

​
Path
string
Path or name of the command to run (e.g., "python", "/usr/bin/node"). Set automatically by sprite.Command.
​
Args
[]string
Command-line arguments including the command as Args[0]. Set automatically by sprite.Command.
​
Env
[]string
Environment variables for the process in "KEY=VALUE" form. If nil, the process uses the current environment.
​
Dir
string
Working directory for the command. If empty, the command runs in the sprite’s default directory.
​
Stdin
io.Reader
Standard input for the process. If nil, the process reads from the null device. Set before calling Start; use StdinPipe for streaming input.
​
Stdout
io.Writer
Standard output destination. If nil, output goes to the null device. Set before calling Start; use StdoutPipe for streaming output.
​
Stderr
io.Writer
Standard error destination. If nil, output goes to the null device. Set before calling Start; use StderrPipe for streaming error output.
​
TextMessageHandler
func([]byte)
Optional callback invoked when text (out-of-band) messages are received from the server, such as port-open/close notifications. The handler receives the raw JSON message bytes.
cmd.TextMessageHandler = func(data []byte) {
    var n sprites.PortNotificationMessage
    if err := json.Unmarshal(data, &n); err != nil {
        return
    }
    switch n.Type {
    case "port_opened":
        fmt.Printf("Port %d opened by PID %d\n", n.Port, n.PID)
    case "port_closed":
        fmt.Printf("Port %d closed by PID %d\n", n.Port, n.PID)
    }
}

​
Execution

​
Run

func (c *Cmd) Run() error
Starts the command and waits for it to complete. Equivalent to calling Start followed by Wait. Returns a *ExitError if the command exits with a non-zero status.
​
error
error
Nil on success. *ExitError if the process exited with a non-zero code. Other errors for connection or I/O failures.
err := sprite.Command("npm", "install").Run()
if err != nil {
    log.Fatal(err)
}

​
Start

func (c *Cmd) Start() error
Starts the command but does not wait for it to finish. Call Wait to collect the result. Returns an error if the command has already been started. Pipes must be set up before calling Start.
​
error
error
Non-nil if the command could not be started or has already been started.

​
Wait

func (c *Cmd) Wait() error
Waits for the command to exit and for any I/O goroutines (stdin/stdout/stderr copying) to complete. Must be called after Start. Returns ErrNotStarted if Start was never called.
​
error
error
Nil on success. *ExitError for non-zero exit codes. ErrNotStarted if Start was not called. "connection closed" if the remote connection was lost.

​
Output

func (c *Cmd) Output() ([]byte, error)
Runs the command and returns its standard output as a byte slice. Returns an error if Stdout has already been set.
​
output
[]byte
Captured standard output.
​
error
error
Non-nil on failure. *ExitError for non-zero exit codes.
out, err := sprite.Command("cat", "/etc/os-release").Output()
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(out))

​
CombinedOutput

func (c *Cmd) CombinedOutput() ([]byte, error)
Runs the command and returns its combined standard output and standard error. Returns an error if either Stdout or Stderr has already been set.
​
output
[]byte
Interleaved standard output and standard error.
​
error
error
Non-nil on failure.

​
Pipes

​
StdinPipe

func (c *Cmd) StdinPipe() (io.WriteCloser, error)
Returns a pipe connected to the command’s standard input. Must be called before Start. Returns an error if Stdin is already set or the command has started.
​
pipe
io.WriteCloser
Write end of the stdin pipe. Close it to signal EOF to the process.
​
error
error
Non-nil if Stdin is already set or the command has already started.
cmd := sprite.Command("python", "-c", "import sys; print(sys.stdin.read())")
stdin, err := cmd.StdinPipe()
if err != nil {
    log.Fatal(err)
}
cmd.Stdout = os.Stdout
if err := cmd.Start(); err != nil {
    log.Fatal(err)
}
fmt.Fprintln(stdin, "hello from Go")
stdin.Close()
cmd.Wait()

​
StdoutPipe

func (c *Cmd) StdoutPipe() (io.ReadCloser, error)
Returns a pipe connected to the command’s standard output. Must be called before Start. Returns an error if Stdout is already set or the command has started.
​
pipe
io.ReadCloser
Read end of the stdout pipe.
​
error
error
Non-nil if Stdout is already set or the command has already started.

​
StderrPipe

func (c *Cmd) StderrPipe() (io.ReadCloser, error)
Returns a pipe connected to the command’s standard error. Must be called before Start. Returns an error if Stderr is already set or the command has started.
​
pipe
io.ReadCloser
Read end of the stderr pipe.
​
error
error
Non-nil if Stderr is already set or the command has already started.

​
TTY

​
SetTTY

func (c *Cmd) SetTTY(enable bool)
Enables or disables TTY (pseudo-terminal) mode for the command. Must be called before Start. Panics if called after the process has started.
​
enable
bool
required
Pass true to run the command with a PTY attached.
cmd := sprite.Command("bash")
cmd.SetTTY(true)
cmd.Stdin = os.Stdin
cmd.Stdout = os.Stdout
if err := cmd.Start(); err != nil {
    log.Fatal(err)
}
cmd.Wait()

​
SetTTYSize

func (c *Cmd) SetTTYSize(rows, cols uint16) error
Sets the terminal dimensions. If called before Start, sets the initial size. If called after Start while the process is running, resizes the live terminal. Requires TTY mode to be enabled with SetTTY(true).
​
rows
uint16
required
Terminal height in rows.
​
cols
uint16
required
Terminal width in columns.
​
error
error
Non-nil if TTY mode is not enabled or the command is not initialized.

​
Resize

func (c *Cmd) Resize(rows, cols uint16) error
Deprecated. Use SetTTYSize instead, which works both before and after Start.
Resizes the terminal of a running TTY command. Must be called after Start and before the command exits.
​
rows
uint16
required
New terminal height in rows.
​
cols
uint16
required
New terminal width in columns.
​
error
error
Non-nil if the command has not started, TTY mode is not enabled, or the command has finished.

​
Signals

​
Signal

func (c *Cmd) Signal(signal string) error
Sends a signal to the remote process. If the server advertises WebSocket signal support via the X-Sprite-Capabilities header, the signal is sent over the existing WebSocket. Otherwise it falls back to an HTTP POST. Must be called after Start and before the process exits. Valid signal names: INT, TERM, HUP, KILL, QUIT, USR1, USR2.
​
signal
string
required
Signal name to send (e.g., "TERM", "INT").
​
error
error
Non-nil if the command has not started, has already finished, or no session ID is available for the HTTP fallback.
if err := cmd.Signal("TERM"); err != nil {
    log.Printf("signal failed: %v", err)
}

​
Inspection

​
ExitCode

func (c *Cmd) ExitCode() int
Returns the exit code of the process. Returns -1 if the process has not yet exited or was terminated abnormally.
​
returns
int
Exit code, or -1 if not yet exited.

​
ConnectionMode

func (c *Cmd) ConnectionMode() string
Returns the connection mode used by this command after Start has been called. Returns "control" for multiplexed control connections, "direct" for per-request WebSocket connections, or "" if Start has not been called yet.
​
returns
string
"control", "direct", or "".

​
String

func (c *Cmd) String() string
Returns a human-readable description of the command intended for debugging (e.g., "python [-c print(2+2)]"). Returns "<nil>" if called on a nil pointer.
​
returns
string
Human-readable command description.

​
Error types

​
ExitError

type ExitError struct {
    Code int
}
Returned by Run, Wait, Output, and CombinedOutput when the command exits with a non-zero status.
​
Code
int
The exit status code from the remote process.
Methods: 
func (e *ExitError) Error() string
Returns a string of the form "exit status N". 
func (e *ExitError) ExitCode() int
Returns e.Code. 
out, err := sprite.Command("false").Output()
var exitErr *sprites.ExitError
if errors.As(err, &exitErr) {
    fmt.Printf("exited with code %d\n", exitErr.ExitCode())
}

​
ErrNotStarted

var ErrNotStarted = errors.New("sprite: command not started")
Returned by Wait when called before Start.

Build docs developers (and LLMs) love

Get started for freeTalk to us