Skip to content

feat: per-command flags for remaining commands, auto-behavior wiring, help/discoverability#897

Merged
Aureliolo merged 3 commits intomainfrom
feat/cli-remaining-flags-help-autowiring
Mar 28, 2026
Merged

feat: per-command flags for remaining commands, auto-behavior wiring, help/discoverability#897
Aureliolo merged 3 commits intomainfrom
feat/cli-remaining-flags-help-autowiring

Conversation

@Aureliolo
Copy link
Copy Markdown
Owner

Summary

PR 3 of 3 for #886 -- completes all 93 items across 8 categories for CLI configurability and discoverability.

  • Per-command flags (items 43-66): update (--dry-run, --no-restart, --timeout, --cli-only, --images-only, --check), cleanup (--dry-run, --all, --keep), backup create (--output/-o, --timeout), backup list (--limit/-n, --sort), backup restore (--confirm, --dry-run, --no-restart, --timeout), wipe (--dry-run, --no-backup, --keep-images), doctor (--checks, --fix), version (--short), uninstall (--keep-data, --keep-images)
  • Auto-behavior wiring: Wire auto_update_cli, auto_pull, auto_restart, auto_apply_compose, auto_start_after_wipe config keys into their respective prompts with precedence --yes > config key > interactive prompt > non-interactive default
  • Help/discoverability (items 77-82): Command groups in --help, Example blocks on every command, did-you-mean suggestions (SuggestionsMinimumDistance=2), footer hints on table output, contextual error hints in Execute(), --help-all recursive flag
  • Hint migration: Verified complete -- all calls use categorized methods (HintError/HintNextStep/HintTip/HintGuidance)

Pre-reviewed by 4 agents (go-reviewer, go-conventions-enforcer, issue-resolution-verifier, docs-consistency), 11 findings addressed.

Test plan

  • go -C cli build ./... -- clean build
  • go -C cli test ./... -- all tests pass (including new flags_test.go with 17 test cases)
  • go -C cli vet ./... -- no issues
  • go -C cli tool golangci-lint run -- 0 issues
  • All pre-commit and pre-push hooks pass
  • Manual: synthorg --help shows command groups (Core, Lifecycle, Data, Diagnostics)
  • Manual: synthorg updat shows did-you-mean suggestion
  • Manual: synthorg update --check exits 0 or 10
  • Manual: synthorg version --short prints version only
  • Manual: synthorg --help-all prints recursive help

Closes #886

Aureliolo and others added 2 commits March 28, 2026 12:14
… help/discoverability

PR 3 of 3 for #886 -- completes all 93 items across 8 categories.

Per-command flags: update (--dry-run, --no-restart, --timeout, --cli-only,
--images-only, --check), cleanup (--dry-run, --all, --keep), backup create
(--output/-o, --timeout), backup list (--limit/-n, --sort), backup restore
(--dry-run, --no-restart, --timeout), wipe (--dry-run, --no-backup,
--keep-images), doctor (--checks, --fix), version (--short), uninstall
(--keep-data, --keep-images).

Auto-behavior wiring: auto_update_cli, auto_pull, auto_restart,
auto_apply_compose, auto_start_after_wipe config keys now drive their
respective prompts with precedence --yes > config key > interactive.

Help/discoverability: command groups in --help, Example blocks on every
command, did-you-mean suggestions, footer hints on tables, contextual
error hints, --help-all flag.

Closes #886

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
… hints, extract helpers)

Pre-reviewed by 4 agents, 11 findings addressed:
- Sort validDoctorChecks map keys for deterministic error messages
- Tighten errorHint "docker" pattern to avoid false positives
- Remove dead-code timeout guards in backup create/restore
- Use cmd.Flags().Changed for reexec flag forwarding
- Extract renderDoctorFiltered, wipeDryRunPreview, copyBackupToLocal helpers
- Move openBrowser + boolToYesNo to helpers.go (wipe.go under 800 lines)
- Add --help-all and --confirm to CLAUDE.md docs
- Use cmd.OutOrStdout() in printAllHelp instead of os.Stdout

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 28, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 93c4a402-78ca-422c-b592-8a7aab3d2a18

📥 Commits

Reviewing files that changed from the base of the PR and between ad8ee0e and 048c84f.

📒 Files selected for processing (8)
  • cli/cmd/backup.go
  • cli/cmd/cleanup.go
  • cli/cmd/doctor.go
  • cli/cmd/flags_test.go
  • cli/cmd/root.go
  • cli/cmd/uninstall.go
  • cli/cmd/update.go
  • cli/cmd/wipe.go
📜 Recent review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
  • GitHub Check: CLI Test (windows-latest)
  • GitHub Check: Dependency Review
  • GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (1)
cli/**/*.go

📄 CodeRabbit inference engine (CLAUDE.md)

cli/**/*.go: CLI (Go): use Cobra for commands, charmbracelet/huh for interactive prompts, charmbracelet/lipgloss for TUI styling, sigstore-go for cosign verification, go-containerregistry for image operations, go-tuf for release verification.
CLI (Go): exit codes: 0 (success), 1 (runtime error), 2 (usage error), 3 (unhealthy), 4 (unreachable), 10 (updates available).

Files:

  • cli/cmd/uninstall.go
  • cli/cmd/backup.go
  • cli/cmd/doctor.go
  • cli/cmd/root.go
  • cli/cmd/cleanup.go
  • cli/cmd/wipe.go
  • cli/cmd/flags_test.go
  • cli/cmd/update.go
🧠 Learnings (21)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: Applies to cli/**/*.go : CLI (Go): use Cobra for commands, charmbracelet/huh for interactive prompts, charmbracelet/lipgloss for TUI styling, sigstore-go for cosign verification, go-containerregistry for image operations, go-tuf for release verification.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/cli.yml : CLI workflow: Go lint (golangci-lint + go vet) + test (-race -coverprofile) + build (cross-compile: linux/darwin/windows × amd64/arm64) + govulncheck + fuzz testing (main-only, 30s/target, continue-on-error, matrix over 4 packages). cli-pass gate includes fuzz as informational. GoReleaser release on v* tags. Cosign keyless signing of checksums.txt. SLSA L3 provenance attestations. Sigstore bundle (.sigstore.json) attached. Post-release appends checksums/verification/provenance to draft release notes.
📚 Learning: 2026-03-28T10:20:33.391Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: Applies to cli/**/*.go : CLI (Go): use Cobra for commands, charmbracelet/huh for interactive prompts, charmbracelet/lipgloss for TUI styling, sigstore-go for cosign verification, go-containerregistry for image operations, go-tuf for release verification.

Applied to files:

  • cli/cmd/uninstall.go
  • cli/cmd/backup.go
  • cli/cmd/root.go
  • cli/cmd/cleanup.go
  • cli/cmd/wipe.go
  • cli/cmd/flags_test.go
  • cli/cmd/update.go
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to cli/**/*.go : Go CLI (Go 1.26+) uses Cobra for commands, charmbracelet/huh for interactive CLI, charmbracelet/lipgloss for styled output. Cross-platform builds (linux/darwin/windows × amd64/arm64). GoReleaser for releases with cosign keyless signing of checksums.txt. SLSA L3 provenance attestations via actions/attest-build-provenance.

Applied to files:

  • cli/cmd/backup.go
  • cli/cmd/root.go
  • cli/cmd/cleanup.go
  • cli/cmd/wipe.go
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Applies to cli/**/*.go : Use Cobra for CLI command structure, charmbracelet/huh for interactive prompts, and charmbracelet/lipgloss for terminal styling

Applied to files:

  • cli/cmd/backup.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
📚 Learning: 2026-03-15T21:49:53.264Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:49:53.264Z
Learning: Fix everything valid — never skip when review agents find valid issues (including pre-existing issues in surrounding code, suggestions, and findings adjacent to the PR's changes). No deferring, no 'out of scope' skipping.

Applied to files:

  • cli/cmd/doctor.go
📚 Learning: 2026-03-15T18:17:43.675Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:17:43.675Z
Learning: Applies to cli/** : CLI: Go 1.26+, dependencies in cli/go.mod (Cobra, charmbracelet/huh).

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/cleanup.go
  • cli/cmd/wipe.go
  • cli/cmd/flags_test.go
  • cli/cmd/update.go
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to cli/go.mod : Go CLI dependencies: Go 1.26+, Cobra (commands), charmbracelet/huh (interactive CLI), charmbracelet/lipgloss (styled output).

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/cleanup.go
  • cli/cmd/wipe.go
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Go 1.26+ required; CLI dependencies in `cli/go.mod` (Cobra, charmbracelet/huh, charmbracelet/lipgloss, sigstore-go, go-containerregistry, go-tuf)

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/update.go
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to cli/go.mod : CLI uses Go 1.26+. Dependencies: Cobra, charmbracelet/huh, charmbracelet/lipgloss, sigstore-go, go-containerregistry, go-tuf

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/cleanup.go
📚 Learning: 2026-03-19T11:19:40.044Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:19:40.044Z
Learning: Applies to go.mod : Maintain Go 1.26+ requirement. Dependencies: Cobra (CLI framework), charmbracelet/huh and charmbracelet/lipgloss (UI), sigstore-go (code signing), go-containerregistry (container image verification), go-tuf (TUF client for Sigstore).

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/wipe.go
📚 Learning: 2026-03-28T10:20:33.391Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: Applies to docker/** : Docker: all images build with `context: .`. Verify images with CLI using cosign signatures + SLSA provenance. Bypass with `--skip-verify`.

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/update.go
📚 Learning: 2026-03-28T10:20:33.391Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: Applies to cli/**/*.go : CLI (Go): exit codes: 0 (success), 1 (runtime error), 2 (usage error), 3 (unhealthy), 4 (unreachable), 10 (updates available).

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/update.go
📚 Learning: 2026-03-16T19:52:03.656Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T19:52:03.656Z
Learning: Applies to cli/**/*.go : Lint CLI Go code with golangci-lint and go vet; test with go test -race; check vulnerabilities with govulncheck

Applied to files:

  • cli/cmd/cleanup.go
  • cli/cmd/flags_test.go
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/cli.yml : CLI workflow: Go lint (golangci-lint + go vet) + test (-race -coverprofile) + build (cross-compile: linux/darwin/windows × amd64/arm64) + govulncheck + fuzz testing (main-only, 30s/target, continue-on-error, matrix over 4 packages). cli-pass gate includes fuzz as informational. GoReleaser release on v* tags. Cosign keyless signing of checksums.txt. SLSA L3 provenance attestations. Sigstore bundle (.sigstore.json) attached. Post-release appends checksums/verification/provenance to draft release notes.

Applied to files:

  • cli/cmd/cleanup.go
  • cli/cmd/flags_test.go
📚 Learning: 2026-03-28T10:20:33.391Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: CLI (Go): never use `cd cli` -- use `go -C cli` which changes directory internally. golangci-lint registered as a tool: `go -C cli tool golangci-lint`.

Applied to files:

  • cli/cmd/cleanup.go
📚 Learning: 2026-03-19T11:30:29.217Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:30:29.217Z
Learning: Applies to cli/**/*.go : Run Go lint via `golangci-lint run`, vet via `go vet`, tests via `go test ./...`, and fuzz via `go test -fuzz=FuzzTarget -fuzztime=30s`

Applied to files:

  • cli/cmd/cleanup.go
  • cli/cmd/flags_test.go
📚 Learning: 2026-03-19T11:19:40.044Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:19:40.044Z
Learning: Applies to cli/**/*.go : Use native Go testing with `testing.F` fuzz functions (`Fuzz*`) for fuzz testing.

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to cli/**/*.go : Use native `testing.F` fuzz functions (`Fuzz*`) for fuzzing

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-19T11:19:40.044Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:19:40.044Z
Learning: Applies to cli/**/*.go : Lint Go code with `golangci-lint` and `go vet`. Run tests with `-race` flag to detect race conditions.

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-19T11:30:29.217Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:30:29.217Z
Learning: Applies to cli/**/*.go : Use native `testing.F` fuzz functions (`Fuzz*`) for fuzz testing Go code

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Applies to cli/**/*.go : Use native Go `testing.F` fuzz functions (`Fuzz*`) for property-based testing

Applied to files:

  • cli/cmd/flags_test.go
🔇 Additional comments (18)
cli/cmd/uninstall.go (2)

63-90: LGTM! Past review concerns are addressed.

The autoAccept flag is now correctly threaded through all confirmation helpers (stopAndRemoveVolumes, confirmAndRemoveImages, confirmAndRemoveData, confirmAndRemoveBinary), enabling non-interactive uninstall with --yes. The --keep-data flag now correctly prevents volume removal by setting removeVolumes = false when keepData is true (lines 117-135), protecting volume-backed app data.


358-362: Good security hardening for Windows batch script safety.

Rejecting % in addition to " prevents cmd.exe variable expansion attacks in the generated batch script. The error message is clear about why the path is rejected.

cli/cmd/wipe.go (2)

160-174: LGTM! Past review concern addressed.

The --keep-images flag now correctly controls whether --rmi all is passed to docker compose down. When wipeKeepImages is true, images are preserved; when false, they are removed. The messaging at lines 170-174 accurately reflects the behavior.


654-661: Auto-behavior precedence implemented correctly.

The promptStartAfterWipe function correctly implements the documented precedence: --yes (via ShouldPrompt()) > config key (AutoStartAfterWipe) > interactive prompt. The config check happens after the non-interactive check, ensuring --yes takes priority.

cli/cmd/doctor.go (2)

186-250: LGTM! Auto-fix now uses scan-then-act pattern with proper filtering.

The doctorAutoFix function correctly implements the scan-then-act pattern requested in prior review:

  1. Phase 1 (lines 200-216): Scans all issues, determines needComposeFix and needRestart flags, respecting --checks filter via doctorCheckEnabled
  2. Phase 2 (lines 223-245): Executes fixes in correct order—compose regeneration first, then a single restart pass

This ensures compose issues are resolved before container restart, avoiding multiple restarts.


158-184: --checks now filters both rendering and auto-fix actions.

The renderDoctorFiltered function gates each diagnostic section by doctorCheckEnabled, and the auto-fix phase (lines 206-212) similarly gates actions. While diagnostics.Collect still runs the full suite, filtered checks are the only ones rendered or acted upon—a reasonable tradeoff since collection is fast and the saved diagnostic file benefits from completeness.

cli/cmd/backup.go (2)

484-510: LGTM! Deterministic sorting implemented as suggested.

The sortBackups function now uses sort.SliceStable with a secondary tie-breaker on BackupID, ensuring deterministic output when timestamps or sizes are equal. This addresses the prior review concern about non-deterministic ordering.


554-563: Good dry-run implementation for restore.

The --dry-run path provides clear preview output with the backup ID, data directory, and restart intention, then exits early without executing the restore. The hint to remove --dry-run is helpful.

cli/cmd/cleanup.go (2)

44-49: LGTM! Flag validation is appropriate.

Rejecting negative --keep values with a clear error message is correct.


86-100: --keep and --dry-run logic is correct.

The --keep implementation correctly truncates the image list to remove only images beyond the N most recent. The --dry-run path provides useful preview output with a hint about how many images would be removed.

cli/cmd/root.go (2)

239-248: LGTM! Past review concerns addressed.

The error handling now:

  1. Properly detects both ChildExitError and ExitError to avoid printing internal messages
  2. Uses ui.NewUIWithOptions(..., globalUIOptions()) which respects --quiet, --no-color, --plain, and --json flags for hint output
  3. The errorHint function correctly guards the --skip-verify suggestion with isTransportError(err) to avoid recommending bypass for genuine integrity failures

54-63: Good UX improvements for help and discoverability.

Command groups (core, lifecycle, data, diagnostics) organize the --help output logically, and SuggestionsMinimumDistance = 2 enables helpful did-you-mean suggestions for typos.

cli/cmd/update.go (3)

571-576: LGTM! --timeout now applies to verification.

The verifyAndPinForUpdate function now parses updateTimeout and uses it for the verification context timeout, with a fallback to 90s if parsing fails or the value is non-positive. This addresses the prior review concern.


348-360: LGTM! Re-exec now forwards --cli-only.

The reexecUpdate function now correctly forwards --cli-only (line 358-360), along with --no-restart, --timeout, and --images-only. This ensures the relaunched CLI preserves the user's intent after a self-update.


631-644: LGTM! auto_restart precedence is correct.

The restart logic now correctly implements precedence: --no-restart (checked at 609-615) > --yes > auto_restart config (checked at 634-636) > interactive prompt > non-interactive default. The AutoRestart check happens before the ShouldPrompt() fallback, ensuring headless runs restart when the config key is set.

cli/cmd/flags_test.go (3)

1-52: Good test coverage for flag validation.

The tests properly save and restore global flag state using defer, preventing test pollution. Coverage includes mutual exclusivity checks, invalid timeout values, and valid configurations.


229-261: Good tests for confirmation precedence.

The tests correctly verify:

  1. autoAccept=true returns true without prompting (config auto-accept)
  2. --yes returns the provided defaultVal (respects the caller's default rather than blindly accepting)

This matches the implementation where confirmUpdate passes defaultVal=true while confirmUpdateWithDefault allows callers to specify their own default.


265-295: Comprehensive error hint test coverage.

The test cases cover the key error patterns and correctly expect no hint for "image verification failed" without a transport error context, validating that the isTransportError guard is working.


Walkthrough

Adds a persistent global --help-all flag and numerous per-command flags and examples: update (--dry-run, --no-restart, --timeout, --cli-only, --images-only, --check), cleanup (--dry-run, --all, --keep), backup (create --output/--timeout, list --limit/--sort, restore --dry-run/--no-restart/--timeout), wipe (--dry-run, --no-backup, --keep-images), doctor (--checks, --fix), version (--short), and uninstall (--keep-data, --keep-images). Adds command grouping, Examples, error-hint mapping, flag validation, helper functions, doctor auto-fix flow, extensive flag/tests coverage, and several CLI UX refinements.

Suggested labels

autorelease: tagged

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main changes: per-command flags for remaining commands, auto-behavior wiring (config key integration), and help/discoverability improvements (command groups, examples, recursive help flag).
Description check ✅ Passed The description provides substantial detail relating to the changeset, including specific per-command flags, auto-behavior wiring details, help/discoverability items, and test plans, all relevant to the implemented changes.
Linked Issues check ✅ Passed The PR implements all required per-command flags [43-66], auto-behavior wiring (auto_update_cli, auto_pull, auto_restart, auto_apply_compose, auto_start_after_wipe), and help/discoverability items [77-82] from issue #886 PR 3 scope, with hint migration complete.
Out of Scope Changes check ✅ Passed All changes align with PR 3 scope: per-command flags, auto-behavior wiring, help improvements, and hint migration. No out-of-scope changes detected; infrastructure additions (helpers.go, flags_test.go) directly support the specified objectives.
Docstring Coverage ✅ Passed Docstring coverage is 60.76% which is sufficient. The required threshold is 40.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request significantly enhances the CLI by adding comprehensive flag support, examples, and command grouping across all subcommands. Key additions include dry-run modes for destructive operations (wipe, update, cleanup, restore), auto-fix capabilities in the doctor command, and improved update checking. It also introduces a centralized error hinting system and a recursive help flag. Feedback was provided regarding the doctor auto-fix implementation, suggesting a shift from brittle string matching to a more robust structured error approach for identifying issues to improve maintainability.

Comment on lines +193 to +195
for _, issue := range issues {
switch {
case strings.Contains(issue, "compose.yml") && (strings.Contains(issue, "not found") || strings.Contains(issue, "invalid")):
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The doctorAutoFix function relies on string matching against human-readable error messages from classifyDoctor to determine which fix to apply. This approach is brittle and can easily break if the error messages are changed in the future, which poses a maintainability risk.

For more robust and maintainable code, I recommend refactoring classifyDoctor to return a slice of a structured error type instead of a []string. This would allow doctorAutoFix to use a type-safe switch on an issue code or type.

For example, you could define a struct like this:

type DoctorIssue struct {
    ID      string
    Message string
}

Then, classifyDoctor would return []DoctorIssue, and doctorAutoFix could reliably switch on issue.ID.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 28, 2026

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 048c84f.
Ensure that dependencies are being submitted on PR branches. Re-running this action after a short time may resolve the issue. See the documentation for more information and troubleshooting advice.

Scanned Files

None

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 11

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cli/cmd/backup.go`:
- Around line 484-500: The sortBackups function uses sort.Slice which is
unstable; change to deterministic sorting by using sort.SliceStable and add a
secondary tie-breaker (e.g., compare backup ID) in each comparator to handle
equal Timestamp or SizeBytes cases: in the "oldest"/"newest" branches compare
Timestamp then fall back to comparing backup ID (e.g., backups[i].ID <
backups[j].ID), and in the "size" branch compare SizeBytes then fall back to
backup ID; update all sort.Slice calls in sortBackups to sort.SliceStable and
include the tie-breaker using the backupInfo.ID field.

In `@cli/cmd/doctor.go`:
- Around line 181-230: doctorAutoFix currently performs fixes inline per issue
which can cause multiple restarts and wrong ordering; change it to first scan
the issues (from classifyDoctor(report)) and set action flags (e.g.,
needComposeFix, needRestart) by checking issue strings (use same checks as
existing cases: "compose.yml" + "not found"/"invalid" => needComposeFix;
"unhealthy"/"exited" => needRestart), then perform actions in a planned order:
call doctorFixCompose once if needComposeFix, and only after regenerating (and
re-evaluating/docker.Detect if necessary) call composeRunQuiet once to restart
if needRestart and docker is available; keep using existing helpers
doctorFixCompose, composeRunQuiet, docker.Detect and preserve error reporting
via out/errOut and atomicWriteFile behavior in doctorFixCompose.
- Around line 49-50: The --checks flag currently only filters output; parse
doctorChecks into a normalized set and ensure that same set is used end-to-end:
pass the selected checks into diagnostics.Collect (or add a new parameter/filter
interface) so Collect runs only those checks, and likewise filter the input to
renderDoctorSummary and doctorAutoFix so they operate only on the selected
checks' results; update function signatures or add a small adapter that filters
the full diagnostics list returned by diagnostics.Collect before calling
renderDoctorSummary and doctorAutoFix (referencing doctorChecks,
diagnostics.Collect, renderDoctorSummary, doctorAutoFix and the doctorCmd flag
registration) so that --checks truly limits what is executed and fixed.

In `@cli/cmd/root.go`:
- Around line 241-243: The hint printing currently constructs a new UI via
ui.NewUI(rootCmd.ErrOrStderr()) which bypasses the CLI output/settings; instead
locate and reuse the existing UI/renderer that respects flags and persisted
settings (the same UI instance used to render normal output), e.g. obtain the UI
from the command/context or the shared variable used elsewhere in root command
initialization and call HintError on that instance rather than calling ui.NewUI;
update the errorHint handling code (where errorHint(err) is checked and
ui.NewUI(...) is invoked) to retrieve the existing UI (or pass it in) so
--quiet, --no-color, --plain and the persisted hints mode are honored.
- Around line 279-280: The current case branch that returns "Try --skip-verify
for air-gapped environments." for any message containing "image verification
failed" is too broad; restrict that advice to only transport-related
verification failures (the same guard used in cli/cmd/update.go) so genuine
signature/digest mismatches won't suggest skipping verification. Locate the case
handling strings.Contains(msg, "image verification failed") and change its
condition to detect transport errors (reuse the transport-error detection logic
from cli/cmd/update.go) before returning the --skip-verify suggestion; leave all
other verification failures to surface their integrity-related messages
unchanged.

In `@cli/cmd/uninstall.go`:
- Around line 30-33: runUninstall advertises a non-interactive --yes but still
invokes confirmation helpers that always prompt (blocking in non-TTY). Modify
runUninstall to pass the opts.Yes flag into each confirmation helper (or
conditionally bypass them when opts.Yes is true) used for removing volumes,
images, data, and the binary (locate calls to the confirmation helpers invoked
from runUninstall and the helpers themselves) so that when opts.Yes is true the
helpers return affirmative without prompting and the uninstall proceeds
non-interactively.
- Around line 82-88: The --keep-data flag only skips confirmAndRemoveData but
does not prevent the earlier step that runs "docker compose down -v", so
volume-backed app data can still be deleted; update the uninstall flow to check
uninstallKeepData before executing the compose down with volumes (the function
or call that runs "docker compose down -v" — locate the method that invokes
compose down/remove volumes) and short-circuit that step when uninstallKeepData
is true, and adjust the prompt/log to indicate volumes were preserved; keep the
existing confirmAndRemoveData behavior but ensure both the
compose-down/volume-removal call and confirmAndRemoveData respect
uninstallKeepData.

In `@cli/cmd/update.go`:
- Around line 345-354: The relaunched process is not receiving the CLI-only
option, so add forwarding of the "--cli-only" flag when re-execing: detect the
existing CLI-only option (the boolean/flag variable used in this file — e.g.,
updateCliOnly or updateCLIOnly) and append "--cli-only" to reArgs when it's set
(similar to how updateNoRestart, updateImagesOnly, and the timeout flag are
forwarded), ensuring the relaunched process preserves the user's CLI-only
intent.
- Around line 52-53: The flag --timeout (updateTimeout) is not being applied in
verifyAndPinForUpdate; replace the hard-coded 120s in verifyAndPinForUpdate's
context.WithTimeout(ctx, 120*time.Second) with a time.Duration derived from
updateTimeout (parse updateTimeout with time.ParseDuration), handle parse errors
(return error or default to 90s) and use that duration for the context timeout
so the verification honors the user's flag; reference updateTimeout and the
verifyAndPinForUpdate function when making this change.
- Around line 629-632: The auto-restart config (state.AutoRestart) is being
ignored in non-interactive runs because the early return for
!opts.ShouldPrompt() happens before the AutoRestart branch; move or evaluate the
state.AutoRestart check before the non-interactive default branch so that
performRestart(ctx, out, info, safeDir, state, opts.UIOptions()) is called when
state.AutoRestart is true regardless of opts.ShouldPrompt(); modify the logic
around opts.ShouldPrompt(), state.AutoRestart, and the performRestart(...) call
so flag > config > default precedence is preserved (e.g., check
state.AutoRestart first, then respect explicit --yes/ShouldPrompt behavior).

In `@cli/cmd/wipe.go`:
- Around line 70-73: The --keep-images flag (wipeKeepImages) is currently a
no-op because the wipe implementation only calls composeRunQuiet(..., "down",
"-v") and never removes images; either remove the flag/help or implement image
removal: when wipeKeepImages is false invoke composeRunQuiet (or the existing
wipe path) with the compose "down" option to remove images (e.g., add "--rmi"
"all" or the equivalent) and ensure dry-run branches reflect that behavior (and
update the paths referenced around the wipeCmd handling and any logic in the
composeRunQuiet call sites mentioned in the comment).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 27ee4014-6de9-4ba3-8032-8b3d187ed0a9

📥 Commits

Reviewing files that changed from the base of the PR and between 4e9673d and ad8ee0e.

📒 Files selected for processing (19)
  • CLAUDE.md
  • cli/cmd/backup.go
  • cli/cmd/cleanup.go
  • cli/cmd/completion_install.go
  • cli/cmd/config.go
  • cli/cmd/doctor.go
  • cli/cmd/flags_test.go
  • cli/cmd/helpers.go
  • cli/cmd/init.go
  • cli/cmd/logs.go
  • cli/cmd/root.go
  • cli/cmd/start.go
  • cli/cmd/status.go
  • cli/cmd/stop.go
  • cli/cmd/uninstall.go
  • cli/cmd/update.go
  • cli/cmd/update_compose.go
  • cli/cmd/version.go
  • cli/cmd/wipe.go
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
  • GitHub Check: CLI Test (windows-latest)
  • GitHub Check: Dependency Review
  • GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (1)
cli/**/*.go

📄 CodeRabbit inference engine (CLAUDE.md)

cli/**/*.go: CLI (Go): use Cobra for commands, charmbracelet/huh for interactive prompts, charmbracelet/lipgloss for TUI styling, sigstore-go for cosign verification, go-containerregistry for image operations, go-tuf for release verification.
CLI (Go): exit codes: 0 (success), 1 (runtime error), 2 (usage error), 3 (unhealthy), 4 (unreachable), 10 (updates available).

Files:

  • cli/cmd/logs.go
  • cli/cmd/init.go
  • cli/cmd/start.go
  • cli/cmd/config.go
  • cli/cmd/stop.go
  • cli/cmd/update_compose.go
  • cli/cmd/completion_install.go
  • cli/cmd/cleanup.go
  • cli/cmd/helpers.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/status.go
  • cli/cmd/backup.go
  • cli/cmd/version.go
  • cli/cmd/doctor.go
  • cli/cmd/uninstall.go
  • cli/cmd/flags_test.go
  • cli/cmd/update.go
🧠 Learnings (18)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: Applies to cli/**/*.go : CLI (Go): use Cobra for commands, charmbracelet/huh for interactive prompts, charmbracelet/lipgloss for TUI styling, sigstore-go for cosign verification, go-containerregistry for image operations, go-tuf for release verification.
📚 Learning: 2026-03-28T10:20:33.391Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: Applies to cli/**/*.go : CLI (Go): use Cobra for commands, charmbracelet/huh for interactive prompts, charmbracelet/lipgloss for TUI styling, sigstore-go for cosign verification, go-containerregistry for image operations, go-tuf for release verification.

Applied to files:

  • cli/cmd/init.go
  • cli/cmd/start.go
  • cli/cmd/config.go
  • cli/cmd/stop.go
  • cli/cmd/completion_install.go
  • cli/cmd/cleanup.go
  • cli/cmd/helpers.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/status.go
  • cli/cmd/backup.go
  • cli/cmd/version.go
  • cli/cmd/doctor.go
  • cli/cmd/uninstall.go
  • cli/cmd/flags_test.go
  • cli/cmd/update.go
📚 Learning: 2026-03-15T18:17:43.675Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:17:43.675Z
Learning: Applies to cli/** : CLI: Go 1.26+, dependencies in cli/go.mod (Cobra, charmbracelet/huh).

Applied to files:

  • cli/cmd/init.go
  • cli/cmd/config.go
  • cli/cmd/stop.go
  • cli/cmd/completion_install.go
  • cli/cmd/cleanup.go
  • cli/cmd/helpers.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/status.go
  • cli/cmd/version.go
  • cli/cmd/flags_test.go
  • cli/cmd/update.go
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Applies to cli/**/*.go : Use Cobra for CLI command structure, charmbracelet/huh for interactive prompts, and charmbracelet/lipgloss for terminal styling

Applied to files:

  • cli/cmd/init.go
  • cli/cmd/start.go
  • cli/cmd/config.go
  • cli/cmd/completion_install.go
  • cli/cmd/helpers.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/backup.go
  • cli/cmd/version.go
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to cli/go.mod : Go CLI dependencies: Go 1.26+, Cobra (commands), charmbracelet/huh (interactive CLI), charmbracelet/lipgloss (styled output).

Applied to files:

  • cli/cmd/init.go
  • cli/cmd/config.go
  • cli/cmd/completion_install.go
  • cli/cmd/helpers.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/version.go
  • cli/cmd/update.go
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Go 1.26+ required; CLI dependencies in `cli/go.mod` (Cobra, charmbracelet/huh, charmbracelet/lipgloss, sigstore-go, go-containerregistry, go-tuf)

Applied to files:

  • cli/cmd/init.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/version.go
  • cli/cmd/update.go
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to cli/**/*.go : Go CLI (Go 1.26+) uses Cobra for commands, charmbracelet/huh for interactive CLI, charmbracelet/lipgloss for styled output. Cross-platform builds (linux/darwin/windows × amd64/arm64). GoReleaser for releases with cosign keyless signing of checksums.txt. SLSA L3 provenance attestations via actions/attest-build-provenance.

Applied to files:

  • cli/cmd/init.go
  • cli/cmd/completion_install.go
  • cli/cmd/helpers.go
  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/backup.go
  • cli/cmd/version.go
  • cli/cmd/flags_test.go
📚 Learning: 2026-03-16T19:52:03.656Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T19:52:03.656Z
Learning: Applies to cli/**/*.go : Lint CLI Go code with golangci-lint and go vet; test with go test -race; check vulnerabilities with govulncheck

Applied to files:

  • cli/cmd/cleanup.go
  • cli/cmd/doctor.go
  • cli/cmd/flags_test.go
  • cli/cmd/update.go
📚 Learning: 2026-03-28T10:20:33.391Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: CLI (Go): never use `cd cli` -- use `go -C cli` which changes directory internally. golangci-lint registered as a tool: `go -C cli tool golangci-lint`.

Applied to files:

  • cli/cmd/cleanup.go
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to cli/go.mod : CLI uses Go 1.26+. Dependencies: Cobra, charmbracelet/huh, charmbracelet/lipgloss, sigstore-go, go-containerregistry, go-tuf

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/version.go
  • cli/cmd/update.go
📚 Learning: 2026-03-19T11:19:40.044Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:19:40.044Z
Learning: Applies to go.mod : Maintain Go 1.26+ requirement. Dependencies: Cobra (CLI framework), charmbracelet/huh and charmbracelet/lipgloss (UI), sigstore-go (code signing), go-containerregistry (container image verification), go-tuf (TUF client for Sigstore).

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/wipe.go
  • cli/cmd/update.go
📚 Learning: 2026-03-28T10:20:33.391Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-28T10:20:33.391Z
Learning: Applies to cli/**/*.go : CLI (Go): exit codes: 0 (success), 1 (runtime error), 2 (usage error), 3 (unhealthy), 4 (unreachable), 10 (updates available).

Applied to files:

  • cli/cmd/root.go
  • cli/cmd/status.go
  • cli/cmd/update.go
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/cli.yml : CLI workflow: Go lint (golangci-lint + go vet) + test (-race -coverprofile) + build (cross-compile: linux/darwin/windows × amd64/arm64) + govulncheck + fuzz testing (main-only, 30s/target, continue-on-error, matrix over 4 packages). cli-pass gate includes fuzz as informational. GoReleaser release on v* tags. Cosign keyless signing of checksums.txt. SLSA L3 provenance attestations. Sigstore bundle (.sigstore.json) attached. Post-release appends checksums/verification/provenance to draft release notes.

Applied to files:

  • cli/cmd/doctor.go
  • cli/cmd/flags_test.go
📚 Learning: 2026-03-19T11:19:40.044Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:19:40.044Z
Learning: Applies to cli/**/*.go : Use native Go testing with `testing.F` fuzz functions (`Fuzz*`) for fuzz testing.

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-19T11:30:29.217Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:30:29.217Z
Learning: Applies to cli/**/*.go : Run Go lint via `golangci-lint run`, vet via `go vet`, tests via `go test ./...`, and fuzz via `go test -fuzz=FuzzTarget -fuzztime=30s`

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-19T11:19:40.044Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:19:40.044Z
Learning: Applies to cli/**/*.go : Lint Go code with `golangci-lint` and `go vet`. Run tests with `-race` flag to detect race conditions.

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-19T11:30:29.217Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:30:29.217Z
Learning: Applies to cli/**/*.go : Use native `testing.F` fuzz functions (`Fuzz*`) for fuzz testing Go code

Applied to files:

  • cli/cmd/flags_test.go
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to cli/**/*.go : Use native `testing.F` fuzz functions (`Fuzz*`) for fuzzing

Applied to files:

  • cli/cmd/flags_test.go
🔇 Additional comments (19)
cli/cmd/cleanup.go (1)

39-39: The --keep flag correctly preserves the most recent images because Docker's images command sorts by creation time in descending order by default (documented behavior). The code relies on this ordering at lines 86–89, which is explicitly documented in the inline comment: "Docker returns images in most-recent-first order." This is a documented and verifiable guarantee from Docker, not an unvalidated assumption. No issue here.

			> Likely an incorrect or invalid review comment.
cli/cmd/backup.go (5)

53-55: LGTM - Example blocks improve discoverability.

Clear and practical examples demonstrating common usage patterns for the backup command and subcommands.


119-130: LGTM - Flag validation is correct.

The validation properly handles the --limit (non-negative) and --sort (enum values) constraints, returning clear error messages.


359-365: LGTM - Timeout validation is thorough.

The timeout parsing validates both format (via time.ParseDuration) and value (> 0), providing clear error messages.


408-425: LGTM - copyBackupToLocal helper is well-structured.

Properly detects Docker, shows spinner feedback, and delegates to copyBackupFromContainer with appropriate error handling.


544-553: No action required — boolToYesNo is already defined in cli/cmd/helpers.go:12.

cli/cmd/logs.go (1)

38-42: LGTM - Example block and GroupID assignment.

Clear examples covering common use cases (default, follow, service filter, time filter). GroupID assignment aligns with other core lifecycle commands.

cli/cmd/init.go (2)

37-38: LGTM - Example block demonstrates both usage modes.

Helpful examples showing interactive vs non-interactive initialization patterns.


49-49: LGTM - GroupID assignment consistent with other core commands.

cli/cmd/start.go (1)

38-42: LGTM - Example block and GroupID assignment.

Clear examples demonstrating key start command options. GroupID placement consistent with other core commands.

cli/cmd/stop.go (1)

25-28: LGTM - Example block and GroupID assignment.

Examples demonstrate the available stop command options clearly.

cli/cmd/update_compose.go (2)

61-61: LGTM - Auto-apply config wiring.

Correctly passes state.AutoApplyCompose to applyComposeDiff, enabling config-driven auto-acceptance of compose changes.


132-139: Function signature is correct. The confirmUpdate function at cli/cmd/update.go:470 accepts autoAccept bool as its third parameter, which properly receives the autoApply boolean passed from line 139.

cli/cmd/status.go (3)

34-38: LGTM - Example block covers key status options.

Clear examples for watch mode, wide output, and scripting exit code mode.


291-291: LGTM - Helpful contextual hint.

The hint guides users to the related logs command after viewing container status, improving discoverability.


62-77: Exit codes correctly follow documented conventions.

ExitUnreachable (4) for Docker/network issues, ExitUnhealthy (3) for backend health failures. As per coding guidelines: CLI exit codes: 0 (success), 1 (runtime error), 2 (usage error), 3 (unhealthy), 4 (unreachable).

CLAUDE.md (2)

86-86: LGTM - Global --help-all flag documented.

Matches the implementation of recursive help display described in PR objectives.


139-147: LGTM - Per-command flags documentation is comprehensive.

The table correctly documents all new flags added in this PR across update, cleanup, backup, wipe, doctor, version, and uninstall commands. The backup subcommands are properly documented with their respective flags.

cli/cmd/root.go (1)

45-47: The concern about --help-all being vulnerable to Cobra lifecycle bypass is not applicable to the current codebase. No subcommand in cli/cmd defines its own PreRunE or PersistentPreRunE hook, so the root command's persistent pre-run hook (line 44) will always execute and the --help-all flag will reliably reach printAllHelp(). The warning in lines 40-43 is a valid maintenance note for future development, but does not describe an actual issue with the current implementation.

			> Likely an incorrect or invalid review comment.

Comment on lines +49 to +50
doctorCmd.Flags().StringVar(&doctorChecks, "checks", "", "comma-separated checks to run (environment,health,containers,images,compose,config,disk,errors,all)")
doctorCmd.Flags().BoolVar(&doctorFix, "fix", false, "auto-fix detected issues")
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

--checks only filters presentation right now.

diagnostics.Collect still runs the full suite, renderDoctorSummary still summarizes the full report, and doctorAutoFix still consumes the full issue list. So synthorg doctor --checks health --fix can still perform unrelated checks and apply unrelated fixes even though the flag text says “checks to run”. Either plumb the selected set into collection/summary/fix, or rename this to an output filter.

Also applies to: 95-142, 151-177

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@cli/cmd/doctor.go` around lines 49 - 50, The --checks flag currently only
filters output; parse doctorChecks into a normalized set and ensure that same
set is used end-to-end: pass the selected checks into diagnostics.Collect (or
add a new parameter/filter interface) so Collect runs only those checks, and
likewise filter the input to renderDoctorSummary and doctorAutoFix so they
operate only on the selected checks' results; update function signatures or add
a small adapter that filters the full diagnostics list returned by
diagnostics.Collect before calling renderDoctorSummary and doctorAutoFix
(referencing doctorChecks, diagnostics.Collect, renderDoctorSummary,
doctorAutoFix and the doctorCmd flag registration) so that --checks truly limits
what is executed and fixed.

… Gemini

Critical: forward --cli-only flag in reexecUpdate to prevent unintended
compose/image updates after CLI self-update re-exec.

Major fixes:
- auto_restart config key now checked before non-interactive default
  (correct precedence: flag > config > prompt > default)
- --timeout flag applied to verifyAndPinForUpdate (was hardcoded 120s)
- errorHint UI respects --quiet/--no-color/--plain via globalUIOptions()
- --skip-verify hint restricted to transport errors only
- doctorAutoFix refactored to scan-then-act (compose first, restart once)
- --checks filter applied to --fix scope (no unfiltered auto-fixes)
- --keep-images in wipe now functional (adds --rmi all to compose down)
- runUpdate/runDoctor extracted helpers to stay under 50-line limit
- uninstall --yes now bypasses all confirmation prompts
- uninstall --keep-data also preserves Docker volumes
- sort.SliceStable with BackupID tie-breaker in sortBackups
- "all" keyword excluded from validDoctorCheckNames error message
- os.Exit(0) in PersistentPreRunE replaced with ExitError sentinel
- Windows bat cleanup rejects % characters in paths
- Duplicate cmd.Context() call fixed in cleanup.go
- errorHint test updated for transport-error guard

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@Aureliolo Aureliolo merged commit 3f7afa2 into main Mar 28, 2026
39 checks passed
@Aureliolo Aureliolo deleted the feat/cli-remaining-flags-help-autowiring branch March 28, 2026 11:44
Aureliolo added a commit that referenced this pull request Mar 30, 2026
🤖 I have created a release *beep* *boop*
---
#MAJOR CHANGES; We got a somewhat working webui :)

##
[0.5.0](v0.4.9...v0.5.0)
(2026-03-30)


### Features

* add analytics trends and budget forecast API endpoints
([#798](#798))
([16b61f5](16b61f5))
* add department policies to default templates
([#852](#852))
([7a41548](7a41548))
* add remaining activity event types (task_started, tool_used,
delegation, cost_incurred)
([#832](#832))
([4252fac](4252fac))
* agent performance, activity, and history API endpoints
([#811](#811))
([9b75c1d](9b75c1d))
* Agent Profiles and Detail pages (biography, career, performance)
([#874](#874))
([62d7880](62d7880))
* app shell, Storybook, and CI/CD pipeline
([#819](#819))
([d4dde90](d4dde90))
* Approvals page with risk grouping, urgency indicators, batch actions
([#889](#889))
([4e9673d](4e9673d))
* Budget Panel page (P&L dashboard, breakdown charts, forecast)
([#890](#890))
([b63b0f1](b63b0f1))
* build infrastructure layer (API client, auth, WebSocket)
([#815](#815))
([9f01d3e](9f01d3e))
* CLI global options infrastructure, UI modes, exit codes, env vars
([#891](#891))
([fef4fc5](fef4fc5))
* CodeMirror editor and theme preferences toggle
([#905](#905),
[#807](#807))
([#909](#909))
([41fbedc](41fbedc))
* Company page (department/agent management)
([#888](#888))
([cfb88b0](cfb88b0))
* comprehensive hint coverage across all CLI commands
([#900](#900))
([937974e](937974e))
* config system extensions, per-command flags for
init/start/stop/status/logs
([#895](#895))
([32f83fe](32f83fe))
* configurable currency system replacing hardcoded USD
([#854](#854))
([b372551](b372551))
* Dashboard page (metric cards, activity feed, budget burn)
([#861](#861))
([7d519d5](7d519d5))
* department health, provider status, and activity feed endpoints
([#818](#818))
([6d5f196](6d5f196))
* design tokens and core UI components
([#833](#833))
([ed887f2](ed887f2))
* extend approval, meeting, and budget API responses
([#834](#834))
([31472bf](31472bf))
* frontend polish -- real-time UX, accessibility, responsive,
performance ([#790](#790),
[#792](#792),
[#791](#791),
[#793](#793))
([#917](#917))
([f04a537](f04a537))
* implement human roles and access control levels
([#856](#856))
([d6d8a06](d6d8a06))
* implement semantic conflict detection in workspace merge
([#860](#860))
([d97283b](d97283b))
* interaction components and animation patterns
([#853](#853))
([82d4b01](82d4b01))
* Login page + first-run bootstrap + Company page
([#789](#789),
[#888](#888))
([#896](#896))
([8758e8d](8758e8d))
* Meetings page with timeline viz, token bars, contribution formatting
([#788](#788))
([#904](#904))
([b207f46](b207f46))
* Messages page with threading, channel badges, sender indicators
([#787](#787))
([#903](#903))
([28293ad](28293ad))
* Org Chart force-directed view and drag-drop reassignment
([#872](#872),
[#873](#873))
([#912](#912))
([a68a938](a68a938))
* Org Chart page (living nodes, status, CRUD, department health)
([#870](#870))
([0acbdae](0acbdae))
* per-command flags for remaining commands, auto-behavior wiring,
help/discoverability
([#897](#897))
([3f7afa2](3f7afa2))
* Providers page with backend rework -- health, CRUD, subscription auth
([#893](#893))
([9f8dd98](9f8dd98))
* scaffold React + Vite + TypeScript + Tailwind project
([#799](#799))
([bd151aa](bd151aa))
* Settings page with search, dependency indicators, grouped rendering
([#784](#784))
([#902](#902))
([a7b9870](a7b9870))
* Setup Wizard rebuild with template comparison, cost estimator, theme
customization ([#879](#879))
([ae8b50b](ae8b50b))
* setup wizard UX -- template filters, card metadata, provider form
reuse ([#910](#910))
([7f04676](7f04676))
* setup wizard UX overhaul -- mode choice, step reorder, provider fixes
([#907](#907))
([ee964c4](ee964c4))
* structured ModelRequirement in template agent configs
([#795](#795))
([7433548](7433548))
* Task Board page (rich Kanban, filtering, dependency viz)
([#871](#871))
([04a19b0](04a19b0))


### Bug Fixes

* align frontend types with backend and debounce WS refetches
([#916](#916))
([134c11b](134c11b))
* auto-cleanup targets newly pulled images instead of old ones
([#884](#884))
([50e6591](50e6591))
* correct wipe backup-skip flow and harden error handling
([#808](#808))
([c05860f](c05860f))
* improve provider setup in wizard, subscription auth, dashboard bugs
([#914](#914))
([87bf8e6](87bf8e6))
* improve update channel detection and add config get command
([#814](#814))
([6b137f0](6b137f0))
* resolve all ESLint warnings, add zero-warnings enforcement
([#899](#899))
([079b46a](079b46a))
* subscription auth uses api_key, base URL optional for cloud providers
([#915](#915))
([f0098dd](f0098dd))


### Refactoring

* semantic analyzer cleanup -- shared filtering, concurrency, extraction
([#908](#908))
([81372bf](81372bf))


### Documentation

* brand identity and UX design system from
[#765](#765) exploration
([#804](#804))
([389a9f4](389a9f4))
* page structure and information architecture for v0.5.0 dashboard
([#809](#809))
([f8d6d4a](f8d6d4a))
* write UX design guidelines with WCAG-verified color system
([#816](#816))
([4a4594e](4a4594e))


### Tests

* add unit tests for agent hooks and page components
([#875](#875))
([#901](#901))
([1d81546](1d81546))


### CI/CD

* bump actions/deploy-pages from 4.0.5 to 5.0.0 in the major group
([#831](#831))
([01c19de](01c19de))
* bump astral-sh/setup-uv from 7.6.0 to 8.0.0 in
/.github/actions/setup-python-uv in the all group
([#920](#920))
([5f6ba54](5f6ba54))
* bump codecov/codecov-action from 5.5.3 to 6.0.0 in the major group
([#868](#868))
([f22a181](f22a181))
* bump github/codeql-action from 4.34.1 to 4.35.0 in the all group
([#883](#883))
([87a4890](87a4890))
* bump sigstore/cosign-installer from 4.1.0 to 4.1.1 in the
minor-and-patch group
([#830](#830))
([7a69050](7a69050))
* bump the all group with 3 updates
([#923](#923))
([ff27c8e](ff27c8e))
* bump wrangler from 4.76.0 to 4.77.0 in /.github in the minor-and-patch
group ([#822](#822))
([07d43eb](07d43eb))
* bump wrangler from 4.77.0 to 4.78.0 in /.github in the all group
([#882](#882))
([f84118d](f84118d))


### Maintenance

* add design system enforcement hook and component inventory
([#846](#846))
([15abc43](15abc43))
* add dev-only auth bypass for frontend testing
([#885](#885))
([6cdcd8a](6cdcd8a))
* add pre-push rebase check hook
([#855](#855))
([b637a04](b637a04))
* backend hardening -- eviction/size-caps and model validation
([#911](#911))
([81253d9](81253d9))
* bump axios from 1.13.6 to 1.14.0 in /web in the all group across 1
directory ([#922](#922))
([b1b0232](b1b0232))
* bump brace-expansion from 5.0.4 to 5.0.5 in /web
([#862](#862))
([ba4a565](ba4a565))
* bump eslint-plugin-react-refresh from 0.4.26 to 0.5.2 in /web
([#801](#801))
([7574bb5](7574bb5))
* bump faker from 40.11.0 to 40.11.1 in the minor-and-patch group
([#803](#803))
([14d322e](14d322e))
* bump https://github.com/astral-sh/ruff-pre-commit from v0.15.7 to
0.15.8 ([#864](#864))
([f52901e](f52901e))
* bump nginxinc/nginx-unprivileged from `6582a34` to `f99cc61` in
/docker/web in the all group
([#919](#919))
([df85e4f](df85e4f))
* bump nginxinc/nginx-unprivileged from `ccbac1a` to `6582a34` in
/docker/web ([#800](#800))
([f4e9450](f4e9450))
* bump node from `44bcbf4` to `71be405` in /docker/sandbox
([#827](#827))
([91bec67](91bec67))
* bump node from `5209bca` to `cf38e1f` in /docker/web
([#863](#863))
([66d6043](66d6043))
* bump picomatch in /site
([#842](#842))
([5f20bcc](5f20bcc))
* bump recharts 2-&gt;3 and @types/node 22-&gt;25 in /web
([#802](#802))
([a908800](a908800))
* Bump requests from 2.32.5 to 2.33.0
([#843](#843))
([41daf69](41daf69))
* bump smol-toml from 1.6.0 to 1.6.1 in /site
([#826](#826))
([3e5dbe4](3e5dbe4))
* bump the all group with 3 updates
([#921](#921))
([7bace0b](7bace0b))
* bump the minor-and-patch group across 1 directory with 2 updates
([#829](#829))
([93e611f](93e611f))
* bump the minor-and-patch group across 1 directory with 3 updates
([#841](#841))
([7010c8e](7010c8e))
* bump the minor-and-patch group across 1 directory with 3 updates
([#869](#869))
([548cee5](548cee5))
* bump the minor-and-patch group in /site with 2 updates
([#865](#865))
([9558101](9558101))
* bump the minor-and-patch group with 2 updates
([#867](#867))
([4830706](4830706))
* consolidate Dependabot groups to 1 PR per ecosystem
([06d2556](06d2556))
* consolidate Dependabot groups to 1 PR per ecosystem
([#881](#881))
([06d2556](06d2556))
* improve worktree skill with full dep sync and status enhancements
([#906](#906))
([772c625](772c625))
* remove Vue remnants and document framework decision
([#851](#851))
([bf2adf6](bf2adf6))
* update web dependencies and fix brace-expansion CVE
([#880](#880))
([a7a0ed6](a7a0ed6))
* upgrade to Storybook 10 and TypeScript 6
([#845](#845))
([52d95f2](52d95f2))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: add config flags for more options (93 items)

1 participant