Files
commandkit/integrations/ckprompt/examples/composed

ConfigKit and PromptKit example

This example combines application and PromptKit configuration, resource inspection, request checks, and smoke tests. It uses local fixtures and an in-memory model client. No model service or credentials are required.

Use Go 1.27.0 on PATH. An aligned workspace containing all three local modules exercises their current sources; follow the workspace setup from the repository root. The current checkout requires the local ckconfig API; its published v0.9.0 dependency does not yet provide that API. The consumer guide owns version and compatibility details.

From the repository root:

cd integrations/ckprompt/examples/composed
export GOWORK=auto GOTOOLCHAIN=local
go run . config scopes
go run . promptkit list prompts --campaign spring
go run . promptkit show prompt briefing --campaign spring --format yaml

The first command lists app, storage, and promptkit configurations and their available operations. The next commands find and inspect the briefing prompt. --campaign is a selector supplied by this example, not a standard PromptKit flag.

Validate and compare configuration

go run . config validate --scope all --campaign spring --limit=0
go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml
go run . config show --scope storage --config fixtures/before.yml
go run . config diff --scope storage --config fixtures/before.yml --against-config fixtures/after.yml
go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring --against-campaign spring

The application scope requires --limit=0 when --campaign is supplied. The app comparison reports a changed default campaign and campaigns.spring.model. The PromptKit comparison selects spring on both sides and reports the changed profiles list as one value.

The two sides have independent selectors and overrides:

go run . config diff --scope app --campaign spring --limit=0 --against-campaign autumn --against-limit=0 --set '/campaigns/spring/model="left"' --against-set '/campaigns/spring/model="right"' --details

The application and storage scopes support --set here. The PromptKit scope does not advertise override support in this example. An aggregate operation that includes that scope rejects overrides.

List resources and select namespaces

go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml
go run . promptkit list backends --campaign spring
go run . promptkit list namespaces --campaign spring
go run . promptkit list collections --campaign spring
go run . promptkit list prompts --namespace field-notes --campaign spring
go run . promptkit show prompt briefing --campaign spring --prompt-namespace field-notes
go run . promptkit show profile spring --campaign spring

The profile list includes the selected autumn profile. PromptKit's default bundle contributes additional resources. The example also supplies a field-notes collection containing a backend, profile, and prompt. Listing filters and resource namespace flags let you inspect that collection.

Discover inputs, then check a request

go run . promptkit requirements show briefing --campaign spring
go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml

The first report is incomplete: the notes input is conditional and mode is missing. Supplying mode=full selects that branch and makes notes required. Both commands succeed; discovery alone does not establish that a request can run.

go run . promptkit requirements validate briefing --campaign spring --llm-input-file topic=fixtures/topic.txt
go run . promptkit requirements validate briefing --campaign spring --llm-input-file topic=fixtures/topic.txt --llm-var mode=full --llm-input-file notes=fixtures/notes.txt --format yaml

Both commands check request preparation and report prompt_id and valid: true. The builder provides campaign-specific variable defaults; the operator supplies the input files. For comparison, this command intentionally fails because the required topic input is missing:

# Intentional failure: missing topic input.
go run . promptkit requirements validate briefing --campaign spring

Preview a request with literal input instead of a file:

go run . promptkit show prepared briefing --campaign spring --input topic=sprint --profile spring --extra-params '{"campaign":"preview"}'

The preview includes rendered messages and effective provider settings. Validation and preview do not call the model or guarantee later execution.

Run smoke tests

go run . promptkit test text_inference --campaign spring --prompt briefing --profile spring
# Some diagnostics can fail or be unsupported; inspect the retained report.
go run . promptkit test all --campaign spring --llm-prompt briefing --llm-profile spring

Inference uses the example's in-memory client. HTTP checks may be unsupported or not applicable because the local backend has no network probe. The aggregate can return a failure while still showing results. Read the facts in the report; a successful command status does not mean every observation is positive.

For any command that returns nonzero, go run prints exit status N and itself exits with status 1. A built executable returns the application's status directly. The CLI reference explains the standard test kinds, results, and statuses.

Try aliases and application commands

go run . list collections --campaign spring
go run . pk list bundles --campaign spring
go run . pk show prompt briefing --campaign spring --fmt yaml
go run . smoke text_inference --campaign spring --llm-prompt briefing --llm-profile spring
go run . pk --hlep
go run . session restore session-42 --campaign spring
go run . request inspect --llm-prompt briefing --llm-profile= --llm-model example --llm-input-text topic=sprint --format json

The first two commands reach promptkit list collections. pk shortens the PromptKit group; --fmt is an alias on prompt inspection and --hlep is a global help alias. smoke shortens promptkit test while leaving the test kind as an argument. The session command uses an in-memory store. request inspect shows how an application command can reuse canonical --llm-* flag collections without installing PromptKit's short aliases.

Try shell completion

go build -o composed-example .
./composed-example completion bash

Initialize bash-completion if using Bash, then load the generated script using the CLI reference. Try completing composed-example pk show prompt briefing --fmt= or composed-example config show --config=fixtures/. The already-entered pk alias selects the command context without loading an engine.

How it is wired

The example installs ckconfig.Command(suite) and ckprompt.Declarations(definitions) with application-owned aliases in a []commandkit.Declaration. NewInput initializes scope inputs; NewState creates a cache shared within an invocation. The application composes PromptKit settings and resources into its ConfigKit load; the engine consumes the same result, and FromConfigKitSubtree exposes storage. The loaders cache successful configuration results by the complete configuration/overlay selection, overrides, and supplied campaign, including whether each value was supplied. These are example choices, not a CommandKit cache policy.

Smoke testing uses WithSmokeTesting with a nil builder, forwarding the request selected by flags. Applications can supply a builder to customize that request. See the consumer guide for suite composition, builders, and ownership, and the source for the complete application.

Run GOWORK=auto GOTOOLCHAIN=local go test ./... from this example directory for an aligned workspace check. Independent ckprompt validation against its declared requirements follows the coordinated ckconfig release.