Skip to content

Commit cf12aca

Browse files
kgiusticlaude
authored and
mmartinv
committed
docs: add man page and CLI reference generation
Add an internal docgen tool that uses cobra/doc to generate man pages and markdown CLI reference from command definitions. Include generated docs in the build (Makefile) and RPM packaging. - add internal/tools/docgen with tests for man and markdown output - add Makefile targets: docs, man, cli - include man pages in RPM spec - improve Short, Long, and Example fields on all cobra commands - fix --default-working-dir to resolve cwd at runtime, not init time - export Root() for use by doc generators - upgrade cobra to 1.10.2 (adds go-md2man, blackfriday deps) Closes: fido-device-onboard#98 Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Kenneth Giusti <kgiusti@redhat.com>
1 parent 59c2f4d commit cf12aca

19 files changed

Lines changed: 705 additions & 19 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ go-fdo-client
77
go-fdo-client-*.tar.*
88
rpmbuild
99
test/coverage
10+
/docgen

‎Makefile‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ VENDOR_TARBALL := $(SOURCEDIR)/$(PROJECT)-$(VERSION)-vendor.tar.bz2
2020
all: build test
2121

2222
.PHONY: build
23-
build: tidy fmt vet
23+
build: tidy fmt vet docs
2424
go build $(GOFLAGS) -ldflags="-X github.com/fido-device-onboard/go-fdo-client/internal/version.VERSION=$(VERSION)"
2525

2626
.PHONY: tidy
@@ -35,6 +35,17 @@ fmt:
3535
vet:
3636
go vet ./...
3737

38+
.PHONY: docs
39+
docs: man cli
40+
41+
.PHONY: man
42+
man:
43+
go run ./internal/tools/docgen -format man
44+
45+
.PHONY: cli
46+
cli:
47+
go run ./internal/tools/docgen -format markdown
48+
3849
.PHONY: test
3950
test:
4051
go test -v ./...

‎build/package/rpm/go-fdo-client.spec‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ export GO_LDFLAGS="-X %{goipath}/internal/version.VERSION=%{version}"
4949
%install
5050
install -m 0755 -vd %{buildroot}%{_bindir}
5151
install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/
52+
# Man pages
53+
install -m 0755 -vd %{buildroot}%{_mandir}/man1
54+
install -m 0644 -vp docs/man/*.1 %{buildroot}%{_mandir}/man1
5255

5356
%check
5457
%if %{with check}
@@ -59,6 +62,11 @@ install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/
5962
%license LICENSE vendor/modules.txt
6063
%doc README.md
6164
%{_bindir}/go-fdo-client
65+
# Man pages
66+
%{_mandir}/man1/go-fdo-client.1*
67+
%{_mandir}/man1/go-fdo-client-device-init.1*
68+
%{_mandir}/man1/go-fdo-client-onboard.1*
69+
%{_mandir}/man1/go-fdo-client-print.1*
6270

6371
%changelog
6472
%autochangelog

‎cmd/onboard.go‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -119,14 +119,6 @@ At least one of --blob or --tpm is required to access device credentials.`,
119119
func onboardCmdInit() {
120120
rootCmd.AddCommand(onboardCmd)
121121

122-
// Get current working directory for default values
123-
currentDir, err := os.Getwd()
124-
if err != nil {
125-
// If we can't get working directory, leave as empty string
126-
// (validation will require user to specify an absolute path)
127-
currentDir = ""
128-
}
129-
130122
onboardCmd.Flags().Bool("allow-credential-reuse", false, "Allow credential reuse protocol during onboarding")
131123
onboardCmd.Flags().String("cipher", "A128GCM", "Name of cipher suite to use for encryption (see usage)")
132124
onboardCmd.Flags().Bool("enable-interop-test", false, "Enable FIDO Alliance interop test module (fsim.Interop)")
@@ -135,7 +127,7 @@ func onboardCmdInit() {
135127
onboardCmd.Flags().Int("max-serviceinfo-size", serviceinfo.DefaultMTU, "Maximum service info size to receive")
136128
onboardCmd.Flags().Bool("resale", false, "Perform resale")
137129
onboardCmd.Flags().Duration("to2-retry-delay", 0, "Delay between failed TO2 attempts when trying multiple Owner URLs from same RV directive (0=disabled)")
138-
onboardCmd.Flags().String("default-working-dir", currentDir, "Default working directory for all FSIMs (fdo.command, fdo.download, fdo.upload, fdo.wget)")
130+
onboardCmd.Flags().String("default-working-dir", "", "Default working directory for all FSIMs (fdo.command, fdo.download, fdo.upload, fdo.wget) (default: current working directory)")
139131
}
140132

141133
func init() {
@@ -544,6 +536,14 @@ func (ufs *WorkingDirFS) Open(name string) (fs.File, error) {
544536
}
545537

546538
func (o *OnboardClientConfig) validate() error {
539+
// Default to current working directory if not specified
540+
if o.Onboard.DefaultWorkingDir == "" {
541+
cwd, err := os.Getwd()
542+
if err != nil {
543+
return fmt.Errorf("failed to determine current working directory: %w", err)
544+
}
545+
o.Onboard.DefaultWorkingDir = cwd
546+
}
547547
// Validate default working directory is an absolute path
548548
if !filepath.IsAbs(o.Onboard.DefaultWorkingDir) {
549549
return fmt.Errorf("default-working-dir must be an absolute path, got: %s", o.Onboard.DefaultWorkingDir)

‎cmd/print.go‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,16 @@ import (
1414

1515
var printCmd = &cobra.Command{
1616
Use: "print",
17-
Short: "Print device credential blob and exit",
17+
Short: "Print device credentials",
18+
Long: `Print the contents of the device's credential store.
19+
20+
The device credentials are read from either a file (--blob) or a TPM device (--tpm)
21+
and printed to standard output.`,
22+
Example: ` # Print credentials from a blob file:
23+
go-fdo-client print --blob cred.bin
24+
25+
# Print credentials from a TPM:
26+
go-fdo-client print --tpm /dev/tpmrm0`,
1827
RunE: func(cmd *cobra.Command, args []string) error {
1928
if rootConfig.Debug {
2029
level.Set(slog.LevelDebug)
@@ -33,7 +42,7 @@ var printCmd = &cobra.Command{
3342
fmt.Printf("%+v\n", tpmCred)
3443
} else {
3544
if !isValidPath(rootConfig.Blob) {
36-
return fmt.Errorf("invalid blob path: %s", rootConfig.Blob)
45+
return fmt.Errorf("invalid blob file path: %s", rootConfig.Blob)
3746
}
3847
var fileCred fdoDeviceCredential
3948
if err := readCredFile(&fileCred); err != nil {

‎cmd/root.go‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,18 @@ var rootCmd = &cobra.Command{
2727
DisableDefaultCmd: true,
2828
},
2929
SilenceUsage: true,
30-
Use: "go-fdo-client",
31-
Short: "FIDO Device Onboard Client",
32-
Long: `FIDO Device Onboard Client`,
30+
Use: "go-fdo-client {device-init|onboard|print}",
31+
Short: "FIDO Device Onboard (FDO) client",
32+
Long: `Run an FDO client to initialize or onboard a device.
33+
34+
Use one of the subcommands to perform device initialization (DI) with a
35+
manufacturer server, onboard a device via TO1/TO2, or print the stored
36+
device credentials.`,
37+
Example: ` # Initialize a device with a manufacturer server:
38+
go-fdo-client device-init http://127.0.0.1:8038 --key ec256 --blob cred.bin
39+
40+
# Onboard a previously initialized device:
41+
go-fdo-client onboard --key ec256 --kex ECDH256 --blob cred.bin`,
3342
PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
3443
if configFile != "" {
3544
viper.SetConfigFile(configFile)
@@ -56,6 +65,9 @@ func (f *FDOClientConfig) validate() error {
5665
return nil
5766
}
5867

68+
// Root returns the root command for use by doc generators.
69+
func Root() *cobra.Command { return rootCmd }
70+
5971
// Called by main to parse the command line and execute the subcommand
6072
func Execute() error {
6173
// Catch interrupts

‎docs/cli/go-fdo-client.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
## go-fdo-client
2+
3+
FIDO Device Onboard (FDO) client
4+
5+
### Synopsis
6+
7+
Run an FDO client to initialize or onboard a device.
8+
9+
Use one of the subcommands to perform device initialization (DI) with a
10+
manufacturer server, onboard a device via TO1/TO2, or print the stored
11+
device credentials.
12+
13+
### Examples
14+
15+
```
16+
# Initialize a device with a manufacturer server:
17+
go-fdo-client device-init http://127.0.0.1:8038 --key ec256 --blob cred.bin
18+
19+
# Onboard a previously initialized device:
20+
go-fdo-client onboard --key ec256 --kex ECDH256 --blob cred.bin
21+
```
22+
23+
### Options
24+
25+
```
26+
--blob string File path of device credential blob
27+
--config string Path to configuration file (YAML or TOML)
28+
--debug Print HTTP contents
29+
-h, --help help for go-fdo-client
30+
--key string Key type for device credential [options: ec256, ec384, rsa2048, rsa3072]
31+
--tpm string Use a TPM at path for device credential secrets
32+
```
33+
34+
### SEE ALSO
35+
36+
* [go-fdo-client device-init](go-fdo-client_device-init.md) - Run device initialization (DI)
37+
* [go-fdo-client onboard](go-fdo-client_onboard.md) - Run FDO TO1 and TO2 onboarding
38+
* [go-fdo-client print](go-fdo-client_print.md) - Print device credentials
39+

‎docs/cli/go-fdo-client_device-init.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
## go-fdo-client device-init
2+
3+
Run device initialization (DI)
4+
5+
### Synopsis
6+
7+
8+
Run device initialization (DI) to register the device with a manufacturer server.
9+
The server URL can be provided as a positional argument, flag or via config file.
10+
At least one of --blob or --tpm is required to store device credentials.
11+
12+
```
13+
go-fdo-client device-init [server-url] [flags]
14+
```
15+
16+
### Examples
17+
18+
```
19+
20+
# Using CLI arguments:
21+
go-fdo-client device-init http://127.0.0.1:8038 --key ec256 --blob cred.bin
22+
23+
# Using config file:
24+
go-fdo-client device-init --config config.yaml
25+
26+
# Mix CLI and config (CLI takes precedence):
27+
go-fdo-client device-init http://127.0.0.1:8038 --config config.yaml --key ec384
28+
```
29+
30+
### Options
31+
32+
```
33+
--device-info string Device information for device credentials, if not specified, it'll be gathered from the system
34+
--device-info-mac string Mac-address's iface e.g. eth0 for device credentials
35+
-h, --help help for device-init
36+
--insecure-tls Skip TLS certificate verification
37+
--key-enc string Public key encoding to use for manufacturer key [x509,x5chain,cose] (default "x509")
38+
--serial-number string Serial number for device credentials, if not specified, it'll be gathered from the system
39+
```
40+
41+
### Options inherited from parent commands
42+
43+
```
44+
--blob string File path of device credential blob
45+
--config string Path to configuration file (YAML or TOML)
46+
--debug Print HTTP contents
47+
--key string Key type for device credential [options: ec256, ec384, rsa2048, rsa3072]
48+
--tpm string Use a TPM at path for device credential secrets
49+
```
50+
51+
### SEE ALSO
52+
53+
* [go-fdo-client](go-fdo-client.md) - FIDO Device Onboard (FDO) client
54+

‎docs/cli/go-fdo-client_onboard.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## go-fdo-client onboard
2+
3+
Run FDO TO1 and TO2 onboarding
4+
5+
### Synopsis
6+
7+
8+
Run FDO TO1 and TO2 onboarding to transfer device ownership to the owner server.
9+
The device must have been initialized (device-init) before running onboard.
10+
At least one of --blob or --tpm is required to access device credentials.
11+
12+
```
13+
go-fdo-client onboard [flags]
14+
```
15+
16+
### Examples
17+
18+
```
19+
20+
# Using CLI arguments:
21+
go-fdo-client onboard --key ec256 --kex ECDH256 --blob cred.bin
22+
23+
# Using config file:
24+
go-fdo-client onboard --config config.yaml
25+
26+
# Mix CLI and config (CLI takes precedence):
27+
go-fdo-client onboard --config config.yaml --cipher A256GCM
28+
```
29+
30+
### Options
31+
32+
```
33+
--allow-credential-reuse Allow credential reuse protocol during onboarding
34+
--cipher string Name of cipher suite to use for encryption (see usage) (default "A128GCM")
35+
--default-working-dir string Default working directory for all FSIMs (fdo.command, fdo.download, fdo.upload, fdo.wget) (default: current working directory)
36+
--enable-interop-test Enable FIDO Alliance interop test module (fsim.Interop)
37+
-h, --help help for onboard
38+
--insecure-tls Skip TLS certificate verification
39+
--kex string Name of cipher suite to use for key exchange (see usage)
40+
--max-serviceinfo-size int Maximum service info size to receive (default 1300)
41+
--resale Perform resale
42+
--to2-retry-delay duration Delay between failed TO2 attempts when trying multiple Owner URLs from same RV directive (0=disabled)
43+
```
44+
45+
### Options inherited from parent commands
46+
47+
```
48+
--blob string File path of device credential blob
49+
--config string Path to configuration file (YAML or TOML)
50+
--debug Print HTTP contents
51+
--key string Key type for device credential [options: ec256, ec384, rsa2048, rsa3072]
52+
--tpm string Use a TPM at path for device credential secrets
53+
```
54+
55+
### SEE ALSO
56+
57+
* [go-fdo-client](go-fdo-client.md) - FIDO Device Onboard (FDO) client
58+

‎docs/cli/go-fdo-client_print.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
## go-fdo-client print
2+
3+
Print device credentials
4+
5+
### Synopsis
6+
7+
Print the contents of the device's credential store.
8+
9+
The device credentials are read from either a file (--blob) or a TPM device (--tpm)
10+
and printed to standard output.
11+
12+
```
13+
go-fdo-client print [flags]
14+
```
15+
16+
### Examples
17+
18+
```
19+
# Print credentials from a blob file:
20+
go-fdo-client print --blob cred.bin
21+
22+
# Print credentials from a TPM:
23+
go-fdo-client print --tpm /dev/tpmrm0
24+
```
25+
26+
### Options
27+
28+
```
29+
-h, --help help for print
30+
```
31+
32+
### Options inherited from parent commands
33+
34+
```
35+
--blob string File path of device credential blob
36+
--config string Path to configuration file (YAML or TOML)
37+
--debug Print HTTP contents
38+
--key string Key type for device credential [options: ec256, ec384, rsa2048, rsa3072]
39+
--tpm string Use a TPM at path for device credential secrets
40+
```
41+
42+
### SEE ALSO
43+
44+
* [go-fdo-client](go-fdo-client.md) - FIDO Device Onboard (FDO) client
45+

0 commit comments

Comments
 (0)