91 lines
3.1 KiB
Markdown
91 lines
3.1 KiB
Markdown
# ConfigKit example
|
|
|
|
This example adds configuration inspection and a custom `greet` command to a
|
|
small application. It uses local fixtures and in-memory defaults, with no
|
|
external services. See [module selection](../../../../docs/consumers/guide.md#module-selection)
|
|
for dependencies and Go requirements. Use Go 1.27.0 on `PATH` for this checkout.
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
cd integrations/ckconfig/examples/simple
|
|
export GOWORK=off GOTOOLCHAIN=local
|
|
go run . config show
|
|
```
|
|
|
|
The output includes the default greeting, `Hello`, and schema version 2.
|
|
This example can run against its declared released dependencies with the
|
|
workspace disabled.
|
|
|
|
## Inspect and override a value
|
|
|
|
```sh
|
|
# Discover configuration paths under schema.
|
|
go run . config explain --list --under /schema
|
|
# Change the greeting for this invocation and show just that value.
|
|
go run . config show --path /greeting --set '/greeting="Hi"'
|
|
```
|
|
|
|
The second command prints `Hi`. It does not edit a file.
|
|
|
|
## Compare configurations
|
|
|
|
```sh
|
|
go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml
|
|
```
|
|
|
|
The report includes `changes.greeting: Goodbye`.
|
|
|
|
```sh
|
|
# Expected status 3: the overridden greeting differs from the ordinary default.
|
|
go run . config diff --set '/greeting="Hi"' --details --check
|
|
```
|
|
|
|
This compares the overridden left side with ordinary configuration on the
|
|
right. `go run` prints `exit status 3` and itself exits with status 1; a built
|
|
executable returns the application's status 3 directly.
|
|
|
|
## Inspect warnings and failed loads
|
|
|
|
```sh
|
|
# Schema version 1 produces a warning, visible in verbose mode.
|
|
go run . config show --config fixtures/before.yml --verbose
|
|
# Quiet mode hides the configuration report and warning.
|
|
go run . config show --config fixtures/before.yml --quiet
|
|
```
|
|
|
|
Ordinary mode hides the warning but still displays configuration.
|
|
|
|
```sh
|
|
# Intentional failure: show detailed validation findings for the invalid fixture.
|
|
go run . config validate --config fixtures/invalid.yml --details --severity error
|
|
# Intentional failure: still show the source recorded before loading failed.
|
|
go run . config sources --config fixtures/invalid.yml --source-id source-1
|
|
```
|
|
|
|
Both commands retain the load failure. `source-1` belongs to this fixture's
|
|
load; other configurations can have different source IDs. See the
|
|
[CLI reference](../../../../docs/cli.md#configuration-scopes) for report and status rules.
|
|
|
|
## Try a custom command
|
|
|
|
```sh
|
|
go run . greet
|
|
go run . greet --count=0 --tag=first --tag second
|
|
```
|
|
|
|
The handler reports its greeting, count, and tags. It distinguishes an omitted
|
|
count from an explicitly supplied zero and preserves repeated tag order.
|
|
|
|
## How it is wired
|
|
|
|
One ConfigKit scope supplies the standard `config` commands. Without `--config`,
|
|
its loader uses an in-memory default. Supplied configuration and overlay values
|
|
are passed to ConfigKit unchanged. The scope enables temporary overrides and
|
|
passes them into its ordinary ConfigKit load. The
|
|
[consumer guide](../../../../docs/consumers/guide.md#configkit-scopes) explains
|
|
loader and scope setup.
|
|
|
|
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` from this example directory to
|
|
check it against its declared dependencies.
|