cli

Documentation

Index

• Constants
• func Execute() error
• func FormatReference(ref Reference) string
• func ResolveVulnSourceKey() string
• func Run() int
• type Action
  • func (a Action) String() string
• type OutputFormat
• type PackageEntry
  • func CollectPackageEntries(pkgs registry.PackageIDs) []PackageEntry
• type PartialFailureError
  • func (e *PartialFailureError) Error() string
• type PendingChangesError
  • func (e *PendingChangesError) Error() string
• type Reference
  • func CollectReferences(cmd *cobra.Command, toolName string) ([]Reference, []string)
• type UsageError
  • func (e *UsageError) Error() string
  • func (e *UsageError) Unwrap() error

Constants

const (
	ExitOK             = 0
	ExitRuntime        = 1
	ExitUsage          = 2
	ExitPartialFailure = 3
)

Exit codes returned by Run. They follow the convention documented in docs/cli-conventions.md:

0 — success
1 — runtime error (default)
2 — usage error (bad flags / args)
3 — partial failure (some operations succeeded, some failed)

Functions

func Execute

func Execute() error

Execute is retained for callers that want a plain error. Prefer Run, which distinguishes usage / runtime / partial-failure exits.

Deprecated: use Run.

func FormatReference

func FormatReference(ref Reference) string

FormatReference renders a Reference as a single human-readable line for the text output of `klim info` and `klim why`. Both surfaces consume this directly so the surrounding wording — and any new Reference.Kind that gets added — stays in lockstep across the two commands. Required + optional refs both preserve their version constraint via roleWithConstraint.

func ResolveVulnSourceKey

func ResolveVulnSourceKey() string

ResolveVulnSourceKey returns the OSV endpoint string used as the cache key for vulnerability scan results. Surfaces that read the cache passively (`klim info`, web `/security`) must use the same key as `klim security vuln`, otherwise they look at a different file. Falls back to vuln.DefaultOSVURL when config is unreadable or the URL is unset.

func Run

func Run() int

Run executes the root command and returns a process exit code.

Exit codes:

0 — success
1 — runtime error
2 — usage error (bad flags, args, or output format)
3 — partial failure (e.g. some imports failed)

Cobra's own flag-parse errors are wrapped in UsageError via SetFlagErrorFunc on rootCmd, and "unknown command" / "unknown flag" errors that escape that hook are detected by message prefix here. All other errors map to ExitRuntime.

Types

type Action

type Action string

Action discriminates the three sibling action commands.

const (
	ActionInstall Action = "install"
	ActionUpgrade Action = "upgrade"
	ActionRemove  Action = "remove"
)

Action values match the subcommand verb so they can be used directly in log lines and JSON output.

func (Action) String

func (a Action) String() string

String returns the verb for human-readable headers.

type OutputFormat

type OutputFormat string

OutputFormat names the canonical output formats supported by commands.

AGENTS.md ("CLI Standards"): commands should expose `--output` for machine-readable output. klim adopts `--output={text,json,yaml}` as the canonical flag and keeps `--json` as a deprecated alias for backward compatibility.

const (
	OutputText OutputFormat = "text"
	OutputJSON OutputFormat = "json"
	OutputYAML OutputFormat = "yaml"
)

Output formats accepted by the canonical --output flag.

type PackageEntry

type PackageEntry struct {
	Source string `json:"source"`
	ID     string `json:"id"`
}

PackageEntry is one populated package-manager ID for a tool. Shared between `klim why` (AvailableVia) and `klim info` (Packages) so the list of supported sources cannot drift between the two commands the next time a package manager is added or renamed.

func CollectPackageEntries

func CollectPackageEntries(pkgs registry.PackageIDs) []PackageEntry

CollectPackageEntries returns the populated PackageEntries for pkgs in canonical display order. Empty IDs are skipped. Both `klim why` and `klim info` consume this so they list the same sources every time.

type PartialFailureError

type PartialFailureError struct {
	Succeeded int
	Failed    int
	Op        string
}

PartialFailureError signals a multi-item operation where some items succeeded and some failed. Run translates this to ExitPartialFailure.

func (*PartialFailureError) Error

func (e *PartialFailureError) Error() string

type PendingChangesError

type PendingChangesError struct {
	Op      string
	Pending int
}

PendingChangesError signals a non-failure outcome that should still map to ExitPartialFailure (exit 3). The canonical use case is `klim plan --detailed-exitcode` — there's no failure, but the diff is non-empty and the CI caller asked us to gate on that. Keeping this distinct from PartialFailureError avoids the misleading "0 succeeded, N failed" framing for an outcome that's really "N changes pending".

func (*PendingChangesError) Error

func (e *PendingChangesError) Error() string

type Reference

type Reference struct {
	Kind        string `yaml:"kind"                            json:"kind"`
	Name        string `yaml:"name,omitempty"                  json:"name,omitempty"`
	DisplayName string `yaml:"display_name,omitempty"          json:"display_name,omitempty"`
	Path        string `yaml:"path,omitempty"                  json:"path,omitempty"`
	Required    bool   `yaml:"required,omitempty"              json:"required,omitempty"`
	Constraint  string `yaml:"version_constraint,omitempty"    json:"version_constraint,omitempty"`
}

Reference describes a place where a tool is mentioned: the local .klim.yaml, a registered project's .klim.yaml, a marketplace pack, or a custom pack. It's the shared shape used by both `klim why` and `klim info` so the two commands cannot drift out of sync.

func CollectReferences

func CollectReferences(cmd *cobra.Command, toolName string) ([]Reference, []string)

CollectReferences scans the four sources where a tool name can appear (CWD-or-ancestor .klim.yaml, registered projects, marketplace packs, custom packs) and returns matched references plus any non-fatal warnings encountered along the way.

Both teamfile parses (local + registered) accumulate parse errors into warnings rather than silently dropping them — otherwise a malformed file could mislead the caller into reporting "no references found" when there really are some.

Pack lookups go through cliCtx via svcFrom(cmd) so tests can stub the service.

type UsageError

type UsageError struct{ Err error }

UsageError signals the user invoked the CLI incorrectly (missing/extra args, unknown flags, malformed input). Run translates this to ExitUsage.

func (*UsageError) Error

func (e *UsageError) Error() string

func (*UsageError) Unwrap

func (e *UsageError) Unwrap() error