From 7a0a083b2e9629f74cf1553523787a625eb804b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=8B=A5=E9=BA=92?= <gongshiqi.gsq@alibaba-inc.com>
Date: Wed, 24 Jun 2026 16:41:09 +0800
Subject: [PATCH] refactor(core): replace skipDefaultApiKeySetup with required
 auth field

Commands now declare their credential requirement explicitly via a
required `auth: "apiKey" | "console" | "none"` field instead of the
boolean `skipDefaultApiKeySetup`. The runtime prepares credentials
based on this declaration and skips API-key setup under --dry-run.

- core: add AuthRequirement type and required `auth` field to
  Command/CommandSpec; drop skipDefaultApiKeySetup
- runtime: gate API-key setup on `auth === "apiKey" && !dryRun`
- commands: annotate all 45 commands (apiKey 25 / console 11 / none 9)
---
 .../commands/src/commands/advisor/recommend.ts  |  1 +
 packages/commands/src/commands/app/call.ts      |  1 +
 packages/commands/src/commands/app/list.ts      |  2 +-
 packages/commands/src/commands/auth/login.ts    |  2 +-
 packages/commands/src/commands/auth/logout.ts   |  2 +-
 packages/commands/src/commands/auth/status.ts   |  1 +
 packages/commands/src/commands/config/set.ts    |  2 +-
 packages/commands/src/commands/config/show.ts   |  2 +-
 packages/commands/src/commands/console/call.ts  |  2 +-
 packages/commands/src/commands/file/upload.ts   |  1 +
 packages/commands/src/commands/image/edit.ts    |  1 +
 .../commands/src/commands/image/generate.ts     |  1 +
 .../commands/src/commands/knowledge/retrieve.ts |  2 +-
 packages/commands/src/commands/mcp/call.ts      |  2 +-
 packages/commands/src/commands/mcp/list.ts      |  2 +-
 packages/commands/src/commands/mcp/tools.ts     |  2 +-
 packages/commands/src/commands/memory/add.ts    |  1 +
 packages/commands/src/commands/memory/delete.ts |  1 +
 packages/commands/src/commands/memory/list.ts   |  1 +
 .../src/commands/memory/profile-create.ts       |  1 +
 .../commands/src/commands/memory/profile-get.ts |  1 +
 packages/commands/src/commands/memory/search.ts |  1 +
 packages/commands/src/commands/memory/update.ts |  1 +
 packages/commands/src/commands/omni/chat.ts     |  1 +
 packages/commands/src/commands/pipeline/run.ts  |  2 +-
 .../commands/src/commands/pipeline/validate.ts  |  2 +-
 packages/commands/src/commands/quota/check.ts   |  2 +-
 packages/commands/src/commands/quota/history.ts |  2 +-
 packages/commands/src/commands/quota/list.ts    |  2 +-
 packages/commands/src/commands/quota/request.ts |  2 +-
 packages/commands/src/commands/search/web.ts    |  1 +
 .../commands/src/commands/speech/recognize.ts   |  1 +
 .../commands/src/commands/speech/synthesize.ts  |  1 +
 packages/commands/src/commands/text/chat.ts     |  1 +
 packages/commands/src/commands/update.ts        |  2 +-
 packages/commands/src/commands/usage/free.ts    |  2 +-
 .../commands/src/commands/usage/freetier.ts     |  2 +-
 packages/commands/src/commands/usage/stats.ts   |  2 +-
 .../commands/src/commands/video/download.ts     |  1 +
 packages/commands/src/commands/video/edit.ts    |  1 +
 .../commands/src/commands/video/generate.ts     |  1 +
 packages/commands/src/commands/video/ref.ts     |  1 +
 .../commands/src/commands/video/task-get.ts     |  1 +
 .../commands/src/commands/vision/describe.ts    |  1 +
 .../commands/src/commands/workspace/list.ts     |  2 +-
 packages/core/src/types/command.ts              | 17 ++++++++++++++---
 packages/runtime/src/create-cli.ts              |  5 +++--
 47 files changed, 62 insertions(+), 26 deletions(-)

diff --git a/packages/commands/src/commands/advisor/recommend.ts b/packages/commands/src/commands/advisor/recommend.ts
index 81c6ddd..aa707ea 100644
--- a/packages/commands/src/commands/advisor/recommend.ts
+++ b/packages/commands/src/commands/advisor/recommend.ts
@@ -217,6 +217,7 @@ function isEmptyResult(result: RecommendResult): boolean {
 export default defineCommand({
   description:
     "Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking)",
+  auth: "apiKey",
   usageArgs: "<prompt> [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/app/call.ts b/packages/commands/src/commands/app/call.ts
index d784a65..a2d624a 100644
--- a/packages/commands/src/commands/app/call.ts
+++ b/packages/commands/src/commands/app/call.ts
@@ -16,6 +16,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Call a Bailian application (agent or workflow)",
+  auth: "apiKey",
   usageArgs: "--app-id <id> --prompt <text> [flags]",
   options: [
     { flag: "--app-id <id>", description: "Application ID (required)", required: true },
diff --git a/packages/commands/src/commands/app/list.ts b/packages/commands/src/commands/app/list.ts
index ca98664..615fa9d 100644
--- a/packages/commands/src/commands/app/list.ts
+++ b/packages/commands/src/commands/app/list.ts
@@ -12,7 +12,7 @@ const APP_LIST_API = "zeldaEasy.broadscope-bailian.app-control.list";
 
 export default defineCommand({
   description: "List Bailian applications",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/auth/login.ts b/packages/commands/src/commands/auth/login.ts
index 3901369..7f8f78e 100644
--- a/packages/commands/src/commands/auth/login.ts
+++ b/packages/commands/src/commands/auth/login.ts
@@ -19,7 +19,7 @@ import {
 
 export default defineCommand({
   description: "Authenticate with API key or console browser login (credentials can coexist)",
-  skipDefaultApiKeySetup: true,
+  auth: "none",
   usageArgs: "--api-key <key> | --console",
   options: [
     { flag: "--api-key <key>", description: "DashScope API key to store" },
diff --git a/packages/commands/src/commands/auth/logout.ts b/packages/commands/src/commands/auth/logout.ts
index f05646a..7626d70 100644
--- a/packages/commands/src/commands/auth/logout.ts
+++ b/packages/commands/src/commands/auth/logout.ts
@@ -19,7 +19,7 @@ async function clearConsoleToken(): Promise<boolean> {
 
 export default defineCommand({
   description: "Clear stored credentials",
-  skipDefaultApiKeySetup: true,
+  auth: "none",
   usageArgs: "[--console] [--yes] [--dry-run]",
   options: [
     {
diff --git a/packages/commands/src/commands/auth/status.ts b/packages/commands/src/commands/auth/status.ts
index aacf4ea..ba6ee87 100644
--- a/packages/commands/src/commands/auth/status.ts
+++ b/packages/commands/src/commands/auth/status.ts
@@ -140,6 +140,7 @@ function emitTextStatus(status: AuthStatusPayload, config: Config): void {
 
 export default defineCommand({
   description: "Show current authentication state",
+  auth: "none",
   options: [
     { flag: "--console-region <region>", description: "Console region" },
     {
diff --git a/packages/commands/src/commands/config/set.ts b/packages/commands/src/commands/config/set.ts
index 748594a..9ec9427 100644
--- a/packages/commands/src/commands/config/set.ts
+++ b/packages/commands/src/commands/config/set.ts
@@ -51,7 +51,7 @@ const KEY_ALIASES: Record<string, string> = {
 
 export default defineCommand({
   description: "Set a config value",
-  skipDefaultApiKeySetup: true,
+  auth: "none",
   usageArgs: "--key <key> --value <value>",
   options: [
     {
diff --git a/packages/commands/src/commands/config/show.ts b/packages/commands/src/commands/config/show.ts
index 7b76687..5d311c3 100644
--- a/packages/commands/src/commands/config/show.ts
+++ b/packages/commands/src/commands/config/show.ts
@@ -11,7 +11,7 @@ import { emitResult } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Display current configuration",
-  skipDefaultApiKeySetup: true,
+  auth: "none",
   exampleArgs: ["", "--output json"],
   async run(config: Config, _flags: GlobalFlags) {
     const file = loadConfigFile();
diff --git a/packages/commands/src/commands/console/call.ts b/packages/commands/src/commands/console/call.ts
index 525377b..084653c 100644
--- a/packages/commands/src/commands/console/call.ts
+++ b/packages/commands/src/commands/console/call.ts
@@ -14,7 +14,7 @@ import { emitResult } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Call a Bailian console API via the CLI gateway",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "--api <api> --data <json> [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/file/upload.ts b/packages/commands/src/commands/file/upload.ts
index f0a1713..7713222 100644
--- a/packages/commands/src/commands/file/upload.ts
+++ b/packages/commands/src/commands/file/upload.ts
@@ -11,6 +11,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Upload a local file to DashScope temporary storage (48h)",
+  auth: "apiKey",
   usageArgs: "--file <path> --model <model>",
   options: [
     {
diff --git a/packages/commands/src/commands/image/edit.ts b/packages/commands/src/commands/image/edit.ts
index e6c302c..69e10ff 100644
--- a/packages/commands/src/commands/image/edit.ts
+++ b/packages/commands/src/commands/image/edit.ts
@@ -28,6 +28,7 @@ import { BOOL_FLAG_PROMPT_EXTEND_CLI_TRUE, BOOL_FLAG_WATERMARK } from "bailian-c
 
 export default defineCommand({
   description: "Edit an existing image with text instructions (Qwen-Image)",
+  auth: "apiKey",
   usageArgs: "--image <url> --prompt <text> [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/image/generate.ts b/packages/commands/src/commands/image/generate.ts
index 000afd3..6eecc2e 100644
--- a/packages/commands/src/commands/image/generate.ts
+++ b/packages/commands/src/commands/image/generate.ts
@@ -39,6 +39,7 @@ function isSyncModel(model: string): boolean {
 
 export default defineCommand({
   description: "Generate images (Qwen-Image / wan2.x)",
+  auth: "apiKey",
   usageArgs: "--prompt <text> [flags]",
   options: [
     { flag: "--prompt <text>", description: "Image description", required: true },
diff --git a/packages/commands/src/commands/knowledge/retrieve.ts b/packages/commands/src/commands/knowledge/retrieve.ts
index aa227b2..820fff6 100644
--- a/packages/commands/src/commands/knowledge/retrieve.ts
+++ b/packages/commands/src/commands/knowledge/retrieve.ts
@@ -24,7 +24,7 @@ const BAILIAN_HOST = "bailian.cn-beijing.aliyuncs.com";
 
 export default defineCommand({
   description: "Retrieve from a Bailian knowledge base",
-  skipDefaultApiKeySetup: true,
+  auth: "apiKey",
   usageArgs: "--index-id <id> --query <text> [flags]",
   options: [
     { flag: "--index-id <id>", description: "Knowledge base index ID (required)", required: true },
diff --git a/packages/commands/src/commands/mcp/call.ts b/packages/commands/src/commands/mcp/call.ts
index 43b36f8..2bfe262 100644
--- a/packages/commands/src/commands/mcp/call.ts
+++ b/packages/commands/src/commands/mcp/call.ts
@@ -31,7 +31,7 @@ function parseArgFlags(raw: string[]): Record<string, unknown> {
 
 export default defineCommand({
   description: "Call a tool on an MCP server (tools/call)",
-  skipDefaultApiKeySetup: true,
+  auth: "apiKey",
   usageArgs: "<server-code>.<tool> [--arg k=v ...] [--json '{...}'] [--url <url>]",
   options: [
     {
diff --git a/packages/commands/src/commands/mcp/list.ts b/packages/commands/src/commands/mcp/list.ts
index e93fa03..0c72978 100644
--- a/packages/commands/src/commands/mcp/list.ts
+++ b/packages/commands/src/commands/mcp/list.ts
@@ -26,7 +26,7 @@ interface ServerSummary {
 
 export default defineCommand({
   description: "List MCP servers activated under your Bailian account",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[flags]",
   options: [
     { flag: "--name <text>", description: "Filter by server name (substring match)" },
diff --git a/packages/commands/src/commands/mcp/tools.ts b/packages/commands/src/commands/mcp/tools.ts
index d30aa99..23e5744 100644
--- a/packages/commands/src/commands/mcp/tools.ts
+++ b/packages/commands/src/commands/mcp/tools.ts
@@ -12,7 +12,7 @@ import { ensureApiKey } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "List tools exposed by an MCP server (tools/list)",
-  skipDefaultApiKeySetup: true,
+  auth: "apiKey",
   usageArgs: "<server-code> [--url <url>]",
   options: [
     {
diff --git a/packages/commands/src/commands/memory/add.ts b/packages/commands/src/commands/memory/add.ts
index 830e7c5..b238f09 100644
--- a/packages/commands/src/commands/memory/add.ts
+++ b/packages/commands/src/commands/memory/add.ts
@@ -13,6 +13,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Add memory from messages or custom content",
+  auth: "apiKey",
   usageArgs: "--user-id <id> [--messages <json>] [--content <text>] [flags]",
   options: [
     { flag: "--user-id <id>", description: "User ID (required)", required: true },
diff --git a/packages/commands/src/commands/memory/delete.ts b/packages/commands/src/commands/memory/delete.ts
index d359c46..83b8852 100644
--- a/packages/commands/src/commands/memory/delete.ts
+++ b/packages/commands/src/commands/memory/delete.ts
@@ -11,6 +11,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Delete a memory node",
+  auth: "apiKey",
   usageArgs: "--node-id <id> --user-id <id>",
   options: [
     { flag: "--node-id <id>", description: "Memory node ID (required)", required: true },
diff --git a/packages/commands/src/commands/memory/list.ts b/packages/commands/src/commands/memory/list.ts
index 77ce5b9..d5e6a5c 100644
--- a/packages/commands/src/commands/memory/list.ts
+++ b/packages/commands/src/commands/memory/list.ts
@@ -12,6 +12,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "List memory nodes for a user",
+  auth: "apiKey",
   usageArgs: "--user-id <id> [flags]",
   options: [
     { flag: "--user-id <id>", description: "User ID (required)", required: true },
diff --git a/packages/commands/src/commands/memory/profile-create.ts b/packages/commands/src/commands/memory/profile-create.ts
index 5f61de3..0e521e9 100644
--- a/packages/commands/src/commands/memory/profile-create.ts
+++ b/packages/commands/src/commands/memory/profile-create.ts
@@ -13,6 +13,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Create a user profile schema for memory profiling",
+  auth: "apiKey",
   usageArgs: "--name <name> --attributes <json> [flags]",
   options: [
     { flag: "--name <name>", description: "Schema name (required)", required: true },
diff --git a/packages/commands/src/commands/memory/profile-get.ts b/packages/commands/src/commands/memory/profile-get.ts
index 9ce1092..92b7f6d 100644
--- a/packages/commands/src/commands/memory/profile-get.ts
+++ b/packages/commands/src/commands/memory/profile-get.ts
@@ -12,6 +12,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Get user profile by schema ID and user ID",
+  auth: "apiKey",
   usageArgs: "--schema-id <id> --user-id <id>",
   options: [
     { flag: "--schema-id <id>", description: "Profile schema ID (required)", required: true },
diff --git a/packages/commands/src/commands/memory/search.ts b/packages/commands/src/commands/memory/search.ts
index d7d4522..ff0f070 100644
--- a/packages/commands/src/commands/memory/search.ts
+++ b/packages/commands/src/commands/memory/search.ts
@@ -13,6 +13,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Search memory nodes by query or messages",
+  auth: "apiKey",
   usageArgs: "--user-id <id> [--query <text>] [flags]",
   options: [
     { flag: "--user-id <id>", description: "User ID (required)", required: true },
diff --git a/packages/commands/src/commands/memory/update.ts b/packages/commands/src/commands/memory/update.ts
index 431327b..4d814ec 100644
--- a/packages/commands/src/commands/memory/update.ts
+++ b/packages/commands/src/commands/memory/update.ts
@@ -12,6 +12,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Update a memory node content",
+  auth: "apiKey",
   usageArgs: "--node-id <id> --user-id <id> --content <text>",
   options: [
     { flag: "--node-id <id>", description: "Memory node ID (required)", required: true },
diff --git a/packages/commands/src/commands/omni/chat.ts b/packages/commands/src/commands/omni/chat.ts
index 5ff15b0..317fe57 100644
--- a/packages/commands/src/commands/omni/chat.ts
+++ b/packages/commands/src/commands/omni/chat.ts
@@ -86,6 +86,7 @@ function buildWavHeader(dataLength: number): Buffer {
 
 export default defineCommand({
   description: "Multimodal chat with text + audio output (Qwen-Omni)",
+  auth: "apiKey",
   usageArgs: "--message <text> [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/pipeline/run.ts b/packages/commands/src/commands/pipeline/run.ts
index c3dd3d0..63a6c7a 100644
--- a/packages/commands/src/commands/pipeline/run.ts
+++ b/packages/commands/src/commands/pipeline/run.ts
@@ -9,7 +9,7 @@ import { loadPipelineFile } from "./load-file.ts";
 
 export default defineCommand({
   description: "Run a pipeline workflow definition",
-  skipDefaultApiKeySetup: true,
+  auth: "none",
   usageArgs: "<file> [flags]",
   options: [
     { flag: "--input <json>", description: "Runtime input as inline JSON" },
diff --git a/packages/commands/src/commands/pipeline/validate.ts b/packages/commands/src/commands/pipeline/validate.ts
index 27cd2b3..c5a994b 100644
--- a/packages/commands/src/commands/pipeline/validate.ts
+++ b/packages/commands/src/commands/pipeline/validate.ts
@@ -7,7 +7,7 @@ import { loadPipelineFile } from "./load-file.ts";
 
 export default defineCommand({
   description: "Validate a pipeline definition without executing",
-  skipDefaultApiKeySetup: true,
+  auth: "none",
   usageArgs: "<file>",
   options: [],
   exampleArgs: ["workflow.yaml", "workflow.json --output json"],
diff --git a/packages/commands/src/commands/quota/check.ts b/packages/commands/src/commands/quota/check.ts
index 817caa6..4cc2a4f 100644
--- a/packages/commands/src/commands/quota/check.ts
+++ b/packages/commands/src/commands/quota/check.ts
@@ -236,7 +236,7 @@ function printTable(rows: CheckRow[], noColor: boolean): void {
 
 export default defineCommand({
   description: "Check current usage against rate limits",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[--model <model>] [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/quota/history.ts b/packages/commands/src/commands/quota/history.ts
index 0a4e0f9..fc48342 100644
--- a/packages/commands/src/commands/quota/history.ts
+++ b/packages/commands/src/commands/quota/history.ts
@@ -92,7 +92,7 @@ function printTable(records: LimitApplicationItem[], noColor: boolean, total: nu
 
 export default defineCommand({
   description: "View quota change history",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/quota/list.ts b/packages/commands/src/commands/quota/list.ts
index 7129fac..79113c3 100644
--- a/packages/commands/src/commands/quota/list.ts
+++ b/packages/commands/src/commands/quota/list.ts
@@ -151,7 +151,7 @@ function printTable(models: ModelWithQpm[], noColor: boolean): void {
 
 export default defineCommand({
   description: "View model RPM/TPM rate limits",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[--model <model>] [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/quota/request.ts b/packages/commands/src/commands/quota/request.ts
index b5b024a..19f2545 100644
--- a/packages/commands/src/commands/quota/request.ts
+++ b/packages/commands/src/commands/quota/request.ts
@@ -79,7 +79,7 @@ async function fetchModelQpmInfo(
 
 export default defineCommand({
   description: "Request a temporary quota increase",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "--model <model> --tpm <value> [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/search/web.ts b/packages/commands/src/commands/search/web.ts
index a7d9594..ab527ed 100644
--- a/packages/commands/src/commands/search/web.ts
+++ b/packages/commands/src/commands/search/web.ts
@@ -13,6 +13,7 @@ import { emitResult } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Search the web using DashScope MCP WebSearch service",
+  auth: "apiKey",
   usageArgs: "--query <text> [flags]",
   options: [
     { flag: "--query <text>", description: "Search query text", required: true },
diff --git a/packages/commands/src/commands/speech/recognize.ts b/packages/commands/src/commands/speech/recognize.ts
index c26d702..9a573e8 100644
--- a/packages/commands/src/commands/speech/recognize.ts
+++ b/packages/commands/src/commands/speech/recognize.ts
@@ -24,6 +24,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Recognize speech from audio files (FunAudio-ASR)",
+  auth: "apiKey",
   usageArgs: "--url <audio-url> [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/speech/synthesize.ts b/packages/commands/src/commands/speech/synthesize.ts
index 2df8c8f..129862c 100644
--- a/packages/commands/src/commands/speech/synthesize.ts
+++ b/packages/commands/src/commands/speech/synthesize.ts
@@ -143,6 +143,7 @@ function printVoiceList(model: string): void {
 
 export default defineCommand({
   description: "Synthesize speech from text (CosyVoice TTS)",
+  auth: "apiKey",
   usageArgs: "--text <text> [flags]",
   options: [
     { flag: "--text <text>", description: "Text to synthesize into speech", required: true },
diff --git a/packages/commands/src/commands/text/chat.ts b/packages/commands/src/commands/text/chat.ts
index 78a03df..d2c58c4 100644
--- a/packages/commands/src/commands/text/chat.ts
+++ b/packages/commands/src/commands/text/chat.ts
@@ -69,6 +69,7 @@ function parseMessages(flags: GlobalFlags): ParsedMessages {
 
 export default defineCommand({
   description: "Send a chat completion (OpenAI compatible, DashScope)",
+  auth: "apiKey",
   usageArgs: "--message <text> [flags]",
   options: [
     { flag: "--model <model>", description: "Model ID (default: qwen3.7-max)" },
diff --git a/packages/commands/src/commands/update.ts b/packages/commands/src/commands/update.ts
index c8a8a27..a226286 100644
--- a/packages/commands/src/commands/update.ts
+++ b/packages/commands/src/commands/update.ts
@@ -29,7 +29,7 @@ function updateAgentSkill(colors: { green: string; yellow: string; reset: string
 
 export default defineCommand({
   description: "Update the CLI to the latest version",
-  skipDefaultApiKeySetup: true,
+  auth: "none",
   exampleArgs: [""],
   async run(config) {
     const npmPackage = config.npmPackage!;
diff --git a/packages/commands/src/commands/usage/free.ts b/packages/commands/src/commands/usage/free.ts
index b6361af..360d567 100644
--- a/packages/commands/src/commands/usage/free.ts
+++ b/packages/commands/src/commands/usage/free.ts
@@ -185,7 +185,7 @@ async function fetchAllModels(config: Config, token: string): Promise<ModelInfo[
 
 export default defineCommand({
   description: "Query free-tier quota for models (all models if --model is omitted)",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[--model <model>[,model2,...]] [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/usage/freetier.ts b/packages/commands/src/commands/usage/freetier.ts
index 6171513..f487d08 100644
--- a/packages/commands/src/commands/usage/freetier.ts
+++ b/packages/commands/src/commands/usage/freetier.ts
@@ -102,7 +102,7 @@ async function fetchAllModelNames(config: Config, token: string): Promise<string
 export default defineCommand({
   description:
     "Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "<--model <model>[,model2,...] | --all> [--off] [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/usage/stats.ts b/packages/commands/src/commands/usage/stats.ts
index f33d4a6..cdc038d 100644
--- a/packages/commands/src/commands/usage/stats.ts
+++ b/packages/commands/src/commands/usage/stats.ts
@@ -286,7 +286,7 @@ function printModelTable(
 
 export default defineCommand({
   description: "Query model usage statistics",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[--model <model>] [--days <days>] [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/video/download.ts b/packages/commands/src/commands/video/download.ts
index 5e99020..17f20d4 100644
--- a/packages/commands/src/commands/video/download.ts
+++ b/packages/commands/src/commands/video/download.ts
@@ -15,6 +15,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Download a completed video by task ID",
+  auth: "none",
   usageArgs: "--task-id <id> --out <path>",
   options: [
     { flag: "--task-id <id>", description: "Task ID to download from" },
diff --git a/packages/commands/src/commands/video/edit.ts b/packages/commands/src/commands/video/edit.ts
index cb2156b..18e8fb5 100644
--- a/packages/commands/src/commands/video/edit.ts
+++ b/packages/commands/src/commands/video/edit.ts
@@ -27,6 +27,7 @@ import { BOOL_FLAG_PROMPT_EXTEND_API_DEFAULT, BOOL_FLAG_WATERMARK } from "bailia
 export default defineCommand({
   description:
     "Edit a video with happyhorse-1.0-video-edit (style transfer, object replacement, etc.)",
+  auth: "apiKey",
   usageArgs: "--video <url> --prompt <text> [flags]",
   options: [
     { flag: "--model <model>", description: "Model ID (default: happyhorse-1.0-video-edit)" },
diff --git a/packages/commands/src/commands/video/generate.ts b/packages/commands/src/commands/video/generate.ts
index 320988a..49ccd43 100644
--- a/packages/commands/src/commands/video/generate.ts
+++ b/packages/commands/src/commands/video/generate.ts
@@ -28,6 +28,7 @@ import { BOOL_FLAG_PROMPT_EXTEND_API_DEFAULT, BOOL_FLAG_WATERMARK } from "bailia
 export default defineCommand({
   description:
     "Generate a video from text or image (happyhorse-1.0-t2v / happyhorse-1.0-i2v / wan2.6-t2v)",
+  auth: "apiKey",
   usageArgs: "--prompt <text> [--image <url>] [flags]",
   options: [
     {
diff --git a/packages/commands/src/commands/video/ref.ts b/packages/commands/src/commands/video/ref.ts
index 1f2cd34..5c2566e 100644
--- a/packages/commands/src/commands/video/ref.ts
+++ b/packages/commands/src/commands/video/ref.ts
@@ -27,6 +27,7 @@ import { BOOL_FLAG_PROMPT_EXTEND_API_DEFAULT, BOOL_FLAG_WATERMARK } from "bailia
 export default defineCommand({
   description:
     "Reference-to-video generation (happyhorse-1.0-r2v / wan2.6-r2v): multi-subject, multi-shot with voice",
+  auth: "apiKey",
   usageArgs: "--prompt <text> --image <url>... [--ref-video <url>...] [flags]",
   options: [
     { flag: "--model <model>", description: "Model ID (default: happyhorse-1.0-r2v)" },
diff --git a/packages/commands/src/commands/video/task-get.ts b/packages/commands/src/commands/video/task-get.ts
index a214889..a814f1f 100644
--- a/packages/commands/src/commands/video/task-get.ts
+++ b/packages/commands/src/commands/video/task-get.ts
@@ -12,6 +12,7 @@ import { emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
   description: "Query async task status",
+  auth: "apiKey",
   usageArgs: "--task-id <id>",
   options: [{ flag: "--task-id <id>", description: "Async task ID" }],
   exampleArgs: [
diff --git a/packages/commands/src/commands/vision/describe.ts b/packages/commands/src/commands/vision/describe.ts
index abe04f2..d2aa1bc 100644
--- a/packages/commands/src/commands/vision/describe.ts
+++ b/packages/commands/src/commands/vision/describe.ts
@@ -58,6 +58,7 @@ async function toImageUrl(image: string): Promise<string> {
 
 export default defineCommand({
   description: "Describe an image or video using Qwen-VL",
+  auth: "apiKey",
   usageArgs: "--image <path-or-url> [--video <url>] [--prompt <text>]",
   options: [
     { flag: "--image <path-or-url>", description: "Local image path or URL" },
diff --git a/packages/commands/src/commands/workspace/list.ts b/packages/commands/src/commands/workspace/list.ts
index eff573e..01dc7cb 100644
--- a/packages/commands/src/commands/workspace/list.ts
+++ b/packages/commands/src/commands/workspace/list.ts
@@ -77,7 +77,7 @@ function printTable(workspaces: WorkspaceInfo[], noColor: boolean): void {
 
 export default defineCommand({
   description: "List all workspaces",
-  skipDefaultApiKeySetup: true,
+  auth: "console",
   usageArgs: "[flags]",
   options: [
     {
diff --git a/packages/core/src/types/command.ts b/packages/core/src/types/command.ts
index f2043da..1605215 100644
--- a/packages/core/src/types/command.ts
+++ b/packages/core/src/types/command.ts
@@ -8,6 +8,15 @@ export interface OptionDef {
   required?: boolean;
 }
 
+/**
+ * Credential a command requires. The runtime prepares it before execution.
+ *  - "apiKey"  : DashScope API Key. The runtime runs ensureApiKey beforehand,
+ *                except under --dry-run (which only prints the request).
+ *  - "console" : Console Gateway credential (usage / quota / app list / workspace, …).
+ *  - "none"    : No credential (config / auth login flow / pipeline validate / update, …).
+ */
+export type AuthRequirement = "apiKey" | "console" | "none";
+
 export interface Command {
   description: string;
   /**
@@ -24,7 +33,8 @@ export interface Command {
    * `<bin> <path>` per product when rendering help.
    */
   exampleArgs?: string[];
-  skipDefaultApiKeySetup?: boolean;
+  /** Credential this command requires. See {@link AuthRequirement}. */
+  auth: AuthRequirement;
   notes?: string[];
   execute: (config: Config, flags: GlobalFlags) => Promise<void>;
 }
@@ -36,7 +46,8 @@ export interface CommandSpec {
   options?: OptionDef[];
   /** See {@link Command.exampleArgs} — argument strings only, no `<bin> <path>` prefix. */
   exampleArgs?: string[];
-  skipDefaultApiKeySetup?: boolean;
+  /** Credential this command requires. See {@link AuthRequirement}. */
+  auth: AuthRequirement;
   notes?: string[];
   run: (config: Config, flags: GlobalFlags) => Promise<void>;
 }
@@ -47,7 +58,7 @@ export function defineCommand(spec: CommandSpec): Command {
     usageArgs: spec.usageArgs,
     options: spec.options,
     exampleArgs: spec.exampleArgs,
-    skipDefaultApiKeySetup: spec.skipDefaultApiKeySetup,
+    auth: spec.auth,
     notes: spec.notes,
     execute: (config, flags) => spec.run(config, flags),
   };
diff --git a/packages/runtime/src/create-cli.ts b/packages/runtime/src/create-cli.ts
index 1ca4531..2738ccf 100644
--- a/packages/runtime/src/create-cli.ts
+++ b/packages/runtime/src/create-cli.ts
@@ -123,8 +123,9 @@ export function createCli(commands: Record<string, Command>, opts: CliOptions):
     config.binName = opts.binName;
     config.npmPackage = npmPackage;
 
-    // 默认执行 ensureApiKey；自行处理鉴权或仅需 Console/AK-SK 等的命令在 defineCommand 上设 skipDefaultApiKeySetup
-    if (!command.skipDefaultApiKeySetup) {
+    // 仅 apiKey 类命令由框架统一准备 API Key；dry-run 时跳过（只打印请求，不要求凭证）。
+    // console 命令在命令体内解析 Console Gateway 凭证；none 命令无需凭证。
+    if (command.auth === "apiKey" && !config.dryRun) {
       await ensureApiKey(config);
       try {
         const credential = await resolveCredential(config);