Skip to content

feat(flags): add --list/-l flag to display available commands and environments#36

Merged
seanseannery merged 1 commit intomainfrom
feat/list-commands-issue-19
Mar 7, 2026
Merged

feat(flags): add --list/-l flag to display available commands and environments#36
seanseannery merged 1 commit intomainfrom
feat/list-commands-issue-19

Conversation

@seanseannery
Copy link
Owner

Key Changes

  • Add --list / -l CLI flag that prints a summary of all commands and environments defined in the Opsfile, then exits
  • Parser now captures # comment descriptions from the first line of a comment block directly above a command declaration
  • Parser returns command declaration order and environment appearance order for stable, deterministic output
  • --help now appends command listing after flag help (silently skips if no Opsfile found)
  • New internal/lister.go module handles formatted output with column-aligned descriptions

Why do we need this?

There is no way to discover available commands without opening the Opsfile manually. Under time pressure (e.g. during incidents), this adds unnecessary friction. The --list flag provides instant command discovery from the terminal.

Closes #19

New modules or other dependencies introduced

  • internal/lister.go — new file containing FormatCommandList() for rendering the command/environment listing. Uses only the standard library (fmt, io, strings).
  • internal/lister_test.go — 7 table-driven test cases for output formatting

No new external dependencies.

How was this tested?

  • Unit tests (parser): 4 new subtests for description extraction (direct comment, blank-line gap, multi-line block first-line capture, no comment), plus command order and environment order tests
  • Unit tests (flag parser): 4 new subtests for --list/-l flag parsing including combination with -D
  • Unit tests (lister): 7 table-driven tests covering descriptions, no descriptions, mixed, env order preservation, column alignment, single command, and empty map
  • Existing tests updated: command_resolver_test.go updated for new ParseOpsFile return signature
  • Manual smoke test: ops --list -D ./examples produces correct output against the example Opsfile
  • make lint and make test pass (88 tests total)

…ironments

Adds a new --list/-l flag that prints Opsfile commands with descriptions
and environments without executing anything. Also integrates command
listing into --help output with silent fallback when no Opsfile is found.

Closes #19
@seanseannery seanseannery merged commit be35ab0 into main Mar 7, 2026
4 checks passed
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.

Support flag that lists available commands

1 participant