Command DSL
Each part of a local group: a command that runs in the CLI and calls no API.
osapi cli command spec get prints the same list from this build.
Building a command tells how to write one.
Definition
Register(Define(name, doc, options...))
Declares a group of local commands and adds it to the registry. A local command runs in the CLI process and calls no API, such as osapi token generate. Its command is osapi <name>, and doc is its help.
Use: One time, in <group>.go under internal/cli/commands/<group>: var Group = command.Register(command.Define(...)). Add its import to internal/cli/commands/all. A command that calls the API is an endpoint or a behavior, not a local command.
Options of Define
Uses[Deps]()
Names the struct of what the group's methods use, such as the config, the file system or the signing of tokens. The CLI gives one with Provide when a command runs, and a test gives one with fakes.
Use: In each group. Keep it to interfaces, so a test can fake each one. An empty struct needs no wiring.
Long("text")
Is the rest of the help of the group's command, after its one line. A method's .Long is the help of its own command.
Use: When the group's command needs more than its one line, such as what each of its commands reads.
Fail()
Is the error a handler returns with its output when the output says what failed, such as the problems of a config: return out, command.Fail(). The output prints as it does on success, then the command exits 1 with no message of its own.
Use: For a check whose answer is the report, such as config validate, so a script or CI fails on it. For any other failure, return the error itself.
Flat()
Makes the group add no word of its own: each method is a command under the group's parent, the root or the words of Under. A command directly under the root has a word of command.Roots, such as version; any other has a verb or an action. The group's name stays its identity, for cli command get --name and its package.
Use: For a command that stands alone, such as osapi version, or that goes under a parent that holds other things, such as osapi controller start. Not for a family of commands under one noun, such as token.
SubDoc("segment", "short")
Is the one line of help of the command that a Sub segment makes, such as roles in osapi token roles list. validate fails a Sub segment that makes a command and has none.
Use: For each Sub segment of the group whose word is not the method's.
Under("word", ...)
Puts the group's command under the command of the words, such as controller for osapi controller endpoint. Attach makes a word that has no command, and uses a hand-written one that cmd/commands.go names.
Use: When the commands belong to a command that is there already, such as controller. Without it, the group is under the root.
Methods
Process("name")
A command, osapi <group> <name>, that runs a process until the command's context ends, such as osapi nats server start. It has no input and prints no output; .Setup sets what it runs. The context is the one the root makes and cancels on SIGINT or SIGTERM.
Use: For a command that starts a component and runs until a signal. Its name is an action, such as start.
.Setup(fn)
Is func(ctx context.Context, d D) (command.Running, error): it makes the process's components with ctx, the command's context, so a signal stops a setup that waits. Running is the components, each with Start() and Stop(ctx), and a Cleanup. command.Serve starts them, waits until ctx ends, stops them together, then runs Cleanup; the stop and the cleanup get context.WithoutCancel(ctx), which keeps its values, with command.ShutdownTimeout, 10 seconds. An error is the command's error, and it exits 1.
Use: On each Process, in place of .Handle. Make each component in Setup and start nothing: Serve starts them.
Then(running, fn)
Is running with fn after its Cleanup, such as the stop of a tracer, which flushes what the components recorded as they stopped.
Use: In a Setup that wraps the components of another, such as osapi start, which runs the NATS server, the controller and the agent under one tracer.
.Flag("key", ...)
Adds a flag to a process for each config key, such as agent.max_jobs: --agent-max-jobs, the key with its dots and underscores as dashes, as OSAPI_AGENT_MAX_JOBS is its environment variable. The flag has the key's type, default and doc, from the config, and sets the key over the environment and the file.
Use: On a Process, for each key a person sets when they start it. A Method's flags are its input, so it has no Flag.
Method[In, Out]("name")
A command, osapi <group> <name>, that takes In and prints Out. Each field of In is a flag. Out prints as JSON with --json, and from its type without it, by the output style of the CLI.
Use: For each command of the group. Its name is the command's last word: a verb (list, get, create, update, delete) or an action in command.Actions, never a noun.
Refinements of a method
.Handle(fn)
Sets the function that runs the command: func(ctx context.Context, d Deps, in In) (Out, error). The generated command reads the flags into In, checks it against its validate tags, and calls it. An error from it prints, and the command exits 1.
Use: On each method. Validate checks the signature.
.Short("text")
Sets the command's one line of help. It starts with a capital letter and has no period at the end; a test of every command holds this.
Use: On each method.
.Long("text")
Sets the rest of the command's help, in sentences.
Use: When a person needs more than the one line, such as what the command reads.
.Example("--flag value", "doc")
Adds an example of the command: the flags after osapi <group> <method>, and, when given, what it shows, as a # line above it. The help and the CLI page show each one.
Use: At least one for each method with input: the call a person makes most.
.Sub("segment")
Puts the command under a command of its own in the group: osapi <group> <segment> <method>, such as token roles list. The method's identity is its segment and its name, so a group can have get and spec get.
Use: When the command is about a noun of the group: the noun is the Sub, and the method is the verb.
.Says("state")
Sets what the one line of a method with no output says, after the key of the input: a state, such as draining. Without it, the line says the past tense of the method, such as admitted for admit. An endpoint method has the same refinement.
Use: On a method with no output whose result is a state, not the past tense of its name. validate fails a method with no output, no past tense and no Says.
.Fails("doc", in)
Declares an input that the command refuses with a usage error, exit code 2: the method's input, with the other fields valid and one rule broken. TestRefusals in internal/cli/commands/all runs each one.
Use: For each rule of each input field, required included, as validate requires.
Tags on input fields
json:"name"
Names the field, its flag (with _ as -) and its key in the JSON of the output.
Use: On each field.
doc:"..."
Is the help of the field's flag. A rule of oneof adds its values in brackets.
Use: On each input field: a capital letter first and no period at the end.
short:"r"
Gives the field's flag a one-letter shorthand, such as -r.
Use: When the CLI uses that shorthand for the flag elsewhere.
default:"value"
Gives the field's flag its value when the caller gives none. A field with a default is never a required flag.
Use: For an option with a value that most calls use.
validate:"..."
The rules of the value, which Run checks before the handler runs: a value that breaks one is a usage error that names the flag, and the command exits 2. required makes the flag required. The rules are those of internal/validation, which endpoints and behaviors use; dive applies the rules after it to each value of a []string. A custom rule, such as permission, is declared with rule.Declare.
Use: On each input field. A field with no limit is validate:"omitempty"; validate refuses an input field with no tag.
the type of a field
Is the kind of its flag: a string, a bool, an int, a []string (a flag given once for each value, or with commas), a map[string]string (key=value pairs) or a []byte (the path of a local file, whose content the field gets).
Use: Pick the type of the value a person types.
Output, from the output type
Render(p, group, out)
Prints the output of a method through a Printer, as the CLI prints it. The terminal and the pages of the docs site both use it, so a page written from a command's output shows what the command shows.
Use: To write an output somewhere other than the terminal, such as a page of the reference.
a list: Items []T, with TotalItems or not, or []T
Prints a heading with the count, such as Files (6):, then a table with one column for each field of T. A list with fewer items than TotalItems counts as (3 of 120). An empty list prints its heading with (0), then None. and the hint of its empty tag.
Use: For each method that returns a list. Name the fields Items and TotalItems, and add no other field.
one object
Prints a heading, then an aligned key-value block, one pair for each field. An object in it is a section under the block, with its label as the heading. A list in it is a table under the block, with its count. An object with one field that is an object or a list is an envelope: the value of the field prints, and the envelope does not.
Use: For each method that returns one thing.
no output
A method whose output type has no field, such as struct{}, or whose answer has no body (204), prints one line: the key of the input and what occurred, such as m-1 admitted. With --json, it prints nothing.
Use: For a write with nothing to return. The text is the past tense of the method, or what .Says gives.
the rules with no options
The columns and the keys have the order of the fields. A field with omitempty or omitzero and no value is not shown. A bool is yes or no. A float32 or float64 has two decimals, such as 0.00. A []string is its values, joined with commas. A time.Time is in the one time format of the CLI. A label is the json name in sentence case, with an initialism such as ID in capitals: machine_id is Machine ID. A column header is the label in capitals. A table leaves out a column that has no value in any row. In a table cell, an object is its values, with a space between them, such as Ubuntu 24.04. A list of objects is the first field of each, with commas, such as HighLoad, DiskPressure. The heading is the name of the group in sentence case, with s for a list.
Use: To change the order of the output, change the order of the fields.
render:"-|bytes|age|time|duration|duration=ms|status|short=N|body"
Changes how a field prints: - leaves it out (--json has it), bytes is a size such as 3.4 GB, age is the time since a time or a number of seconds, time is a time as text in the one time format, duration is a Go duration, duration=ms is an integer of milliseconds as a duration, status is a status word in its color, short=N is the first N characters with ... after them, in a table only: a key-value block shows all of the value, and body makes the field the whole output, as it is, such as the text of a document; the other fields are only in --json.
Use: On an output field whose raw value a person cannot read at a glance. validate fails a value that is not one of these.
label:"..."
Gives the field a different label, and the column the same text in capitals.
Use: When the json name does not say what the value is to a person, such as Last seen for registered_at.
none:"..."
Is the text of a field with no value: absent, null, empty or a zero time. A field with omitempty and a none tag is shown, with the text. A table keeps a column with a none tag, because no cell of it is empty.
Use: When no value means something, such as never for a time or (deleted) for a hash.
empty:"..."
On a list field: the hint that an empty list prints after None., such as Upload one with osapi client file upload.
Use: On each list that a person can add to, to tell what to do next.
prefix:"..."
Is text in front of each value of the field, such as @fact. in front of a fact key.
Use: When a person types the value with the prefix.
table:"-"
Leaves the field out of a table. The key-value block of a get shows it.
Use: On a field that a list does not need and a get does, such as a reason or a time of each change.
title:"..."
On the field _ struct{} of the output type: a different heading. The blank field is not in the JSON or the spec.
Use: When the name of the group is not what the output is, such as Stale deployments in the file group.
What a Deps takes
avfs.VFS
The filesystem, for a command that reads or writes files on the machine where it runs, such as a key or the config. cmd/commands.go gives the real one. A test gives memfs.New(), an in-memory filesystem, and reads what the command wrote from it.
Use: For each file that a command reads or writes. Never the os package, which a test cannot replace.
fs.FS
A read-only tree of files, such as the skills and templates that the binary embeds. A test gives fstest.MapFS with the files that it needs.
Use: For files that the binary carries, not files on the host.
config.Config, string
The config that osapi read, and plain values such as the path of the config file, a directory or the version. A test gives the value.
Use: For what the command reads and does not change. A value is not a service, so it needs no interface.
*slog.Logger
The logger of the process. A test gives slog.New(slog.DiscardHandler).
Use: For a process, such as osapi agent start, that logs while it runs. A command that prints its result returns it as its output instead.
func(...)
A function that the CLI gives, such as Behaviors, Validate or NewAgent: it reads the registry of this binary, or makes a part of the process. A test gives a function that returns what the case needs.
Use: For one call, or a constructor. When a test must check the calls that a part gets, make the part an interface, as Agent is, and return it from the function.
an interface of the group, in deps.go
A service with methods, such as Tokens, or a part that a constructor returns, such as Agent, Controller and Server. The tests give the mockgen mock from the group's mocks/, from go generate ./internal/cli/commands/<group>/mocks.
Use: For a service whose calls a test asserts. Never write a fake by hand: a fake does not fail on a call that the test did not expect.
*cobra.Command
The root command of the CLI, for a group that reads the tree of commands, such as cli docs and cli command.
Use: Only to read the commands of this binary.
another group's Deps
The Deps of a different group, for a command that runs that group's work, as osapi start runs the NATS server, the controller and the agent.
Use: For a command that is several other commands at one time. Each part keeps its own Deps.
Wiring
Provide[Deps](Group, fn)
Gives the group's methods their Deps: fn makes them when a command runs, after osapi read its config. A command of a group whose Deps has a field, and that has no Provide, fails.
Use: In cmd/commands.go, one time for each group whose Deps has a field, with the real config, file system or client.
What holds a group to its rules
Flaggable(type)
Whether a flag holds a value of the type: string, bool, int, []string, map[string]string or []byte, a file. The command generator builds a flag of each, and behavior validate asks it of each CLI behavior's input, so the two agree.
Use: Give an input field one of those types.
TagProblems(type)
Each output tag, such as render, that the output does not know, in the type and the types it holds: the check that cli command validate makes of a registered command. behavior validate asks it of each behavior's output, so its author sees the problem in the validator they run.
Use: Use a render value that cli command spec get lists.
osapi cli command validate
Checks every local group against the rules of a definition, and the output of every group: each output tag is one the output knows, and each method with no output says what occurred. Each problem names the rule and ends with its fix. validate --help lists each rule. go generate fails on a local group that breaks one.
Use: After each change to a group.
TestRefusals
Runs each input that a method's Fails declares through Run, as the generated command does, and expects a usage error.
Use: It is in internal/cli/commands/all, and covers each group with no change.
TestCommandShape
Holds each command under osapi client, and each command of a local group, to <resource> <verb>, with the verbs and actions of command.Verbs and command.Actions.
Use: It is in cmd/help_style_test.go. A new action goes in command.Actions; a noun does not.
go generate ./internal/cli/commands/all
Writes, for each local group, the cobra commands in gen/cli.go, and internal/cli/commands/all/gen, which registers every group's commands. cmd attaches them under the root.
Use: After each change to a group. go-generate-check fails when a gen/ file is stale. Never edit a gen/ file.
osapi cli command create --name <group> --description "..."
Writes a new group under internal/cli/commands/<group>: a list and a get, an empty Deps, its types and the tests of its methods, and adds its import to internal/cli/commands/all. It builds, validates and passes its tests; command-scaffold-check in just test holds it to that.
Use: To start a new group. Then run go generate ./internal/cli/commands/all and just cli-docs-generate, and change it.
osapi cli command get --name <group>
Describes a group, local, endpoint or behavior: each command and its one line of help. A local group's commands also have their flags and the inputs they refuse.
Use: To see a group's commands, and the flags and refusals of a local group.
osapi cli command list
Lists each command of the binary, and the layer that made it: command, endpoint, behavior, or hand-written.
Use: To see what a definition makes, and what is still written by hand in cmd/.
Generated, never edited
internal/cli/commands/<group>/gen/
The cobra commands of the group, from go generate ./internal/cli/commands/all.
Use: Change the definition, then generate. A generated file that is wrong is fixed in the definition or in internal/cli/command/gen.
internal/cli/commands/<group>/mocks/
The doubles of the group's Deps, from go generate ./internal/cli/commands/<group>/mocks.
Use: Run it again after deps.go changes.
internal/cli/commands/all/gen/
The import of each group's gen package, so the CLI registers its commands, from go generate ./internal/cli/commands/all.
Use: Change the definition, then generate.
docs/docs/sidebar/usage/cli/
The CLI pages, from just cli-docs-generate. The page of a local command comes from .Short, .Long, .Example and each input field's doc.
Use: Change the definition, then generate. Do not write a CLI page by hand.