cmd

Documentation

Overview

Package cmd wires the cobra command tree for the civitai CLI.

Index

• Variables
• func NewRootCmd() *cobra.Command
• func SetBuildInfo(v, c, d string)
• type ExitCodeDoc
  • func ExitCodeDocs() []ExitCodeDoc

Variables

var (
	// ErrInsufficientBuzz marks a refusal for lack of spendable Buzz — whether
	// caught locally against the balance or reported by the server.
	ErrInsufficientBuzz = errors.New("insufficient Buzz")
	// ErrGenerationDisabled marks generation being switched off server-side (or
	// restricted to members). Not the caller's fault and not fixable by them.
	ErrGenerationDisabled = errors.New("generation disabled")
	// ErrAccountRestricted marks a muted account or an incomplete onboarding —
	// the two failures that read byte-identical to a missing scope.
	ErrAccountRestricted = errors.New("account restricted")
	// ErrPromptBlocked marks a prompt the content audit refused. 🔴 A caller must
	// NEVER retry this: repeated blocked prompts increment a 30-day counter that
	// auto-mutes the account.
	ErrPromptBlocked = errors.New("prompt blocked")
	// ErrModelSubstituted marks a run refused by --fail-on-substitution because
	// the server reported it would run a different checkpoint than the one asked
	// for. It is raised BEFORE the submit, so nothing has been spent.
	//
	// It is a distinct sentinel rather than a usage error because it is not a
	// mistake in the command line: the invocation was well-formed and the server
	// answered it — what failed is an expectation about WHICH MODEL runs, and a
	// script needs to tell that apart from a typo'd flag.
	ErrModelSubstituted = errors.New("model substituted")
)

Classification sentinels for generation failures that the HTTP-status mapping alone gets wrong. They carry NO user-visible text: they are ATTACHED via civitai.Tag so errors.Is reports the KIND while the printed message is whatever classifyGenerateError composed.

🔴 Why they exist: civitai.TagStatus maps BOTH 401 and 403 to civitai.ErrUnauthorized -> exit 3, documented as "login required / credential lacks scope". A muted account and an incomplete onboarding both arrive as a bare 403, so without this a restricted user is told to re-run `civitai login` — forever. Changing statusKind was not an option: it would silently move the exit code of every other command.

None of these is mapped in cmd/civitai's exitCode, so they all land on the GENERIC exit 1 — deliberately distinct from 3 (auth) and 2 (usage), neither of which describes them. They are still errors.Is-assertable, which is what pins the contract.

var ErrDirtyWorkTree = errors.New("the packaged directory has uncommitted changes")

ErrDirtyWorkTree classifies the dirty-tree refusal. Like ErrVersionRegression it carries no user-facing text of its own — it is ATTACHED to the message-bearing error, so errors.Is reports the KIND while the printed message is unchanged.

🔴 EXIT CODE 1, THE SAME VERDICT #412's REFUSAL TAKES, AND FOR THE SAME REASON. Exit 2 is documented as a mistake about the INVOCATION, and every flag, argument and path is well-formed when this fires: `civitai app submit --yes` in a directory that exists, holding a manifest that validates. What is wrong is the PROJECT — its working tree relative to its own history — which is the shape exitCodeDocs already publishes under code 1 as a validation verdict. Leaving it untagged for the exit mapper's `default` is what produces 1; TestDirtyWorkTreeExitsGeneric (cmd/civitai) pins it so the code cannot drift.

var ErrListingBlocked = errors.New("listing not ready to publish")

ErrListingBlocked is the sentinel `app doctor` returns when at least one BLOCKING problem was found. It carries the non-zero exit, and nothing else — the findings have already been printed by the time it is returned.

🔴 EXIT 1, AND THAT IS A DECISION RATHER THAN A FALLTHROUGH. Exit 2 is documented as a mistake about the INVOCATION, and every flag and argument is well-formed when this fires; what is wrong is the LISTING. That is the same shape as an invalid manifest, which exitCodeDocs already publishes under code 1 as a validation verdict, and it is the code `app validate` uses for the same reason. It is deliberately left UNTAGGED for the exit mapper (tagging it civitai.ErrBadRequest — the only route to exit 2 — would move it), which TestDoctorBlockingExitsGeneric in cmd/civitai is what makes deliberate.

var ErrOnsiteTextNotEditable = errors.New("this app's listing text is manifest-governed")

ErrOnsiteTextNotEditable is returned when `set-text` is pointed at an ON-SITE listing, whose tagline/description/category are manifest-governed. It carries the exit code and nothing else; the message names the remedy.

A named sentinel rather than a bare error so the exit-code contract can be asserted with errors.Is rather than by matching prose — AGENTS item 7.

var ErrUsage = errors.New("usage error")

ErrUsage classifies a command-line USAGE error — a bad flag or malformed invocation — as distinct from a runtime failure. It carries no visible text of its own: it is attached to Cobra's own flag-parsing error (see NewRootCmd's SetFlagErrorFunc) so that errors.Is(err, ErrUsage) is true while the message the user sees stays exactly what Cobra produced. The process entrypoint (cmd/civitai) maps it to a dedicated exit code.

var ErrVersionRegression = errors.New("submitted version is not greater than the highest approved version")

ErrVersionRegression classifies the monotonic-version refusal. It carries no user-facing text of its own — it is ATTACHED (civitai.Tag) to the message-bearing error, so errors.Is reports the KIND while the printed message is unchanged.

🔴 EXIT CODE 1, NOT 2, AND THAT IS DELIBERATE. It is intentionally NOT tagged with civitai.ErrBadRequest (the only route to exit 2 from a command error): exit 2 is documented as a mistake about the INVOCATION, and every flag, argument and path here is well-formed. What is wrong is the PROJECT — the manifest's version relative to what is published — which is the same shape as an invalid manifest, and exitCodeDocs already publishes a validation verdict under code 1. Leaving it untagged for the exit mapper's `default` is what produces 1; TestVersionRegressionExitsGeneric (cmd/civitai) pins it so the code cannot drift silently.

Functions

func NewRootCmd

func NewRootCmd() *cobra.Command

NewRootCmd builds the root command with all subcommands attached.

func SetBuildInfo

func SetBuildInfo(v, c, d string)

SetBuildInfo lets main inject the build version, commit, and date. Goreleaser release binaries pass real ldflag values, which are authoritative. For a plain `go install github.com/civitai/cli/cmd/civitai@latest` (or any source build), the ldflags are absent and the injected values are still the "dev" defaults — in that case we fall back to runtime/debug.ReadBuildInfo so `civitai version` reports the module version (e.g. v0.1.1 or a pseudo-version) and the embedded VCS revision/time instead of dev/none/unknown.

Types

type ExitCodeDoc

type ExitCodeDoc struct {
	Code    int
	Summary string
	Detail  []string
}

ExitCodeDoc is the documented meaning of one process exit code.

Summary is the SHORT text, rendered into BOTH surfaces: `--help` (with markdown emphasis stripped) and the README table cell, verbatim. Detail is the long text, rendered into the README's per-code subsection ONLY — one bullet per entry. See the file header for why the terminal gets the summary.

Nothing `--help` says can therefore contradict the README: the summary line it prints IS the README's table row, from one string.

func ExitCodeDocs

func ExitCodeDocs() []ExitCodeDoc

ExitCodeDocs returns a copy of the exit-code contract, for callers outside this package (cmd/civitai pins its constants against it).