Skip to content

feat(cli)!: tidy --help output and make search a real command #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jpage-godaddy merged 3 commits into from
Jul 30, 2026
Merged

feat(cli)!: tidy --help output and make search a real command #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b80f0d4
feat(cli)!: tidy --help output and make search a real command
jpage-godaddy Jul 30, 2026
8fb6887
fix(cli): give the conditional --env flag an explicit display_order
jpage-godaddy Jul 30, 2026
cfd24ca
fix(cli): warn on stderr for an unresolvable --scope; close order-con…
jpage-godaddy Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions docs/argv0-dispatch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,7 @@ my-cli argv0 pl --team platform # dispatch as if invoked as `pl`
my-cli argv0 legacy-tool ... # dispatch the `legacy-tool` personality
```

It is recognized as the first argument after the program name, is never registered with `clap`, and
so never appears in `--help`, `tree`, or `--search`. It is active only when the application has
registered at least one route.
It is recognized as the first argument after the program name, is never registered with `clap`, and so never appears in `--help`, `tree`, or the `search` command. It is active only when the application has registered at least one route.

Unlike the silent symlink fall-through, an **explicit** `argv0` invocation is strict: an unknown
name, or a bare `argv0` with no name, exits non-zero with an error listing the known names. This
Expand Down
5 changes: 1 addition & 4 deletions docs/concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,6 @@ populate middleware:
| `--reason` | `reason` | empty | Reason passed to authorization, audit, and activity. Only registered when `CliConfig` has an `authz`, `auditor`, or `activity` hook configured directly (not via `init_deps`, which runs after flag registration) — apps with none of those simply don't have the flag. |
| `--timeout` | `timeout` | `0s` | Command deadline (e.g. `60s`, `5m`); default `0s` = no timeout. |
| `--debug` | `debug` | empty | Enables debug components (comma-separated patterns). Bare `--debug` enables all; a specific value uses the `=` form: `--debug=transport`, `--debug='*,-auth'`. `transport` dumps HTTP requests/responses to stderr. See [HTTP debug logging](#http-debug-logging). |
| `--search` | `search` | empty | Searches command and guide documentation before command execution. |

Applications can add additional global flags through `CliConfig::register_flags` and copy parsed
values into middleware through `CliConfig::apply_flags`.
Expand Down Expand Up @@ -659,9 +658,7 @@ The renderer only recognizes `* `-prefixed bullets (with 0–3 leading spaces fo

## Search

`--search` searches command metadata, aliases, guides, and extra registered search documents. Search
short-circuits normal command execution so users and agents can find help without satisfying command
flags.
`search <query...> [--scope <path>]` is a built-in command (alongside `help`, `guide`, `tree`, and `completion`) that searches command metadata, aliases, guides, and extra registered search documents (`CliConfig::with_extra_search_docs`). `<query...>` accepts multiple words without quoting (`app search deploy pipeline`); quoting still works the same way (`app search "deploy pipeline"`) since both forms are just joined with spaces. `--scope` limits results to one command subtree using the same colon-separated path form as elsewhere (`--scope domain` or `--scope domain:list`), resolving aliases the same way a real command path would; an unresolvable scope falls back to an unscoped (root) search rather than erroring.

## Transport

Expand Down
5 changes: 1 addition & 4 deletions docs/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,7 +250,6 @@ Framework global flags populate middleware and apply consistently to every comma
| `--reason` | Reason passed to authorization, audit, and activity. Only registered when `CliConfig` has an `authz`, `auditor`, or `activity` hook configured directly (not via `init_deps`, which runs after flag registration). |
| `--timeout` | Command deadline (e.g. `60s`, `5m`); default is no timeout (`0s`). |
| `--debug` | Debug selector for integrations that use it. |
| `--search` | Searches command and guide documentation before command execution. |
| `--version`, `-v` | Prints version/build metadata. |

Applications can add their own global flags with `CliConfig::with_register_flags` and copy parsed
Expand Down Expand Up @@ -377,9 +376,7 @@ available for simple or dynamic cases.
Guides are markdown documents registered globally or by module. They can come from filesystem paths,
embedded `(path, bytes)` pairs, or explicit `GuideEntry` values.

`--search` indexes command metadata, aliases, guide content, and extra registered search documents.
Search bypasses normal command execution so users and agents can discover commands without
satisfying required command flags.
`search <query...> [--scope <path>]` is a built-in command that indexes command metadata, aliases, guide content, and extra registered search documents. `<query...>` accepts multiple words without quoting. `--scope` limits results to one command subtree (e.g. `--scope domain:list`).

## Transport

Expand Down
Loading