feat(cli): add help command

[owainlewis]

Summary

• add a first-class push help command
• support -h and --help before config or command execution
• prevent push init --help from creating an assistant repository named --help
• list all current commands, including restart, and document the help forms
• add parser and real-binary regression coverage

Acceptance proof

• push help exits successfully and prints command and option usage
• help does not load config or change files
• existing help flags remain supported
• unknown-command guidance includes help
• the branch is rebased onto current main and is conflict-free

Checks

• cargo fmt --all --check
• cargo clippy --locked --all-targets -- -D warnings
• cargo build --locked
• cargo test --locked (266 tests passed)
• bash tests/install.sh
• mkdocs build --strict
• two independent subagent reviews: no actionable findings

Risks

Low. Help exits before configuration loading or command side effects.

Related issue

None.

[coderabbitai]

Warning

Review limit reached

@owainlewis, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0c8e7493-86b5-43cb-806b-1e5b12e0449c

📥 Commits

Reviewing files that changed from the base of the PR and between 8b9cbbf and 580e6e1.

📒 Files selected for processing (3)

• docs/reference/cli.md
• src/main.rs
• tests/init_cli.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-help-document-creation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[owainlewis]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[greptile-apps]

Greptile Summary

This PR adds a first-class push help command and -h/--help flag support to the CLI, with an explicit fix preventing push init --help from creating an assistant repository named --help.

• Adds a static HELP constant and Command::Help variant; the parser performs an early-return flag scan for -h/--help before any config loading or file I/O, so help is always safe to invoke.
• Adds ["help"] positional matching alongside the flag path, and updates the unknown-command error message to include help in the accepted list.
• Covers both paths with a unit test in main.rs and an integration test in tests/init_cli.rs that asserts successful exit, expected stdout content, empty stderr, and zero filesystem side-effects.

Confidence Score: 5/5

Safe to merge — the change exits before any config loading or file operations, and the existing command paths are untouched.

The help command is isolated: it short-circuits before config loading, before any file I/O, and before any async work. The early-return flag scan correctly handles all documented forms (push help, push --help, push -h, push init --help). Unit and integration tests verify both the parser and the real binary. No existing command path is modified.

No files require special attention.

Important Files Changed

Filename	Overview
src/main.rs	Adds Command::Help variant, a HELP constant, an early-return flag scan for -h/--help before any config loading, and positional "help" matching — all correct and well-integrated with the existing hand-rolled parser.
tests/init_cli.rs	Adds an integration test covering both "push help" and "push init --help", asserting successful exit, expected stdout content, empty stderr, and zero filesystem side-effects.
docs/reference/cli.md	Updates CLI reference table and examples to include the help command, and removes the now-stale caveat about the absence of a --help page.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[push args] --> B{Any arg is -h or --help?}
    B -- yes --> H[Command::Help with DEFAULT_CONFIG_PATH]
    B -- no --> C[Parse --config flag and collect positional args]
    C --> D{Match positional slice}
    D -- empty --> E[Command::Run]
    D -- help --> H
    D -- init --> F[Command::Init path]
    D -- doctor --> G[Command::Doctor]
    D -- restart --> I[Command::Restart]
    D -- job ... --> J[Command::Job subcommand]
    D -- unknown --> K[bail! unknown command error]
    H --> L[print HELP string and return Ok]
    E --> M[load_run_config and start gateway]
    F --> N[assistant init]
    G --> O[doctor::doctor]
    I --> P[restart::gateway]
    J --> Q[run_job_command]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[push args] --> B{Any arg is -h or --help?}
    B -- yes --> H[Command::Help with DEFAULT_CONFIG_PATH]
    B -- no --> C[Parse --config flag and collect positional args]
    C --> D{Match positional slice}
    D -- empty --> E[Command::Run]
    D -- help --> H
    D -- init --> F[Command::Init path]
    D -- doctor --> G[Command::Doctor]
    D -- restart --> I[Command::Restart]
    D -- job ... --> J[Command::Job subcommand]
    D -- unknown --> K[bail! unknown command error]
    H --> L[print HELP string and return Ok]
    E --> M[load_run_config and start gateway]
    F --> N[assistant init]
    G --> O[doctor::doctor]
    I --> P[restart::gateway]
    J --> Q[run_job_command]

Loading

_{Reviews (1): Last reviewed commit: "fix(cli): include restart in help" | Re-trigger Greptile}