[cli-consistency] CLI Consistency Issues - 2026-11-05

Open Beginner friendly
  • Is something wrong?
#75,181 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
github-actions, go
Domain
cli, documentation

Research direction

Read the lint flag help and the **Options:** entries for lint and logs in docs/src/content/docs/setup/cli.md. Find the command flag definitions and their documentation source, then update the lint shorthand and include the three missing logs options. Done when the help and docs consistently show these flags.

Written by the indexing model from the issue text.

Description

automation cli cookie documentation
Summary

Inspected the pre-collected help for about 45 top-level commands, plus subcommand and flag help files, against docs/src/content/docs/setup/cli.md.

Severity: high 0, medium 0, low 2. No typos were found by keyword scan. Every top-level command is documented. All --dir defaults use .github/workflows consistently.

Findings
1. gh aw lint --json has no -j short flag (low)

  • Every other command with --json pairs it with -j: audit, checks, compile, doctor, domains, forecast, health, list, logs, models, run, status, trial, upgrade and validate.

  • lint help shows the flag with no short form:

      --json                                  Emit structured diagnostics (requires --rules)

  • Expected: -j, --json, or an explicit note that the omission is intentional.

  • The docs **Options:** line for lint also lists plain --json.

  • Suggested fix: add the -j shorthand to lint and update the docs.

2. Docs logs Options line omits --episodes, --outcomes and --outcomes-dir (low)

  • Help for gh aw logs includes these flags. The quoted lines below are from help-output/logs.txt:

    Use --outcomes to evaluate the current GitHub state of each selected run's safe
...
    --episodes                        Include recorded episode membership and hops; combine with --outcomes for episode outcome summaries

  • The main **Options:** list for logs in cli.md (about line 754) does not mention them.

  • They are only documented in the separate logs --outcomes section (about line 1047), and that section's options line omits --outcomes itself.

  • Suggested fix: add the three flags to the main logs Options list.

Inspection metadata

  • Date: 2026-11-05

  • Run: 42033865672

  • Method:

    • Read /tmp/gh-aw/agent/all-help.txt and help-output/*.txt.
    • Cross-checked the **Options:** lines in cli.md against help flags, using a script.
    • Compared short and long flag pairings across commands.
    • Scanned for typos.

  • Not reported: --pr is a documented compatibility alias for --create-pull-request. It appears in cli.md but not as a flag line in help, and it is mentioned in the help text of add, deploy and others.

Generated by ✅ CLI Consistency Checker · copilot · auto · ~33 AIC · ⌖ ~1 AIC · ⊞ 4.4K · ◷

  • expires on Nov 7, 2026, 5:31 AM UTC-08:00
Dominant language
Go
Stars
5.6k
Forks
615
Avg merge
5h 36m
Merged PRs (30d)
805

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/gh-aw

All issues in github/gh-aw

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.