CLI Documentation and Developer Experience Improvements

[Mossaka]

Overview

Track all work related to CLI documentation, test coverage, and help text organization.

Key Findings

• 6 undocumented flags in docs/usage.md
• 2 undocumented validation constraints
• 4 flags with incomplete test coverage
• Help text organization issues
• Limited short flag availability

Child Issues

P0 - Critical (Documentation)

• Document missing CLI flags in usage.md #495 - Document missing CLI flags in usage.md
• Document flag validation constraints #496 - Document flag validation constraints

P1 - High (Testing)

• Add integration test for --skip-pull flag #497 - Add integration test for --skip-pull flag
• Add tests for --allow-host-ports validation #498 - Add tests for --allow-host-ports validation
• Add tests for --proxy-logs-dir flag #499 - Add tests for --proxy-logs-dir flag

P2 - Medium (Enhancement)

• Improve help text organization and consistency #500 - Improve help text organization and consistency

P3 - Low

• Add short flags for frequently used options #501 - Add short flags for frequently used options
• Clarify --image-tag behavior with presets #502 - Clarify --image-tag behavior with presets

Implementation Order

Week 1 (Documentation):
  Issue #495 (Doc flags) ────────┐
                                 ├──► Week 3 (Enhancement)
  Issue #496 (Doc constraints) ──┘         │
                                           ├──► Issue #500 (Help text)
Week 2 (Testing):                          │
  Issue #497 (skip-pull tests) ───────────►┤
  Issue #498 (host-ports tests) ──────────►┤
  Issue #499 (proxy-logs tests) ──────────►┘

Week 4 (Low Priority):
  Issue #501 (Short flags) - Requires RFC
  Issue #502 (Image-tag clarity)

Recommended PR Sequence

1. PR 1: Issues Document missing CLI flags in usage.md #495 + Document flag validation constraints #496 + Clarify --image-tag behavior with presets #502 (all documentation, one PR)
2. PR 2: Issue Add integration test for --skip-pull flag #497 (skip-pull integration tests)
3. PR 3: Issues Add tests for --allow-host-ports validation #498 + Add tests for --proxy-logs-dir flag #499 (validation tests)
4. PR 4: Issue Improve help text organization and consistency #500 (help text reorganization)
5. PR 5: Issue Add short flags for frequently used options #501 (short flags - after RFC)

Backward Compatibility

All changes are backward compatible:

• Documentation updates only affect developer experience
• Test additions do not change behavior
• Help text changes do not affect CLI parsing
• Short flag additions are additive, not breaking

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster

[Mossaka]

Closing as all child issues appear to have been resolved in main. All documented sub-tasks are addressed: #495 (missing CLI flags) - fixed by commits #695, #521, #1223, and #1241 (help text organization); #496 (validation constraints) - fixed by commit #1230 (5f63ba3); #497 (--skip-pull test) - fixed by #1222; #498 (--allow-host-ports tests) - fixed by #1221; #499 (--proxy-logs-dir tests) - fixed by #1220; #500 (help text organization) - fixed by #1241; #501 (short flags) - fixed by #1229; #502 (--image-tag clarity) - fixed by #1228.