Skip to content

Getting Started

Installation

go get github.com/GiGurra/cmder

Basic Usage

The simplest way to run a command:

import "github.com/GiGurra/cmder"

result := cmder.New("ls", "-la").Run(context.Background())

if result.Err != nil {
    fmt.Printf("Error: %v\n", result.Err)
} else {
    fmt.Printf("Output:\n%s", result.StdOut)
}

Creating Commands

cmder.New() accepts the command and arguments:

// Command with arguments
cmder.New("git", "status", "--short")

// Just the command
cmder.New("pwd")

Alternatively, use cmder.NewA() for explicit separation:

cmder.NewA("git", "status", "--short")

Builder Pattern

All configuration methods return a new Spec, enabling chaining:

result := cmder.New("make", "build").
    WithWorkingDirectory("/path/to/project").
    WithAttemptTimeout(5 * time.Minute).
    WithVerbose(true).
    Run(ctx)

Result Structure

The Result struct contains:

type Result struct {
    StdOut   string  // Captured stdout
    StdErr   string  // Captured stderr
    Combined string  // Interleaved stdout + stderr
    Err      error   // Error if command failed
    Attempts int     // Number of attempts made
    ExitCode int     // Exit code (0 for success)
}

Working Directory

Set where the command runs:

result := cmder.New("npm", "install").
    WithWorkingDirectory("/path/to/project").
    Run(ctx)

Standard Input

Provide input to the command:

result := cmder.New("cat").
    WithStdIn(strings.NewReader("hello world")).
    Run(ctx)

// result.StdOut == "hello world"

Verbose Mode

Enable logging of command execution:

result := cmder.New("build.sh").
    WithVerbose(true).
    Run(ctx)

This logs the working directory, command, and retry information.

Reusable Templates

Since Spec is immutable, you can create templates:

// Create a template
gitCmd := cmder.New("git").
    WithAttemptTimeout(30 * time.Second).
    WithRetries(2)

// Use it for different operations
gitCmd.WithArgs("status").Run(ctx)
gitCmd.WithArgs("pull").Run(ctx)
gitCmd.WithArgs("push").Run(ctx)

Next Steps