api.go

This page maps the parts of the runtime you use in main.go, in handlers and in tests. Every type and method is documented in full on pkg.go.dev.

In main.go

main.go builds the program with the generated NewProgram(), configures it and calls Execute. The generated NewProgram calls rotini.NewWiredProgram with the runtime features its spec uses:

func main() {
	cmd.NewProgram().
		WithDependency(cmd.Store, openStore()). // something your handlers share
		WithVersion(version).                   // what rtx.Version() returns
		Execute()                               // runs the command, then exits with its code
}

A dependency is declared once in the generated package’s directory, next to your handlers, and read in any hook:

var Store = rotini.NewDependency[*store.Store]("todo.store")

In a handler

Each command’s handler has five hooks, which run in this order:

CascadingPreRun → PreRun → Run → PostRun → CascadingPostRun

PreRun, Run and PostRun run only for the command that was invoked. A command’s cascading hooks also run when any command beneath it is invoked: CascadingPreRun from the root down, CascadingPostRun from the invoked command back up. So a parent can set up what its sub-commands need and tear it down afterward. The teardown hooks, PostRun and CascadingPostRun, run even after a halt or a panic, for exactly the hooks whose setup ran.

A generated handler embeds rotini.NoCascadingPreRun, rotini.NoPreRun, rotini.NoPostRun and rotini.NoCascadingPostRun, which do nothing. To use a hook, declare the method on your handler type.

Every hook receives a *rotini.Context, conventionally named rtx:

func (*todoAddHandler) Run(ctx context.Context, rtx *rotini.Context) {
	in, err := rtx.Inputs[TodoAddInputs]()
	if err != nil {
		rtx.HaltWith(err)
		return
	}
	if err := rtx.MustGetDependency(Store).Add(in.TodoAdd.Arguments.Title); err != nil {
		rtx.HaltWith(err)
		return
	}
	rtx.RecordSuccess("task added")
}

Stopping

Each call stops the hooks that have not started yet; it does not end the function you call it from, so return after it. The first non-zero exit code set wins.

Errors

By default each recorded error is printed to stderr as Error: …, each warning as Warning: …, and the program exits 1 when anything failed, unless a handler already set a non-zero code.

Mark an error as the user’s to fix with rotini.UsageError(err), or as a fault in the program with rotini.InternalError(err). An unknown flag or a bad value is already a usage error. rotini.CategoryOf(err) returns rotini.CategoryUsage, rotini.CategoryInternal or rotini.CategoryNone, so a custom reporter can map each to its own exit code.

A custom reporter is a rotini.Reporter, func(ctx context.Context, rtx *rotini.Context, out rotini.Outcome), installed with Program.WithReporter. It replaces the default entirely: it prints only what it prints, and sets the exit code with rtx.Exit, so a failed run exits 0 unless it does. The guide has a complete one. For scripts, rotini.StructuredReporter writes each outcome to stderr as one JSON object per line.

errors.Is(err, rotini.ErrUsage) and errors.Is(err, rotini.ErrInternal) test the same categories, and rotini.ErrDependencyNotFound is what a *rotini.DependencyError unwraps to. The error types are *rotini.ParseError (the command line and validation, with a Kind), *rotini.InputError (environment, config files and stdin), *rotini.PluginError, *rotini.WiringError, *rotini.DependencyError and *rotini.PanicError; reach them with errors.As. rotini.SuggestionFacts(err) returns the word the user typed and what it could have been, and rotini.NewSuggestor().For(err) ranks them; see suggesting a correction. To end a run with your own code from outside its hooks, cancel its context with rotini.ExitCause(code); see signals and cancellation.

Testing

Run a program in-process and check its exit code, error and output:

func TestAdd(t *testing.T) {
	var out bytes.Buffer
	code, err := NewProgram().WithStdout(&out).Run([]string{"add", "buy milk"})
	if err != nil || code != 0 {
		t.Fatalf("code %d, err %v", code, err)
	}
}

Build a fresh program per test with NewProgram(), as main.go does. Run never calls os.Exit, and the error it returns joins every recorded error, so errors.Is and errors.As reach each one; see handling errors in a handler for branching on them.

To test a single hook or the input parsing without the generated program, rotini.NewContextFor builds a context from a rotini.Definition you write in the test. A Definition is the runtime form of the command tree rotini generate produces from your spec. Building one by hand is supported for tests and for tooling; it is not a way to define a CLI, which the spec is. Fields are added as the spec gains keys, including in minor releases, so write them with field names (rotini.FlagDef{Name: "verbose"}), not positionally. Context.WithStdin, WithStdout, WithStderr, WithEnviron, WithDir, WithClock and WithOutputChecks set up such a context.

rotinitest.Run runs a command from its generated inputs type, each run with its own environment and directory, so tests can run in parallel. rotinitest.Output decodes stdout against the output schema, and rotinitest.ExitDocumented checks the exit code against exit_status; see testing with typed inputs. Underneath, rotini.ArgvOf turns an inputs value into argv and env, and Program.Definition returns the command tree it reads.

DecodeOutput[T](p, stdout, format) reads captured output back into the command’s output type, checking it against the declared shape.

Other packages

Both are opt-in: a program that doesn’t import them links none of their code.

Building blocks

Generated code and most programs never need these, but they are supported: