commandkit/docs/consumers/guide.md

Consumer guide

CommandKit's currently implemented Go API is the root commandkit package. Start with an App, register CommandKit's standard inspection families, register application commands, and call App.Execute with the caller's context and streams. The caller retains process startup, signal handling, and exit mapping.

Go compatibility

The consumer minimum is declared in go.mod: Go 1.26.0. ReleaseKit v0.3.0 requires that version and is selected as a tool dependency in the same module graph. The minimum therefore applies to library consumers even though production packages do not import ReleaseKit. Consumers using Go 1.25 need a Go 1.26 or newer toolchain to adopt this revision.

The release policy defines support assumptions and versioning for changes to that minimum. Maintainers select their validation toolchain separately in the release procedure. Updating that toolchain's patch version alone leaves the consumer minimum unchanged.

A configuration scope

Use NewConfigKitScope to adapt one ConfigKit loader. The loader receives the invocation's explicit Selection; the application decides how those supplied config and overlay values map to its inputs.

scope, err := commandkit.NewConfigKitScope[appContext, appConfig](
	"app",
	"Application settings.",
	func(ctx context.Context, selection commandkit.Selection, app appContext) (*configkit.Result[appConfig], error) {
		return loadAppConfig(ctx, selection, app)
	},
)
if err != nil {
	return err
}
err = commandkit.RegisterConfig(app, commandkit.ConfigSuite[appContext]{
	Scopes: []commandkit.ConfigScope[appContext]{scope},
})

config show, config sources, and config explain use the configuration captured by that load. A scope can support only the operations it provides. When several scopes share invocation-local application state, create it in ConfigSuite.NewContext; use typed Selector bindings to copy only the values that apply to each scope. See the composed example for a cache shared by the app and promptkit scopes.

PromptKit configuration and definitions

Register NewPromptKitScope with the config suite when you want the effective PromptKit configuration and its ConfigKit provenance available under config. Register NewPromptKitSuite and RegisterPromptKit separately to enable promptkit show prompt and/or promptkit show profile. Each adapter calls the owning public inspection method and preserves acquisition diagnostics with a failed named lookup. Definition inspection does not invoke execution APIs or resolve provider credentials.

The composed example shares its ordinary app and engine-loading functions across the configuration and definition suites. It also keeps session restore as an application-owned typed command, including its session data and domain outcome mapping.

Typed application commands

Declare flags, operands, and a typed input struct with NewCommand. Bindings preserve whether a value was explicitly supplied, so an explicit zero can differ from an omitted default. RepeatFlag retains occurrence order. The simple example combines both features with a typed ConfigKit scope.

Outcomes and process exit

Handlers return Success, Failure, or an application-owned Outcome. The caller chooses how a nonzero status maps to process exit; Execute never exits the process. It writes CommandKit diagnostics to the supplied error stream and returns the resulting classification and delivery information. Applications keep their domain meanings and output in their own handlers.

Exact CommandKit contracts are documented on the exported declarations and their GoDoc comments. ConfigKit owns configuration decoding and provenance; consult its inspection API. PromptKit owns prompt formats and profile resolution; consult its public engine methods, configuration inspection, and inspection types.