71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# Core example
|
|
|
|
This example shows typed flags, command shortcuts, shared reporting, and shell
|
|
completion. It needs no external service. See the [consumer guide](../../docs/consumers/guide.md#go-compatibility)
|
|
for Go requirements; maintainers use the toolchain in the
|
|
[developer guide](../../docs/development.md#documentation-validation).
|
|
|
|
Run from the repository root, with that Go toolchain on `PATH`:
|
|
|
|
```sh
|
|
export GOWORK=off GOTOOLCHAIN=local
|
|
go run ./examples/core workspace greet --count=2
|
|
```
|
|
|
|
The result shows the selected count and whether it was supplied. It also shows
|
|
the entered command path and the original command path, which differ when you
|
|
use a shortcut.
|
|
|
|
## Try shortcuts and explicit values
|
|
|
|
```sh
|
|
# The hello shortcut runs workspace greet; --times means --count.
|
|
go run ./examples/core hello --times=0 --tag=first
|
|
# ws is a shortcut for the workspace group.
|
|
go run ./examples/core ws greet --count=2
|
|
# Inspect the group or use the example's global help alias.
|
|
go run ./examples/core ws --help
|
|
go run ./examples/core hello --hlep
|
|
```
|
|
|
|
An explicit zero remains a supplied value. The handler prints both
|
|
`Invocation.EnteredPath()` and `Invocation.CanonicalPath()` so you can see how
|
|
shortcuts resolve.
|
|
|
|
## Try reporting
|
|
|
|
```sh
|
|
go run ./examples/core report
|
|
go run ./examples/core report --verbose
|
|
go run ./examples/core report --quiet
|
|
```
|
|
|
|
The default scenario succeeds and writes its result. Verbose mode also shows
|
|
warnings and information; quiet mode hides the result. The
|
|
[CLI reference](../../docs/cli.md#reporting) defines the shared visibility rules.
|
|
|
|
## Try shell completion
|
|
|
|
```sh
|
|
go build -o core-example ./examples/core
|
|
./core-example completion bash
|
|
```
|
|
|
|
This prints the Bash completion script. Initialize `bash-completion`, then load
|
|
the script as described in the [CLI reference](../../docs/cli.md#shell-completion).
|
|
Use the executable basename `core-example` and try completing
|
|
`core-example report d` or `core-example ws gr`. Other supported shells are
|
|
listed in the reference.
|
|
|
|
## How it is wired
|
|
|
|
The example installs `workspace greet` alongside command and flag aliases in a
|
|
`[]commandkit.Declaration`. It also installs `Completion("core-example")` and
|
|
provides static choices for the reporting scenario argument. The
|
|
[consumer guide](../../docs/consumers/guide.md#application-owned-aliases)
|
|
explains declaration composition; the [composed example](../../integrations/ckprompt/examples/composed)
|
|
adds integration commands.
|
|
|
|
Run `GOWORK=off GOTOOLCHAIN=local go test ./examples/core` from the repository
|
|
root to check this example.
|