invoke

invoke

A Go library for running commands across Local, SSH, and Docker environments using a single interface.

Instead of writing separate logic for os/exec, crypto/ssh, and the Docker SDK, write it once and swap the provider.

Install

go get github.com/ruffel/invoke

Providers are separate modules:

go get github.com/ruffel/invoke/providers/local
go get github.com/ruffel/invoke/providers/ssh
go get github.com/ruffel/invoke/providers/docker

Support

invoke is currently being hardened as a POSIX-focused library.

• supported host environments for this cycle: Linux and macOS
• first-party providers in scope: Local, SSH, Docker
• primary target assumptions: POSIX-style shells, Unix-like process semantics, Linux containers
• out of scope for this cycle: Windows support and new first-party backends
• first-party providers are expected to support documented features or return ErrNotSupported explicitly

Getting Started

Every provider implements invoke.Environment — the basic non-interactive execution examples below work with any of them. Provider-specific caveats (TTY, signals, file transfer details) are documented in docs/provider-caveats.md.

Usage

Run a command

env, err := local.New()
if err != nil {
    return err
}
defer env.Close()

exec := invoke.NewExecutor(env)
result, err := exec.RunBuffered(ctx, &invoke.Command{Cmd: "uptime"})
if err != nil {
    return err
}
fmt.Println(string(result.Stdout))

Commands are argv-style by default. Use RunShell or ShellCommand only when you need shell features such as pipes, redirects, globbing, or variable expansion.

Shell one-liners

result, err := exec.RunShell(ctx, "ls -la | grep foo")

Or construct the command directly:

cmd := invoke.ShellCommand("cat /etc/os-release | head -5")
result, err := exec.RunBuffered(ctx, cmd)

Stream output

cmd := &invoke.Command{
    Cmd:    "make",
    Args:   []string{"build"},
    Stdout: os.Stdout,
    Stderr: os.Stderr,
}

_, err := env.Run(ctx, cmd)

Live line-by-line streaming

err := exec.RunLineStream(ctx, &invoke.Command{Cmd: "deploy"}, func(line string) {
    log.Println(line)
})

RunBuffered keeps stdout and stderr in memory. For long-running commands or unbounded output, stream to writers or use RunLineStream for stdout-only line logs.

SSH

env, err := ssh.New(
    ssh.WithHost("10.0.0.1"),
    ssh.WithUser("deploy"),
    ssh.WithKeyPath("/home/deploy/.ssh/id_ed25519"),
    ssh.WithDefaultKnownHosts(),
)
if err != nil {
    // handle error
}
defer env.Close()

// Same API as local
exec := invoke.NewExecutor(env)
result, err := exec.RunBuffered(ctx, &invoke.Command{Cmd: "uptime"})

For testing only, you can disable host key checking (not recommended for production):

env, err := ssh.New(
    ssh.WithHost("10.0.0.1"),
    ssh.WithUser("deploy"),
    ssh.WithPassword("secret"),
    ssh.WithInsecureSkipVerify(true),
)

Docker

env, err := docker.New(docker.WithContainerID("my-app"))
if err != nil {
    return err
}
defer env.Close()

result, err := env.Run(ctx, &invoke.Command{Cmd: "cat", Args: []string{"/etc/os-release"}})

Sudo

exec.Run(ctx, cmd, invoke.WithSudo())

// With options
exec.Run(ctx, cmd, invoke.WithSudo(
    invoke.WithSudoUser("postgres"),
    invoke.WithSudoPreserveEnv(),
))

Sudo is intentionally non-interactive (sudo -n). Configure passwordless sudo or run a TTY session yourself if the target command expects prompts.

File transfers

// Upload with permissions
env.Upload(ctx, "./configs/nginx", "/etc/nginx", invoke.WithPermissions(0o644))

// Download
env.Download(ctx, "/var/log/app.log", "./app.log")

Interactive TTY

cmd := invoke.ShellCommand("bash")
exec.RunInteractiveTTY(ctx, cmd)

Retry on transport errors

result, err := exec.Run(ctx, cmd, invoke.WithRetry(3, time.Second))

Error Model

invoke distinguishes between two failure modes:

• ExitError — the command ran but exited non-zero. Contains the exit code. Stderr is populated when using RunBuffered. Not retryable — this is a definitive result.
• TransportError — the underlying transport failed (connection lost, daemon unreachable). Retryable via WithRetry.

_, err := exec.RunBuffered(ctx, cmd)
if err != nil {
    var exitErr *invoke.ExitError
    if errors.As(err, &exitErr) {
        fmt.Printf("exit code %d: %s\n", exitErr.ExitCode, exitErr.Stderr)
    }
}

When Wait() returns an error, the *Result is still populated with the exit code and duration.

Design

• Streaming-first — interfaces use io.Reader and io.Writer, not buffers
• Context-aware — all blocking operations respect context.Context
• Secure defaults — SSH host key checking is enforced; you must explicitly opt out
• Provider-agnostic — write once, deploy to local, SSH, or Docker

License

MIT