feat: add subcommand for generating docs

.github/workflows/validate_docs.yaml

@@ -0,0 +1,41 @@
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  validate_docs:
+    name: Validate CLI Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        with:
+          fetch-depth: 1
+
+      - name: Set up Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
+        with:
+          go-version-file: go.mod
+
+      - name: Build CLI docs
+        run: make docs
+
+      - name: Detect Uncommitted Docs
+        id: validate_docs
+        run: make docs-check
+
+      - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
+        if: always() && (steps.validate_docs.outcome == 'failure')
+        with:
+          header: pr-docs-error
+          message: |
+            Uncommitted changes were detected in the `docs/` directory.  Please run `make docs` and commit the changes to your branch.
+
+      # Delete a previous comment when the docs have been updated
+      - if: ${{ steps.validate_docs.outcome == 'success' }}
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
+        with:
+          header: pr-docs-error
+          delete: true

Makefile

@@ -1,6 +1,6 @@
+.PHONY: lint fix build docs docs-check
 BINARY=equinix
 
-
 GOLANGCI_LINT_VERSION=v2.3.0
 GOLANGCI_LINT=go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@${GOLANGCI_LINT_VERSION}
 
@@ -11,4 +11,15 @@ fix:
 	$(GOLANGCI_LINT) run -v --fix
 
 build:
-	go build $(LDFLAGS) -o bin/$(BINARY) main.go
+	go build $(LDFLAGS) -o bin/$(BINARY) main.go
+
+docs:
+	rm -rf docs/
+	mkdir -p docs
+	go run main.go docs ./docs
+
+docs-check: docs
+	if git status --porcelain | grep docs; then \
+		echo "Uncommitted changes detected. Run 'make docs' and commit changes."; \
+		exit 1; \
+	fi

README.md

@@ -8,4 +8,4 @@ TODO
 
 ## Usage
 
-TODO
+The full CLI documentation can be found [in the docs directory](docs/equinix.md).

cmd/docs.go

@@ -0,0 +1,25 @@
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+var docsCmd = &cobra.Command{
+	Use:   `docs <destination>`,
+	Short: "Generate markdown documentation for this CLI",
+	Long:  "Generates markdown documentation for this CLI in the specified directory. Each command gets a markdown file.",
+	Example: `  # Generate documentation in the ./docs directory:
+  equinix docs ./docs`,
+
+	DisableFlagsInUseLine: true,
+	Args:                  cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		dest := args[0]
+		return doc.GenMarkdownTree(cmd.Parent(), dest)
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(docsCmd)
+}

docs/equinix.md

@@ -0,0 +1,22 @@
+## equinix
+
+Equinix CLI
+
+### Synopsis
+
+Command-line interface for Equinix APIs
+
+### Options
+
+```
+      --config string   config file (default is $HOME/.cli.yaml)
+  -h, --help            help for equinix
+```
+
+### SEE ALSO
+
+* [equinix api](equinix_api.md)	 - Make a raw API request to the given Equinix API path
+* [equinix completion](equinix_completion.md)	 - Generate the autocompletion script for the specified shell
+* [equinix docs](equinix_docs.md)	 - Generate markdown documentation for this CLI
+
+###### Auto generated by spf13/cobra on 6-Oct-2025

docs/equinix_api.md

@@ -0,0 +1,33 @@
+## equinix api
+
+Make a raw API request to the given Equinix API path
+
+### Synopsis
+
+Make a raw authenticated request to the Equinix API using your configured credentials.
+
+```
+equinix api [url-path] [flags]
+```
+
+### Options
+
+```
+  -d, --data string     Data to send with POST/PUT requests
+  -f, --format string   Format to use for output (json or yaml) (default "json")
+  -h, --help            help for api
+  -X, --method string   HTTP method to use (default "GET")
+      --portal          Use Equinix Portal API (cookie auth)
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file (default is $HOME/.cli.yaml)
+```
+
+### SEE ALSO
+
+* [equinix](equinix.md)	 - Equinix CLI
+
+###### Auto generated by spf13/cobra on 6-Oct-2025

docs/equinix_completion.md

@@ -0,0 +1,31 @@
+## equinix completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for equinix for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file (default is $HOME/.cli.yaml)
+```
+
+### SEE ALSO
+
+* [equinix](equinix.md)	 - Equinix CLI
+* [equinix completion bash](equinix_completion_bash.md)	 - Generate the autocompletion script for bash
+* [equinix completion fish](equinix_completion_fish.md)	 - Generate the autocompletion script for fish
+* [equinix completion powershell](equinix_completion_powershell.md)	 - Generate the autocompletion script for powershell
+* [equinix completion zsh](equinix_completion_zsh.md)	 - Generate the autocompletion script for zsh
+
+###### Auto generated by spf13/cobra on 6-Oct-2025

docs/equinix_completion_bash.md

@@ -0,0 +1,50 @@
+## equinix completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(equinix completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	equinix completion bash > /etc/bash_completion.d/equinix
+
+#### macOS:
+
+	equinix completion bash > $(brew --prefix)/etc/bash_completion.d/equinix
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+equinix completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file (default is $HOME/.cli.yaml)
+```
+
+### SEE ALSO
+
+* [equinix completion](equinix_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 6-Oct-2025

docs/equinix_completion_fish.md

@@ -0,0 +1,41 @@
+## equinix completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	equinix completion fish | source
+
+To load completions for every new session, execute once:
+
+	equinix completion fish > ~/.config/fish/completions/equinix.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+equinix completion fish [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file (default is $HOME/.cli.yaml)
+```
+
+### SEE ALSO
+
+* [equinix completion](equinix_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 6-Oct-2025

docs/equinix_completion_powershell.md

@@ -0,0 +1,38 @@
+## equinix completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	equinix completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+equinix completion powershell [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for powershell
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file (default is $HOME/.cli.yaml)
+```
+
+### SEE ALSO
+
+* [equinix completion](equinix_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 6-Oct-2025

docs/equinix_completion_zsh.md

@@ -0,0 +1,52 @@
+## equinix completion zsh
+
+Generate the autocompletion script for zsh
+
+### Synopsis
+
+Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+	echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+	source <(equinix completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	equinix completion zsh > "${fpath[1]}/_equinix"
+
+#### macOS:
+
+	equinix completion zsh > $(brew --prefix)/share/zsh/site-functions/_equinix
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+equinix completion zsh [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for zsh
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file (default is $HOME/.cli.yaml)
+```
+
+### SEE ALSO
+
+* [equinix completion](equinix_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 6-Oct-2025