Getting started

rungrad is a Go framework for building CLIs and a rungrad binary for scaffolding and scoring them.

Install

Install the tool:

go install github.com/vincentsch/rungrad/cmd/[email protected]

Add the framework to an existing Go module:

go get github.com/vincentsch/[email protected]

If your shell cannot find rungrad

go install puts the executable in GOBIN, or in the first GOPATH entry’s bin directory when GOBIN is empty. Check those paths with:

go env GOBIN GOPATH

Add the install directory to your shell’s PATH. With the default Go settings on Linux or macOS, this makes it available in the current shell:

export PATH="$PATH:$(go env GOPATH)/bin"
rungrad --help

If you set GOBIN or use multiple GOPATH entries, use the install directory from those settings instead. Add the same directory to your shell startup file to keep it available in new terminals. On Windows, add it to your user Path environment variable and open a new terminal.

Scaffold a new CLI

rungrad new mytool
cd mytool
go mod tidy
go test ./...        # the generated tool's tests pass
go run . widget list
go run . widget list --json
go run . widget create gamma --dry-run
go run . widget delete alpha --dry-run
go run . update --check

rungrad new writes a project: go.mod, main.go, a widget resource, tests, a manifest endpoint, and a README. The generated commands show JSON output, dry-run previews, destructive-action confirmation, and an offline update command.

Scaffold flags:

• --module sets the Go module path.
• --dir chooses the parent directory.
• --dry-run shows the files without writing them.

Product profile

For a larger product CLI, generate the expanded scaffold:

rungrad new acmectl \
  --product-profile \
  --env-prefix ACME \
  --product-name "Acme Control" \
  --service api=https://api.example.invalid \
  --metadata-namespace example.com/acme \
  --surface host \
  --skill

--product-profile keeps the widget example but adds product identity, profile/auth-file/config resolution, service endpoints, manifest extensions, and release placeholders. --skill adds .agents/skills/acmectl/SKILL.md and .agents/README.md as repository-scoped agent starter files. The product-only flags are documented in the CLI reference.

Score a CLI against the spec

Point the scorer at any executable and tell it which commands exercise each behavior:

go build -o mytool .
rungrad score ./mytool \
  --read        "widget list" \
  --mutate      "widget create demo" \
  --destructive "widget delete alpha" \
  --update

The output is a per-section report and an overall score. If the target exposes a valid manifest, the scorer also checks fixture paths and command metadata. Add --json for a JSON score and --strict to fail CI when a required rule fails. Commands you do not provide are reported as not-applicable, not as failures.

See Conformance and the spec for the full flag list and scoring rules.

Next

• To build a CLI, read Building a CLI with rungrad.
• The worked reference tool is cmd/rgref in this repository; it scores 100% against the spec and is a good example to read.