From 5e4a90b3e5694af0678d9f34b5e9c25c601a9a89 Mon Sep 17 00:00:00 2001
From: Tam Nhu Tran <kaitran.ntt@gmail.com>
Date: Mon, 22 Jun 2026 12:05:34 -0400
Subject: [PATCH] fix(cli): warn on tokens --variant without --api-key; list
 bar serve in help

'ccs tokens --variant <x>' without --api-key was a silent no-op; now it explains
that --variant only applies with --api-key. Add the existing 'serve' subcommand
to the bar help Commands list.
---
 src/commands/bar/help-subcommand.ts | 1 +
 src/commands/tokens-command.ts      | 7 +++++++
 2 files changed, 8 insertions(+)

diff --git a/src/commands/bar/help-subcommand.ts b/src/commands/bar/help-subcommand.ts
index 0511a1ba..95b63095 100644
--- a/src/commands/bar/help-subcommand.ts
+++ b/src/commands/bar/help-subcommand.ts
@@ -14,6 +14,7 @@ export async function showHelp(): Promise<void> {
       'Commands:',
       [
         ['launch', 'Spawn the server detached, write ~/.ccs/bar.json, open the app (default)'],
+        ['serve', 'Run the CCS Bar server in the foreground (used internally by launch)'],
         ['stop', 'Stop the detached CCS Bar server'],
         ['status', 'Show whether the CCS Bar server is running'],
         ['install', 'Download CCS Bar from the ccs-bar-latest GitHub release into ~/Applications'],
diff --git a/src/commands/tokens-command.ts b/src/commands/tokens-command.ts
index 7d3f06cf..0dfe92c9 100644
--- a/src/commands/tokens-command.ts
+++ b/src/commands/tokens-command.ts
@@ -141,6 +141,13 @@ export async function handleTokensCommand(args: string[]): Promise<number> {
     return 1;
   }
 
+  // --variant without --api-key is a misuse — it has no effect without a key to assign.
+  if (variantValue !== undefined && !hasApiKeyFlag) {
+    console.error(fail('--variant requires --api-key'));
+    console.error(info('Usage: ccs tokens --variant <name> --api-key <key>'));
+    return 1;
+  }
+
   let updated = false;
 
   if (regenerateSecretFlag) {