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.