Here's an example:
List projects in an organization
Usage:
harness list project [parentid] [flags]
Flags:
--all Fetch all pages (incompatible with --offset and --limit)
--columns string Columns to display by ID or expr, e.g. "name,org" or "+sparkline" or "Name:it.name"
--count Print total item count and exit (incompatible with --offset, --limit, --all)
--format string Output format: json, yaml, jsonl, table, csv, tsv
-h, --help help for project
--json Output as JSON (shorthand for --format json)
--level string Scope level: project, org, or account (overrides prefix on id)
--limit int Return at most N items
--list-columns Print available column IDs and exit (use with --columns to customize output)
--no-headers Suppress column headers (table/csv/tsv) and paging footer (table)
--offset int Skip the first N items (item-level)
-o, --out string Write output to file instead of stdout
--raw Output the full raw API response (only with --format json)
--search string Filter projects by name
--ui Launch interactive TUI (requires a TTY)
--yaml Output as YAML (shorthand for --format yaml)
Global Flags:
--debug Enable debug logging
--org string Harness org identifier (overrides profile default)
--profile string Auth profile to use
--project string Harness project identifier (overrides profile default)
--timeout float Command timeout in seconds (0 = no timeout, e.g. 1.5)
Framework flags like --all, --count, --format, --json, etc. are all getting mixed into the "Flags" section even though those are "Verb" or "Global" level flags. This is a mechanical problem due to us adding those flags on the final "command" itself (because some are optional or conditional). Even though they are conditional, the help should not group them in the generic "Flags" section because this makes it much harder to actually parse out which flags are specific to this command.
An AI Agent must read through all those flags even though the bulk of those are generic global flags that work the same across a whole class of commands/nouns.
We might also consider whether to even list global/verb level flags at all since it increases token usage. These flags could be documented on list --help or in the root help, and not duplicated on each command (this will need Agent testing to verify that it does not reduce AI's effectiveness).
Here's an example:
Framework flags like --all, --count, --format, --json, etc. are all getting mixed into the "Flags" section even though those are "Verb" or "Global" level flags. This is a mechanical problem due to us adding those flags on the final "command" itself (because some are optional or conditional). Even though they are conditional, the help should not group them in the generic "Flags" section because this makes it much harder to actually parse out which flags are specific to this command.
An AI Agent must read through all those flags even though the bulk of those are generic global flags that work the same across a whole class of commands/nouns.
We might also consider whether to even list global/verb level flags at all since it increases token usage. These flags could be documented on
list --helpor in the root help, and not duplicated on each command (this will need Agent testing to verify that it does not reduce AI's effectiveness).