Preview with --dry-run
Mutating commands take --dry-run and print the change they would make, with secrets masked.
$ ./hello widget create gamma --dry-run DRY RUN: would POST /widgets body: name = gamma token = *** no changes were made
rungrad
A Go framework and spec for CLIs used in terminals, scripts, and CI.
Each command has text output for people, stable --json for programs, --dry-run before changes, confirmation before destructive actions, stable exit codes, and help text with examples.
$ go install github.com/vincentsch/rungrad/cmd/[email protected]
- MIT license
- v0.2.1
- Go 1.22.2+
- GitHub
Documentation
- Getting startedInstall, scaffold a CLI, score a CLI
- Building a CLI with rungradThe framework guide for tool authors
- Migrating from CobraPort an existing Cobra CLI without changing its public surface
- Config and auth referenceProfiles, auth files, services, and credential hooks
- Conformance and the specThe agent-ready spec and the scorer
- Machine manifestThe hidden manifest protocol
- CLI referenceThe rungrad command: score and new
Proof in your terminal
$ rungrad new hello
Created hello
$ cd hello && go mod tidy && go test ./...
ok example.com/hello 0.006s
$ go build -o hello .
$ ./hello widget delete alpha --dry-run
DRY RUN: would DELETE /widgets/alpha
no changes were made
$ rungrad score ./hello --read "widget list" \
--mutate "widget create demo" \
--destructive "widget delete alpha" --update
Conformance against rungrad-spec/1
100% weighted
15/15 applicable rules passed, 22 total rules
[PASS]output.json-parseableread --json emitted valid JSON
[PASS]exit.unknown-usageunknown subcommand exited 1
[PASS]dryrun.no-side-effects--dry-run emitted a preview
[PASS]determinism.stable-sortlist order stable across runs
[PASS]help.examples--help contains a manifest example
[n/a ]exit.not-foundno not-found command configured
$
Captured from rungrad v0.2.1 and the starter that rungrad new generates.
What rungrad covers
Preview with
Text and JSON from one result
A command renders its result for people or as stable --json for programs. Both forms come from the same value.
$ ./hello widget list ID Name 1 alpha 2 beta $ ./hello widget list --json [ { "id": "1", "name": "alpha" }, ...
Stable exit codes
Scripts and agents branch on the exit code instead of parsing text. Destructive commands refuse to act without confirmation.
$ ./hello widget delete alpha --no-prompt Error: destructive action requires --confirm exit code 1 $ ./hello widget delete alpha --confirm Deleted widget alpha exit code 0
rungrad also covers name-to-ID resolution, a hidden manifest for tools that inspect a CLI, and helpers for generated command docs. The spec stands on its own: a CLI written in any language can follow it and be checked with rungrad score. Conformance and the spec