cli: migrate the CLI and integration tests to the v1 HTTP API

Replace the gRPC client with the generated HTTP client across every
command: locally over the unix socket without auth (matching the previous
local gRPC socket), remotely over TLS with a Bearer API key. Output
rendering and integration tests move to the HTTP client types; the
transport changes, the assertions do not.

cmd/headscale/cli/api_key.go

@@ -3,9 +3,10 @@ package cli
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strconv"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/spf13/cobra"
 )
@@ -43,26 +44,36 @@ var listAPIKeys = &cobra.Command{
 	Use:     cmdList,
 	Short:   "List the Api keys for headscale",
 	Aliases: []string{"ls", cmdShow},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
-		response, err := client.ListApiKeys(ctx, &v1.ListApiKeysRequest{})
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		resp, err := client.ListApiKeysWithResponse(ctx)
 		if err != nil {
 			return fmt.Errorf("listing api keys: %w", err)
 		}
 
-		return printListOutput(cmd, response.GetApiKeys(), func() error {
-			rows := make([][]string, 0, len(response.GetApiKeys()))
-			for _, key := range response.GetApiKeys() {
-				expiration := "-"
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
 
-				if key.GetExpiration() != nil {
-					expiration = ColourTime(key.GetExpiration().AsTime())
+		apiKeys := resp.JSON200.ApiKeys
+
+		return printListOutput(cmd, apiKeys, func() error {
+			rows := make([][]string, 0, len(apiKeys))
+			for _, key := range apiKeys {
+				expiration := "-"
+				if key.Expiration != nil {
+					expiration = ColourTime(*key.Expiration)
+				}
+
+				var created string
+				if key.CreatedAt != nil {
+					created = key.CreatedAt.Format(HeadscaleDateTimeFormat)
 				}
 
 				rows = append(rows, []string{
-					strconv.FormatUint(key.GetId(), util.Base10),
-					key.GetPrefix(),
+					key.Id,
+					key.Prefix,
 					expiration,
-					key.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
+					created,
 				})
 			}
 
@@ -79,20 +90,24 @@ Creates a new Api key, the Api key is only visible on creation
 and cannot be retrieved again.
 If you lose a key, create a new one and revoke (expire) the old one.`,
 	Aliases: []string{"c", cmdNew},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
-		expiration, err := expirationFromFlag(cmd)
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		expiryTime, err := expirationFromFlag(cmd)
 		if err != nil {
 			return err
 		}
 
-		response, err := client.CreateApiKey(ctx, &v1.CreateApiKeyRequest{
-			Expiration: expiration,
+		resp, err := client.CreateApiKeyWithResponse(ctx, clientv1.CreateApiKeyJSONRequestBody{
+			Expiration: &expiryTime,
 		})
 		if err != nil {
 			return fmt.Errorf("creating api key: %w", err)
 		}
 
-		return printOutput(cmd, response.GetApiKey(), response.GetApiKey())
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.ApiKey, resp.JSON200.ApiKey)
 	}),
 }
 
@@ -116,21 +131,33 @@ var expireAPIKeyCmd = &cobra.Command{
 	Use:     cmdExpire,
 	Short:   "Expire an ApiKey",
 	Aliases: []string{"revoke", aliasExp, "e"},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		id, prefix, err := apiKeyIDOrPrefix(cmd)
 		if err != nil {
 			return err
 		}
 
-		response, err := client.ExpireApiKey(ctx, &v1.ExpireApiKeyRequest{
-			Id:     id,
-			Prefix: prefix,
-		})
+		body := clientv1.ExpireApiKeyJSONRequestBody{}
+
+		if id != 0 {
+			idStr := strconv.FormatUint(id, util.Base10)
+			body.Id = &idStr
+		}
+
+		if prefix != "" {
+			body.Prefix = &prefix
+		}
+
+		resp, err := client.ExpireApiKeyWithResponse(ctx, body)
 		if err != nil {
 			return fmt.Errorf("expiring api key: %w", err)
 		}
 
-		return printOutput(cmd, response, "Key expired")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key expired")
 	}),
 }
 
@@ -138,20 +165,59 @@ var deleteAPIKeyCmd = &cobra.Command{
 	Use:     cmdDelete,
 	Short:   "Delete an ApiKey",
 	Aliases: []string{"remove", aliasDel},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		id, prefix, err := apiKeyIDOrPrefix(cmd)
 		if err != nil {
 			return err
 		}
 
-		response, err := client.DeleteApiKey(ctx, &v1.DeleteApiKeyRequest{
-			Id:     id,
-			Prefix: prefix,
-		})
+		// The DELETE route addresses the key by its prefix in the path. When the
+		// user deletes by --id we resolve the id to its (masked) prefix first,
+		// since the path segment is required and a query-only id cannot be routed.
+		if prefix == "" {
+			prefix, err = apiKeyPrefixForID(ctx, client, id)
+			if err != nil {
+				return err
+			}
+		}
+
+		resp, err := client.DeleteApiKeyWithResponse(ctx, prefix, &clientv1.DeleteApiKeyParams{})
 		if err != nil {
 			return fmt.Errorf("deleting api key: %w", err)
 		}
 
-		return printOutput(cmd, response, "Key deleted")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key deleted")
 	}),
 }
+
+// apiKeyPrefixForID resolves an API key id to its display prefix by listing the
+// keys. The DELETE endpoint addresses keys by prefix in the URL path, so a
+// delete by --id needs the prefix; the returned masked prefix is accepted by
+// the server's lookup.
+func apiKeyPrefixForID(
+	ctx context.Context,
+	client *clientv1.ClientWithResponses,
+	id uint64,
+) (string, error) {
+	resp, err := client.ListApiKeysWithResponse(ctx)
+	if err != nil {
+		return "", fmt.Errorf("listing api keys: %w", err)
+	}
+
+	if resp.StatusCode() != http.StatusOK {
+		return "", apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+	}
+
+	idStr := strconv.FormatUint(id, util.Base10)
+	for _, key := range resp.JSON200.ApiKeys {
+		if key.Id == idStr {
+			return key.Prefix, nil
+		}
+	}
+
+	return "", fmt.Errorf("%w: api key %d not found", errMissingParameter, id)
+}

cmd/headscale/cli/auth.go

@@ -3,8 +3,9 @@ package cli
 import (
 	"context"
 	"fmt"
+	"net/http"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/spf13/cobra"
 )
 
@@ -33,62 +34,66 @@ var authCmd = &cobra.Command{
 var authRegisterCmd = &cobra.Command{
 	Use:   "register",
 	Short: "Register a node to your network",
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetString("user")
 		authID, _ := cmd.Flags().GetString("auth-id")
 
-		request := &v1.AuthRegisterRequest{
-			AuthId: authID,
-			User:   user,
-		}
-
-		response, err := client.AuthRegister(ctx, request)
+		resp, err := client.AuthRegisterWithResponse(ctx, clientv1.AuthRegisterJSONRequestBody{
+			AuthId: &authID,
+			User:   &user,
+		})
 		if err != nil {
 			return fmt.Errorf("registering node: %w", err)
 		}
 
-		return printOutput(
-			cmd,
-			response.GetNode(),
-			fmt.Sprintf("Node %s registered", response.GetNode().GetGivenName()),
-		)
-	}),
-}
-
-// authDecisionRunE builds a RunE for an auth decision command (approve or
-// reject) that reads the auth-id flag, invokes the given gRPC call, and prints
-// the response. errVerb is used in the error message; okMsg is printed on
-// success.
-func authDecisionRunE[Resp any](
-	errVerb, okMsg string,
-	call func(ctx context.Context, client v1.HeadscaleServiceClient, authID string) (Resp, error),
-) func(*cobra.Command, []string) error {
-	return grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
-		authID, _ := cmd.Flags().GetString("auth-id")
-
-		response, err := call(ctx, client, authID)
-		if err != nil {
-			return fmt.Errorf("%s auth request: %w", errVerb, err)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		return printOutput(cmd, response, okMsg)
-	})
+		node := resp.JSON200.Node
+
+		return printOutput(
+			cmd,
+			node,
+			fmt.Sprintf("Node %s registered", node.GivenName),
+		)
+	}),
 }
 
 var authApproveCmd = &cobra.Command{
 	Use:   "approve",
 	Short: "Approve a pending authentication request",
-	RunE: authDecisionRunE("approving", "Auth request approved",
-		func(ctx context.Context, client v1.HeadscaleServiceClient, authID string) (*v1.AuthApproveResponse, error) {
-			return client.AuthApprove(ctx, &v1.AuthApproveRequest{AuthId: authID})
-		}),
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		resp, err := client.AuthApproveWithResponse(ctx, clientv1.AuthApproveJSONRequestBody{AuthId: &authID})
+		if err != nil {
+			return fmt.Errorf("approving auth request: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Auth request approved")
+	}),
 }
 
 var authRejectCmd = &cobra.Command{
 	Use:   "reject",
 	Short: "Reject a pending authentication request",
-	RunE: authDecisionRunE("rejecting", "Auth request rejected",
-		func(ctx context.Context, client v1.HeadscaleServiceClient, authID string) (*v1.AuthRejectResponse, error) {
-			return client.AuthReject(ctx, &v1.AuthRejectRequest{AuthId: authID})
-		}),
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		resp, err := client.AuthRejectWithResponse(ctx, clientv1.AuthRejectJSONRequestBody{AuthId: &authID})
+		if err != nil {
+			return fmt.Errorf("rejecting auth request: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Auth request rejected")
+	}),
 }

cmd/headscale/cli/debug.go

@@ -3,8 +3,9 @@ package cli
 import (
 	"context"
 	"fmt"
+	"net/http"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/spf13/cobra"
 )
@@ -32,7 +33,7 @@ var debugCmd = &cobra.Command{
 var createNodeCmd = &cobra.Command{
 	Use:   "create-node",
 	Short: "Create a node that can be registered with `auth register <>` command",
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetString("user")
 		name, _ := cmd.Flags().GetString("name")
 		registrationID, _ := cmd.Flags().GetString("key")
@@ -44,18 +45,20 @@ var createNodeCmd = &cobra.Command{
 
 		routes, _ := cmd.Flags().GetStringSlice("route")
 
-		request := &v1.DebugCreateNodeRequest{
-			Key:    registrationID,
-			Name:   name,
-			User:   user,
-			Routes: routes,
-		}
-
-		response, err := client.DebugCreateNode(ctx, request)
+		resp, err := client.DebugCreateNodeWithResponse(ctx, clientv1.DebugCreateNodeJSONRequestBody{
+			Key:    &registrationID,
+			Name:   &name,
+			User:   &user,
+			Routes: &routes,
+		})
 		if err != nil {
 			return fmt.Errorf("creating node: %w", err)
 		}
 
-		return printOutput(cmd, response.GetNode(), "Node created")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.Node, "Node created")
 	}),
 }

cmd/headscale/cli/health.go

@@ -3,8 +3,9 @@ package cli
 import (
 	"context"
 	"fmt"
+	"net/http"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/spf13/cobra"
 )
 
@@ -16,12 +17,16 @@ var healthCmd = &cobra.Command{
 	Use:   "health",
 	Short: "Check the health of the Headscale server",
 	Long:  "Check the health of the Headscale server. This command will return an exit code of 0 if the server is healthy, or 1 if it is not.",
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
-		response, err := client.Health(ctx, &v1.HealthRequest{})
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		resp, err := client.HealthWithResponse(ctx)
 		if err != nil {
 			return fmt.Errorf("checking health: %w", err)
 		}
 
-		return printOutput(cmd, response, "")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "")
 	}),
 }

cmd/headscale/cli/nodes.go

@@ -3,17 +3,17 @@ package cli
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"net/netip"
 	"strconv"
 	"strings"
 	"time"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/pterm/pterm"
 	"github.com/samber/lo"
 	"github.com/spf13/cobra"
-	"google.golang.org/protobuf/types/known/timestamppb"
 	"tailscale.com/types/key"
 )
 
@@ -67,24 +67,30 @@ var registerNodeCmd = &cobra.Command{
 	Use:        "register",
 	Short:      "Registers a node to your network",
 	Deprecated: "use 'headscale auth register --auth-id <id> --user <user>' instead",
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetString("user")
 		registrationID, _ := cmd.Flags().GetString("key")
 
-		request := &v1.RegisterNodeRequest{
-			Key:  registrationID,
-			User: user,
+		params := &clientv1.RegisterNodeParams{
+			User: &user,
+			Key:  &registrationID,
 		}
 
-		response, err := client.RegisterNode(ctx, request)
+		resp, err := client.RegisterNodeWithResponse(ctx, params)
 		if err != nil {
 			return fmt.Errorf("registering node: %w", err)
 		}
 
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		node := resp.JSON200.Node
+
 		return printOutput(
 			cmd,
-			response.GetNode(),
-			fmt.Sprintf("Node %s registered", response.GetNode().GetGivenName()),
+			node,
+			fmt.Sprintf("Node %s registered", node.GivenName),
 		)
 	}),
 }
@@ -93,16 +99,27 @@ var listNodesCmd = &cobra.Command{
 	Use:     cmdList,
 	Short:   "List nodes",
 	Aliases: []string{"ls", cmdShow},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetString("user")
 
-		response, err := client.ListNodes(ctx, &v1.ListNodesRequest{User: user})
+		params := &clientv1.ListNodesParams{}
+		if user != "" {
+			params.User = &user
+		}
+
+		resp, err := client.ListNodesWithResponse(ctx, params)
 		if err != nil {
 			return fmt.Errorf("listing nodes: %w", err)
 		}
 
-		return printListOutput(cmd, response.GetNodes(), func() error {
-			tableData, err := nodesToPtables(response.GetNodes())
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		nodes := resp.JSON200.Nodes
+
+		return printListOutput(cmd, nodes, func() error {
+			tableData, err := nodesToPtables(nodes)
 			if err != nil {
 				return fmt.Errorf("converting to table: %w", err)
 			}
@@ -116,27 +133,32 @@ var listNodeRoutesCmd = &cobra.Command{
 	Use:     "list-routes",
 	Short:   "List routes available on nodes",
 	Aliases: []string{"lsr", "routes"},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
 
-		response, err := client.ListNodes(ctx, &v1.ListNodesRequest{})
+		resp, err := client.ListNodesWithResponse(ctx, &clientv1.ListNodesParams{})
 		if err != nil {
 			return fmt.Errorf("listing nodes: %w", err)
 		}
 
-		nodes := response.GetNodes()
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		nodes := resp.JSON200.Nodes
 		if identifier != 0 {
-			for _, node := range response.GetNodes() {
-				if node.GetId() == identifier {
-					nodes = []*v1.Node{node}
+			idStr := strconv.FormatUint(identifier, util.Base10)
+			for _, node := range nodes {
+				if node.Id == idStr {
+					nodes = []clientv1.Node{node}
 
 					break
 				}
 			}
 		}
 
-		nodes = lo.Filter(nodes, func(n *v1.Node, _ int) bool {
-			return len(n.GetSubnetRoutes()) > 0 || len(n.GetApprovedRoutes()) > 0 || len(n.GetAvailableRoutes()) > 0
+		nodes = lo.Filter(nodes, func(n clientv1.Node, _ int) bool {
+			return len(n.SubnetRoutes) > 0 || len(n.ApprovedRoutes) > 0 || len(n.AvailableRoutes) > 0
 		})
 
 		return printListOutput(cmd, nodes, func() error {
@@ -152,23 +174,27 @@ var expireNodeCmd = &cobra.Command{
 
 Use --disable to disable key expiry (node will never expire).`,
 	Aliases: []string{"logout", aliasExp, "e"},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
 		disableExpiry, _ := cmd.Flags().GetBool("disable")
+		nodeID := strconv.FormatUint(identifier, util.Base10)
 
 		// Handle disable expiry - node will never expire.
 		if disableExpiry {
-			request := &v1.ExpireNodeRequest{
-				NodeId:        identifier,
-				DisableExpiry: true,
-			}
+			disable := true
 
-			response, err := client.ExpireNode(ctx, request)
+			resp, err := client.ExpireNodeWithResponse(ctx, nodeID, clientv1.ExpireNodeJSONRequestBody{
+				DisableExpiry: &disable,
+			})
 			if err != nil {
 				return fmt.Errorf("disabling node expiry: %w", err)
 			}
 
-			return printOutput(cmd, response.GetNode(), "Node expiry disabled")
+			if resp.StatusCode() != http.StatusOK {
+				return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+			}
+
+			return printOutput(cmd, resp.JSON200.Node, "Node expiry disabled")
 		}
 
 		expiry, _ := cmd.Flags().GetString("expiry")
@@ -186,28 +212,31 @@ Use --disable to disable key expiry (node will never expire).`,
 			}
 		}
 
-		request := &v1.ExpireNodeRequest{
-			NodeId: identifier,
-			Expiry: timestamppb.New(expiryTime),
-		}
-
-		response, err := client.ExpireNode(ctx, request)
+		resp, err := client.ExpireNodeWithResponse(ctx, nodeID, clientv1.ExpireNodeJSONRequestBody{
+			Expiry: &expiryTime,
+		})
 		if err != nil {
 			return fmt.Errorf("expiring node: %w", err)
 		}
 
-		if now.Equal(expiryTime) || now.After(expiryTime) {
-			return printOutput(cmd, response.GetNode(), "Node expired")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		return printOutput(cmd, response.GetNode(), "Node expiration updated")
+		node := resp.JSON200.Node
+
+		if now.Equal(expiryTime) || now.After(expiryTime) {
+			return printOutput(cmd, node, "Node expired")
+		}
+
+		return printOutput(cmd, node, "Node expiration updated")
 	}),
 }
 
 var renameNodeCmd = &cobra.Command{
 	Use:   "rename NEW_NAME",
 	Short: "Renames a node in your network",
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
 
 		newName := ""
@@ -215,17 +244,16 @@ var renameNodeCmd = &cobra.Command{
 			newName = args[0]
 		}
 
-		request := &v1.RenameNodeRequest{
-			NodeId:  identifier,
-			NewName: newName,
-		}
-
-		response, err := client.RenameNode(ctx, request)
+		resp, err := client.RenameNodeWithResponse(ctx, strconv.FormatUint(identifier, util.Base10), newName)
 		if err != nil {
 			return fmt.Errorf("renaming node: %w", err)
 		}
 
-		return printOutput(cmd, response.GetNode(), "Node renamed")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.Node, "Node renamed")
 	}),
 }
 
@@ -233,34 +261,35 @@ var deleteNodeCmd = &cobra.Command{
 	Use:     cmdDelete,
 	Short:   "Delete a node",
 	Aliases: []string{aliasDel},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
+		nodeID := strconv.FormatUint(identifier, util.Base10)
 
-		getRequest := &v1.GetNodeRequest{
-			NodeId: identifier,
-		}
-
-		getResponse, err := client.GetNode(ctx, getRequest)
+		getResponse, err := client.GetNodeWithResponse(ctx, nodeID)
 		if err != nil {
 			return fmt.Errorf("getting node: %w", err)
 		}
 
-		deleteRequest := &v1.DeleteNodeRequest{
-			NodeId: identifier,
+		if getResponse.StatusCode() != http.StatusOK {
+			return apiError(getResponse.StatusCode(), getResponse.ApplicationproblemJSONDefault)
 		}
 
 		if !confirmAction(cmd, fmt.Sprintf(
 			"Do you want to remove the node %s?",
-			getResponse.GetNode().GetName(),
+			getResponse.JSON200.Node.Name,
 		)) {
 			return printOutput(cmd, map[string]string{colResult: "Node not deleted"}, "Node not deleted")
 		}
 
-		_, err = client.DeleteNode(ctx, deleteRequest)
+		deleteResponse, err := client.DeleteNodeWithResponse(ctx, nodeID)
 		if err != nil {
 			return fmt.Errorf("deleting node: %w", err)
 		}
 
+		if deleteResponse.StatusCode() != http.StatusOK {
+			return apiError(deleteResponse.StatusCode(), deleteResponse.ApplicationproblemJSONDefault)
+		}
+
 		return printOutput(
 			cmd,
 			map[string]string{colResult: "Node deleted"},
@@ -289,23 +318,26 @@ be assigned to nodes.`,
 			return nil
 		}
 
-		ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
-		if err != nil {
-			return fmt.Errorf("connecting to headscale: %w", err)
-		}
-		defer cancel()
-		defer conn.Close()
+		return withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+			confirmed := true
 
-		changes, err := client.BackfillNodeIPs(ctx, &v1.BackfillNodeIPsRequest{Confirmed: true})
-		if err != nil {
-			return fmt.Errorf("backfilling IPs: %w", err)
-		}
+			resp, err := client.BackfillNodeIPsWithResponse(ctx, &clientv1.BackfillNodeIPsParams{
+				Confirmed: &confirmed,
+			})
+			if err != nil {
+				return fmt.Errorf("backfilling IPs: %w", err)
+			}
 
-		return printOutput(cmd, changes, "Node IPs backfilled successfully")
+			if resp.StatusCode() != http.StatusOK {
+				return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+			}
+
+			return printOutput(cmd, resp.JSON200, "Node IPs backfilled successfully")
+		})
 	},
 }
 
-func nodesToPtables(nodes []*v1.Node) (pterm.TableData, error) {
+func nodesToPtables(nodes []clientv1.Node) (pterm.TableData, error) {
 	tableHeader := []string{
 		"ID",
 		"Hostname",
@@ -325,75 +357,49 @@ func nodesToPtables(nodes []*v1.Node) (pterm.TableData, error) {
 	tableData[0] = tableHeader
 
 	for _, node := range nodes {
-		var ephemeral bool
-		if node.GetPreAuthKey() != nil && node.GetPreAuthKey().GetEphemeral() {
-			ephemeral = true
+		// An absent pre-auth key decodes into a zero NodePreAuthKey, so guard
+		// on Id before reading its flags.
+		ephemeral := node.PreAuthKey.Id != "" && node.PreAuthKey.Ephemeral
+
+		var lastSeenTime string
+		if node.LastSeen != nil {
+			lastSeenTime = node.LastSeen.Format(HeadscaleDateTimeFormat)
 		}
 
-		var (
-			lastSeen     time.Time
-			lastSeenTime string
-		)
-
-		if node.GetLastSeen() != nil {
-			lastSeen = node.GetLastSeen().AsTime()
-			lastSeenTime = lastSeen.Format(HeadscaleDateTimeFormat)
-		}
-
-		var (
-			expiry     time.Time
-			expiryTime string
-		)
-
-		if node.GetExpiry() != nil {
-			expiry = node.GetExpiry().AsTime()
-			expiryTime = expiry.Format(HeadscaleDateTimeFormat)
-		} else {
-			expiryTime = "N/A"
+		expiryTime := "N/A"
+		if node.Expiry != nil {
+			expiryTime = node.Expiry.Format(HeadscaleDateTimeFormat)
 		}
 
 		var machineKey key.MachinePublic
 
-		err := machineKey.UnmarshalText(
-			[]byte(node.GetMachineKey()),
-		)
+		err := machineKey.UnmarshalText([]byte(node.MachineKey))
 		if err != nil {
 			machineKey = key.MachinePublic{}
 		}
 
 		var nodeKey key.NodePublic
 
-		err = nodeKey.UnmarshalText(
-			[]byte(node.GetNodeKey()),
-		)
+		err = nodeKey.UnmarshalText([]byte(node.NodeKey))
 		if err != nil {
 			return nil, err
 		}
 
-		var online string
-		if node.GetOnline() {
+		online := pterm.LightRed("offline")
+		if node.Online {
 			online = pterm.LightGreen("online")
-		} else {
-			online = pterm.LightRed("offline")
 		}
 
-		var expired string
-		if node.GetExpiry() != nil && node.GetExpiry().AsTime().Before(time.Now()) {
+		expired := pterm.LightGreen("no")
+		if node.Expiry != nil && node.Expiry.Before(time.Now()) {
 			expired = pterm.LightRed("yes")
-		} else {
-			expired = pterm.LightGreen("no")
 		}
 
-		tags := strings.Join(node.GetTags(), "\n")
-
-		var user string
-		if node.GetUser() != nil {
-			user = node.GetUser().GetName()
-		}
+		tags := strings.Join(node.Tags, "\n")
 
 		var ipBuilder strings.Builder
 
-		for _, addr := range node.GetIpAddresses() {
+		for _, addr := range node.IpAddresses {
 			ip, err := netip.ParseAddr(addr)
 			if err == nil {
 				if ipBuilder.Len() > 0 {
@@ -407,12 +413,12 @@ func nodesToPtables(nodes []*v1.Node) (pterm.TableData, error) {
 		ipAddresses := ipBuilder.String()
 
 		nodeData := []string{
-			strconv.FormatUint(node.GetId(), util.Base10),
-			node.GetName(),
-			node.GetGivenName(),
+			node.Id,
+			node.Name,
+			node.GivenName,
 			machineKey.ShortString(),
 			nodeKey.ShortString(),
-			user,
+			node.User.Name,
 			tags,
 			ipAddresses,
 			strconv.FormatBool(ephemeral),
@@ -431,7 +437,7 @@ func nodesToPtables(nodes []*v1.Node) (pterm.TableData, error) {
 }
 
 func nodeRoutesToPtables(
-	nodes []*v1.Node,
+	nodes []clientv1.Node,
 ) pterm.TableData {
 	tableHeader := []string{
 		"ID",
@@ -445,11 +451,11 @@ func nodeRoutesToPtables(
 
 	for _, node := range nodes {
 		nodeData := []string{
-			strconv.FormatUint(node.GetId(), util.Base10),
-			node.GetGivenName(),
-			strings.Join(node.GetApprovedRoutes(), "\n"),
-			strings.Join(node.GetAvailableRoutes(), "\n"),
-			strings.Join(node.GetSubnetRoutes(), "\n"),
+			node.Id,
+			node.GivenName,
+			strings.Join(node.ApprovedRoutes, "\n"),
+			strings.Join(node.AvailableRoutes, "\n"),
+			strings.Join(node.SubnetRoutes, "\n"),
 		}
 		tableData = append(
 			tableData,
@@ -464,43 +470,43 @@ var tagCmd = &cobra.Command{
 	Use:     "tag",
 	Short:   "Manage the tags of a node",
 	Aliases: []string{"tags", "t"},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
 		tagsToSet, _ := cmd.Flags().GetStringSlice("tags")
 
-		// Sending tags to node
-		request := &v1.SetTagsRequest{
-			NodeId: identifier,
-			Tags:   tagsToSet,
-		}
-
-		resp, err := client.SetTags(ctx, request)
+		resp, err := client.SetTagsWithResponse(ctx, strconv.FormatUint(identifier, util.Base10), clientv1.SetTagsJSONRequestBody{
+			Tags: &tagsToSet,
+		})
 		if err != nil {
 			return fmt.Errorf("setting tags: %w", err)
 		}
 
-		return printOutput(cmd, resp.GetNode(), "Node updated")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.Node, "Node updated")
 	}),
 }
 
 var approveRoutesCmd = &cobra.Command{
 	Use:   "approve-routes",
 	Short: "Manage the approved routes of a node",
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
 		routes, _ := cmd.Flags().GetStringSlice("routes")
 
-		// Sending routes to node
-		request := &v1.SetApprovedRoutesRequest{
-			NodeId: identifier,
-			Routes: routes,
-		}
-
-		resp, err := client.SetApprovedRoutes(ctx, request)
+		resp, err := client.SetApprovedRoutesWithResponse(ctx, strconv.FormatUint(identifier, util.Base10), clientv1.SetApprovedRoutesJSONRequestBody{
+			Routes: &routes,
+		})
 		if err != nil {
 			return fmt.Errorf("setting approved routes: %w", err)
 		}
 
-		return printOutput(cmd, resp.GetNode(), "Node updated")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.Node, "Node updated")
 	}),
 }

cmd/headscale/cli/policy.go

@@ -4,9 +4,10 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/http"
 	"os"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/db"
 	"github.com/juanfont/headscale/hscontrol/policy"
 	"github.com/juanfont/headscale/hscontrol/types"
@@ -15,14 +16,13 @@ import (
 )
 
 const (
-	bypassFlag = "bypass-grpc-and-access-database-directly" //nolint:gosec // not a credential
+	bypassFlag = "bypass-server-and-access-database-directly" //nolint:gosec // not a credential
 )
 
 var errAborted = errors.New("command aborted by user")
 
-// bypassDatabase loads the server config and opens the database directly,
-// bypassing the gRPC server. The caller is responsible for closing the
-// returned database handle.
+// bypassDatabase opens the database directly, bypassing the running server.
+// The caller must close the returned handle.
 func bypassDatabase() (*db.HSDatabase, error) {
 	cfg, err := types.LoadServerConfig()
 	if err != nil {
@@ -50,16 +50,16 @@ func openBypassDB(cmd *cobra.Command) (*db.HSDatabase, error) {
 func init() {
 	rootCmd.AddCommand(policyCmd)
 
-	getPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing gRPC and does not require the server to be running")
+	getPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing the API and does not require the server to be running")
 	policyCmd.AddCommand(getPolicy)
 
 	setPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
-	setPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing gRPC and does not require the server to be running")
+	setPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing the API and does not require the server to be running")
 	mustMarkRequired(setPolicy, "file")
 	policyCmd.AddCommand(setPolicy)
 
 	checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
-	checkPolicy.Flags().BoolP(bypassFlag, "", false, "Open the database directly (no gRPC, no running server) to resolve user references and to evaluate the policy's tests and sshTests blocks. Required when those checks are needed.")
+	checkPolicy.Flags().BoolP(bypassFlag, "", false, "Open the database directly (no running server required) to resolve user references and to evaluate the policy's tests and sshTests blocks. Required when those checks are needed.")
 	mustMarkRequired(checkPolicy, "file")
 	policyCmd.AddCommand(checkPolicy)
 }
@@ -90,13 +90,17 @@ var getPolicy = &cobra.Command{
 
 			policyData = pol.Data
 		} else {
-			err := withGRPC(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
-				response, err := client.GetPolicy(ctx, &v1.GetPolicyRequest{})
+			err := withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+				resp, err := client.GetPolicyWithResponse(ctx)
 				if err != nil {
 					return fmt.Errorf("loading ACL policy: %w", err)
 				}
 
-				policyData = response.GetPolicy()
+				if resp.StatusCode() != http.StatusOK {
+					return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+				}
+
+				policyData = resp.JSON200.Policy
 
 				return nil
 			})
@@ -150,14 +154,20 @@ var setPolicy = &cobra.Command{
 				return fmt.Errorf("setting ACL policy: %w", err)
 			}
 		} else {
-			request := &v1.SetPolicyRequest{Policy: string(policyBytes)}
+			policyStr := string(policyBytes)
 
-			err := withGRPC(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
-				_, err := client.SetPolicy(ctx, request)
+			err := withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+				resp, err := client.SetPolicyWithResponse(ctx, clientv1.SetPolicyJSONRequestBody{
+					Policy: &policyStr,
+				})
 				if err != nil {
 					return fmt.Errorf("setting ACL policy: %w", err)
 				}
 
+				if resp.StatusCode() != http.StatusOK {
+					return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+				}
+
 				return nil
 			})
 			if err != nil {
@@ -176,8 +186,8 @@ var checkPolicy = &cobra.Command{
 	Short: "Check the Policy file for errors",
 	Long: `
 	Check validates the policy against the server's live users and nodes,
-	running any "tests" or "sshTests" block. By default the command is a
-	thin frontend for a gRPC call to a running headscale; pass --` + bypassFlag + ` to
+	running any "tests" or "sshTests" block. By default the command calls a
+	running headscale over its API; pass --` + bypassFlag + ` to
 	open the database directly when headscale is not running.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		policyPath, _ := cmd.Flags().GetString("file")
@@ -223,10 +233,21 @@ var checkPolicy = &cobra.Command{
 			return nil
 		}
 
-		err = withGRPC(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
-			_, err := client.CheckPolicy(ctx, &v1.CheckPolicyRequest{Policy: string(policyBytes)})
+		policyStr := string(policyBytes)
 
-			return err
+		err = withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+			resp, err := client.CheckPolicyWithResponse(ctx, clientv1.CheckPolicyJSONRequestBody{
+				Policy: &policyStr,
+			})
+			if err != nil {
+				return err
+			}
+
+			if resp.StatusCode() != http.StatusOK {
+				return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+			}
+
+			return nil
 		})
 		if err != nil {
 			return err

cmd/headscale/cli/preauthkeys.go

@@ -3,10 +3,11 @@ package cli
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strconv"
 	"strings"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/spf13/cobra"
 )
@@ -44,37 +45,40 @@ var listPreAuthKeys = &cobra.Command{
 	Use:     cmdList,
 	Short:   "List all preauthkeys",
 	Aliases: []string{"ls", cmdShow},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
-		response, err := client.ListPreAuthKeys(ctx, &v1.ListPreAuthKeysRequest{})
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		resp, err := client.ListPreAuthKeysWithResponse(ctx)
 		if err != nil {
 			return fmt.Errorf("listing preauthkeys: %w", err)
 		}
 
-		return printListOutput(cmd, response.GetPreAuthKeys(), func() error {
-			rows := make([][]string, 0, len(response.GetPreAuthKeys()))
-			for _, key := range response.GetPreAuthKeys() {
-				expiration := "-"
-				if key.GetExpiration() != nil {
-					expiration = ColourTime(key.GetExpiration().AsTime())
-				}
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
 
-				var owner string
-				if len(key.GetAclTags()) > 0 {
-					owner = strings.Join(key.GetAclTags(), "\n")
-				} else if key.GetUser() != nil {
-					owner = key.GetUser().GetName()
-				} else {
-					owner = "-"
+		preAuthKeys := resp.JSON200.PreAuthKeys
+
+		return printListOutput(cmd, preAuthKeys, func() error {
+			rows := make([][]string, 0, len(preAuthKeys))
+			for _, key := range preAuthKeys {
+				expiration := ColourTime(key.Expiration)
+
+				owner := "-"
+
+				switch {
+				case len(key.AclTags) > 0:
+					owner = strings.Join(key.AclTags, "\n")
+				case key.User.Id != "":
+					owner = key.User.Name
 				}
 
 				rows = append(rows, []string{
-					strconv.FormatUint(key.GetId(), util.Base10),
-					key.GetKey(),
-					strconv.FormatBool(key.GetReusable()),
-					strconv.FormatBool(key.GetEphemeral()),
-					strconv.FormatBool(key.GetUsed()),
+					key.Id,
+					key.Key,
+					strconv.FormatBool(key.Reusable),
+					strconv.FormatBool(key.Ephemeral),
+					strconv.FormatBool(key.Used),
 					expiration,
-					key.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
+					key.CreatedAt.Format(HeadscaleDateTimeFormat),
 					owner,
 				})
 			}
@@ -97,31 +101,39 @@ var createPreAuthKeyCmd = &cobra.Command{
 	Use:     "create",
 	Short:   "Creates a new preauthkey",
 	Aliases: []string{"c", cmdNew},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetUint64("user")
 		reusable, _ := cmd.Flags().GetBool("reusable")
 		ephemeral, _ := cmd.Flags().GetBool("ephemeral")
 		tags, _ := cmd.Flags().GetStringSlice("tags")
 
-		expiration, err := expirationFromFlag(cmd)
+		expiryTime, err := expirationFromFlag(cmd)
 		if err != nil {
 			return err
 		}
 
-		request := &v1.CreatePreAuthKeyRequest{
-			User:       user,
-			Reusable:   reusable,
-			Ephemeral:  ephemeral,
-			AclTags:    tags,
-			Expiration: expiration,
+		userStr := strconv.FormatUint(user, util.Base10)
+
+		request := clientv1.CreatePreAuthKeyJSONRequestBody{
+			User:       &userStr,
+			Reusable:   &reusable,
+			Ephemeral:  &ephemeral,
+			AclTags:    &tags,
+			Expiration: &expiryTime,
 		}
 
-		response, err := client.CreatePreAuthKey(ctx, request)
+		resp, err := client.CreatePreAuthKeyWithResponse(ctx, request)
 		if err != nil {
 			return fmt.Errorf("creating preauthkey: %w", err)
 		}
 
-		return printOutput(cmd, response.GetPreAuthKey(), response.GetPreAuthKey().GetKey())
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		preAuthKey := resp.JSON200.PreAuthKey
+
+		return printOutput(cmd, preAuthKey, preAuthKey.Key)
 	}),
 }
 
@@ -139,22 +151,26 @@ var expirePreAuthKeyCmd = &cobra.Command{
 	Use:     cmdExpire,
 	Short:   "Expire a preauthkey",
 	Aliases: []string{"revoke", aliasExp, "e"},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		id, err := preAuthKeyID(cmd)
 		if err != nil {
 			return err
 		}
 
-		request := &v1.ExpirePreAuthKeyRequest{
-			Id: id,
-		}
+		idStr := strconv.FormatUint(id, util.Base10)
 
-		response, err := client.ExpirePreAuthKey(ctx, request)
+		resp, err := client.ExpirePreAuthKeyWithResponse(ctx, clientv1.ExpirePreAuthKeyJSONRequestBody{
+			Id: &idStr,
+		})
 		if err != nil {
 			return fmt.Errorf("expiring preauthkey: %w", err)
 		}
 
-		return printOutput(cmd, response, "Key expired")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key expired")
 	}),
 }
 
@@ -162,21 +178,25 @@ var deletePreAuthKeyCmd = &cobra.Command{
 	Use:     cmdDelete,
 	Short:   "Delete a preauthkey",
 	Aliases: []string{aliasDel, "rm", "d"},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		id, err := preAuthKeyID(cmd)
 		if err != nil {
 			return err
 		}
 
-		request := &v1.DeletePreAuthKeyRequest{
-			Id: id,
-		}
+		idStr := strconv.FormatUint(id, util.Base10)
 
-		response, err := client.DeletePreAuthKey(ctx, request)
+		resp, err := client.DeletePreAuthKeyWithResponse(ctx, &clientv1.DeletePreAuthKeyParams{
+			Id: &idStr,
+		})
 		if err != nil {
 			return fmt.Errorf("deleting preauthkey: %w", err)
 		}
 
-		return printOutput(cmd, response, "Key deleted")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key deleted")
 	}),
 }

cmd/headscale/cli/root_test.go

@@ -213,7 +213,8 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			result := filterPreReleasesIfStable(func() string { return tt.currentVersion })(tt.tag)
 			if result != tt.expectedFilter {
-				t.Errorf("%s: got %v, want %v\nDescription: %s\nCurrent version: %s, Tag: %s",
+				t.Errorf(
+					"%s: got %v, want %v\nDescription: %s\nCurrent version: %s, Tag: %s",
 					tt.name,
 					result,
 					tt.expectedFilter,
@@ -293,7 +294,8 @@ func TestIsPreReleaseVersion(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			result := isPreReleaseVersion(tt.version)
 			if result != tt.expected {
-				t.Errorf("%s: got %v, want %v\nDescription: %s\nVersion: %s",
+				t.Errorf(
+					"%s: got %v, want %v\nDescription: %s\nVersion: %s",
 					tt.name,
 					result,
 					tt.expected,

cmd/headscale/cli/users.go

@@ -4,10 +4,11 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/http"
 	"net/url"
 	"strconv"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
 	"github.com/rs/zerolog/log"
@@ -45,27 +46,39 @@ func usernameAndIDFromFlag(cmd *cobra.Command) (uint64, string, error) {
 // returning the raw flag id and the matched user.
 func resolveSingleUser(
 	ctx context.Context,
-	client v1.HeadscaleServiceClient,
+	client *clientv1.ClientWithResponses,
 	cmd *cobra.Command,
-) (uint64, *v1.User, error) {
+) (uint64, *clientv1.User, error) {
 	id, username, err := usernameAndIDFromFlag(cmd)
 	if err != nil {
 		return 0, nil, err
 	}
 
-	users, err := client.ListUsers(ctx, &v1.ListUsersRequest{
-		Name: username,
-		Id:   id,
-	})
+	params := &clientv1.ListUsersParams{}
+	if username != "" {
+		params.Name = &username
+	}
+
+	if id != 0 {
+		idStr := strconv.FormatUint(id, util.Base10)
+		params.Id = &idStr
+	}
+
+	resp, err := client.ListUsersWithResponse(ctx, params)
 	if err != nil {
 		return 0, nil, fmt.Errorf("listing users: %w", err)
 	}
 
-	if len(users.GetUsers()) != 1 {
+	if resp.StatusCode() != http.StatusOK {
+		return 0, nil, apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+	}
+
+	users := resp.JSON200.Users
+	if len(users) != 1 {
 		return 0, nil, errMultipleUsersMatch
 	}
 
-	return id, users.GetUsers()[0], nil
+	return id, &users[0], nil
 }
 
 func init() {
@@ -102,19 +115,19 @@ var createUserCmd = &cobra.Command{
 
 		return nil
 	},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		userName := args[0]
 
-		log.Trace().Interface(zf.Client, client).Msg("obtained gRPC client")
+		log.Trace().Interface(zf.Client, client).Msg("obtained API client")
 
-		request := &v1.CreateUserRequest{Name: userName}
+		request := clientv1.CreateUserJSONRequestBody{Name: &userName}
 
 		if displayName, _ := cmd.Flags().GetString("display-name"); displayName != "" {
-			request.DisplayName = displayName
+			request.DisplayName = &displayName
 		}
 
 		if email, _ := cmd.Flags().GetString("email"); email != "" {
-			request.Email = email
+			request.Email = &email
 		}
 
 		if pictureURL, _ := cmd.Flags().GetString("picture-url"); pictureURL != "" {
@@ -122,17 +135,21 @@ var createUserCmd = &cobra.Command{
 				return fmt.Errorf("invalid picture URL: %w", err)
 			}
 
-			request.PictureUrl = pictureURL
+			request.PictureUrl = &pictureURL
 		}
 
 		log.Trace().Interface(zf.Request, request).Msg("sending CreateUser request")
 
-		response, err := client.CreateUser(ctx, request)
+		resp, err := client.CreateUserWithResponse(ctx, request)
 		if err != nil {
 			return fmt.Errorf("creating user: %w", err)
 		}
 
-		return printOutput(cmd, response.GetUser(), "User created")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.User, "User created")
 	}),
 }
 
@@ -140,27 +157,29 @@ var destroyUserCmd = &cobra.Command{
 	Use:     "destroy --identifier ID or --name NAME",
 	Short:   "Destroys a user",
 	Aliases: []string{cmdDelete},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		_, user, err := resolveSingleUser(ctx, client, cmd)
 		if err != nil {
 			return err
 		}
 
 		if !confirmAction(cmd, fmt.Sprintf(
-			"Do you want to remove the user %q (%d) and any associated preauthkeys?",
-			user.GetName(), user.GetId(),
+			"Do you want to remove the user %q (%s) and any associated preauthkeys?",
+			user.Name, user.Id,
 		)) {
 			return printOutput(cmd, map[string]string{colResult: "User not destroyed"}, "User not destroyed")
 		}
 
-		deleteRequest := &v1.DeleteUserRequest{Id: user.GetId()}
-
-		response, err := client.DeleteUser(ctx, deleteRequest)
+		resp, err := client.DeleteUserWithResponse(ctx, user.Id)
 		if err != nil {
 			return fmt.Errorf("destroying user: %w", err)
 		}
 
-		return printOutput(cmd, response, "User destroyed")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "User destroyed")
 	}),
 }
 
@@ -168,8 +187,8 @@ var listUsersCmd = &cobra.Command{
 	Use:     cmdList,
 	Short:   "List all the users",
 	Aliases: []string{"ls", cmdShow},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
-		request := &v1.ListUsersRequest{}
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		params := &clientv1.ListUsersParams{}
 
 		id, _ := cmd.Flags().GetInt64("identifier")
 		username, _ := cmd.Flags().GetString("name")
@@ -178,29 +197,36 @@ var listUsersCmd = &cobra.Command{
 		// filter by one param at most
 		switch {
 		case id > 0:
-			request.Id = uint64(id)
+			idStr := strconv.FormatInt(id, util.Base10)
+			params.Id = &idStr
 		case username != "":
-			request.Name = username
+			params.Name = &username
 		case email != "":
-			request.Email = email
+			params.Email = &email
 		}
 
-		response, err := client.ListUsers(ctx, request)
+		resp, err := client.ListUsersWithResponse(ctx, params)
 		if err != nil {
 			return fmt.Errorf("listing users: %w", err)
 		}
 
-		return printListOutput(cmd, response.GetUsers(), func() error {
-			rows := make([][]string, 0, len(response.GetUsers()))
-			for _, user := range response.GetUsers() {
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		users := resp.JSON200.Users
+
+		return printListOutput(cmd, users, func() error {
+			rows := make([][]string, 0, len(users))
+			for _, user := range users {
 				rows = append(
 					rows,
 					[]string{
-						strconv.FormatUint(user.GetId(), util.Base10),
-						user.GetDisplayName(),
-						user.GetName(),
-						user.GetEmail(),
-						user.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
+						user.Id,
+						user.DisplayName,
+						user.Name,
+						user.Email,
+						user.CreatedAt.Format(HeadscaleDateTimeFormat),
 					},
 				)
 			}
@@ -214,7 +240,7 @@ var renameUserCmd = &cobra.Command{
 	Use:     "rename",
 	Short:   "Renames a user",
 	Aliases: []string{"mv"},
-	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		id, _, err := resolveSingleUser(ctx, client, cmd)
 		if err != nil {
 			return err
@@ -222,16 +248,15 @@ var renameUserCmd = &cobra.Command{
 
 		newName, _ := cmd.Flags().GetString("new-name")
 
-		renameReq := &v1.RenameUserRequest{
-			OldId:   id,
-			NewName: newName,
-		}
-
-		response, err := client.RenameUser(ctx, renameReq)
+		resp, err := client.RenameUserWithResponse(ctx, strconv.FormatUint(id, util.Base10), newName)
 		if err != nil {
 			return fmt.Errorf("renaming user: %w", err)
 		}
 
-		return printOutput(cmd, response.GetUser(), "User renamed")
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.User, "User renamed")
 	}),
 }

cmd/headscale/cli/utils.go

@@ -6,11 +6,15 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net"
+	"net/http"
 	"os"
 	"slices"
+	"strings"
 	"time"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/cenkalti/backoff/v5"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/juanfont/headscale/hscontrol/util"
@@ -19,10 +23,6 @@ import (
 	"github.com/pterm/pterm"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-	"google.golang.org/grpc"
-	"google.golang.org/grpc/credentials"
-	"google.golang.org/grpc/credentials/insecure"
-	"google.golang.org/protobuf/types/known/timestamppb"
 	"gopkg.in/yaml.v3"
 )
 
@@ -38,11 +38,45 @@ const (
 var (
 	errAPIKeyNotSet     = errors.New("HEADSCALE_CLI_API_KEY environment variable needs to be set")
 	errMissingParameter = errors.New("missing parameters")
+	errResponseStatus   = errors.New("unexpected response status")
 )
 
-// mustMarkRequired marks the named flags as required on cmd, panicking
-// if any name does not match a registered flag.  This is only called
-// from init() where a failure indicates a programming error.
+// apiError turns a non-2xx response into an error, surfacing the server's
+// RFC7807 problem detail. detail holds the operation context and errors[] the
+// wrapped cause (e.g. "name is too long"); both are joined so the server's
+// message text is not lost.
+func apiError(statusCode int, problem *clientv1.ErrorModel) error {
+	if problem == nil {
+		return fmt.Errorf("%w: %d %s", errResponseStatus, statusCode, http.StatusText(statusCode))
+	}
+
+	parts := make([]string, 0, 2)
+
+	if problem.Detail != nil && *problem.Detail != "" {
+		parts = append(parts, *problem.Detail)
+	}
+
+	if problem.Errors != nil {
+		for _, e := range *problem.Errors {
+			if e.Message != nil && *e.Message != "" {
+				parts = append(parts, *e.Message)
+			}
+		}
+	}
+
+	if len(parts) == 0 && problem.Title != nil && *problem.Title != "" {
+		parts = append(parts, *problem.Title)
+	}
+
+	if len(parts) == 0 {
+		return fmt.Errorf("%w: %d %s", errResponseStatus, statusCode, http.StatusText(statusCode))
+	}
+
+	return fmt.Errorf("%w: %s", errResponseStatus, strings.Join(parts, ": "))
+}
+
+// mustMarkRequired marks the named flags as required, panicking on an unknown
+// flag. Only called from init(), where a failure is a programming error.
 func mustMarkRequired(cmd *cobra.Command, names ...string) {
 	for _, n := range names {
 		err := cmd.MarkFlagRequired(n)
@@ -69,45 +103,47 @@ func newHeadscaleServerWithConfig() (*hscontrol.Headscale, error) {
 	return app, nil
 }
 
-// grpcRunE wraps a cobra [cobra.Command.RunE] func, injecting a ready
-// gRPC client and context. Connection lifecycle is managed by the
-// wrapper — callers never see the underlying conn or cancel func.
-func grpcRunE(
-	fn func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error,
+// clientRunE wraps a [cobra.Command.RunE] func, injecting a ready API client
+// and a context whose timeout/cancel the wrapper owns.
+func clientRunE(
+	fn func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error,
 ) func(*cobra.Command, []string) error {
 	return func(cmd *cobra.Command, args []string) error {
-		ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
+		ctx, client, cancel, err := newHeadscaleCLIWithConfig()
 		if err != nil {
 			return fmt.Errorf("connecting to headscale: %w", err)
 		}
 		defer cancel()
-		defer conn.Close()
 
 		return fn(ctx, client, cmd, args)
 	}
 }
 
-// withGRPC opens a gRPC client, runs fn with it, and tears the
-// connection down afterwards. It is the building block for commands
-// that branch on a flag before deciding to talk to the server, where
-// grpcRunE's whole-RunE wrapping does not fit.
-func withGRPC(
-	fn func(ctx context.Context, client v1.HeadscaleServiceClient) error,
+// withClient runs fn with an API client. For commands that branch on a flag
+// before talking to the server, where clientRunE's whole-RunE wrapping does
+// not fit.
+func withClient(
+	fn func(ctx context.Context, client *clientv1.ClientWithResponses) error,
 ) error {
-	ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
+	ctx, client, cancel, err := newHeadscaleCLIWithConfig()
 	if err != nil {
 		return fmt.Errorf("connecting to headscale: %w", err)
 	}
 	defer cancel()
-	defer conn.Close()
 
 	return fn(ctx, client)
 }
 
-func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc, error) {
+// newHeadscaleCLIWithConfig builds an HTTP client for the Headscale v1 API.
+//
+// When cfg.CLI.Address is unset the CLI is assumed to run on the server host
+// and talks to the unix socket over HTTP without authentication (local trust).
+// Otherwise it talks to the remote TCP address over HTTPS and injects the
+// configured API key as a bearer token.
+func newHeadscaleCLIWithConfig() (context.Context, *clientv1.ClientWithResponses, context.CancelFunc, error) {
 	cfg, err := types.LoadCLIConfig()
 	if err != nil {
-		return nil, nil, nil, nil, fmt.Errorf("loading configuration: %w", err)
+		return nil, nil, nil, fmt.Errorf("loading configuration: %w", err)
 	}
 
 	log.Debug().
@@ -116,10 +152,6 @@ func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *g
 
 	ctx, cancel := context.WithTimeout(context.Background(), cfg.CLI.Timeout)
 
-	grpcOptions := []grpc.DialOption{
-		grpc.WithBlock(), //nolint:staticcheck // SA1019: deprecated but supported in 1.x
-	}
-
 	address := cfg.CLI.Address
 
 	// If the address is not set, we assume that we are on the server hosting [hscontrol].
@@ -128,80 +160,111 @@ func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *g
 			Str("socket", cfg.UnixSocket).
 			Msgf("HEADSCALE_CLI_ADDRESS environment is not set, connecting to unix socket.")
 
-		address = cfg.UnixSocket
-
-		// Try to give the user better feedback if we cannot write to the headscale
-		// socket.  Note: [os.OpenFile] on a Unix domain socket returns ENXIO on
-		// Linux which is expected — only permission errors are actionable here.
-		// The actual gRPC connection uses [net.Dial] which handles sockets properly.
-		socket, err := os.OpenFile(cfg.UnixSocket, os.O_WRONLY, SocketWritePermissions) //nolint
+		client, err := newSocketClient(cfg.UnixSocket)
 		if err != nil {
-			if os.IsPermission(err) {
-				cancel()
-
-				return nil, nil, nil, nil, fmt.Errorf(
-					"unable to read/write to headscale socket %q, do you have the correct permissions? %w",
-					cfg.UnixSocket,
-					err,
-				)
-			}
-		} else {
-			socket.Close()
-		}
-
-		grpcOptions = append(
-			grpcOptions,
-			grpc.WithTransportCredentials(insecure.NewCredentials()),
-			grpc.WithContextDialer(util.GrpcSocketDialer),
-		)
-	} else {
-		// If we are not connecting to a local server, require an API key for authentication
-		apiKey := cfg.CLI.APIKey
-		if apiKey == "" {
 			cancel()
 
-			return nil, nil, nil, nil, errAPIKeyNotSet
+			return nil, nil, nil, err
 		}
 
-		grpcOptions = append(
-			grpcOptions,
-			grpc.WithPerRPCCredentials(tokenAuth{
-				token: apiKey,
-			}),
-		)
+		log.Trace().Caller().Str(zf.Address, cfg.UnixSocket).Msg("connecting via unix socket")
 
-		if cfg.CLI.Insecure {
-			tlsConfig := &tls.Config{
-				// turn of gosec as we are intentionally setting
-				// insecure.
-				//nolint:gosec
-				InsecureSkipVerify: true,
-			}
-
-			grpcOptions = append(
-				grpcOptions,
-				grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
-			)
-		} else {
-			grpcOptions = append(
-				grpcOptions,
-				grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
-			)
-		}
+		return ctx, client, cancel, nil
 	}
 
-	log.Trace().Caller().Str(zf.Address, address).Msg("connecting via gRPC")
+	// Remote connections require an API key for authentication.
+	apiKey := cfg.CLI.APIKey
+	if apiKey == "" {
+		cancel()
 
-	conn, err := grpc.DialContext(ctx, address, grpcOptions...) //nolint:staticcheck // SA1019: deprecated but supported in 1.x
+		return nil, nil, nil, errAPIKeyNotSet
+	}
+
+	client, err := newRemoteClient(address, apiKey, cfg.CLI.Insecure)
 	if err != nil {
 		cancel()
 
-		return nil, nil, nil, nil, fmt.Errorf("connecting to %s: %w", address, err)
+		return nil, nil, nil, err
 	}
 
-	client := v1.NewHeadscaleServiceClient(conn)
+	log.Trace().Caller().Str(zf.Address, address).Msg("connecting via HTTPS")
 
-	return ctx, client, conn, cancel, nil
+	return ctx, client, cancel, nil
+}
+
+// newSocketClient builds an API client that dials the local unix socket. The
+// base-URL host is irrelevant; the custom dialer routes every request to the
+// socket.
+func newSocketClient(socketPath string) (*clientv1.ClientWithResponses, error) {
+	// Probe for a clearer permission error up front. [os.OpenFile] on a unix
+	// socket returns ENXIO on Linux (expected); only permission errors are
+	// actionable. The real connection goes through [net.Dial].
+	socket, err := os.OpenFile(socketPath, os.O_WRONLY, SocketWritePermissions) //nolint
+	if err != nil {
+		if os.IsPermission(err) {
+			return nil, fmt.Errorf(
+				"unable to read/write to headscale socket %q, do you have the correct permissions? %w",
+				socketPath,
+				err,
+			)
+		}
+	} else {
+		socket.Close()
+	}
+
+	httpClient := &http.Client{
+		Transport: &http.Transport{
+			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+				return dialHeadscaleSocket(ctx, socketPath)
+			},
+		},
+	}
+
+	return clientv1.NewClientWithResponses(
+		"http://local",
+		clientv1.WithHTTPClient(httpClient),
+	)
+}
+
+// dialHeadscaleSocket connects to the unix socket, retrying until it appears or
+// ctx (the CLI timeout) expires. The socket is created late in startup (after
+// noise key, database, migrations), so a command run right after the server
+// starts can race its creation; retrying preserves the old gRPC client's
+// blocking-dial tolerance rather than failing on a not-yet-present socket.
+func dialHeadscaleSocket(ctx context.Context, socketPath string) (net.Conn, error) {
+	b := backoff.NewExponentialBackOff()
+	b.InitialInterval = 50 * time.Millisecond
+	b.MaxInterval = 1 * time.Second
+
+	return backoff.Retry(ctx, func() (net.Conn, error) {
+		return util.SocketDialer(ctx, socketPath)
+	}, backoff.WithBackOff(b))
+}
+
+// newRemoteClient builds an API client for a remote Headscale over HTTPS,
+// honouring insecure (skip TLS verification) and injecting the API key as a
+// bearer token on every request.
+func newRemoteClient(address, apiKey string, insecure bool) (*clientv1.ClientWithResponses, error) {
+	transport := &http.Transport{}
+	if insecure {
+		transport.TLSClientConfig = &tls.Config{
+			// turn off gosec as we are intentionally setting insecure.
+			//nolint:gosec
+			InsecureSkipVerify: true,
+		}
+	}
+
+	httpClient := &http.Client{Transport: transport}
+
+	return clientv1.NewClientWithResponses(
+		"https://"+address,
+		clientv1.WithHTTPClient(httpClient),
+		clientv1.WithRequestEditorFn(func(_ context.Context, req *http.Request) error {
+			req.Header.Set("Authorization", "Bearer "+apiKey)
+
+			return nil
+		}),
+	)
 }
 
 // formatOutput serialises result into the requested format. For the
@@ -250,16 +313,16 @@ func printOutput(cmd *cobra.Command, result any, override string) error {
 }
 
 // expirationFromFlag parses the --expiration flag as a Prometheus-style
-// duration (e.g. "90d", "1h") and returns an absolute timestamp.
-func expirationFromFlag(cmd *cobra.Command) (*timestamppb.Timestamp, error) {
+// duration (e.g. "90d", "1h") and returns an absolute time.
+func expirationFromFlag(cmd *cobra.Command) (time.Time, error) {
 	durationStr, _ := cmd.Flags().GetString("expiration")
 
 	duration, err := model.ParseDuration(durationStr)
 	if err != nil {
-		return nil, fmt.Errorf("parsing duration: %w", err)
+		return time.Time{}, fmt.Errorf("parsing duration: %w", err)
 	}
 
-	return timestamppb.New(time.Now().UTC().Add(time.Duration(duration))), nil
+	return time.Now().UTC().Add(time.Duration(duration)), nil
 }
 
 // confirmAction returns true when the user confirms a prompt, or when
@@ -323,21 +386,3 @@ func hasMachineOutputFlag() bool {
 		return arg == outputFormatJSON || arg == outputFormatJSONLine || arg == outputFormatYAML
 	})
 }
-
-type tokenAuth struct {
-	token string
-}
-
-// Return value is mapped to request headers.
-func (t tokenAuth) GetRequestMetadata(
-	ctx context.Context,
-	in ...string,
-) (map[string]string, error) {
-	return map[string]string{
-		"authorization": "Bearer " + t.token,
-	}, nil
-}
-
-func (tokenAuth) RequireTransportSecurity() bool {
-	return true
-}

cmd/headscale/cli/utils_socket_test.go

@@ -0,0 +1,72 @@
+package cli
+
+import (
+	"context"
+	"net"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestDialHeadscaleSocketRetriesUntilPresent proves the CLI socket dialer
+// tolerates a not-yet-created socket (the server-still-starting race) by
+// retrying until it appears, rather than failing immediately like a bare dial.
+func TestDialHeadscaleSocketRetriesUntilPresent(t *testing.T) {
+	sock := filepath.Join(t.TempDir(), "headscale.sock")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	type result struct {
+		conn net.Conn
+		err  error
+	}
+
+	done := make(chan result, 1)
+
+	go func() {
+		conn, err := dialHeadscaleSocket(ctx, sock)
+		done <- result{conn, err}
+	}()
+
+	// Listen only after the dialer has begun, so its backoff must retry the
+	// absent socket and connect once it exists.
+	var lc net.ListenConfig
+
+	ln, err := lc.Listen(ctx, "unix", sock)
+	require.NoError(t, err)
+
+	defer ln.Close()
+
+	go func() {
+		if conn, _ := ln.Accept(); conn != nil {
+			conn.Close()
+		}
+	}()
+
+	res := <-done
+	require.NoError(t, res.err)
+	require.NotNil(t, res.conn)
+
+	res.conn.Close()
+}
+
+// TestDialHeadscaleSocketRespectsDeadline proves the retry is bounded by the
+// context: when the socket never appears, the dialer returns an error around the
+// deadline instead of hanging.
+func TestDialHeadscaleSocketRespectsDeadline(t *testing.T) {
+	sock := filepath.Join(t.TempDir(), "absent.sock")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+
+	conn, err := dialHeadscaleSocket(ctx, sock)
+	require.Error(t, err)
+	assert.Nil(t, conn)
+	assert.Less(t, time.Since(start), 5*time.Second, "should stop near the deadline, not hang")
+}