commands

package
v0.2.16 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package commands holds the implementations behind the declared commands.

Declaration and implementation are separate packages on purpose. The registry describes what a command is: its risk, its flags, its examples, its error codes. This package describes what it does. Keeping them apart means the registry stays a pure data structure that anything can import, including the schema generator, the help renderer and the documentation build, without dragging in an HTTP client.

The two are joined by the command path. A declaration with no handler is a command that is documented but not yet implemented, which the CLI reports honestly rather than pretending to work.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Flags

type Flags map[string]any

Flags is parsed flag values, keyed by flag name without dashes.

The accessors below return zero values for absent flags rather than an error. A flag that was declared always exists; one that was not is a programming mistake caught by the golden tests, not something a handler should have to check on every line.

func (Flags) Bool

func (f Flags) Bool(name string) bool

func (Flags) String

func (f Flags) String(name string) string

func (Flags) Strings

func (f Flags) Strings(name string) []string

Strings returns a repeatable flag's values, in the order they were given.

Order is part of the contract for anything a caller can pass twice: the last --env for a key is the one that means something, and a reader who wrote them in that order expects that.

type Handler

type Handler func(ctx context.Context, req Request) (output.Table, error)

Handler runs one command and returns a renderable result.

It returns data rather than printing, which is what lets the same function produce a terminal table, a JSON object and an NDJSON stream without knowing which one the caller wants.

func Lookup

func Lookup(path []string) (Handler, bool)

Lookup finds the handler for a command path, if one exists.

type Request

type Request struct {
	CLI   *cli.Context
	Args  []string
	Flags Flags

	// GivenFlags is which flags the caller actually wrote, read through Given.
	GivenFlags map[string]bool
}

Request is everything a handler receives.

Args and Flags arrive already parsed, so a handler never touches cobra and can be called from anywhere: a test, and later an MCP tool server.

func (Request) Given

func (r Request) Given(flag string) bool

Given reports whether a flag was written, rather than left at its default.

Most commands never need this: a flag that was not given and one given as an empty string both arrive as "" and both mean the same thing. It exists for the ones where the empty string is itself a value. `build set --start-command ""` clears the start command, and not passing the flag at all has to leave it exactly as it was; without this the two are the same request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址