Documentation
¶
Overview ¶
Package cli is the CLI shell over the Vellum library facade: it parses flags and calls vellum.Vellum's methods, and contains no business logic of its own — every decision about what a specification renders to, what a template declares, or what a binding does belongs to the packages this one wraps.
One file per verb group, per CLAUDE.md's package map: compose.go, validate.go, fill.go, inspect.go, boxes.go, capabilities.go, schema.go, provenance.go, and the mcp/doctor stubs. New assembles all of them into one *cli.Command tree; cmd/vellum/main.go is wiring only.
Exit codes ¶
CLAUDE.md and the PRD do not pin an exact convention, so this package states one, deliberately, since it is effectively public contract once a script depends on it:
0 success — the command ran and produced no errors. 1 the command ran, was itself well-formed, and the operation it asked the facade to perform failed: a rejected specification, a binding that would not reconcile, a template that would not open. The coded error is whatever the facade returned, unwrapped. 2 usage error — the command itself was malformed: an unrecognised --format value, a required flag or argument left unset, a file path that does not exist, or a flag combination this CLI refuses (see VELLUM_CLI_OUTPUT_CONFLICT). Nothing was attempted.
This mirrors the conventional Unix shape (getopt-style tools use 2 for a usage error) and gives a caller scripting against this CLI a way to tell "my input was bad" from "my invocation was bad" without parsing stderr.
Index ¶
Constants ¶
const ( // ExitOK is the process exit code for a command that ran without error. ExitOK = 0 // ExitFailure is the process exit code for a command that ran, was // itself well-formed, and reports that the operation it asked for // failed — a rejected specification, a template that would not fill. ExitFailure = 1 // ExitUsage is the process exit code for a command whose own invocation // was malformed: a bad flag, a missing argument, a file that does not // exist. Nothing was attempted. ExitUsage = 2 )
Variables ¶
This section is empty.
Functions ¶
func CodeOf ¶
CodeOf returns the process exit code err implies. A nil error is ExitOK; any error that is not an *ExitError is treated as ExitFailure, which is the conservative default for a failure this package did not classify.
func New ¶
New builds the root *cli.Command: every verb FR-U2 names, wired against the library facade. cmd/vellum/main.go's whole job is to call this and run the result — no flag parsing, no facade calls, no business logic live there, per CLAUDE.md's "The library is the deliverable; the CLI is an adapter."
Types ¶
type DoctorCheck ¶
type DoctorCheck struct {
// Name identifies the check, dot-separated and stable across releases —
// a consumer scripting against --json can key off it.
Name string `json:"name"`
// OK reports whether the check passed.
OK bool `json:"ok"`
// Detail is one line of human-readable context: what was found, or what
// is wrong.
Detail string `json:"detail"`
}
DoctorCheck is one diagnostic doctor ran: a name, whether it passed, and a one-line human-readable detail. It is the unit both the --json envelope's data and the human table are built from, so the two presentations can never name a different set of checks or disagree about which passed.
type DoctorReport ¶
type DoctorReport struct {
// OK is the AND of every check's own OK. A single failing check makes
// the whole report not OK, but every check still runs and is reported —
// doctor never stops at the first failure, so one broken theme does not
// hide an unwritable output directory behind it.
OK bool `json:"ok"`
// Checks is every diagnostic doctor ran, in a fixed declaration order
// (never a map range, per CLAUDE.md's determinism conventions), so the
// same environment produces the same ordering of rows on every run.
Checks []DoctorCheck `json:"checks"`
}
DoctorReport is every check doctor ran, plus the overall verdict.
func (*DoctorReport) Table ¶
func (r *DoctorReport) Table() [][]string
Table renders the report as rows of strings for [printTable]: a header row, then one row per check in DoctorReport.Checks's own order. A nil receiver still returns the header row so a caller need not nil-check before ranging the result — the same convention [template.InspectReport.AnchorsTable] establishes.
type ExitError ¶
ExitError pairs a process exit code with the error that produced it.
urfave/cli/v3's own os.Exit-on-ExitCoder machinery is deliberately not used: it would exit the process before this package had a chance to write a --json error envelope to stdout, which the Output Format Contract requires happen even on failure. Every Action in this package returns a plain error (already reported to the right stream by the Action itself) wrapped in one of these, and cmd/vellum/main.go reads the code back out with CodeOf after urfave/cli/v3.Command.Run returns.
Source Files