cmsctl: persist a scoped API key for script auth

Add `auth api-key {set|clear}` and prefer a stored key over the device
token, so scripts authenticate with a permanent minted API key
(X-API-Key) instead of re-running the 12h device flow. Explicit flags
and env still win over persisted credentials. Also treat a zero-byte
config file as defaults (previously every command failed to parse), and
correct AGENTS.md, which claimed device tokens auto-refresh.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

cmd/cmsctl/config.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -23,6 +24,9 @@ type Config struct {
 	AccessToken string    `json:"access_token,omitempty"`
 	TokenType   string    `json:"token_type,omitempty"`
 	ExpiresAt   time.Time `json:"expires_at,omitempty"`
+	// APIKey is a minted scoped API key (AUTH_APIKEYS_FILE). Prefer over a
+	// device access token for scripts: it has no expiry. Sent as X-API-Key.
+	APIKey string `json:"api_key,omitempty"`
 }
 
 func defaultConfig() Config {
@@ -64,6 +68,11 @@ func loadConfig(path string) (Config, error) {
 	if err != nil {
 		return Config{}, fmt.Errorf("read config %s: %w", path, err)
 	}
+	// A zero-byte or whitespace-only file (e.g. created by `touch` or a
+	// botched write) is not a corrupt config; fall back to defaults.
+	if len(bytes.TrimSpace(body)) == 0 {
+		return cfg, nil
+	}
 	if err := json.Unmarshal(body, &cfg); err != nil {
 		return Config{}, fmt.Errorf("parse config %s: %w", path, err)
 	}
@@ -118,10 +127,11 @@ func saveConfig(path string, cfg Config) error {
 	return nil
 }
 
-func clearToken(cfg *Config) {
+func clearCredentials(cfg *Config) {
 	cfg.AccessToken = ""
 	cfg.TokenType = "Bearer"
 	cfg.ExpiresAt = time.Time{}
+	cfg.APIKey = ""
 }
 
 func effectiveBaseURL(cfg Config) string {

cmd/cmsctl/main.go

@@ -21,6 +21,7 @@ const usageText = `cmsctl — CMS and finder API CLI
 
 Usage:
   cmsctl auth login [--scope read,write]       Device-login and persist token
+  cmsctl auth api-key {set|clear} [<key>]      Store/remove a minted API key (no expiry)
   cmsctl auth status                           Show current credential status
   cmsctl auth token [--raw]                    Print the persisted token
   cmsctl auth logout                           Remove the persisted token
@@ -140,8 +141,14 @@ func runWithStdin(args []string, stdin io.Reader, stdout, stderr io.Writer) erro
 	if global.apiKey == "" {
 		global.apiKey = os.Getenv("CMSCTL_API_KEY")
 	}
+	// Fall back to persisted credentials only when nothing was supplied on
+	// the command line or via env for either mechanism. The persisted API
+	// key (no expiry) is preferred over the persisted device token.
 	if global.token == "" && global.apiKey == "" {
-		global.token = cfg.AccessToken
+		global.apiKey = cfg.APIKey
+		if global.apiKey == "" {
+			global.token = cfg.AccessToken
+		}
 	}
 
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
@@ -211,10 +218,46 @@ func parseGlobal(args []string) (globalOptions, []string, error) {
 
 func runAuth(ctx context.Context, cfgPath string, cfg *Config, args []string, stdout, stderr io.Writer, timeout time.Duration) error {
 	if len(args) == 0 || args[0] == "help" || args[0] == "--help" {
-		_, _ = io.WriteString(stdout, "Usage: cmsctl auth login [--scope read,write] [--no-poll]\n       cmsctl auth status\n       cmsctl auth token [--raw]\n       cmsctl auth logout\n")
+		_, _ = io.WriteString(stdout, "Usage: cmsctl auth login [--scope read,write] [--no-poll]\n       cmsctl auth api-key [set <key> | clear]\n       cmsctl auth status\n       cmsctl auth token [--raw]\n       cmsctl auth logout\n")
 		return nil
 	}
 	switch args[0] {
+	case "api-key":
+		fs := flag.NewFlagSet("auth api-key", flag.ContinueOnError)
+		fs.SetOutput(stderr)
+		if err := fs.Parse(args[1:]); err != nil {
+			return err
+		}
+		rest := fs.Args()
+		if len(rest) == 0 {
+			if cfg.APIKey == "" {
+				fmt.Fprintln(stdout, "no API key stored")
+			} else {
+				fmt.Fprintf(stdout, "API key stored in %s\n", cfgPath)
+			}
+			return nil
+		}
+		switch rest[0] {
+		case "set":
+			if len(rest) < 2 || rest[1] == "" {
+				return errors.New("usage: cmsctl auth api-key set <key>")
+			}
+			cfg.APIKey = rest[1]
+			if err := saveConfig(cfgPath, *cfg); err != nil {
+				return err
+			}
+			fmt.Fprintf(stdout, "API key stored in %s\n", cfgPath)
+			return nil
+		case "clear":
+			cfg.APIKey = ""
+			if err := saveConfig(cfgPath, *cfg); err != nil {
+				return err
+			}
+			fmt.Fprintf(stdout, "API key removed from %s\n", cfgPath)
+			return nil
+		default:
+			return fmt.Errorf("unknown api-key subcommand %q (use set|clear)", rest[0])
+		}
 	case "login":
 		fs := flag.NewFlagSet("auth login", flag.ContinueOnError)
 		fs.SetOutput(stderr)
@@ -308,7 +351,8 @@ func runAuth(ctx context.Context, cfgPath string, cfg *Config, args []string, st
 			"config":        cfgPath,
 			"base_url":      effectiveBaseURL(*cfg),
 			"finder_url":    effectiveFinderURL(*cfg),
-			"authenticated": cfg.AccessToken != "" && (cfg.ExpiresAt.IsZero() || time.Now().Before(cfg.ExpiresAt)),
+			"api_key":       cfg.APIKey != "",
+			"authenticated": cfg.APIKey != "" || (cfg.AccessToken != "" && (cfg.ExpiresAt.IsZero() || time.Now().Before(cfg.ExpiresAt))),
 		}
 		if !cfg.ExpiresAt.IsZero() {
 			status["expires_at"] = cfg.ExpiresAt
@@ -333,11 +377,11 @@ func runAuth(ctx context.Context, cfgPath string, cfg *Config, args []string, st
 		}
 		return writeJSON(stdout, map[string]any{"access_token": cfg.AccessToken, "token_type": cfg.TokenType, "expires_at": cfg.ExpiresAt})
 	case "logout":
-		clearToken(cfg)
+		clearCredentials(cfg)
 		if err := saveConfig(cfgPath, *cfg); err != nil {
 			return err
 		}
-		fmt.Fprintf(stdout, "Logged out; token removed from %s\n", cfgPath)
+		fmt.Fprintf(stdout, "Logged out; credentials removed from %s\n", cfgPath)
 		return nil
 	default:
 		return fmt.Errorf("unknown auth command %q", args[0])

cmd/cmsctl/precedence_test.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestCredentialPrecedence(t *testing.T) {
+	cases := []struct {
+		name     string
+		args     []string
+		wantAuth string
+		wantKey  string
+	}{
+		{"persisted key sent", []string{"cms", "nodes", "list"}, "", "persisted-key"},
+		{"explicit token beats persisted key", []string{"--token", "flag-token", "cms", "nodes", "list"}, "Bearer flag-token", ""},
+		{"explicit api-key flag wins", []string{"--api-key", "flag-key", "cms", "nodes", "list"}, "", "flag-key"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var gotAuth, gotKey string
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				gotAuth = r.Header.Get("Authorization")
+				gotKey = r.Header.Get("X-API-Key")
+				_, _ = w.Write([]byte(`{"data":[]}`))
+			}))
+			defer srv.Close()
+			cfgPath := filepath.Join(t.TempDir(), "config.json")
+			cfg := defaultConfig()
+			cfg.BaseURL = srv.URL
+			cfg.APIKey = "persisted-key"
+			if err := saveConfig(cfgPath, cfg); err != nil {
+				t.Fatal(err)
+			}
+			var stdout, stderr strings.Builder
+			full := append([]string{"--config", cfgPath, "--base-url", srv.URL}, tc.args...)
+			if err := runWithStdin(full, strings.NewReader(""), &stdout, &stderr); err != nil {
+				t.Fatalf("run: %v (stderr=%s)", err, stderr.String())
+			}
+			if gotAuth != tc.wantAuth || gotKey != tc.wantKey {
+				t.Fatalf("auth=%q key=%q, want auth=%q key=%q", gotAuth, gotKey, tc.wantAuth, tc.wantKey)
+			}
+		})
+	}
+}
+
+func TestMain(m *testing.M) { os.Exit(m.Run()) }