cmder

package module
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2026 License: MIT Imports: 12 Imported by: 2

README

cmder

CI Status Go Report Card Docs

Go package for executing external commands with retries, timeouts, and output collection.

Features

  • Attempt timeouts - Kill commands that run too long
  • Total timeouts - Limit total time including retries
  • Automatic retries - Retry on timeout with configurable filters
  • Output collection - Capture stdout, stderr, and combined output
  • Reset timeout on output - Keep alive commands that produce output
  • Fluent API - Builder pattern for clean configuration

Installation

go get github.com/GiGurra/cmder

Quick Start

result := cmder.New("ls", "-la").
    WithAttemptTimeout(5 * time.Second).
    WithRetries(3).
    Run(context.Background())

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

Common Patterns

Command with timeout
result := cmder.New("slow-command").
    WithAttemptTimeout(30 * time.Second).
    Run(ctx)
Retry on failure
result := cmder.New("flaky-service").
    WithRetries(5).
    WithAttemptTimeout(10 * time.Second).
    Run(ctx)
Keep alive on output
// Timeout resets each time command produces output
result := cmder.New("long-running-task").
    WithAttemptTimeout(5 * time.Second).
    WithResetAttemptTimeoutOnOutput(true).
    Run(ctx)
Stream output while running
result := cmder.New("build-script").
    WithStdOutErrForwarded().  // Print to terminal
    Run(ctx)
Custom retry logic
result := cmder.New("api-call").
    WithRetries(3).
    WithRetryFilter(func(err error, isTimeout bool) bool {
        return isTimeout  // Only retry timeouts
    }).
    Run(ctx)

API

See the API documentation for full details.

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultRetryFilter 

func DefaultRetryFilter(err error, isAttemptTimeout bool) bool

func TimeoutRetryFilter 

func TimeoutRetryFilter(err error, isAttemptTimeout bool) bool

TimeoutRetryFilter is a simple retry policy that retries on timeouts only

Types

type Result 

type Result struct {
	StdOut   string
	StdErr   string
	Combined string
	Err      error
	Attempts int
	ExitCode int
}

type Spec 

type Spec struct {

	// Minimum input
	App  string
	Args []string

	// Extra options
	WorkingDirectory            string
	AttemptTimeout              time.Duration
	TotalTimeout                time.Duration
	ResetAttemptTimeoutOnOutput bool
	Retries                     int
	RetryFilter                 func(err error, isAttemptTimeout bool) bool

	// Input/Output
	StdIn            io.Reader
	StdOut           io.Writer // if capturing output while running
	StdErr           io.Writer // if capturing output while running
	CollectAllOutput bool      // if running for a very long time, set this false to avoid OOM

	// debug functionality
	Verbose bool
}

func New 

func New(appAndArgs ...string) Spec

func NewA 

func NewA(app string, args ...string) Spec

func (Spec) Run 

func (c Spec) Run(ctx context.Context) Result

func (Spec) WithApp 

func (c Spec) WithApp(app string) Spec

WithApp sets the application to run

func (Spec) WithArgs 

func (c Spec) WithArgs(newArgs ...string) Spec

WithArgs sets the arguments for the command

func (Spec) WithAttemptTimeout 

func (c Spec) WithAttemptTimeout(timeout time.Duration) Spec

WithAttemptTimeout sets the timeout for the command This is the total time the command can run, per attempt

func (Spec) WithCmd added in v0.0.2 

func (c Spec) WithCmd(app string, args ...string) Spec

WithCmd sets the application and arguments for the command

func (Spec) WithCollectAllOutput 

func (c Spec) WithCollectAllOutput(collect bool) Spec

WithCollectAllOutput sets whether to collect all output. Default is true. If false, you need to inject your own io.Writer

func (Spec) WithExtraArgs 

func (c Spec) WithExtraArgs(extraArgs ...string) Spec

WithExtraArgs appends the arguments to the command

func (Spec) WithResetAttemptTimeoutOnOutput 

func (c Spec) WithResetAttemptTimeoutOnOutput(enabled bool) Spec

WithResetAttemptTimeoutOnOutput resets the timeout if output is received from the command

func (Spec) WithRetries 

func (c Spec) WithRetries(n int) Spec

WithRetries sets the number of retries before giving up

func (Spec) WithRetryFilter 

func (c Spec) WithRetryFilter(filter func(err error, isAttemptTimeout bool) bool) Spec

WithRetryFilter sets the retry filter

func (Spec) WithStdErr 

func (c Spec) WithStdErr(writer io.Writer) Spec

WithStdErr sets the standard error for the command

func (Spec) WithStdErrForwarded 

func (c Spec) WithStdErrForwarded() Spec

func (Spec) WithStdIn 

func (c Spec) WithStdIn(reader io.Reader) Spec

WithStdIn sets the standard input for the command

func (Spec) WithStdInForwarded 

func (c Spec) WithStdInForwarded() Spec

WithStdInForwarded sets the standard input to os.Stdin

func (Spec) WithStdOut 

func (c Spec) WithStdOut(writer io.Writer) Spec

WithStdOut sets the standard output for the command

func (Spec) WithStdOutErrForwarded 

func (c Spec) WithStdOutErrForwarded() Spec

func (Spec) WithStdOutForwarded 

func (c Spec) WithStdOutForwarded() Spec

func (Spec) WithTotalTimeout 

func (c Spec) WithTotalTimeout(timeout time.Duration) Spec

WithTotalTimeout sets the total timeout for the command including retries

func (Spec) WithVerbose 

func (c Spec) WithVerbose(verbose bool) Spec

WithVerbose sets the verbose flag

func (Spec) WithWorkingDirectory 

func (c Spec) WithWorkingDirectory(wd string) Spec

WithWorkingDirectory sets the working directory for the command

Source Files

View all Source files

Directories

Path Synopsis
internal
util

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.