fix(rebase): port co-located command changes missed during rebase

After rebasing onto main's co-location refactor, several changes from
the PR's commits were only present in the old monolithic cli-program.ts
and needed to be forwarded to the co-located command files:

- cli-program.ts: expand Program type to include quiet and color opts
- apps/index.ts: use field-aware --json descriptions for list and create
- auth/index.ts: add --token option to auth login and hidden login commands

Author: rafa-thayto

packages/cli-core/src/cli-program.ts

@@ -50,7 +50,10 @@ import { registerExtras } from "@clerk/cli-extras";
  * The root `clerk` program with its global options applied, so registrants
  * can rely on the typed global option contract instead of a generic Command.
  */
-export type Program = Command<[], { inputJson?: string; mode?: string; verbose?: boolean }>;
+export type Program = Command<
+  [],
+  { inputJson?: string; mode?: string; verbose?: boolean; quiet?: boolean; color?: boolean }
+>;
 
 type CommandRegistrant = (program: Program) => void;
 

packages/cli-core/src/commands/apps/index.ts

@@ -8,7 +8,10 @@ export function registerApps(program: Program): void {
   apps
     .command("list")
     .description("List your Clerk applications")
-    .option("--json", "Output as JSON")
+    .option(
+      "--json",
+      "Output as JSON. Fields: application_id, name, instances[] (instance_id, environment_type, publishable_key)",
+    )
     .setExamples([
       { command: "clerk apps list", description: "List all applications" },
       { command: "clerk apps list --json", description: "Output as JSON" },
@@ -19,7 +22,10 @@ export function registerApps(program: Program): void {
     .command("create")
     .description("Create a new Clerk application (not idempotent by default — use --if-not-exists)")
     .argument("<name>", "Application name")
-    .option("--json", "Output as JSON")
+    .option(
+      "--json",
+      "Output as JSON. Fields: application_id, name, instances[] (instance_id, environment_type, publishable_key)",
+    )
     .option(
       "--if-not-exists",
       "Make the operation idempotent: if an application with this name already exists, return it instead of creating a duplicate",

packages/cli-core/src/commands/auth/index.ts

@@ -11,17 +11,29 @@ export function registerAuth(program: Program): void {
       { command: "clerk auth logout", description: "Remove stored credentials" },
     ]);
 
+  const TOKEN_OPTION_DESC =
+    "Headless authentication with a Clerk PLAPI access token (skips OAuth; use `-` to read from stdin). For per-instance API access, CLERK_SECRET_KEY also works directly with `clerk api` / `users` / `config`.";
+
   auth
     .command("login")
     .aliases(["signup", "signin", "sign-in"])
     .description("Log in to your Clerk account")
     .option("-y, --yes", "Proceed with OAuth without prompting when already logged in")
+    .option("--token <key>", TOKEN_OPTION_DESC)
     .setExamples([
       { command: "clerk auth login", description: "Log in via browser (OAuth)" },
       {
         command: "clerk auth login -y",
         description: "Re-authenticate via OAuth without confirmation when already signed in",
       },
+      {
+        command: "clerk auth login --token $CLERK_OAUTH_TOKEN",
+        description: "Headless login with a PLAPI access token (CI / agents)",
+      },
+      {
+        command: "cat token.txt | clerk auth login --token -",
+        description: "Read the token from stdin",
+      },
     ])
     .action(async (opts) => {
       await login(opts);
@@ -38,6 +50,7 @@ export function registerAuth(program: Program): void {
     .command("login", { hidden: true })
     .description("Log in to your Clerk account")
     .option("-y, --yes", "Proceed with OAuth without prompting when already logged in")
+    .option("--token <key>", TOKEN_OPTION_DESC)
     .action(async (opts) => {
       await login(opts);
     });