chore: access command root so that subcommands can be worked in parallel (#100)

* chore: add shared infrastructure for access commands

Adds base command helpers, auth API client methods, test utilities,
and key ID completion support needed by the access key commands.

Author: Davidonium

AGENTS.md

@@ -50,6 +50,33 @@ If make lint fails from formatting problems, use `make format` to fix them.
 
 ## Conventions
 
+### Long descriptions and examples — mandatory
+
+Every leaf command and group command **must** have a `Long` description and an `Example` block.
+
+**`Long`:**
+- First line expands the `Short` description into a full sentence.
+- Blank line, then one or two paragraphs explaining behaviour, use cases, and important caveats.
+- Use the proto service/message comments as the authoritative source of truth for what a resource or operation does.
+- Do NOT describe individual flags — only document unusual or non-obvious flag interactions.
+
+**`Example`:**
+- One example per meaningful use case (basic call, common flag combinations, scripting).
+- Prefix every line with `# ` comment explaining what the example does.
+- Real command invocations with plausible IDs/values.
+
+All five base types (`ListCmd`, `DescribeCmd`, `CreateCmd`, `UpdateCmd`, `Cmd`) expose `Long` and `Example` as top-level struct fields. Never set them inside `BaseCobraCommand()`.
+
+### Tests — mandatory
+
+Every new command package **must** ship tests. This is not optional.
+
+- Place tests in `internal/cmd/<group>/` as `<file>_test.go` using `package <group>_test`.
+- Use `testutil.NewTestEnv` + `testutil.Exec` — never call command functions directly.
+- When adding a new gRPC service, also add a `fake_<service>.go` in `internal/testutil/` and register it in `server.go` / `TestEnv`.
+- Cover: table output (assert header columns + key values), JSON output (unmarshal and assert), request fields sent to server, backend errors (use `Returns(nil, fmt.Errorf(...))` and assert `require.Error`), input errors (missing args, wrong flags).
+- Run `make test` before declaring done.
+
 ### Subcommand pattern
 
 Each subcommand group lives in `internal/cmd/<group>/`:

internal/cli/root.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/qdrant/qcloud-cli/internal/cmd/access"
 	"github.com/qdrant/qcloud-cli/internal/cmd/backup"
 	"github.com/qdrant/qcloud-cli/internal/cmd/cloudprovider"
 	"github.com/qdrant/qcloud-cli/internal/cmd/cloudregion"
@@ -65,6 +66,7 @@ Documentation: https://github.com/qdrant/qcloud-cli`,
 	s.Config.BindPFlag(config.KeyEndpoint, cmd.PersistentFlags().Lookup("endpoint"))
 
 	cmd.AddCommand(version.NewCommand(s))
+	cmd.AddCommand(access.NewCommand(s))
 	cmd.AddCommand(cluster.NewCommand(s))
 	cmd.AddCommand(cloudprovider.NewCommand(s))
 	cmd.AddCommand(cloudregion.NewCommand(s))

internal/cmd/access/access.go

@@ -0,0 +1,18 @@
+package access
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/qdrant/qcloud-cli/internal/state"
+)
+
+// NewCommand creates the access command group.
+func NewCommand(s *state.State) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "access",
+		Short: "Manage access to Qdrant Cloud",
+		Long:  `Manage access settings for the Qdrant Cloud account.`,
+		Args:  cobra.NoArgs,
+	}
+	return cmd
+}

internal/cmd/base/cmd.go

@@ -10,6 +10,7 @@ import (
 // return a resource. Use for delete, wait, use, set, and similar operations.
 type Cmd struct {
 	BaseCobraCommand  func() *cobra.Command
+	Long              string
 	Example           string
 	Run               func(s *state.State, cmd *cobra.Command, args []string) error
 	ValidArgsFunction func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)
@@ -18,6 +19,9 @@ type Cmd struct {
 // CobraCommand builds a cobra.Command from this Cmd.
 func (gc Cmd) CobraCommand(s *state.State) *cobra.Command {
 	cmd := gc.BaseCobraCommand()
+	if gc.Long != "" {
+		cmd.Long = gc.Long
+	}
 	cmd.Example = gc.Example
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		return gc.Run(s, cmd, args)

internal/cmd/base/create.go

@@ -14,6 +14,7 @@ import (
 // Read flags in Run via cmd.Flags().GetString() etc. — do not use bound vars.
 type CreateCmd[T any] struct {
 	BaseCobraCommand  func() *cobra.Command
+	Long              string
 	Example           string
 	Run               func(s *state.State, cmd *cobra.Command, args []string) (T, error)
 	PrintResource     func(cmd *cobra.Command, out io.Writer, resource T)
@@ -23,6 +24,9 @@ type CreateCmd[T any] struct {
 // CobraCommand builds a cobra.Command from this CreateCmd.
 func (cc CreateCmd[T]) CobraCommand(s *state.State) *cobra.Command {
 	cmd := cc.BaseCobraCommand()
+	if cc.Long != "" {
+		cmd.Long = cc.Long
+	}
 	cmd.Example = cc.Example
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		resource, err := cc.Run(s, cmd, args)

internal/cmd/base/list.go

@@ -14,6 +14,7 @@ import (
 type ListCmd[T any] struct {
 	Use               string
 	Short             string
+	Long              string
 	Example           string
 	Fetch             func(s *state.State, cmd *cobra.Command) (T, error)
 	PrintText         func(cmd *cobra.Command, out io.Writer, resp T) error
@@ -25,6 +26,7 @@ func (lc ListCmd[T]) CobraCommand(s *state.State) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     lc.Use,
 		Short:   lc.Short,
+		Long:    lc.Long,
 		Example: lc.Example,
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {

internal/cmd/base/update.go

@@ -15,6 +15,7 @@ import (
 // Read flags in Update via cmd.Flags().GetString() etc. — do not use bound vars.
 type UpdateCmd[T any] struct {
 	BaseCobraCommand  func() *cobra.Command
+	Long              string
 	Example           string
 	Fetch             func(s *state.State, cmd *cobra.Command, args []string) (T, error)
 	Update            func(s *state.State, cmd *cobra.Command, resource T) (T, error)
@@ -25,6 +26,9 @@ type UpdateCmd[T any] struct {
 // CobraCommand builds a cobra.Command from this UpdateCmd.
 func (uc UpdateCmd[T]) CobraCommand(s *state.State) *cobra.Command {
 	cmd := uc.BaseCobraCommand()
+	if uc.Long != "" {
+		cmd.Long = uc.Long
+	}
 	cmd.Example = uc.Example
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		resource, err := uc.Fetch(s, cmd, args)

internal/cmd/completion/completion.go

@@ -3,6 +3,7 @@ package completion
 import (
 	"github.com/spf13/cobra"
 
+	authv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/auth/v1"
 	backupv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/backup/v1"
 	clusterv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/v1"
 	platformv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/platform/v1"
@@ -75,6 +76,39 @@ func CloudRegionCompletion(s *state.State) func(*cobra.Command, []string, string
 	}
 }
 
+// ManagementKeyIDCompletion returns a ValidArgsFunction that completes management key IDs.
+func ManagementKeyIDCompletion(s *state.State) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, _ string) ([]string, cobra.ShellCompDirective) {
+		if len(args) > 0 {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+
+		ctx := cmd.Context()
+		client, err := s.Client(ctx)
+		if err != nil {
+			return nil, cobra.ShellCompDirectiveError
+		}
+
+		accountID, err := s.AccountID()
+		if err != nil {
+			return nil, cobra.ShellCompDirectiveError
+		}
+
+		resp, err := client.Auth().ListManagementKeys(ctx, &authv1.ListManagementKeysRequest{
+			AccountId: accountID,
+		})
+		if err != nil {
+			return nil, cobra.ShellCompDirectiveError
+		}
+
+		completions := make([]string, 0, len(resp.GetItems()))
+		for _, k := range resp.GetItems() {
+			completions = append(completions, k.GetId()+"\t"+k.GetPrefix())
+		}
+		return completions, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
 // BackupIDCompletion returns a ValidArgsFunction that completes backup IDs.
 func BackupIDCompletion(s *state.State) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 	return func(cmd *cobra.Command, args []string, _ string) ([]string, cobra.ShellCompDirective) {

internal/qcloudapi/client.go

@@ -7,6 +7,7 @@ import (
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/metadata"
 
+	authv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/auth/v1"
 	bookingv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/booking/v1"
 	clusterauthv2 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/auth/v2"
 	backupv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/backup/v1"
@@ -26,6 +27,7 @@ type Client struct {
 	backup         backupv1.BackupServiceClient
 	hybrid         hybridv1.HybridCloudServiceClient
 	monitoring     monitoringv1.MonitoringServiceClient
+	auth           authv1.AuthServiceClient
 }
 
 // New creates a new gRPC client connected to the given endpoint with the given API key.
@@ -57,6 +59,7 @@ func newFromConn(conn *grpc.ClientConn) *Client {
 		backup:         backupv1.NewBackupServiceClient(conn),
 		hybrid:         hybridv1.NewHybridCloudServiceClient(conn),
 		monitoring:     monitoringv1.NewMonitoringServiceClient(conn),
+		auth:           authv1.NewAuthServiceClient(conn),
 	}
 }
 
@@ -95,6 +98,11 @@ func (c *Client) Monitoring() monitoringv1.MonitoringServiceClient {
 	return c.monitoring
 }
 
+// Auth returns the AuthService gRPC client.
+func (c *Client) Auth() authv1.AuthServiceClient {
+	return c.auth
+}
+
 // Close closes the underlying gRPC connection.
 func (c *Client) Close() error {
 	return c.conn.Close()

internal/testutil/fake_auth.go

@@ -0,0 +1,35 @@
+package testutil
+
+import (
+	"context"
+
+	authv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/auth/v1"
+)
+
+// FakeAuthService is a test fake that implements AuthServiceServer.
+// Use the *Calls fields to configure responses and inspect captured requests.
+type FakeAuthService struct {
+	authv1.UnimplementedAuthServiceServer
+
+	ListManagementKeysCalls  MethodSpy[*authv1.ListManagementKeysRequest, *authv1.ListManagementKeysResponse]
+	CreateManagementKeyCalls MethodSpy[*authv1.CreateManagementKeyRequest, *authv1.CreateManagementKeyResponse]
+	DeleteManagementKeyCalls MethodSpy[*authv1.DeleteManagementKeyRequest, *authv1.DeleteManagementKeyResponse]
+}
+
+// ListManagementKeys records the call and dispatches via ListManagementKeysCalls.
+func (f *FakeAuthService) ListManagementKeys(ctx context.Context, req *authv1.ListManagementKeysRequest) (*authv1.ListManagementKeysResponse, error) {
+	f.ListManagementKeysCalls.record(req)
+	return f.ListManagementKeysCalls.dispatch(ctx, req, f.UnimplementedAuthServiceServer.ListManagementKeys)
+}
+
+// CreateManagementKey records the call and dispatches via CreateManagementKeyCalls.
+func (f *FakeAuthService) CreateManagementKey(ctx context.Context, req *authv1.CreateManagementKeyRequest) (*authv1.CreateManagementKeyResponse, error) {
+	f.CreateManagementKeyCalls.record(req)
+	return f.CreateManagementKeyCalls.dispatch(ctx, req, f.UnimplementedAuthServiceServer.CreateManagementKey)
+}
+
+// DeleteManagementKey records the call and dispatches via DeleteManagementKeyCalls.
+func (f *FakeAuthService) DeleteManagementKey(ctx context.Context, req *authv1.DeleteManagementKeyRequest) (*authv1.DeleteManagementKeyResponse, error) {
+	f.DeleteManagementKeyCalls.record(req)
+	return f.DeleteManagementKeyCalls.dispatch(ctx, req, f.UnimplementedAuthServiceServer.DeleteManagementKey)
+}