feat: add docs generation from the cobra commands so that further LLM (#116)

models swallow the CLI shape

Author: Davidonium

.github/workflows/ci.yml

@@ -68,3 +68,22 @@ jobs:
 
       - if: failure()
         run: echo "::error::Check failed, please run 'go mod tidy' and commit the changes."
+
+  docs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up tools
+        uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
+        with:
+          version: 2026.3.8
+
+      - name: Check docs are up to date
+        run: make docs-check
+
+      - if: failure()
+        run: echo "::error::Check failed, please run 'make docs' and commit the changes."

Makefile

@@ -1,6 +1,6 @@
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo unknown)
 
-.PHONY: build debug debug-run test lint format clean bootstrap
+.PHONY: build debug debug-run test lint format clean bootstrap docs docs-check
 
 build:
 	CGO_ENABLED=0 go build -ldflags "-X main.version=$(VERSION)" -o build/qcloud ./cmd/qcloud
@@ -32,3 +32,10 @@ bootstrap:
 		{ echo "mise is not installed. Install it from https://mise.jdx.dev/installing-mise.html"; exit 1; }
 	mise install
 
+docs:
+	go run ./cmd/docgen ./docs/reference
+
+docs-check: docs
+	@git diff --exit-code docs/reference/ || \
+		(echo "docs/reference is out of date — run 'make docs' and commit the result" && exit 1)
+

cmd/docgen/main.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"log"
+	"os"
+
+	"github.com/spf13/cobra/doc"
+
+	"github.com/qdrant/qcloud-cli/internal/cli"
+	"github.com/qdrant/qcloud-cli/internal/state"
+)
+
+func main() {
+	outDir := "./docs/reference"
+	if len(os.Args) > 1 {
+		outDir = os.Args[1]
+	}
+
+	if err := os.MkdirAll(outDir, 0755); err != nil {
+		log.Fatalf("create output dir: %v", err)
+	}
+
+	s := state.New("dev")
+	root := cli.NewRootCommand(s)
+	root.DisableAutoGenTag = true
+
+	if err := doc.GenMarkdownTree(root, outDir); err != nil {
+		log.Fatalf("generate docs: %v", err)
+	}
+}

docs/reference/qcloud.md

@@ -0,0 +1,41 @@
+## qcloud
+
+Qdrant Cloud CLI
+
+### Synopsis
+
+The command-line interface for Qdrant Cloud.
+
+Get started:
+  qcloud context set default --api-key <KEY> --account-id <ID>
+  qcloud cluster list
+
+Documentation: https://github.com/qdrant/qcloud-cli
+
+### Options
+
+```
+      --account-id string   Qdrant Cloud Account ID (env: QDRANT_CLOUD_ACCOUNT_ID)
+      --api-key string      Management API Key (env: QDRANT_CLOUD_API_KEY)
+  -c, --config string       Config file path (env: QDRANT_CLOUD_CONFIG, default ~/.config/qcloud/config.yaml)
+      --context string      Override the active context (env: QDRANT_CLOUD_CONTEXT)
+      --debug               Enable debug logging to stderr
+      --endpoint string     gRPC API endpoint (env: QDRANT_CLOUD_ENDPOINT, default grpc.cloud.qdrant.io:443)
+  -h, --help                help for qcloud
+      --json                Output as JSON
+```
+
+### SEE ALSO
+
+* [qcloud account](qcloud_account.md)	 - Manage Qdrant Cloud accounts
+* [qcloud backup](qcloud_backup.md)	 - Manage Qdrant Cloud backups
+* [qcloud cloud-provider](qcloud_cloud-provider.md)	 - Manage cloud providers
+* [qcloud cloud-region](qcloud_cloud-region.md)	 - Manage cloud regions
+* [qcloud cluster](qcloud_cluster.md)	 - Manage Qdrant Cloud clusters
+* [qcloud context](qcloud_context.md)	 - Manage named configuration contexts
+* [qcloud hybrid](qcloud_hybrid.md)	 - Manage hybrid cloud environments
+* [qcloud iam](qcloud_iam.md)	 - Manage IAM resources in Qdrant Cloud
+* [qcloud package](qcloud_package.md)	 - Manage packages
+* [qcloud self-upgrade](qcloud_self-upgrade.md)	 - Upgrade qcloud to the latest version
+* [qcloud version](qcloud_version.md)	 - Print the qcloud CLI version
+

docs/reference/qcloud_account.md

@@ -0,0 +1,38 @@
+## qcloud account
+
+Manage Qdrant Cloud accounts
+
+### Synopsis
+
+Manage Qdrant Cloud accounts and their members.
+
+Use these commands to list, inspect, and update accounts that the current
+management key has access to. Account member commands show who belongs to the
+current account and whether they are the owner.
+
+### Options
+
+```
+  -h, --help   help for account
+```
+
+### Options inherited from parent commands
+
+```
+      --account-id string   Qdrant Cloud Account ID (env: QDRANT_CLOUD_ACCOUNT_ID)
+      --api-key string      Management API Key (env: QDRANT_CLOUD_API_KEY)
+  -c, --config string       Config file path (env: QDRANT_CLOUD_CONFIG, default ~/.config/qcloud/config.yaml)
+      --context string      Override the active context (env: QDRANT_CLOUD_CONTEXT)
+      --debug               Enable debug logging to stderr
+      --endpoint string     gRPC API endpoint (env: QDRANT_CLOUD_ENDPOINT, default grpc.cloud.qdrant.io:443)
+      --json                Output as JSON
+```
+
+### SEE ALSO
+
+* [qcloud](qcloud.md)	 - Qdrant Cloud CLI
+* [qcloud account describe](qcloud_account_describe.md)	 - Describe an account
+* [qcloud account list](qcloud_account_list.md)	 - List accounts
+* [qcloud account member](qcloud_account_member.md)	 - Manage account members
+* [qcloud account update](qcloud_account_update.md)	 - Update an account
+

docs/reference/qcloud_account_describe.md

@@ -0,0 +1,50 @@
+## qcloud account describe
+
+Describe an account
+
+### Synopsis
+
+Describe an account by its ID.
+
+If no account ID is provided, the current account (from --account-id, the
+active context, or the QDRANT_CLOUD_ACCOUNT_ID environment variable) is used.
+
+```
+qcloud account describe [account-id] [flags]
+```
+
+### Examples
+
+```
+# Describe the current account
+qcloud account describe
+
+# Describe a specific account
+qcloud account describe a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+# Output as JSON
+qcloud account describe --json
+```
+
+### Options
+
+```
+  -h, --help   help for describe
+```
+
+### Options inherited from parent commands
+
+```
+      --account-id string   Qdrant Cloud Account ID (env: QDRANT_CLOUD_ACCOUNT_ID)
+      --api-key string      Management API Key (env: QDRANT_CLOUD_API_KEY)
+  -c, --config string       Config file path (env: QDRANT_CLOUD_CONFIG, default ~/.config/qcloud/config.yaml)
+      --context string      Override the active context (env: QDRANT_CLOUD_CONTEXT)
+      --debug               Enable debug logging to stderr
+      --endpoint string     gRPC API endpoint (env: QDRANT_CLOUD_ENDPOINT, default grpc.cloud.qdrant.io:443)
+      --json                Output as JSON
+```
+
+### SEE ALSO
+
+* [qcloud account](qcloud_account.md)	 - Manage Qdrant Cloud accounts
+

docs/reference/qcloud_account_list.md

@@ -0,0 +1,48 @@
+## qcloud account list
+
+List accounts
+
+### Synopsis
+
+List all accounts associated with the authenticated management key.
+
+Returns every account the current API key has access to. No account ID is
+required because the server resolves accounts from the caller's credentials.
+
+```
+qcloud account list [flags]
+```
+
+### Examples
+
+```
+# List all accessible accounts
+qcloud account list
+
+# Output as JSON
+qcloud account list --json
+```
+
+### Options
+
+```
+  -h, --help         help for list
+      --no-headers   Do not print column headers
+```
+
+### Options inherited from parent commands
+
+```
+      --account-id string   Qdrant Cloud Account ID (env: QDRANT_CLOUD_ACCOUNT_ID)
+      --api-key string      Management API Key (env: QDRANT_CLOUD_API_KEY)
+  -c, --config string       Config file path (env: QDRANT_CLOUD_CONFIG, default ~/.config/qcloud/config.yaml)
+      --context string      Override the active context (env: QDRANT_CLOUD_CONTEXT)
+      --debug               Enable debug logging to stderr
+      --endpoint string     gRPC API endpoint (env: QDRANT_CLOUD_ENDPOINT, default grpc.cloud.qdrant.io:443)
+      --json                Output as JSON
+```
+
+### SEE ALSO
+
+* [qcloud account](qcloud_account.md)	 - Manage Qdrant Cloud accounts
+

docs/reference/qcloud_account_member.md

@@ -0,0 +1,36 @@
+## qcloud account member
+
+Manage account members
+
+### Synopsis
+
+Manage members of the current Qdrant Cloud account.
+
+Members are users who have been added to the account. Each member has an
+associated user record and an ownership flag indicating whether they are the
+account owner.
+
+### Options
+
+```
+  -h, --help   help for member
+```
+
+### Options inherited from parent commands
+
+```
+      --account-id string   Qdrant Cloud Account ID (env: QDRANT_CLOUD_ACCOUNT_ID)
+      --api-key string      Management API Key (env: QDRANT_CLOUD_API_KEY)
+  -c, --config string       Config file path (env: QDRANT_CLOUD_CONFIG, default ~/.config/qcloud/config.yaml)
+      --context string      Override the active context (env: QDRANT_CLOUD_CONTEXT)
+      --debug               Enable debug logging to stderr
+      --endpoint string     gRPC API endpoint (env: QDRANT_CLOUD_ENDPOINT, default grpc.cloud.qdrant.io:443)
+      --json                Output as JSON
+```
+
+### SEE ALSO
+
+* [qcloud account](qcloud_account.md)	 - Manage Qdrant Cloud accounts
+* [qcloud account member describe](qcloud_account_member_describe.md)	 - Describe an account member
+* [qcloud account member list](qcloud_account_member_list.md)	 - List account members
+

docs/reference/qcloud_account_member_describe.md

@@ -0,0 +1,46 @@
+## qcloud account member describe
+
+Describe an account member
+
+### Synopsis
+
+Describe a member of the current account by their user ID.
+
+Shows the member's user details and whether they are the account owner.
+
+```
+qcloud account member describe <user-id> [flags]
+```
+
+### Examples
+
+```
+# Describe a member
+qcloud account member describe a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+# Output as JSON
+qcloud account member describe a1b2c3d4-e5f6-7890-abcd-ef1234567890 --json
+```
+
+### Options
+
+```
+  -h, --help   help for describe
+```
+
+### Options inherited from parent commands
+
+```
+      --account-id string   Qdrant Cloud Account ID (env: QDRANT_CLOUD_ACCOUNT_ID)
+      --api-key string      Management API Key (env: QDRANT_CLOUD_API_KEY)
+  -c, --config string       Config file path (env: QDRANT_CLOUD_CONFIG, default ~/.config/qcloud/config.yaml)
+      --context string      Override the active context (env: QDRANT_CLOUD_CONTEXT)
+      --debug               Enable debug logging to stderr
+      --endpoint string     gRPC API endpoint (env: QDRANT_CLOUD_ENDPOINT, default grpc.cloud.qdrant.io:443)
+      --json                Output as JSON
+```
+
+### SEE ALSO
+
+* [qcloud account member](qcloud_account_member.md)	 - Manage account members
+

docs/reference/qcloud_account_member_list.md

@@ -0,0 +1,49 @@
+## qcloud account member list
+
+List account members
+
+### Synopsis
+
+List all members of the current account.
+
+Each member has an associated user record and an ownership flag. Use
+"qcloud iam user list" to see users with their status, or this command to
+see who is in the account and who owns it.
+
+```
+qcloud account member list [flags]
+```
+
+### Examples
+
+```
+# List all members
+qcloud account member list
+
+# Output as JSON
+qcloud account member list --json
+```
+
+### Options
+
+```
+  -h, --help         help for list
+      --no-headers   Do not print column headers
+```
+
+### Options inherited from parent commands
+
+```
+      --account-id string   Qdrant Cloud Account ID (env: QDRANT_CLOUD_ACCOUNT_ID)
+      --api-key string      Management API Key (env: QDRANT_CLOUD_API_KEY)
+  -c, --config string       Config file path (env: QDRANT_CLOUD_CONFIG, default ~/.config/qcloud/config.yaml)
+      --context string      Override the active context (env: QDRANT_CLOUD_CONTEXT)
+      --debug               Enable debug logging to stderr
+      --endpoint string     gRPC API endpoint (env: QDRANT_CLOUD_ENDPOINT, default grpc.cloud.qdrant.io:443)
+      --json                Output as JSON
+```
+
+### SEE ALSO
+
+* [qcloud account member](qcloud_account_member.md)	 - Manage account members
+