Analyzes all workflows in the repository to determine which secrets
are required, checks which ones are already configured, and interactively
prompts for any missing required secrets.
```
**Issue**: Every other command uses **imperative** form (e.g., "Analyze", "List", "Show", "Download", "Compile"), but `secrets bootstrap` uses third-person present tense ("Analyzes"). This is inconsistent with the entire CLI.
**Suggested Fix**: Change the `Long` description in `pkg/cli/tokens_bootstrap.go` to start with:
```
Analyze all workflows in the repository to determine which secrets
are required, check which ones are already configured, and interactively
prompt for any missing required secrets.
```
---
#### 2. `list` and `status` Under Wrong Category in Main Help
**Commands Affected**: `gh aw list`, `gh aw status`
**Priority**: Medium
**Type**: Misleading categorization
**Current Output** (from `./gh-aw --help`):
```
Development Commands:
compile Compile agentic workflow Markdown files into GitHub Actions YAML
domains List network domains configured in agentic workflows
fix Apply automatic codemod-style fixes to agentic workflow files
list List agentic workflows in the repository
mcp Manage MCP (Model Context Protocol) servers
status Show status of all agentic workflows in the repository
validate Validate agentic workflows without generating lock files
```
**Issue**: `list` and `status` are passive read-only monitoring/observation commands, not development commands. The documentation (`cli.md`) correctly categorizes them under "Monitoring". Having them under "Development Commands" in the CLI is confusing — users looking for "how do I see what's happening?" would look in Analysis or Monitoring, not Development.
Compare with the main help's existing "Analysis Commands" group that already has `audit`, `checks`, `health`, and `logs` — `status` and `list` belong there or in a new "Monitoring Commands" group.
**Suggested Fix**: Move `list` and `status` from the "Development Commands" group to "Analysis Commands" (or a new "Monitoring Commands" group) in `pkg/cli/commands.go` (or wherever command groups are defined).
---
#### 3. `fix` — Internal Codebase Path Exposed in Help Text
**Command Affected**: `gh aw fix`
**Priority**: Medium
**Type**: Internal implementation detail exposed to users
**Current Output** (from `./gh-aw fix --help`):
```
With --write, the command performs all steps and additionally:
4. Write updated files back to disk
5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists
6. Delete old template files from pkg/cli/templates/ if present
7. Delete old workflow-specific .agent.md files from .github/agents/ if present
```
**Issue**: `pkg/cli/templates/` is an internal Go source directory in the repository. End users would never have this path on their systems. Seeing it in help text is confusing (they may think they need to create this directory) and exposes implementation details.
Steps 5 and 7 reference paths that make sense to users (`.github/aw/schemas/` and `.github/agents/` are in the user's repository). Step 6 references a path inside the `gh-aw` source code itself.
**Suggested Fix** in `pkg/cli/fix_command.go`: Replace the internal path reference with a user-friendly description:
```
6. Remove old bundled template files if present (legacy cleanup)
```
---
#### 4. Documentation `cli.md` — Incomplete Options Lists
**Commands Affected**: `add`, `add-wizard`, `run`, `trial`, `upgrade`
**Priority**: Low
**Type**: Documentation gap
The `docs/src/content/docs/setup/cli.md` options lists for several commands are significantly incomplete compared to the actual CLI flags. Users reading the docs won't know these options exist.
**`gh aw add`** — Documented options: `--dir`, `--create-pull-request`, `--no-gitattributes`
Missing from docs (from `./gh-aw add --help`):
- `--append string` — Append extra content to the end of the workflow on installation
- `--disable-security-scanner` — Disable security scanning
- `-e/--engine string` — Override AI engine
- `-f/--force` — Overwrite existing workflow files
- `-n/--name string` — Specify name for the added workflow
- `--no-stop-after` — Remove any stop-after field
- `-r/--repo string` — Source repository
- `--stop-after string` — Override stop-after value
**`gh aw run`** — Documented options: `--repeat`, `--push`, `--ref`, `--enable-if-needed`, `--json/-j`
Missing from docs (from `./gh-aw run --help`):
- `--auto-merge-prs` — Auto-merge any pull requests created during execution
- `--dry-run` — Validate without triggering execution
- `-e/--engine string` — Override AI engine
- `-F/--raw-field stringArray` — Pass workflow inputs
- `-r/--repo string` — Target repository
**`gh aw trial`** — Documented options: `-e`, `--engine`, `--repeat`, `--delete-host-repo-after`, `--logical-repo`, `--clone-repo`, `--trigger-context`, `--host-repo`, `--dry-run`
Missing from docs (from `./gh-aw trial --help`):
- `--append string` — Append extra content to the workflow on installation
- `--auto-merge-prs` — Auto-merge any pull requests created during trial
- `--disable-security-scanner` — Disable security scanning
- `--force-delete-host-repo-before` — Force delete host repo before creation
- `--timeout int` — Execution timeout in minutes
- `-y/--yes` — Skip confirmation prompts
**`gh aw upgrade`** — Documented options: `--dir`, `--no-fix`, `--no-actions`, `--create-pull-request`, `--audit`, `--json`
Missing from docs:
- `--no-compile` — Skip recompiling workflows (shown in `./gh-aw upgrade --help`)
**Suggested Fix**: Update the **Options** sections in `cli.md` to match the full flag list from the CLI help output. The options lists for `add`, `run`, `trial` are particularly incomplete and may confuse users trying to use these flags.
---
#### 5. `trial` — Unintuitive `-s` Shorthand for `--logical-repo`
**Command Affected**: `gh aw trial`
**Priority**: Low
**Type**: Minor inconsistency / discoverability issue
**Current Output** (from `./gh-aw trial --help`):
```
-s, --logical-repo string The repo we're simulating the execution for...
Summary
Automated CLI consistency inspection (running all commands with
--help) found 5 inconsistencies across command help text and documentation that should be addressed for better user experience.Breakdown by Severity
Issue Categories
secrets bootstrapuses third-person present tense, all others use imperativestatusandlistare in "Development Commands" in CLI help but "Monitoring" in docsfixexposespkg/cli/templates/in user-facing helpadd,run,trial,upgrade,add-wizardoptions lists are incomplete incli.md-sfor--logical-repointrialInspection Details
--helpfor all top-level and subcommands)make build, executed all./gh-aw [command] --helpand analyzed outputFindings Summary
✅ No issues found in these areas:
-v,-e,-r,-o,-j,-f,-ware respected)--banner,-v/--verbose,-h/--help)secrets bootstrap)status,list)fix)docs/src/content/docs/setup/cli.mdDetailed Findings
1.
secrets bootstrap— Third-Person Verb InconsistencyCommand Affected:
gh aw secrets bootstrapPriority: Medium
Type: Inconsistency in verb form
Current Output (from
./gh-aw secrets bootstrap --help):Issue: The
-sshorthand for--logical-repohas no intuitive connection to "logical" or "repo". Additionally, the flag description uses informal language ("we're simulating") compared to the style of other flag descriptions which are more formal and direct (e.g., "Target repository", "Filter runs by branch or tag name"). The-rshorthand is conventionally used for--repoin other commands, buttrialdoesn't have a--repoflag, so-rcould alternatively be used here.Suggested Fix (in
pkg/cli/trial_command.go):"The repo we're simulating the execution for, as if the workflow was installed in that repo (defaults to current repository)"to"Repository to simulate the workflow running against (defaults to current repository)"-sto-l(for "logical") or keep as-is if-sis intentional (e.g., for "simulated")