Quick Start

Try It Without Installing

Run gbash directly with go run - no install required:

go run github.com/ewhauser/gbash/cmd/gbash@latest -c 'echo hello; pwd; ls -la'

You should see hello, the default working directory /home/agent, and the initial listing for the empty sandbox home directory.

Everything runs inside a virtual filesystem - nothing touches your host.

Go API

Use gbash.New to create a runtime and Run for one-shot execution:

package main
 
import (
	"context"
	"fmt"
 
	"github.com/ewhauser/gbash"
)
 
func main() {
	gb, err := gbash.New()
	if err != nil {
		panic(err)
	}
 
	result, err := gb.Run(context.Background(), &gbash.ExecutionRequest{
		Script: "echo hello\npwd\n",
	})
	if err != nil {
		panic(err)
	}
 
	fmt.Printf("exit=%d\n", result.ExitCode)
	fmt.Print(result.Stdout)
}

exit=0
hello
/home/agent

CLI Piping

Pipe a script into the gbash CLI:

printf 'echo hi\npwd\n' | gbash

hi
/home/agent

Interactive Mode

When stdin is a terminal, gbash starts an interactive shell automatically:

gbash

You can also force interactive mode explicitly:

printf 'pwd\ncd /tmp\npwd\nexit\n' | gbash -i

The interactive shell reuses one sandbox session and carries forward filesystem and environment state across commands. It exposes a session-local history command, but it does not provide readline-style line editing or job control.

Host-Backed CLI Runs

Mount a real project into the sandbox under a writable in-memory overlay:

gbash --root /path/to/project --cwd /home/agent/project -c 'pwd; ls'

--root mounts the host directory read-only at /home/agent/project. Writes stay inside the sandbox overlay, so the host tree is not mutated.

JSON Output

Non-interactive runs can emit a single structured result object:

gbash -c 'echo hello' --json

The JSON payload includes stdout, stderr, exitCode, truncation flags, timing metadata, and trace metadata when tracing is enabled by the wrapper.

Extras CLI

Install gbash-extras when you want the stable official contrib commands (awk, html-to-markdown, jq, sqlite3, and yq) pre-registered:

go install github.com/ewhauser/gbash/contrib/extras/cmd/gbash-extras@latest
gbash-extras -c 'jq -r .name data.json'

See Contrib Commands for the Go modules behind the extras registry.