Using rotini

This guide builds todo, a small task CLI, from install to tests, covers what you need to write your own rotini program, and gives recipes for common tasks. The quick start is the short version; the spec and conf references list every key.

Install

Rotini is one module with two parts: the tool that generates your code and the runtime package that code imports. Add the tool as a tool dependency, so everyone working on the project runs the same version through go.mod:

mkdir todo
cd todo
go mod init github.com/me/todo
go get -tool github.com/go-rotini/rotini/cmd/rotini@latest

Rotini requires Go 1.27 or later. The tool and the runtime are one module, so this also adds the runtime to go.mod, as an indirect dependency until your code imports it.

The files and the loop

rotini init sets up a program that builds and runs as it is. Run go mod tidy after it to record the runtime as a direct dependency, since the generated code imports it:

go tool rotini init todo
go mod tidy

These are the files it writes:

Specs and confs can also be JSON, JSONC or TOML: rotini init todo --format toml.

The spec init writes declares a --help flag, a --version flag (long only, so -v stays free for a --verbose), and help and version commands. Both flags are cascading, so every command’s help lists them. Rotini adds no flags or commands of its own, so these are ordinary spec entries you can rename, change or delete.

From then on, development is a loop: change the spec, regenerate, implement any new handler, build.

go tool rotini validate ./cmd/todo/.rotini.spec.yaml --config ./cmd/todo/.rotini.conf.yaml   # optional
go generate ./...
go build ./cmd/todo

validate checks the spec and conf against their JSON Schemas and rotini’s lint rules, and reports each problem with its file:line:col:

$ go tool rotini validate ./cmd/todo/.rotini.spec.yaml --config ./cmd/todo/.rotini.conf.yaml
spec: ./cmd/todo/.rotini.spec.yaml
conf: ./cmd/todo/.rotini.conf.yaml
Error: spec: ./cmd/todo/.rotini.spec.yaml:31:19: /command/commands/0/flags/0/sumary: unknown key "sumary" on a flag input

Beyond the schemas, validate catches specs that can never work: bounds or lengths that leave no value, enum values that aren’t the declared type, required with a default, contradictory flag groups, config keys read with two types, an identifier that hides every identifier of a parent’s cascading flag, -ab beside -a and -b, names that make the same Go identifier (two commands, inputs or schema properties, or a schema and a generated type), a Windows device name (aux, con, com1) in a generated package’s path, and a Go keyword or main as a package name. It warns, without failing, about an identifier that hides only some of them, one-dash multi-letter identifiers, flags with no long form, a literal default on a secret input, an environment variable two inputs read differently, a summary of more than one line, a required flag that isn’t cascading on a command with sub-commands, a completion value the carapace spec leaves out, and a --help or other short-circuit flag that isn’t cascading on a command whose sub-commands don’t declare their own. Two opt-in conf keys add warnings: validate.flags_first for env and config inputs no flag or argument can set, and validate.posix_names for a program name that isn’t a POSIX utility name.

generate runs the same checks first, so validate is mostly for CI. To also check in CI that the committed code matches the spec, run go tool rotini generate --dry-run: it writes nothing, lists what would change, and exits 2 if anything would. See the companion CLI for its exit codes and the dry_run_env conf key.

Keeping specs tidy

go tool rotini fmt rewrites the spec and conf in one canonical layout: keys in reading order (a command’s name and documentation, then its inputs, output and sub-commands), two-space indentation, and lists indented under their key. Comments move with the entries they describe, and every value is kept exactly as written, quotes and block scalars included. With no file it formats the spec in the working directory and the conf beside it; name files to format others, such as a composed command’s file.

In CI, --check writes nothing and exits 2 when a file isn’t formatted:

go tool rotini validate ./cmd/todo/.rotini.spec.yaml
go tool rotini fmt --check ./cmd/todo/.rotini.spec.yaml ./cmd/todo/.rotini.conf.yaml
go tool rotini generate --dry-run ./cmd/todo/.rotini.spec.yaml

Only YAML files can be formatted for now.

Starting from a template

rotini init <name> --template <shape> starts from a shape other than the plain seed. Every format works (--format yaml|json|jsonc|toml), and --dry-run lists what it would write.

Examples that parse

validate checks each examples: line that runs the program against the spec, with the same parser a run uses: the command path, the flags, enum values and the number of arguments. Values aren’t run, nothing is read from files or stdin, and an input with an environment or config fallback may be left out. A line that doesn’t start with the program’s name (or its display_name) is prose and is skipped; in a pipeline or a list (|, &&, ;) each command that runs the program is checked. A word with $, a backtick or a glob, and a <placeholder>, stands for any value. Words after a composed command or a plugin aren’t checked.

Error: spec: ./cmd/todo/.rotini.spec.yaml:12:7: command todo: example "todo lst --all" does not parse: unknown command "lst" for "todo"

Importing a Cobra CLI

An existing Cobra program can start its spec for you (rotini import also reads Kong and urfave/cli programs). Point rotini import cobra at the package that builds the command tree, usually the one declaring rootCmd:

go tool rotini import cobra ./cmd
go get github.com/go-rotini/rotini
go build ./cmd/acme

It reads the tree the program builds at run time, so it sees what the program declares, and writes cmd/<name>/.rotini.spec.yaml and its conf, then generates as init does: a handler for every command, plus the help and version handling init seeds. Your program’s files and go.mod are left as they are, so both CLIs build side by side while you port; when Cobra’s code already lives in internal/cmd/<name>, pass --dir <name>-rotini. If the root isn’t a package-level variable or a function like NewRootCmd(), name it with --root, any Go expression that yields a command.

A command with no Args rule accepts any positionals in Cobra, so it imports with a trailing args list; --strict leaves that out and keeps only the arguments its Use line names.

What can’t be carried across exactly is reported on stderr, one line each: lossy (carried across with something lost, such as a custom pflag.Value imported as a string or a completion function to rewrite as a completer), unsupported (dropped), and info. In a YAML spec the lossy and unsupported lines also sit as comments above the command they concern, next to a pointer to each hook to port:

    # cobra RunE -> rotini Run: cmd/deploy.go:42
    # [lossy] --at is a time flag: the formats it accepts are not exported; set layout: if they are not RFC 3339
    - name: deploy

Move each hook’s code into the matching method of the command’s handler: PersistentPreRun to CascadingPreRun, PreRun to PreRun, Run to Run, and so on. A few behaviors differ, and the import notes each one that applies:

• Rotini prints no deprecation warnings itself; a hook reads rotini.Deprecations and prints them.
• A command with sub-commands runs its own handler when invoked bare; the generated handler prints help.
• Every CascadingPreRun from the root down runs, not only the nearest persistent hook.
• A command’s own flags are also accepted after a sub-command’s name.

Flags and commands a program adds while running (inside a run hook, an OnInitialize function or a plugin loader) aren’t in the tree, so they aren’t imported. Neither are viper’s bindings: declare variable: and key: on the inputs, env_prefix, and config_files with discover. The import runs the package’s init functions, as its tests do, and fails with an explanation when one calls flag.Parse. See the companion CLI for its flags.

Importing a Kong CLI

rotini import kong reads the model Kong builds from a program’s grammar struct. Point it at the package that declares the grammar; it finds a package-level var CLI struct{…} (giving &CLI) or a grammar type named like CLI (giving &CLI{}), and --root names any other expression that yields a pointer to the grammar:

go tool rotini import kong --name acme --var version=1.4.2 ./cmd/acme

Kong names a program after the binary it runs as, so the CLI takes its name from --name, else from the last element of the package’s import path. Pass each variable the program gives kong.Vars with --var name=value: a ${name} left out is reported, help keeps it as written, and a default, enum or environment variable built from it is dropped. Options the program passes to kong.Parse or kong.New in main (a description, configuration loaders, resolvers, mappers) aren’t seen.

Kong has no help or completion command, so none is seeded. A default command (default:"1") is dropped, and a branching argument becomes a command; each is noted. type:"path" imports as a string with a file hint, and a custom mapper as a string, both with a note.

Importing a urfave/cli CLI

rotini import urfave reads a urfave/cli v3 command tree. Point it at the package that builds the root *cli.Command; it finds a package-level command variable that no other command lists, or a function such as newApp() that returns the root. A tree built inside main needs moving into such a function, or --root naming an expression that yields it:

go tool rotini import urfave --root 'buildApp(nil)' ./cmd/tasks

The CLI takes the root command’s Name, else --name, else the last element of the package’s import path. urfave/cli adds its help command, help and version flags and completion command only while running, so the import adds them in the shape rotini init seeds.

A command with no Arguments accepts any positionals, so it imports with a trailing args list; --strict leaves that out and keeps only the arguments its ArgsUsage names. DefaultCommand, PrefixMatchCommands and Suggest are dropped, and ShellComplete, a flag’s Action or Validator, and file sources are noted for porting.

Commands, flags and arguments

The root command is the binary, and commands: nests sub-commands to any depth. Each command declares its own flags: and arguments:, and each input has a schema: that sets its type and rules:

  commands:
    - name: add
      summary: add a task
      aliases: [a]
      arguments:
        - name: title
          summary: the task title
          schema: { type: string, required: true, minLength: 1 }
      flags:
        - name: priority
          summary: how urgent
          identifiers: [-p, --priority]
          schema: { type: string, default: normal, enum: [low, normal, high] }
        - name: tag
          summary: a label
          identifiers: [--tag]
          schema: { type: '[]string' }

• Types are Go names (string, int, bool, []string, map[string]string) or value types that rotini parses for you: duration, date, url, ip, bytesize and more.
• Rules such as required, default, enum, pattern, minimum and maximum, lengths and item counts are checked when the handler reads its inputs with rtx.Inputs, which the generated handler does first. A bad value is a usage error naming the flag the user typed. An empty value (--name "", --name=, '') counts as given; add minLength: 1 to refuse it.
• A flag applies to its own command unless it is cascading: true. Given with a sub-command, before or after its name, it is a usage error naming the command it belongs to (--init belongs to "app", not "app db migrate").
• cascading: true makes a flag apply to every command below its own: it works anywhere after its command’s name, a sub-command’s handler reads it through its generated inputs, and sub-commands’ help lists it under “Global Flags” (GLOBAL OPTIONS in man pages). Rename the heading with cascading: under the command’s headings:.
• A flag written before a sub-command’s name belongs to a parent, which lets a parent and a sub-command both declare a flag with the same name. A different flag that reuses an identifier of a cascading parent flag is flagged by validate.

Mistakes are reported before your code runs:

$ ./todo add "buy milk" -p urgent
Error: invalid value "urgent" for -p (one of: low, normal, high)
$ ./todo add
Error: missing required input: <title>
$ ./todo add "buy milk" --loud
Error: unknown flag "--loud"

Where flags stop

A flag works anywhere after its command until a --, which makes every later word an argument. A command can move that point earlier:

• options_first: true stops flags at the command’s first argument, as POSIX utilities do, so app ssh host -v ls passes -v ls on. A -- after that argument is an argument too, and so is a --help there. Sub-commands don’t inherit it.
• passthrough: true on the last argument (a []string) takes every word from that argument on as typed. The command’s own flags still parse before it: app exec --region eu ls -la --help sets --region and passes ls -la --help on. A first word that starts with - goes after -- (app exec -- -x). rtx.DashIndex() says how many arguments came before a -- the user typed, for a handler that forwards them. passthrough: true on the command itself takes every word after its name raw, with no flags at all.

Other argument shapes:

• A digit option, identifiers: ['-4', --ipv4] on a bool or count flag, makes -4 (and -46, clustered) a flag, while other negative numbers stay numbers. Quote it in YAML. validate rejects one where an argument of the command, or of a command below it, takes negative numbers.
• A variadic argument before fixed ones, <src...> <dst>: the fixed arguments after it must be required, and take the last words.
• A literal @ for a from: [file] flag is doubled: --to @@alice gives @alice, and --to @./@name reads a file whose name starts with @.
• Enum values with summaries, enum: [json, {value: yaml, summary: human-friendly}], are described on the help, man and markdown pages and in completion; the value is still what the user types.

Response files

response_files: {prefix: "@"} on the root reads arguments from a file: before the first --, @args.rsp is replaced by the file’s lines, one argument per line, with blank lines and # comment lines skipped. Words read from a file aren’t expanded again, and @@x is the literal argument @x. Expansion happens before anything else reads the command line, so a file can hold the command’s name, and rtx.Argv holds the expanded words. Choose a prefix other than @ when a flag or argument reads from: [file]. The root man and markdown pages tell users about the prefix and the doubled form.

Repeated values

A single-value flag given twice keeps the last value, so a script can override an alias’s setting. Two schema keys make repeats an error instead:

• repeatable: false on a single-value flag rejects a second occurrence, naming both values: --name was given more than once ("a", then "b"); it takes one value. -vv and --color --no-color are repeats too, and so is a root flag given before and after a sub-command’s name. Environment and config values never count as repeats.
• uniqueItems: true on a list rejects one that holds the same value twice: --port must not repeat a value (got "01" twice). Values compare as their type reads them, so 01 and 1 are the same int and 1h and 60m the same duration; a time compares as the instant it names, and a list of objects compares whole objects. It applies on every channel, including an environment list (PORTS=80,80), and in rtx.CheckInputs.

Deprecating a command or flag

deprecated: <message> marks a command, flag, argument, environment or config input as deprecated: help, man and markdown show the message beside it. To deprecate only some spellings, list them in deprecated_identifiers (aliases for a command, identifiers for a flag); the others are the ones to move to.

Rotini prints nothing when a deprecated spelling is used. rotini.Deprecations(rtx) lists what this run used, and the handler decides what to say. In the root handler’s CascadingPreRun, one loop covers every command on the path:

for _, d := range rotini.Deprecations(rtx) {
	rtx.RecordWarning(d)
}

Plan the removal with deprecated_since and removed_in (both X.Y.Z) beside deprecated. Pages then read (deprecated since 1.4.0, removed in 2.0.0: use --config), the contract carries both, and each Deprecation has them as Since and RemovedIn, so a handler can compare them with rtx.Version() (for example with golang.org/x/mod/semver, which wants a leading v). To plan the removal of a deprecated spelling while the command or flag stays, map it to its release with deprecated_identifiers_removed_in:

flags:
  - name: config
    identifiers: [--config, --conf]
    deprecated_identifiers: [--conf]
    deprecated_identifiers_removed_in: {--conf: 2.0.0}
  - name: legacy
    deprecated: use --config
    deprecated_since: 1.4.0
    removed_in: 2.0.0

rotini validate --release 2.0.0 then fails for each item still declared whose removal is due at or before that release, so a planned removal can’t ship by accident. Set the conf’s validate.release_env to the name of a variable your release job sets, and rotini validate and rotini diff read the release from it; --release wins. rotini generate never runs this check.

Pointing at a replacement

replaced_by beside deprecated names what to use instead: on a command, its path below the root (purge, remote add), without the program’s name; on a flag, one of its identifiers. A command from a composed spec names a command of that spec, and rotini writes it under the path the parent mounts it at. Help, man and markdown add it to the note, (deprecated: renamed; use todo purge instead), and validate checks that it exists and isn’t deprecated itself:

commands:
  - name: clear
    deprecated: renamed
    replaced_by: purge
    flags:
      - name: out
        deprecated: renamed
        replaced_by: --output
        schema: { type: string }

Each Deprecation carries it as ReplacedBy, written as the user types it (todo purge, --output, or the enum value), so the handler can say it:

for _, d := range rotini.Deprecations(rtx) {
	if d.ReplacedBy != "" {
		rtx.RecordWarning(fmt.Errorf("%w; use %s instead", d, d.ReplacedBy))
		continue
	}
	rtx.RecordWarning(d)
}

Times, patterns and negated forms

• Several time layouts, layout: ['2006-01-02 15:04', '2006-01-02', unix], are tried in order and the first that parses wins. Help shows the first, an error names them all, and validate warns when an earlier layout would read a later one’s values as a different time.

• Relative times, relative: past, also accept a time measured from now: 2h or 3d ago, now, today and yesterday. future takes 2h or +2h from now and tomorrow; both needs a sign (-2h, +3d). Absolute values are still read first. On a date the result is the calendar date it falls on, and an offset must be whole days. Every relative value in a run is measured from one clock reading, which rtx.Now() returns; set the clock in tests with Program.WithClock:

  at := time.Date(2026, 10, 8, 12, 0, 0, 0, time.UTC)
  code, err := cmd.NewProgram().
  	WithClock(func() time.Time { return at }).
  	Run([]string{"log", "--since", "2h"}) // since is 10:00
  

  today follows the clock’s time zone, which is the process’s unless the clock says otherwise.

• base: prefixed on an integer also accepts 0x1F, 0o17 and 0b101, with a sign and _ between digits, wherever the value comes from; a value without a prefix is still decimal, so 010 is ten. Without base, every source is decimal-only: PORT=0x10 is an invalid value.

• Numbers from a config file. YAML, TOML, JSON and JSONC hold numbers, not text, so a whole number written as a float (450.0, 1e3) fills an integer input, and 1 or 0 fills a bool. The command line, the environment and .env files spell an integer as one. A null list item is refused, and a list of uint8 (or byte) is a list of integers wherever it comes from, not raw bytes.

• type: regexp is compiled when parsed into a *regexp.Regexp, so a bad expression is a usage error naming the flag. The syntax is Go’s RE2, which has no backreferences or lookaround.

• type: glob is a rotini.Glob, a path.Match pattern checked when parsed, with a Match method that reads \ in a name as / on Windows. ** is not recursive: it is two *. It keeps the pattern as a value; it doesn’t expand it into file names.

• negatable: --plain names the negated form of a bool flag instead of deriving --no-color: --plain sets --color false, and --no-color isn’t accepted. Help lists it beside the flag, --color, --plain.

Enum aliases, hidden and deprecated values

An enum value written as an object can declare more than a summary:

schema:
  type: string
  enum:
    - json
    - { value: yaml, aliases: [yml] }
    - { value: xml, hidden: true }
    - { value: ini, deprecated: INI output is going away, deprecated_since: 1.4.0, removed_in: 2.0.0, replaced_by: json }

• An alias is accepted on every channel and bound as its value, so the handler only ever sees yaml. deprecated_aliases: [yml] retires one spelling while the value stays.
• A hidden value is accepted but never offered: help, completion and error messages leave it out.
• A deprecated value is still accepted and left out of the same lists. Given on the command line, it is reported by rotini.Deprecations with Deprecation.Value set, as a deprecated alias is. Man and markdown pages list each value with its aliases and deprecation; help keeps its short list of the values to use.

Sharing flags between commands

Flags that several commands take are declared once under the root’s flag_sets, and each command adds them with use:. A set’s flags come after the command’s own, with the set’s flag_groups and flag_dependencies, and from then on they are the command’s flags: they parse, fall back, show in help and appear in the contract like any other. group: on the set lists its flags under one heading in help, unless a flag names its own:

command:
  name: todo
  flag_sets:
    Output:
      group: Output
      flags:
        - name: format
          summary: how to print
          schema: { type: string, enum: [text, json], default: text }
  commands:
    - name: list
      use: [Output]
    - name: show
      use: [Output]

The generated code has one struct per set, embedded in each command’s flags, so a handler reads in.TodoList.Flags.Format whether the flag is the command’s own or from a set, and moving a flag into a set changes no handler code. A helper that every using command shares can take the set’s struct:

func print(rtx *rotini.Context, out TodoOutputFlagSet, items []Item) { /* … */ }

print(rtx, in.TodoList.Flags.TodoOutputFlagSet, items)

Set names are PascalCase, since each names a struct. A set belongs to the spec that declares it: a composed child uses its own sets. validate rejects a set flag whose name or generated field repeats one of the command’s, and warns about a set no command uses.

Flags that depend on other flags

flag_groups constrain which flags go together (mutually_exclusive, required_together, one_of, at_least_one). A flag_dependencies entry is a rule with a trigger and an effect:

• when: <flag> triggers the rule when that flag is set, and equals: [...] narrows it to some of the flag’s values. The value is compared as the flag stores it, so ignore_case and enum aliases apply, and a bool compares as true or false (--no-x is false).
• unless: [...] turns the rule off when any of those flags is set. Without when, the rule applies on every run unless one of them is set.
• requires: [...] must then be set, and forbids: [...] can’t be.

flag_dependencies:
  - when: format
    equals: [csv]
    requires: [delimiter]
  - when: all
    forbids: [limit]
  - unless: [anonymous]
    requires: [token]

$ ./todo export --format csv
Error: flag --delimiter is required when --format is csv
$ ./todo export --all --limit 5
Error: flag --limit can't be used when --all is set

Only the command line counts, for groups and dependencies alike: a value from the environment, a config file or a default neither triggers a rule nor satisfies one. A short-circuit flag such as --help waives them, and rtx.CheckInputs applies them to values you collected yourself, comparing the typed values.

Hidden aliases and identifiers

hidden_aliases on a command and hidden_identifiers on a flag are accepted on the command line but listed nowhere: not in help, completion or suggestions. Use them for an old spelling that scripts still use, without advertising it. The help resolvers accept a hidden alias too, the contract lists them as hidden_aliases and hidden_identifiers, and they may be listed in deprecated_identifiers to report their use:

commands:
  - name: remove
    aliases: [rm]
    hidden_aliases: [del]
    flags:
      - name: output
        identifiers: [-o, --output]
        hidden_identifiers: [--out]
        schema: { type: string }

Your own metadata

metadata on a command, flag, argument, env or config input, or stdin holds labels of your own, string keys with string values, for tools you write: an owner to page, a team, an audit tag. Rotini never acts on them and shows them on no page. They are copied as written into the generated definition (CommandDef.Metadata, FlagDef.Metadata, ArgDef.Metadata, and rtx.Command().Metadata in a handler) and into the contract, and rotini diff rates any change to them as safe:

commands:
  - name: purge
    metadata: { owner: storage-team, audit: "true" }

Where values come from

A flag can also be read from an environment variable and a configuration file. Give it a key: and declare the file:

command:
  name: todo
  env_prefix: TODO
  config_files:
    - name: user
      discover: { strategy: xdg, app: todo, file: config.yaml }
  commands:
    - name: add
      flags:
        - name: priority
          identifiers: [-p, --priority]
          schema: { type: string, default: normal, key: defaults.priority }

--priority now falls back to TODO_DEFAULTS_PRIORITY, then to defaults.priority in $XDG_CONFIG_HOME/todo/config.yaml (by default ~/.config/todo/config.yaml), then to its default. The command line always wins:

$ cat ~/.config/todo/config.yaml
defaults:
  priority: high
$ ./todo add "buy milk"
added "buy milk" (priority high)
$ TODO_DEFAULTS_PRIORITY=low ./todo add "buy milk"
added "buy milk" (priority low)
$ TODO_DEFAULTS_PRIORITY=low ./todo add "buy milk" -p normal
added "buy milk" (priority normal)

Help shows both sources on the line under the flag, the variable first because it wins. The config key appears only for a command that reads a config file:

$ ./todo add --help
...
Flags:
  -p, --priority string    how urgent (default normal) [low|normal|high]
                           also set by TODO_DEFAULTS_PRIORITY or config key defaults.priority
      --tag []string       a label (repeatable)

A key set to null in a config file (priority: or priority: null) counts as not set, so the next file or the default applies.

Use variable: to name the environment variable exactly instead of deriving it. Config files can also be found by walking up from the working directory (strategy: walk-up) or read from a fixed path:; see config_files.

Commands can also declare pure env: and config: inputs, and a typed stdin: payload. They all land in the same generated inputs struct.

Arguments from the environment and files

An argument takes variable: and key: as a flag does, for a position the command line leaves out: the command line, then the environment, then the config file, then the default.

- name: deploy
  arguments:
    - name: env
      schema: { type: string, required: true, variable: DEPLOY_ENV }
    - name: service
      schema: { type: string, default: api }

DEPLOY_ENV=prod ./app deploy deploys api to prod, and ./app deploy dev still wins over the variable. Positionals fill left to right, so a fallback applies only when every argument before it has a value, and validate asks for a fallback or a default on any argument after one with a fallback: otherwise ./app deploy web would put web into <env>. A variadic argument splits its variable on its separator; without one, the whole value is one item. Help shows the sources under the argument, and an error about such a value names the variable it came from.

from: [file, stdin] works on an argument before any variadic one, as on a flag: ./app cat - reads stdin and ./app cat @notes.txt the file. Stdin can be read once, so one input on a command path may take it.

An env list input splits its variable on commas; separator: ':' splits a PATH-style value instead (KUBECONFIG=a:b). It’s a plain split with spaces trimmed, not the CSV quoting a flag’s separator allows, and item counts and per-item rules are checked on the split items.

Reading stdin

A declared stdin: is read once per run, whole, and held in memory; a second rtx.Inputs call sees the same payload. For a filter that should handle any size, stream it: stream: true on format: lines (or jsonl, one JSON record per line) makes the field an iterator that reads one item at a time.

unless_argument: names an optional file argument: stdin is read only when that argument gets no file, or -. This is the grep PATTERN [FILE...] shape, and it keeps a command that was given a file from waiting on a stdin its caller holds open:

commands:
  - name: grep
    arguments:
      - name: pattern
        schema: { type: string, required: true }
      - name: files
        schema: { type: '[]inputfile' }
    stdin:
      format: lines
      stream: true
      unless_argument: files

in, err := rtx.Inputs[LogsGrepInputs]()
if err != nil {
	rtx.HaltWith(err)
	return
}
if in.LogsGrep.Stdin == nil {
	// Files were given (or stdin is a terminal): read in.LogsGrep.Arguments.Files.
	return
}
for line, err := range in.LogsGrep.Stdin {
	if err != nil {
		rtx.HaltWith(err) // a read error, or Ctrl-C: the run exits 130
		return
	}
	if strings.Contains(line, in.LogsGrep.Arguments.Pattern) {
		fmt.Fprintln(rtx.Stdout, line)
	}
}

The iterator is nil whenever stdin is not read: a terminal, a short-circuit flag such as --help, or a file given. Ranging over a nil iterator panics, so check it first. It reads the run’s one stdin: a break leaves the rest unread, and a later range continues from there. A jsonl record is checked against the schema as it is read, and an error names its line (stdin line 12: …). A line is limited only by memory. CheckInputs and InputReport.Validate carry a stream but don’t check its items.

format: bytes binds the payload byte for byte (*[]byte); every other format removes one leading byte-order mark. separator: nul splits lines on NUL bytes instead of newlines, as find -print0 writes them, with each item kept exactly:

$ find . -name '*.log' -print0 | logs rotate

A list or map flag with from: [file] or from: [stdin] takes one value per line of the file (blank lines skipped), each split further on its separator; separator: nul splits that content on NUL instead. --tags @tags.txt with a,b and c on two lines is [a b c].

Secrets in files and .env files

variable_file: names a variable holding the path of a file to read the value from, the way Docker and Kubernetes mount secrets. Setting both forms is an error:

env:
  - name: token
    schema: { type: string, variable: TODO_TOKEN, variable_file: TODO_TOKEN_FILE, secret: true }

$ TODO_TOKEN_FILE=/run/secrets/todo ./todo sync

A config_files entry with format: dotenv and as: env supplies environment variables instead of configuration. Env inputs and flag fallbacks read it, and the real environment wins variable by variable, so the order is: command line, environment, .env file, configuration files, default. Its values are literal (${OTHER} is not expanded), and rotini’s own variables (HOME, XDG_*, PATH) never come from it. Prefer a fixed path: .env to discovery:

config_files:
  - name: dotenv
    path: .env
    format: dotenv
    as: env

Secrets on the command line

A value typed on the command line shows in the process list and in shell history. A secret flag or argument whose from: leaves out value refuses one, so the secret can only come from a file or stdin:

flags:
  - name: token
    schema: { type: string, secret: true, from: [file, stdin] }

$ ./todo login --token sk_live_123
Error: --token takes @file or -, not a value
$ ./todo login --token @token.txt
$ ./todo login --token - < token.txt

Environment variables and config files are still read as written, so variable: or variable_file: beside it keeps those routes open. validate warns about a secret flag that accepts a typed value; add value to from to keep accepting one on purpose. rotini.ArgvOf can’t write such a flag, since it has no file to point at: pass it through a file or stdin yourself.

Config directories

discover: finds a config file at run time with one of four strategies:

Declare a system tier as its own entry after the user’s: the first declared entry wins per key, so the user’s file overrides the system one key by key.

Profiles

One config file can hold several named sets of settings, with a flag or variable choosing one per run, like --profile prod. Declare where the profiles live and which input chooses:

command:
  name: todo
  config_files:
    - name: user
      discover: { strategy: xdg, app: todo, file: config.yaml }
      profiles: { under: profiles, select: profile, default: default }
  flags:
    - name: profile
      summary: the configuration profile to use
      identifiers: [--profile]
      cascading: true
      schema: { type: string, variable: TODO_PROFILE }

server: { host: todo.example.com, port: 443 }
profiles:
  default: {}
  local:
    server: { host: localhost }

The chosen profile’s keys are read as if they sat at the top of the file, and win over the file’s other top-level keys, which every profile shares. With --profile local, the host is localhost and the port still 443. Merging is per key: a list in a profile replaces the shared list, and a map’s entries merge.

• The choice: --profile on the command line, then the first set variable (the flag’s own variable: names, then an env input named by select), then the default. A .env file can set the variable. The choice is never read from a config file, so the selector can’t declare key:.
• Precedence is otherwise unchanged: command line, environment, config files (the chosen profile, then the shared keys), default.
• An unknown profile chosen on the command line or in the environment is a usage error that lists the defined ones, and carries them as SuggestionFacts candidates: --profile: profile "lcoal" is not defined in configuration file /home/ada/.config/todo/config.yaml (profiles: default, local). A default that a file doesn’t define just leaves the shared keys, and --help never fails on a bad choice.
• Several files may share a selector: a profile is unknown only when none of them defines it.
• The file’s schema: checks the shared keys merged with the chosen profile, without the profiles key. Profiles that aren’t chosen aren’t read or checked.
• Provenance names the profile: config:user#profiles.local.server.host for a key the profile set, config:user#server.port for a shared one.

Profiles are a single top-level key of named maps; a kubeconfig-style list of contexts isn’t supported. The generated config schema describes the profiles key, and leaves out the file’s own schema:, which checks the merged view instead. rotini.ConfigProfiles(rtx, "user") lists the defined names for a completer.

Writing config values

Rotini adds no config command, but a config set you declare can write a value into a config file the way your users would by hand:

err := rotini.SetConfigValue(rtx, "user", "server.port", "8443")

The arguments are the config_files name, the key as written in the file, and the value as the user typed it. rotini.UnsetConfigValue removes a key, and rotini.ConfigFilePath reports which file a write goes to and whether it exists yet. The recipe builds all three commands.

• Checks: the key must be one an input reads from the file. The value is checked as the command line checks the same input’s flag: its type, enum, bounds, pattern and item counts, and the file’s schema: after the edit. A list value is split on the input’s separator (, when none), a map’s entries are key=value, and an enum value is written in its declared spelling. A failed check is a usage error and leaves the file as it was: invalid value "loud" for config key level (one of: debug, info, warn).
• Which file: the one the command reads, through its config_source path, fixed path or discover search. A missing file is created there, with its directories: walk-up creates it in the run’s directory and xdg under $XDG_CONFIG_HOME/<app>. A file found by xdg-system is refused, since a user’s file would hide every system setting. A symbolic link is followed.
• The edit: only the value’s text changes; comments, key order, quoting and indentation stay. A new key goes at the end of its parent mapping. YAML, JSON, JSONC, TOML and dotenv files are written; a layout that can’t be edited safely, such as a key reached through a YAML alias, is a usage error asking the user to edit by hand. The file is replaced atomically, keeping its permissions. Two commands writing one file at once can lose one of the changes.
• Secrets: a key declared secret: true is refused unless the call passes rotini.AllowSecretWrite(). A new file holding any secret key gets mode 0600, and an existing file that others can read is refused rather than changed. On Windows, file modes don’t control who can read a file, so the file gets its directory’s access rules and nothing is refused.
• Profiles: in a file with profiles, the value goes into the chosen profile, which is created if the file doesn’t define it yet. rotini.ToProfile(name) and rotini.ToSharedKeys() pick another target. A shared key that the chosen profile overrides is written, with a warning.
• Custom types: an input whose type comes from import: needs rotini.ParseConfigValue(fn) to check its value; an object-valued key is edited by hand.

Each config file’s keys, with their types and rules, are in the generated InputSettings.ConfigFiles[i].Keys, which a key completer can offer.

Paths

A value is taken as written unless its input declares expand. home expands a leading ~ (or ~name) and env expands $NAME and ${NAME} ($$ is a literal $), in values from every source: the command line, environment variables, .env files, configuration files and the default. The expanded path is what gets checked and bound. An existingfile or existingdir input is checked on every channel, environment and configuration included:

flags:
  - name: file
    identifiers: [--file]
    schema: { type: existingfile, expand: [home, env] }
config:
  - name: cache
    schema: { type: string, default: ~/.cache/todo, expand: [home], relative_to: config }

$ ./todo add --file '~/notes.txt'
$ ./todo add --file '$NOTES/today.txt'
Error: --file: $NOTES is not set (in "$NOTES/today.txt")

• An unset or empty variable is an error, and so are shell operators such as ${NAME:-x}. Expansion is one pass: text a variable supplies is never expanded again.
• A command-line path that doesn’t exist is named as expanded and as written: --file: no such file: "/home/ada/x" (written as "~/x").
• ~name reads the system’s user database, so an injected environment can’t change it.
• %VAR% is not expanded on Windows; $NAME and ~\ are.
• relative_to: config resolves a relative value read from a configuration file against that file’s directory. Values from anywhere else stay relative to the run’s directory.
• A project file found by walk-up can set inputs it reads, so prefer expand: [home] there: with env, a cloned repository’s file could write a token from your environment into a path. rotini validate warns about the combination. expand is refused on secret inputs.

Files your program keeps

rotini.AppDirs(rtx, app, strategy) returns the config, data, cache and state directories for app, read through the run’s environment. It creates nothing. strategy takes the words of discover.strategy: xdg for the XDG layout on every platform, or native for the platform’s own (~/Library on macOS, %AppData% and %LocalAppData% on Windows). Use the same strategy as your config files, and create data and state directories with 0o700:

dirs, err := rotini.AppDirs(rtx, "todo", "xdg")
if err != nil {
	rtx.HaltWith(err)
	return
}
if err := os.MkdirAll(dirs.State, 0o700); err != nil {
	rtx.HaltWith(err)
	return
}

A directory flag

role: chdir on a root flag makes it a directory flag, like git’s -C dir: the program runs as if it had been started in that directory. Rotini acts on whichever flag carries the role, under the identifiers you declare; -C, --dir below is one spelling, and -w, --workdir works the same.

command:
  name: todo
  flags:
    - name: dir
      summary: run as if started in this directory
      identifiers: [-C, --dir]
      role: chdir
      cascading: true
      schema: { type: existingdir }

Rotini reads the flag before anything else, wherever it is typed on the command line. Walk-up config discovery starts from the directory, and relative config paths, @file values, existingfile and existingdir checks, and rotini.OpenInput and rotini.CreateOutput resolve against it. A plugin typed after it runs in it. A relative directory is resolved against the run’s directory (WithDir, else the process’s), and the flag binds as the absolute path. Given more than once, the last wins; one that isn’t a directory is a usage error, even beside --help.

The flag is read from the command line only, so rotini validate keeps it narrow: on the root, cascading, an existingdir or string, one per program, with no default, key, variable or from:, and outside flag groups and dependencies.

Rotini never changes the process’s working directory. rtx.Dir() returns the run’s, so a handler that opens a relative path joins it first:

f, err := os.Open(filepath.Join(rtx.Dir(), name))

A shell completes the words after the directory flag against its own directory; Rotini’s completers see rtx.Dir().

Explaining where values came from

rtx.InputsWithReport returns the inputs with an InputReport, and report.Format(w) writes one line per field a layer set: the value, where it came from, and what it overrode, nearest first. A secret prints [redacted], whatever layer supplied it:

$ todo deploy prod --token s3cr3t --explain-inputs
TodoDeploy.Arguments.Target = "prod" from argv:<target>
TodoDeploy.Flags.ExplainInputs = "true" from argv:--explain-inputs
TodoDeploy.Flags.Port = "9000" from env:TODO_PORT; overrides config:user#deploy.port "8000", default "8080"
TodoDeploy.Flags.Token = [redacted] from argv:--token

Each InputSource names its origin: argv:<identifier as typed>, argv:<argument>, env:<VARIABLE> (env:TODO_HTTP__* for a nested family; the variable_file variable, such as env:TODO_TOKEN_FILE, for a value read from its file), config:<file name>#<key>, default or stdin. A hand-built layer’s origin is empty, and the line names its layer. A streamed stdin prints (stream) and is never read.

To offer this to users, declare a hidden short-circuit flag on the command and print the report in its handler, before checking the error, since the run may be the one being explained:

func (*todoDeployHandler) Run(ctx context.Context, rtx *rotini.Context) {
	in, report, err := rtx.InputsWithReport[TodoDeployInputs]()
	if in.TodoDeploy.Flags.ExplainInputs {
		_ = report.Format(rtx.Stdout)
		return
	}
	if err != nil {
		rtx.HaltWith(err)
		return
	}
	// …
}

With a short-circuit flag set, the requirements are waived and a declared stdin: isn’t read, so the explanation works on a command line that is still incomplete. Inputs belong to the running command, so the flag goes on each command that explains its own, not on the root.

To list each field with only the value that won, as a config list --show-origin command does, walk report.Fields() and read report.Winner(path); report.History(path) returns every layer that set it, the winner last. See the recipe.

Editor support for your users’ config

With generate.schemas.config.dir in the conf, rotini generate writes a JSON Schema for each config file the spec declares: todo.user.config.json for a file named user on the root, todo-deploy.team.config.json for one declared on deploy. It lists every key a command that reads the file binds, nested by dot, with its type, enum values and their summaries, default (never a secret’s), bounds, description and deprecation. Other keys are allowed, since rotini ignores them. A file’s own schema: is included, and dotenv files get none.

generate:
  schemas:
    config:
      dir: schemas/config

Publish the files with your docs, and your users point their editor at them: a # yaml-language-server: $schema=<url> first line in YAML, #:schema <url> in TOML, or a "$schema" key in JSON.

Example config and .env files

The config_example feature writes an example of each config file the spec declares, in the file’s own format, for your users to copy: examples/config/<name>.example.yaml (or .toml, .jsonc, .json, .env), with the conf’s file choosing the directory. env_example writes .env.example, every environment variable the program reads.

generate:
  features:
    - type: config_example
      enabled: true
    - type: env_example
      enabled: true

Every key is commented out, so a copy changes nothing until a line is uncommented. A line starting with # (// in JSONC) is a key, nested by dot as the file holds it; a line starting with ## (/// ) is a note: the summary, type, enum values and default. A key any file may hold is listed once, in the first such file’s example; a key pinned to a file with file: is listed in that file’s. A secret’s value is left blank, and a file with profiles shows where they go. JSON has no comments, so a JSON file’s example holds only the keys with a default, set. With generate.schemas.config on, YAML and TOML examples point editors at the file’s schema.

## app: ./todo.yaml, read by todo and its sub-commands.
## Each line starting with "# " is a key: remove the "# " to set it.

# deploy:
##   how long a deploy may take (duration; default 5m)
#   timeout: 5m

Both features also generate ConfigExample(name string) (string, error), keyed by the config file’s name, and EnvExample() string, so a command of your own can print them (todo config example app). embed and embed_dir choose how that text is stored, as for help. The files are rewritten on every generate and never removed.

Handlers

go generate creates one handler file per command, once, and never overwrites it: it is yours. When its command leaves the spec, the next go generate disables the file (adding //go:build ignore) and the one after deletes it. If the command comes back in between, the file returns to the build as it was. To keep it, delete its var _ rotini.Handler line or list it under the conf’s keep:. Fill in Run:

package todo

import (
	"context"
	"fmt"

	"github.com/go-rotini/rotini"
)

var _ rotini.Handler = (*todoAddHandler)(nil)

type todoAddHandler struct {
	rotini.NoCascadingPreRun
	rotini.NoPreRun
	rotini.NoPostRun
	rotini.NoCascadingPostRun
}

func (*todoAddHandler) Run(ctx context.Context, rtx *rotini.Context) {
	// One call reads every declared source (command line, environment, config files, stdin
	// and defaults) in precedence order, and validates the result.
	inputs, err := rtx.Inputs[TodoAddInputs]()
	if err != nil {
		rtx.HaltWith(err) // record the error and stop; the reporter prints it and sets the exit code
		return
	}

	add := inputs.TodoAdd
	fmt.Fprintf(rtx.Stdout, "added %q (priority %s)\n", add.Arguments.Title, add.Flags.Priority)
}

• TodoAddInputs is generated from the spec, so the compiler holds the handler to it.
• Five hooks, in this order: CascadingPreRun runs for every command on the path from the root to the invoked command, root first. PreRun, Run and PostRun run only for the invoked command. CascadingPostRun runs for every command on the path again, invoked command first. Teardown (PostRun and CascadingPostRun) runs even after a halt or panic, for exactly the hooks whose setup ran. The No* embeds are no-ops; declare the method to use a hook.
• Write to rtx.Stdout, not os.Stdout, so tests can capture it.
• Record results and errors with rtx.RecordSuccess, rtx.RecordWarning and rtx.HaltWith rather than printing them. The runtime reports them once, after teardown.

The runtime itself only works out which command was invoked. Flags and arguments are parsed and validated when a handler calls rtx.Inputs[T](), or one of the per-source methods rtx.ArgvInputs, EnvInputs, FileInputs, StdinInputs and DefaultInputs. A handler that calls none of them gets the raw rtx.Argv and no validation, so you can bring your own parser or collect inputs another way, and check what you collect with rtx.CheckInputs.

A dependency the handlers share, such as a database or an API client, is registered once in main.go and read in any hook:

var Store = rotini.NewDependency[*store.Store]("todo.store") // in the cmd package

cmd.NewProgram().WithDependency(cmd.Store, openStore()) // in main.go
s := rtx.MustGetDependency(Store)                            // in a handler

A dependency built from the command line, such as a client for the server a flag names, is set per run instead; see per-run dependencies.

Flags that skip the run

Some flags replace a command’s run instead of changing it: --help, --version, or a flag of your own such as --print-plan. Mark one short_circuit: true in the spec. When it is set on the command line, Rotini waives every requirement the spec declares for the command chain (required inputs, enums, bounds, patterns, flag groups and flag dependencies), so rtx.Inputs succeeds and your handler can act on the flag. Input that can’t be read is still an error: an unknown flag or command, a value of the wrong type, or too many arguments. A configuration file that can’t be parsed, or holds a value of the wrong type, is skipped for that run, so --help works in a broken directory; a normal run still reports it. Each hook reads only the channels its inputs type describes: a hook whose inputs have no configuration values or fallbacks opens no configuration file. Rotini takes no action of its own; your handler checks the flag and decides what to do.

rotini init marks --help and --version this way, makes both cascading so every command’s page lists them, and writes one CascadingPreRun in the root handler that answers both for every command: --version prints the program’s name, then its version (todo 1.2.3). So a command’s handler needs no help code, and todo add --help works even with the title missing. The hook reads the root’s flags with rtx.ArgvInputs, which parses only the command line, since a short-circuit flag can only come from there. So --help and --version answer even when an environment variable or a configuration file can’t be read, and the hook doesn’t check what only a sub-command reads: todo add one two --help prints the page, though add takes one argument. Without the flag, the command’s own handler reads and validates every source.

A short-circuit flag can belong to one command, too:

// spec, under the deploy command:
//   - name: print-plan
//     summary: print what would be deployed, and deploy nothing
//     short_circuit: true
//     schema: { type: bool }

func (*deployHandler) Run(ctx context.Context, rtx *rotini.Context) {
	in, err := rtx.Inputs[DeployInputs]() // succeeds even with <service> missing
	if err != nil {
		rtx.HaltWith(err)
		return
	}
	if in.Deploy.Flags.PrintPlan {
		fmt.Fprintf(rtx.Stdout, "%+v\n", in.Deploy)
		return
	}
	// … deploy
}

A short-circuit flag must be a bool. It can’t be required, default to true, be negatable, be read from an environment variable or config key, or be named in a flag group or dependency, since it waives those; rotini validate reports any of these. Completion offers nothing more once one is on the line.

Checking inputs you collected yourself

When values come from somewhere rotini didn’t read, such as a prompt, a secrets service or a test, check them against the spec with rtx.CheckInputs. It applies the same rules rtx.Inputs applies (required inputs, enums, bounds, patterns, flag groups and dependencies) and returns the same errors:

argv, err := rtx.ArgvInputs[TodoAddInputs]()
if err != nil {
	rtx.HaltWith(err)
	return
}

in := askForMissing(rtx, argv.Values) // your own prompting code

if err := rtx.CheckInputs(in, rotini.PresenceOf(in)); err != nil {
	rtx.HaltWith(err)
	return
}

The second argument says which fields were supplied. rotini.PresenceOf(in) treats every non-zero field as supplied; when a zero value (false, 0, "") must count as supplied, build the rotini.Presence yourself. A value’s rules are checked only when it was supplied, with one exception that matches the command line: a list flag or variadic argument left out has zero items, so a minItems still applies to it unless it has a default. CheckInputs reads nothing, applies no defaults and never changes the value, and it names each input by its usual spelling (--priority, <title>).

A layer you build yourself can also join rotini’s own in a merge. Its values are checked too when you validate the merged report:

argv, _ := rtx.ArgvInputs[TodoAddInputs]()
env, _ := rtx.EnvInputs[TodoAddInputs]()
vault := rotini.InputLayer[TodoAddInputs]{Name: "vault", Values: fromVault(), Set: vaultSet}

merged, report := rotini.MergeInputsWithReport(env, vault, argv)
if err := report.Validate(); err != nil {
	rtx.HaltWith(err)
	return
}

Errors and exit codes

A handler that fails calls rtx.HaltWith(err). The program’s reporter runs once, after teardown, and decides what to print and which exit code to use. The default reporter prints each warning to stderr as Warning: … and each error as Error: …, and exits 1 when anything failed, unless a handler already set a non-zero code with rtx.HaltWithCode. It prints infos and successes to stderr too, so stdout carries only what handlers write. After Ctrl-C (or another trapped signal) it leaves out the error the cancellation caused, and the run exits 128+n.

Every error carries a category, which rotini.CategoryOf(err) returns: rotini.CategoryUsage for a mistake the user can fix, rotini.CategoryInternal for a fault in the program, and rotini.CategoryNone for an error nobody classified. Parse and validation failures are already usage errors. Mark your own with rotini.UsageError(err) or rotini.InternalError(err).

To give each kind of failure its own exit code, write a reporter. A reporter replaces the default entirely: it prints only what it prints, and it sets the exit code with rtx.Exit. If it doesn’t, the run keeps any code a handler set, and otherwise exits 0, so give it a fallback code for errors with no category. The codes below are common conventions, not Rotini defaults:

package todo

import (
	"context"
	"errors"
	"fmt"

	"github.com/go-rotini/rotini"
)

// Exit codes: 2 for a usage error (BSD's sysexits.h uses 64, EX_USAGE), 70 (EX_SOFTWARE) for
// a fault in the program, and the shell's 127 and 126 for a plugin that is missing or can't
// be run.
const (
	exitUsage         = 2
	exitInternal      = 70
	exitNotExecutable = 126
	exitNotFound      = 127
)

// Report prints warnings and errors to stderr, points at help after a usage error, and sets the
// exit code from the first error.
func Report(ctx context.Context, rtx *rotini.Context, out rotini.Outcome) {
	if ctx.Err() != nil {
		return // stopped by a signal: keep the 128+n exit code the run already set
	}
	for _, w := range out.Warnings {
		fmt.Fprintln(rtx.Stderr, "Warning:", w)
	}
	for _, err := range out.Errors {
		fmt.Fprintln(rtx.Stderr, "Error:", err)
	}
	for _, p := range out.Panics {
		fmt.Fprintln(rtx.Stderr, "Error:", p)
	}
	if !out.Failed() {
		return
	}
	if len(out.Errors) > 0 && rotini.CategoryOf(out.Errors[0]) == rotini.CategoryUsage {
		fmt.Fprintf(rtx.Stderr, "Run '%s --help' for usage.\n", rtx.CommandPath())
	}
	rtx.Exit(exitCode(out))
}

func exitCode(out rotini.Outcome) int {
	if len(out.Errors) == 0 {
		return exitInternal // only panics
	}
	err := out.Errors[0]
	var pe *rotini.PluginError
	if errors.As(err, &pe) { // before the category: a mistyped plugin name is also a usage error
		switch pe.Kind {
		case rotini.PluginNotFound:
			return exitNotFound
		case rotini.PluginStartFailed:
			return exitNotExecutable
		}
	}
	switch rotini.CategoryOf(err) {
	case rotini.CategoryUsage:
		return exitUsage
	case rotini.CategoryInternal:
		return exitInternal
	}
	return 1
}

• Check ctx.Err() first. After Ctrl-C or SIGTERM the run has already set 128+n (130 or 143), and the canceled context’s error is in out.Errors; without the check, the reporter would replace that code. The same goes for a cancellation with ExitCause.
• A reporter can’t read the code a handler set. rtx.Exit replaces any code from rtx.HaltWithCode, so map only the errors you mean to, or carry a handler’s code in an error type of your own, as in linking exit codes to docs.
• A plugin’s own exit code passes through unchanged and never reaches the reporter. A file found next to the binary or in plugin_path that can’t be run is PluginStartFailed; one on PATH without the execute bit isn’t found at all, so it exits 127. A plugin that runs past its timeout: falls through to 1 here.
• List the codes under exit_status:, so man and markdown pages and the contract say what they mean. --help leaves them out.

Install it in main.go with cmd.NewProgram().WithReporter(cmd.Report). Keeping it in the command package, rather than in main.go, lets tests install the same reporter (see Testing). The Outcome also carries Infos and Successes, from rtx.RecordInfo and rtx.RecordSuccess, for a reporter that prints those too.

For errors that scripts parse, rotini.StructuredReporter writes them as JSON lines; see errors scripts can read. Declare exit_status: in the spec to document a command’s codes in its man and markdown pages.

Once a command declares exit_status:, rotini generate checks its handler against it: a code the handler passes to rtx.HaltWithCode or rtx.Exit as a number or a constant, but that the list leaves out, is reported as a warning with its file and line. Code 0 needs no entry. A command that prints its help when called without a sub-command exits 1, so list 1 for it. (The stub rotini generate writes for a root or a group command does this, printing the help on stderr.) The check reads only the methods of the command’s handler type, so it can’t see a code computed at run time, set in another function or package, or set by a reporter, and it skips a command whose handler lives in another package (handler:). rotini validate also reports a code listed twice, and warns about a code above 128, which a process stopped by a signal also exits with.

Give a code a name and rotini generate writes a constant for it, named after the command, so a handler doesn’t repeat the number:

- name: get
  exit_status:
    - { code: 3, name: not_found, summary: no such task }
    - { code: 4, name: busy, summary: the store is locked, retryable: true }

rtx.HaltWithCode(TodoGetExitNotFound)

Names are snake_case and unique within a command. The man and markdown EXIT STATUS sections and the contract show them, and retryable: true tells callers such as agents that running the command again may succeed. The constants are in the cmd package, or in the models package when the conf declares one, re-exported in the cmd package. The check above reads a constant like its number, and warns when a handler uses another command’s constant: declare the code on the command that exits with it.

Linking exit codes to docs

docs_url on an exit_status entry links the code to a page about it. The man and markdown EXIT STATUS sections show the link, and the contract carries it. Help and the default reporter don’t print it. To print it when the command exits with that code, write a reporter: the generated Definition carries each code’s link as ExitStatusDef.DocsURL.

- name: get
  exit_status:
    - { code: 3, name: not_found, summary: no such task, docs_url: "https://todo.example/errors/not-found" }

A reporter can’t read the code a handler set, so the handler records it with the error:

package todo

import (
	"context"
	"errors"
	"fmt"

	"github.com/go-rotini/rotini"
)

// ExitError ends a command with one of its documented exit codes:
// rtx.HaltWith(&ExitError{Code: TodoGetExitNotFound, Err: err}).
type ExitError struct {
	Code int
	Err  error
}

func (e *ExitError) Error() string { return e.Err.Error() }
func (e *ExitError) Unwrap() error { return e.Err }

// ReportWithLinks prints warnings and errors to stderr, and after an ExitError the link its
// code declares, then exits with that code (1 for any other failure).
func ReportWithLinks(def rotini.Definition) rotini.Reporter {
	return func(ctx context.Context, rtx *rotini.Context, out rotini.Outcome) {
		for _, w := range out.Warnings {
			fmt.Fprintln(rtx.Stderr, "Warning:", w)
		}
		code := 0
		for _, err := range out.Errors {
			fmt.Fprintln(rtx.Stderr, "Error:", err)
			var exit *ExitError
			if errors.As(err, &exit) && code == 0 {
				code = exit.Code
				if url := docsURL(def, rtx.CommandChain(), code); url != "" {
					fmt.Fprintln(rtx.Stderr, "See", url)
				}
			}
		}
		for _, p := range out.Panics {
			fmt.Fprintln(rtx.Stderr, "Error:", p)
		}
		switch {
		case !out.Failed() || ctx.Err() != nil:
		case code != 0:
			rtx.Exit(code)
		default:
			rtx.Exit(1)
		}
	}
}

// docsURL returns the docs_url the invoked command declares for code, or "".
func docsURL(def rotini.Definition, chain []rotini.Command, code int) string {
	exits, cmds := def.ExitStatus, def.Commands
	for _, c := range chain[1:] {
		for _, d := range cmds {
			if d.Name == c.Name {
				exits, cmds = d.ExitStatus, d.Commands
				break
			}
		}
	}
	for _, e := range exits {
		if e.Code == code {
			return e.DocsURL
		}
	}
	return ""
}

Install it with the program’s own Definition: p := cmd.NewProgram(), then p.WithReporter(cmd.ReportWithLinks(p.Definition())).

Handling errors in a handler

An error about the user’s input, from rtx.Inputs, the per-source methods, rtx.CheckInputs or report.Validate, is one of two types:

• *rotini.ParseError: the command line, and validation of any value. Its Kind says what went wrong, Token holds the value at fault and Candidates what it could have been.
• *rotini.InputError: reading an environment variable, a config file or stdin. Channel and Input say which.

(rtx.Inputs can also return a *rotini.WiringError, for a fault in the program’s own setup rather than the input.) Wrapping an error with rotini.UsageError or rotini.InternalError changes only its category: errors.Is and errors.As still reach the original.

Branch on the type, the kind or the category, never on the message text, which can improve between releases:

inputs, err := rtx.Inputs[TodoAddInputs]()
if err != nil {
	var pe *rotini.ParseError
	switch {
	case errors.As(err, &pe) && pe.Kind == rotini.ParseKindMissingRequired:
		fmt.Fprintf(rtx.Stderr, "%s\nRun '%s --help' for usage.\n", err, rtx.CommandPath())
		rtx.HaltWithCode(2)
	case rotini.CategoryOf(err) == rotini.CategoryUsage:
		rtx.RecordError(err)
		rtx.HaltWithCode(2)
	default:
		rtx.HaltWith(err)
	}
	return
}

The kinds are ParseKindUnknownFlag, ParseKindUnknownCommand, ParseKindNeedsValue, ParseKindInvalidValue, ParseKindEnumViolation, ParseKindConstraintViolation, ParseKindMissingRequired, ParseKindNoArguments, ParseKindTooManyArguments, ParseKindMisplacedFlag and ParseKindInternal. ParseKindMisplacedFlag is a flag typed where it can’t apply: before a plugin’s name, where the plugin would never see it (todo --verbose sync is refused; todo sync --verbose passes --verbose to the plugin). A short-circuit flag such as --help and a directory flag are the exceptions: the program answers or applies them itself. This error reaches the reporter, not a handler.

Each response is one call:

• Point at help: print a hint built from rtx.CommandPath(), or the whole page with rtx.Help().
• Suggest a correction: rotini.NewSuggestor().For(err) returns the nearest candidates; see suggesting a correction.
• Choose the exit code: rtx.HaltWithCode(n). The first non-zero code wins, and the default reporter keeps it. rtx.HaltWithCode records no error, so print the error yourself (as the first branch does) or record it with rtx.RecordError for the reporter to print.
• Or just stop: rtx.HaltWith(err) records the error and leaves the code to the reporter.
• Or carry on: rtx.RecordError(err) records the error without stopping, so a handler can collect several and check rtx.Failed() later.

When an exit code means something, list it under the command’s exit_status:. Handle an error in the handler when the response depends on the command; for one policy across the whole program, use a reporter.

Suggesting a correction

When a user mistypes something from a fixed list, the error carries the word they typed and the words it could have been:

• a flag, a command, or a value outside a flag’s or argument’s enum: a *rotini.ParseError, in Token and Candidates;
• an environment variable or config value outside its enum: a *rotini.InputError, in Token and Candidates;
• a mistyped sub-command at a command with plugin_discovery: a *rotini.PluginError, in Name and Candidates. It reaches the reporter, not a handler.

rotini.NewSuggestor().For(err) reads them from any of the three and returns the nearest candidates, closest first, or nothing when none is close. The wording is yours:

if hits := rotini.NewSuggestor().For(err); len(hits) > 0 {
	fmt.Fprintf(rtx.Stderr, "Did you mean %q?\n", hits[0])
}

To rank them your own way, read them with rotini.SuggestionFacts(err), which returns the typed word, the candidates and whether err carried them:

if typed, candidates, ok := rotini.SuggestionFacts(err); ok {
	if best := closest(typed, candidates); best != "" {
		fmt.Fprintf(rtx.Stderr, "Did you mean %q?\n", best)
	}
}

WithMaxResults(n) caps how many suggestions For returns, and WithMinScore(s) sets how close one must be, from 0 to 1. Closest(typed, candidates) returns the single nearest. A secret input’s value is never offered for ranking. Rotini never prints a suggestion itself.

Printing the usage line

rtx.Usage() returns the usage line of the command whose hook is running, the line its help prints under Usage: (todo add [flags] <title>): the spec’s usage: when set, else the line rotini derives from the command’s shape. The generated Usage(path...) returns any command’s, by names or aliases, and is generated whether or not the help feature is on. Nothing prints the line by default. A reporter can print it after a usage error:

package todo

import (
	"context"
	"fmt"

	"github.com/go-rotini/rotini"
)

// ReportWithUsage prints warnings and errors to stderr, then the command's usage line after a
// usage error, and exits 1 when the run failed.
func ReportWithUsage(ctx context.Context, rtx *rotini.Context, out rotini.Outcome) {
	for _, w := range out.Warnings {
		fmt.Fprintln(rtx.Stderr, "Warning:", w)
	}
	for _, err := range out.Errors {
		fmt.Fprintln(rtx.Stderr, "Error:", err)
	}
	for _, p := range out.Panics {
		fmt.Fprintln(rtx.Stderr, "Error:", p)
	}
	if len(out.Errors) > 0 && rotini.CategoryOf(out.Errors[0]) == rotini.CategoryUsage {
		if u := rtx.Usage(); u != "" {
			fmt.Fprintf(rtx.Stderr, "Usage: %s\n", u)
		}
		fmt.Fprintf(rtx.Stderr, "Run '%s --help' for more.\n", rtx.CommandPath())
	}
	if out.Failed() && ctx.Err() == nil {
		rtx.Exit(1)
	}
}

$ todo add
Error: missing required input: <title>
Usage: todo add [flags] <title>
Run 'todo add --help' for more.

A command with a verbatim help: page still has the spec’s line, so the two can differ. In a handler, use rtx.Usage() rather than the generated function: a command composed from another spec then reports the line of the program it runs in. A schema named Usage would collide with the generated function, and rotini validate reports it.

Runtime control

How a run stops: on a signal, on a canceled context or a deadline, and after a panic, and how to give one run its own dependencies. What a run used is covered elsewhere: where each value came from and which deprecated spellings it used.

Signals and cancellation

By default Rotini traps Ctrl-C (SIGINT) and SIGTERM. The first signal cancels the run’s context and stops the run as rtx.HaltWithCode does: no further hook starts, the teardown of every hook whose setup ran still runs, and the run exits 128+n, so 130 for SIGINT and 143 for SIGTERM. A second signal exits 130 at once. Cancellation never interrupts a running hook, so a hook that waits on something passes ctx to it or checks ctx.Err().

Execute leaves Rotini’s handler registered until the process exits, so a signal that arrives after the run has finished is ignored and the process exits with the run’s code.

WithSignals() with no signals restores the default. Signals Rotini doesn’t trap keep Go’s behaviour: SIGHUP ends the process at once with no teardown (129), unless you add it to WithSignals or handle it yourself, and a write to a closed pipe, as in todo list | head -1, ends the program quietly with 141.

To stop a run with an exit code of your own, cancel its context with rotini.ExitCause:

//go:generate go tool rotini generate ./.rotini.spec.yaml --config ./.rotini.conf.yaml
package main

import (
	"context"
	"os"
	"syscall"
	"time"

	"github.com/go-rotini/rotini"
	cmd "github.com/me/todo/internal/cmd/todo"
)

var version = "0.0.0"

// main stops a run that takes longer than ten minutes with exit code 124, and still stops on
// Ctrl-C and SIGTERM.
func main() {
	ctx, cancel := context.WithCancelCause(context.Background())
	time.AfterFunc(10*time.Minute, func() { cancel(rotini.ExitCause(124)) })

	cmd.NewProgram().
		WithContext(ctx).
		WithSignals(os.Interrupt, syscall.SIGTERM).
		WithVersion(version).
		Execute()
}

A cancellation without an ExitCause stops the run the same way, and the exit code is decided as usual. The default reporter leaves out the error a signal’s cancellation caused; a custom reporter checks ctx.Err() to keep the code the run set.

Passing a context on

Every hook receives the run’s context.Context. A hook that derives one, to add a deadline or a tracing span, hands it to the hooks after it with rtx.SetContext, so a root --timeout can limit the command’s Run:

type todoHandler struct {
	rotini.NoPreRun
	rotini.NoPostRun
	cancel context.CancelFunc
}

func (h *todoHandler) CascadingPreRun(ctx context.Context, rtx *rotini.Context) {
	ctx, h.cancel = context.WithTimeout(ctx, 30*time.Second)
	rtx.SetContext(ctx)
}

func (h *todoHandler) CascadingPostRun(ctx context.Context, rtx *rotini.Context) {
	h.cancel()
}

• Later hooks get it, Run included, and so do their teardowns. A teardown gets the context its own setup hook received: the CascadingPostRun above gets the run’s context, never a deadline that has already passed.
• Keep the cancel function in a handler field and call it in the matching teardown. Handlers are created once per run, so the field belongs to this run.
• A derived context ending doesn’t stop the run. Check ctx.Err() in the hook and stop with rtx.HaltWith(err). A stdin read still waiting for data does end with it, returning an error the hook can halt with. Canceling the run’s own context still stops it between hooks. An ExitCause on a derived context sets no exit code: use rtx.HaltWithCode.
• Calls from a teardown change nothing, and the reporter always gets the run’s context. rtx.Context() returns the running hook’s context; read it in the hook.

A deadline after a signal

On Ctrl-C or SIGTERM, rotini cancels the run’s context and waits for the hooks and their teardowns to finish; a second signal exits at once with 130. A process that a supervisor stops with one SIGTERM can’t send the second, so a handler that ignores its context would keep it running. WithTerminationTimeout bounds the wait:

cmd.NewProgram().WithTerminationTimeout(10 * time.Second).Execute()

If the run hasn’t returned 10 seconds after the first signal, the program exits with that signal’s code (143 for SIGTERM, 130 for SIGINT), as a second signal would. The exit is abrupt: buffered stdout is flushed if it can be, but the remaining teardown doesn’t run and the reporter may not have printed. The timeout covers the reporter too, and it has no effect when rotini traps no signals (WithoutSignalHandling, or WithContext without WithSignals).

Panics

A panic in a hook is recovered: the hooks after it don’t start, teardown runs, and the reporter receives it in out.Panics as a *rotini.PanicError, whose Value is what was passed to panic and Stack the stack where it happened. The default reporter prints Fatal Error: <value> without the stack, and the run exits 1. A dependency that rtx.MustGetDependency can’t find panics with a *rotini.DependencyError, and faults in the program’s own wiring, such as a command with no handler, arrive the same way with no stack.

Two settings change this:

Re-raising is for a host that recovers panics itself, or for debugging. Only the hook’s own goroutine is covered: a panic in a goroutine a handler starts crashes the process. To print the stack on request, see a DEBUG variable; to save crash reports, see the recipe.

Per-run dependencies

Program.WithDependency gives every run the same value, which suits something built once in main.go. A dependency that depends on the command line, such as a client for the server a --endpoint flag names, is built in the root’s CascadingPreRun and set for that run only:

package todo

import "github.com/go-rotini/rotini"

// Client talks to the server --endpoint names.
type Client struct{ Endpoint string }

// clientDep is the run's client. Each run sets its own, so two runs in one process, such as
// parallel tests, never share one.
var clientDep = rotini.NewDependency[*Client]("todo.client")

// connect builds the run's client from its flags, from the root's CascadingPreRun. A client
// that a test registered with Program.WithDependency stays.
func connect(rtx *rotini.Context, in TodoInputs) {
	rtx.SetDependencyIfAbsent(clientDep, &Client{Endpoint: in.Todo.Flags.Endpoint})
}

The root handler calls connect(rtx, inputs) after reading its inputs, and a command reads the client with rtx.MustGetDependency(clientDep). Each run starts with a copy of the program’s dependencies, so rtx.SetDependency and rtx.SetDependencyIfAbsent never reach another run. SetDependencyIfAbsent keeps a value already registered, so a test that passes a double with NewProgram().WithDependency(clientDep, fake) gets it. rtx.GetDependency returns the value and whether it is set; rtx.MustGetDependency treats a missing one as a fault, which reaches the reporter as a panic.

What a program links

The generated NewProgram passes rotini.NewWiredProgram the runtime features its spec uses: rotini.Env() for env inputs, rotini.ConfigFiles() and rotini.YAML() for a YAML configuration file, rotini.URLValues() for a url flag, and so on. The program links only those, so a CLI that uses few of them builds a smaller binary that starts faster. go generate keeps the list in step with the spec. A config_files entry that a config_source input names links every config format, since the user may name any kind of file, unless the entry declares format:; rotini validate warns about it.

Code the spec does not describe can need a feature the list leaves out, for example a custom InputSettings.Sources entry, which needs rotini.ConfigFiles(). Add it in main.go:

cmd.NewProgram().
	WithFeatures(rotini.ConfigFiles(), rotini.TOML()).
	Execute()

A run that needs a feature its program does not wire fails with a *rotini.WiringError whose Feature names it, and the message says which constructor to add. Completion never reports it; it leaves out the candidates the missing feature would have offered. rotini.NewProgram and rotini.NewProgramFunc give a program every feature, so hand-built programs need no list.

Structured output

output: declares the shape of what a command writes. Rotini generates a Go type for it, documents it, and publishes it as JSON Schema for scripts and other tools.

Writing the output, in whatever format, stays the handler’s job: rotini adds no format flag. The helpers below for writing and checking output are optional, and a command without output: gets none of this.

Declare the shape

output: is a schema. Named shapes go under the root’s schemas:, and each becomes an exported Go type. The format is an ordinary flag, declared here on the root with cascading: true so every command’s help lists it:

command:
  name: todo
  schemas:
    Task:
      type: object
      required: [id, title, status]
      properties:
        id: { type: integer }
        title: { type: string }
        status: { type: string, enum: [open, done] }
    TaskList:
      type: object
      description: Every task, oldest first.
      properties:
        tasks: { type: array, items: { $ref: "#/schemas/Task" } }
  flags:
    # … the help and version flags `rotini init` declared
    - name: output
      summary: how to write the result
      identifiers: [-o, --output]
      cascading: true
      schema: { type: string, default: table, enum: [table, json, yaml, toml] }
  commands:
    - name: list
      summary: list tasks
      output: { $ref: "#/schemas/TaskList" }

rotini generate writes the types Task and TaskList, and TodoListOutput, the list command’s output type. A command that writes a stream of items, one at a time, declares the shape of one item.

An exit status can declare a shape too, for an outcome that still writes data:

command:
  name: todo
  exit_status:
    - code: 3
      summary: some tasks failed; stdout lists the ones that succeeded
      output: { type: array, items: { $ref: "#/schemas/Task" } }

Write it

Choosing a format is up to you; here it is the value of the --output flag above. rtx.WriteOutput is an optional helper that writes a value to stdout in the format you pass. It writes json (indented), yaml and toml itself, and hands any other format to your renderer. Pass nil as the renderer if you only ever use those three:

func (*todoListHandler) Run(ctx context.Context, rtx *rotini.Context) {
	in, err := rtx.Inputs[TodoListInputs]()
	if err != nil {
		rtx.HaltWith(err)
		return
	}
	if err := rtx.WriteOutput(TodoListOutput{Tasks: load()}, in.Todo.Flags.Output, renderTable); err != nil {
		rtx.HaltWith(err)
	}
}

func renderTable(w io.Writer, format string, v TodoListOutput) error {
	fmt.Fprintln(w, "ID  STATUS  TITLE")
	for _, t := range v.Tasks {
		fmt.Fprintf(w, "%-3d %-7s %s\n", t.ID, t.Status, t.Title)
	}
	return nil
}