feat(cli): full --help, --version, and a man page - #40
Merged
Conversation
The standalone actions (--self-upgrade, --install-service and friends) are parsed before the flag set, so they never appeared in the flag package's auto-generated -help. Surface them properly and add a man page. - --help / -h now prints a complete usage on stdout (exit 0): a synopsis, a "Standalone actions" section (--version, --self-upgrade [--check], --install-service / --uninstall-service / --service-status) and every option via a custom flag.Usage. - --version (and a bare `version` subcommand) prints the build version. - Ship deploy/dockercmd.1, embedded in the binary and kept byte-identical by a test; --install-service and the install-linux.sh / install-macos.sh scripts install it to /usr/local/share/man/man1 so `man dockercmd` works on the box. - Tests: embedded man page == deploy copy, man page documents every config flag and every standalone action, and the action arg-parsing (incl. `--` cutoff).
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves dockercmd CLI discoverability by providing complete --help output, adding --version/version, and shipping a man page that can be installed alongside the service and installer scripts.
Changes:
- Add custom
flag.Usagehelp text and a--version/versionstandalone action. - Embed and (best-effort) install/uninstall
dockercmd(1)as part of service installs on Linux/macOS, plus installer-script support. - Add tests to keep man-page copies in sync and to ensure the man page documents all CLI flags/actions; update docs/changelog accordingly.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
cmd/dockercmd/main.go |
Adds custom --help output and early --version/version handling. |
cmd/dockercmd/main_test.go |
Adds tests for standalone-action arg scanning, usage output, and action docs in the man page. |
internal/service/service.go |
Embeds dockercmd.1 and adds best-effort man-page install/remove helpers. |
internal/service/service_linux.go |
Installs/removes the man page during service install/uninstall on Linux. |
internal/service/service_darwin.go |
Installs/removes the man page during service install/uninstall on macOS. |
internal/service/service_test.go |
Adds a drift test to keep embedded man page byte-identical to deploy/dockercmd.1. |
internal/service/dockercmd.1 |
Embedded man page content for installation from the binary. |
deploy/dockercmd.1 |
Canonical man page content shipped with deploy artifacts/scripts. |
deploy/install-linux.sh |
Installs man page to /usr/local/share/man/man1 during script-based install. |
deploy/install-macos.sh |
Installs man page to /usr/local/share/man/man1 during script-based install (via sudo). |
internal/config/manpage_test.go |
Adds a test to ensure all flags in config.go are documented in the man page. |
docs/deployment.md |
Documents man dockercmd availability and improved --help/--version discovery. |
CHANGELOG.md |
Adds an Unreleased entry describing --help, --version, and the new man page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+42
to
+44
| if !strings.Contains(manStr, name) { | ||
| t.Errorf("flag -%s is defined in config.go but not documented in deploy/dockercmd.1", name) | ||
| } |
Comment on lines
+109
to
+112
| Standalone actions: | ||
| --version print the version and exit | ||
| --self-upgrade [--check] upgrade to the latest GitHub release (--check only reports) | ||
| --install-service install as a systemd (Linux) / launchd (macOS) service |
Comment on lines
+24
to
+27
| .TP | ||
| .B \-\-version | ||
| Print the version and exit. | ||
| .TP |
Comment on lines
+24
to
+27
| .TP | ||
| .B \-\-version | ||
| Print the version and exit. | ||
| .TP |
| > **Discovering the CLI.** `dockercmd --help` (or `-h`) prints a complete usage | ||
| > — a synopsis, the **standalone actions** (`--version`, `--self-upgrade`, | ||
| > `--install-service` / `--uninstall-service` / `--service-status`) and every | ||
| > option with its default. `dockercmd --version` prints the build version. |
…version` - TestManPageDocumentsAllFlags now requires the roff option token (\-name) as a whole word, so a short flag like -p can't pass on a stray letter and -port can't satisfy -p. - Document the bare `version` subcommand (accepted by wantsVersion()) alongside --version in --help, the man page (deploy + embedded copy) and deployment.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The standalone actions (
--self-upgrade,--install-serviceand friends) are intercepted before the flag set parses, so they never showed up in theflagpackage's auto-generated-help— and there was no--versionand no man page. This surfaces them all.--help/-hnow prints a complete usage on stdout (exit 0): a synopsis, a Standalone actions section (--version,--self-upgrade [--check],--install-service/--uninstall-service/--service-status) and every option, via a customflag.Usage.--version(and a bareversionsubcommand) prints the build version.man dockercmd— shipsdeploy/dockercmd.1, embedded in the binary (kept byte-identical to the deploy copy by a test) and installed to/usr/local/share/man/man1/by--install-serviceand theinstall-linux.sh/install-macos.shscripts, so the reference is available offline once installed.Type of change
Checklist
go test -short ./...andgo vet ./...passgofmtgate is clean (gofmt -l $(git ls-files '*.go')after staging)cd web && npx tsc --noEmit) — N/A (no UI change)web/dist— N/A (nothing underweb/srcchanged)docs/and added aCHANGELOG.mdentry for user-facing changesNotes for reviewers
TestManPageMatchesDeployFile(embedded ==deploy/dockercmd.1),TestManPageDocumentsAllFlags(scrapesconfig.go, fails if a flag is undocumented),TestManPageDocumentsActions+TestUsageListsStandaloneActions+TestStandaloneActionArgs(incl.--cutoff).man dockercmddate in the.THline is static (2026-06-15); it'll drift, which is normal for man pages.## [Unreleased]section was opened in the CHANGELOG for this change.