sho

将 (Shō)

A simple, extensible task runner for automating workflows with Go.

Features

• Simple task registration
• Multiple task types, commands, shell or Go functions
• Selective execution, run tasks by name, by tag, or mix and match
• Support for interactive commands, proxies stdin/stdout/stderr for interactive prompts (like sudo passwords)
• Type-safe, IDE support, tools - it's Go all the way down
• Run tasks sequentially or in parallel
• Binary caching, compiled task binaries are cached so repeated runs skip the Go toolchain entirely
• User global tasks in addition to per-project tasks
• Auto-resolution, sho walks up to the VCS root to find the nearest tasks/ directory

Quick Start

Install the sho CLI tool:

go install codeberg.org/zerodeps/sho/cmd/sho@latest

Scaffold a tasks directory in your project:

sho --init

This creates a tasks/ directory with its own go.mod that imports the sho library, plus a starter tasks.go template. Edit tasks/tasks.go to define your tasks, then run them:

sho           # list all tasks
sho hello     # run the "hello" task
sho -a        # run all tasks

The sho CLI provides quality-of-life tooling for working with the task runner, e.g. it auto-resolves the nearest tasks/ directory, compiles it on first use, and caches the binary so subsequent runs are instant:

sho [flags] [task|tag...]     Run tasks in the nearest tasks directory
sho -g [flags] [task|tag...]  Run tasks in the global tasks directory
sho --init                    Scaffold a tasks directory
sho --clean [-g]              Remove cached binary for the resolved tasks directory
sho --purge                   Remove all cached task binaries

sho --init scaffolds a tasks/ directory in the current project:

• Always writes tasks/go.mod
• Downloads the latest tasks/main.go entry-point and a starter tasks/tasks.go template (skipped if one already exists)

To reset a template file, delete it and re-run sho --init

Tasks directory resolution

When you run sho, it finds the tasks directory to use as follows:

1. If -g/--global is set, use the user global directory (~/.config/sho/tasks/ on Linux, platform-specific elsewhere).
2. Otherwise, walk up from the current directory to the nearest VCS root (.git, .hg, .svn, etc.) and find the nearest tasks/ subdirectory.
3. If no VCS root is found, check for tasks/ in the current directory only.
4. Fall back to the global user directory if no local directory is found.

Usage

Registering Tasks

Tasks are defined in one or more .go files and registered in each file's init() function:

// tasks.go
package main

func init() {
    Register(
        // Shell command task (uses sh -l -c, supports shell syntax)
        Task{
            Name:        "apt-update",
            Description: "Update APT packages",
            Command:     ShellCommand{"sudo apt update && sudo apt upgrade -y"},
            Tags:        []string{"system"},
        },
        // Go function task
        Task{
            Name:        "custom",
            Description: "Custom task",
            Command: FuncCommand{func(ctx context.Context) error {
                // Your custom Go code here
                return nil
            }},
        },
    )
}

Task, ExecCommand, ShellCommand, FuncCommand, and Register are provided as aliases in the generated main.go so task files need no extra imports.

See the examples folder.

Running Tasks

sho [flags] [name...]

Each positional name is resolved using the following logic:

1. If the name matches a registered task, that task is run.
2. Otherwise, if it matches a registered tag, all tasks carrying that tag are run.
3. If it matches neither, an error is returned.

Use flags to skip the fallback and enforce a specific interpretation:

# Smart resolution: runs "build" task, then expands "ci" tag
sho build ci

# Force task-only: error if "ci" is not a task name
sho --task ci

# Force tag-only: error if "build" is not a tag name
sho --tag build

Task Types

Exec Commands

ExecCommand runs an external program directly, without a shell. Arguments are passed verbatim — no shell expansion, globbing, or variable substitution. This is the safest choice when you do not need shell features and cannot trust input.

Register(Task{
    Name:        "hello",
    Description: "Say hello",
    Command:     ExecCommand{"echo", "Hello, World!"},
})

Shell Commands

ShellCommand passes a single string to sh -c, giving you full shell syntax: &&, ||, pipes, redirections, variable expansion, and globbing. Environment variables from the calling process (including $PATH) are available to the shell.

Register(Task{
    Name:        "update",
    Description: "Update packages",
    Command:     ShellCommand{"apt update && apt upgrade -y"},
})

Security note: because the string is passed directly to the shell, interpolating untrusted user input creates a shell-injection risk. Use ExecCommand when you need to pass user-supplied values as arguments.

Go Functions

FuncCommand wraps any Go function as a task. The function receives a context.Context for cancellation awareness.

Register(Task{
    Name:        "complex",
    Description: "Complex task",
    Command: FuncCommand{func(ctx context.Context) error {
        // Complex logic here
        fmt.Println("Doing something complex")
        return nil
    }},
})

Environment Filtering

By default, tasks inherit the full environment of the calling process. The Env field on a Task restricts which variables are passed to spawned subprocesses: only the listed variable names are looked up from the current process and forwarded.

Register(Task{
    Name:        "deploy",
    Description: "Deploy to production",
    Command:     ShellCommand{"./deploy.sh"},
    Env:         []string{"PATH", "HOME", "CI_TOKEN"},
})

• Env: nil (or omitted) — subprocess inherits the full environment (default).
• Env: []string{"PATH", "HOME"} — subprocess receives only PATH and HOME.
• Env: []string{"NONE"} — by convention, passes an empty environment (NONE is not a real variable, so nothing is forwarded).

This mechanism is provided to restrict commands from accessing sensitive variables, like API secrets. There will be no support for setting environment variables values directly in task files to guarantee their safety for storing in VCS and share.

Note: Env filtering applies to ExecCommand and ShellCommand. A FuncCommand runs in-process and has access to os.Environ() regardless.

How It Works

1. Resolution — sho locates the nearest tasks/ directory by walking up to the VCS root, falling back to the global directory.
2. Build & cache — on first run, sho compiles the tasks directory into a binary and caches it. Subsequent runs skip the Go toolchain entirely.
3. Initialization — all init() functions in the tasks binary run before main(), registering tasks with the default runner.
4. Filtering — main() resolves names to tasks: positional args match task names first, then tag names. --task enforces task-only lookup; --tag/-t enforces tag-only lookup.
5. Execution — the task selection is passed to a Runner to run sequentially or in parallel.
6. Error handling — failed tasks are captured and reported; execution continues with remaining tasks.

License

EUPL v1.2