cli

Documentation

Overview

Package cli is the cobra command tree for the dockyard CLI (RFC §9).

The CLI is one statically-linked, CGo-free binary — no npx, no Node, no package fan-out (RFC §9.1, brief 04 §3). It is a multi-verb tool built on spf13/cobra, the stack settled in RFC §9.3 (brief 06 §2.5): subcommands, generated help, shell completions, and gh/kubectl-familiar ergonomics.

Phase 17 shipped the command tree and `dockyard new`, the no-template project scaffold (RFC §9.1, §10); Phase 18 adds `generate` and `validate` (RFC §6, §9.4). The remaining verbs land in later Wave 7 phases and each registers itself onto the same root:

• `generate`, `validate` — Phase 18 (RFC §6, §9.4) — landed
• `dev` — Phase 19 (RFC §9.2)
• `build`, `run`, `install` — Phase 20 (RFC §14)
• `test` — Phase 21 (RFC §9.1, §9.4)
• `inspect` — the inspector phase (RFC §12)

The extension contract is deliberately simple: a later phase adds one file holding a `func newXxxCmd() *cobra.Command` constructor and one line in NewRootCmd that calls `root.AddCommand(newXxxCmd())`. No phase restructures the tree; each verb is self-contained.

Index

• Variables
• func Execute(ctx context.Context) int
• func NewRootCmd(stdout, stderr io.Writer) *cobra.Command
• func ResolvedVersion() string

Variables

var Version = "0.0.0-dev"

Version is the dockyard CLI version. It is overridden at build time via -ldflags -X by the release pipeline (internal/releasebuild); the in-tree default is a dev placeholder. Prefer ResolvedVersion() over reading this directly — it also recovers the module version from the build info for a `go install …@vX.Y.Z` binary, which carries no ldflags stamp.

Functions

func Execute

func Execute(ctx context.Context) int

Execute builds the root command and runs it against os.Args, returning the process exit code. main is a thin wrapper around it.

A command failure is logged through a log/slog text handler — the dev-mode handler mandated by CLAUDE.md §5 — and mapped to exit code 1. Execute never panics: a misuse surfaces as a typed error and a clean non-zero exit.

func NewRootCmd

func NewRootCmd(stdout, stderr io.Writer) *cobra.Command

NewRootCmd builds the root `dockyard` cobra command with every subcommand that has landed registered onto it. It is the single composition point: a later Wave 7 phase adds its verb with one root.AddCommand line here and one command-constructor file, never a tree restructure.

stdout/stderr are injected so the command tree is testable without touching the process streams; pass os.Stdout / os.Stderr in main.

func ResolvedVersion

func ResolvedVersion() string

ResolvedVersion returns the best-known CLI version, in order of confidence:

1. the -ldflags -X stamp (the release-pipeline cross-compiled binaries);
2. the module version from the build info (a `go install …@vX.Y.Z` binary — it has no ldflags stamp but Go records the module version);
3. the dev placeholder (a `make build` / `go build` from a checkout).

It is what `dockyard --version` reports and what `dockyard new` pins into a scaffolded go.mod's require directive (so the published-module path resolves without a hand edit).