feat(config-agent): add --restore to roll back agent configs from latest backup

Author: lishengzxc

packages/commands/src/commands/config/agent/index.ts

@@ -1,9 +1,20 @@
 import { platform } from "os";
-import { defineCommand, detectOutputFormat, maskToken, type FlagsDef } from "bailian-cli-core";
+import {
+  defineCommand,
+  detectOutputFormat,
+  maskToken,
+  BailianError,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
 import { emitResult, emitBare } from "bailian-cli-runtime";
 import { AGENTS, VALID_AGENT_NAMES, type WriteParams } from "./writers.ts";
 import { decodeTokenPlanKey } from "./decode-key.ts";
-import { resolveRegionBaseUrl } from "./writers/utils.ts";
+import {
+  resolveRegionBaseUrl,
+  findLatestBackup,
+  restoreLatestBackup,
+} from "./writers/utils.ts";
 
 const FLAGS = {
   agent: {
@@ -39,12 +50,12 @@ const FLAGS = {
     type: "string",
     valueHint: "<model>",
     description: "Default model name",
-    required: true,
   },
   contextWindow: {
     type: "number",
     valueHint: "<tokens>",
-    description: "OpenClaw only: model context window in tokens (default: 256000)",
+    description:
+      "OpenClaw only: model context window in tokens (default: 256000)",
   },
   wireApi: {
     type: "string",
@@ -53,38 +64,106 @@ const FLAGS = {
       'Codex only: wire protocol (default: responses). "chat" only works with legacy Codex <= 0.80.0',
     choices: ["chat", "responses"],
   },
+  restore: {
+    type: "switch",
+    description:
+      "Restore the agent's config files from the latest .bak backup created by this command",
+  },
 } satisfies FlagsDef;
 
 export default defineCommand({
   description: "Configure a coding agent to use DashScope API",
   auth: "none",
   usageArgs:
-    "--agent <name> (--base-url <url> | --region <region>) (--api-key <key> | --key <encoded>) --model <model>",
+    "--agent <name> ((--base-url <url> | --region <region>) (--api-key <key> | --key <encoded>) --model <model> | --restore)",
   flags: FLAGS,
   exampleArgs: [
     "--agent claude-code --base-url https://dashscope.aliyuncs.com/apps/anthropic --api-key sk-xxxxx --model qwen3-max",
     "--agent qwen-code --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus",
     "--agent codex --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus",
+    "--agent claude-code --restore",
   ],
   validate(flags) {
-    if (!flags.baseUrl && !flags.region) return "one of --base-url or --region is required";
-    if (flags.baseUrl && flags.region) return "--base-url and --region are mutually exclusive";
-    if (!flags.apiKey && !flags.key) return "one of --api-key or --key is required";
-    if (flags.apiKey && flags.key) return "--api-key and --key are mutually exclusive";
+    if (flags.restore) {
+      const writeFlags = [
+        flags.baseUrl,
+        flags.region,
+        flags.apiKey,
+        flags.key,
+        flags.model,
+      ];
+      if (writeFlags.some((value) => value !== undefined)) {
+        return "--restore cannot be combined with --base-url/--region/--api-key/--key/--model";
+      }
+      return undefined;
+    }
+    if (!flags.model) return "--model is required";
+    if (!flags.baseUrl && !flags.region)
+      return "one of --base-url or --region is required";
+    if (flags.baseUrl && flags.region)
+      return "--base-url and --region are mutually exclusive";
+    if (!flags.apiKey && !flags.key)
+      return "one of --api-key or --key is required";
+    if (flags.apiKey && flags.key)
+      return "--api-key and --key are mutually exclusive";
     return undefined;
   },
   async run(ctx) {
     const { settings, flags } = ctx;
     const agentName = flags.agent;
-    const { model, contextWindow, wireApi } = flags;
+    const { contextWindow, wireApi } = flags;
+    const agentDef = AGENTS[agentName];
+    const format = detectOutputFormat(settings.output);
+
+    // --restore: roll each managed config file back to its newest .bak sibling.
+    if (flags.restore) {
+      const paths = agentDef.configPaths();
+
+      if (settings.dryRun) {
+        emitResult(
+          {
+            agent: agentName,
+            label: agentDef.label,
+            restore: paths.map((path) => ({
+              path,
+              backup: findLatestBackup(path) ?? null,
+            })),
+          },
+          format,
+        );
+        return;
+      }
+
+      const results = paths.map((path) => restoreLatestBackup(path));
+      if (results.every((result) => !result.backupPath)) {
+        throw new BailianError(
+          `No backups found for ${agentDef.label}.`,
+          ExitCode.GENERAL,
+          "Backups are created as <config>.bak.<timestamp> next to each config file when this command writes it.",
+        );
+      }
+
+      if (!settings.quiet) {
+        emitBare(`${agentDef.label} config restored from backup.`);
+        for (const result of results) {
+          if (result.backupPath)
+            emitBare(`  Restored: ${result.path} <- ${result.backupPath}`);
+          else emitBare(`  Skipped (no backup): ${result.path}`);
+        }
+      }
+      return;
+    }
+
+    // Write mode — validate() guarantees these flags are present.
+    const model = flags.model!;
     // --region is a Token Plan convenience: convert it into a base URL and use
     // it exactly as --base-url would be.
-    const baseUrl = flags.region ? resolveRegionBaseUrl(flags.region) : flags.baseUrl!;
+    const baseUrl = flags.region
+      ? resolveRegionBaseUrl(flags.region)
+      : flags.baseUrl!;
     // --key carries the web console's obfuscated form; decode it up front so
     // even --dry-run validates the token.
     const apiKey = flags.key ? decodeTokenPlanKey(flags.key) : flags.apiKey!;
-    const agentDef = AGENTS[agentName];
-    const format = detectOutputFormat(settings.output);
 
     // Hermes has no native Windows support.
     if (agentName === "hermes" && platform() === "win32") {

packages/commands/src/commands/config/agent/writers/claude-code.ts

@@ -9,20 +9,28 @@ import {
 } from "./utils.ts";
 
 /** Fill a tier/default model env only when the user has not set it yet. */
-function setModelEnvIfAbsent(env: Record<string, string>, key: string, model: string): void {
+function setModelEnvIfAbsent(
+  env: Record<string, string>,
+  key: string,
+  model: string,
+): void {
   const current = env[key];
   if (current === undefined || current.trim() === "") {
     env[key] = model;
   }
 }
 
+function configPaths(): string[] {
+  // Claude Code honors CLAUDE_CONFIG_DIR for its settings location.
+  const configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+  return [join(configDir, "settings.json"), join(homedir(), ".claude.json")];
+}
+
 export default {
   label: "Claude Code",
+  configPaths,
   write({ baseUrl, apiKey, model }) {
-    // Claude Code honors CLAUDE_CONFIG_DIR for its settings location.
-    const configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
-    const settingsPath = join(configDir, "settings.json");
-    const onboardingPath = join(homedir(), ".claude.json");
+    const [settingsPath, onboardingPath] = configPaths();
     const warnings: string[] = [];
 
     const resolved = resolveClaudeCodeBaseUrl(baseUrl);

packages/commands/src/commands/config/agent/writers/codex.ts

@@ -2,14 +2,28 @@ import { homedir } from "os";
 import { join } from "path";
 import { existsSync, readFileSync } from "fs";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-import { backup, readJson, writeJsonAtomic, writeTextAtomic, type AgentDef } from "./utils.ts";
+import {
+  backup,
+  readJson,
+  writeJsonAtomic,
+  writeTextAtomic,
+  type AgentDef,
+} from "./utils.ts";
 
 const PROVIDER_KEY = "bailian-cli";
 
+function configPaths(): string[] {
+  return [
+    join(homedir(), ".codex", "config.toml"),
+    join(homedir(), ".codex", "auth.json"),
+  ];
+}
+
 export default {
   label: "Codex",
+  configPaths,
   write({ baseUrl, apiKey, model, wireApi: wireApiParam }) {
-    const configPath = join(homedir(), ".codex", "config.toml");
+    const [configPath, authPath] = configPaths();
     const warnings: string[] = [];
 
     // config.toml — merge into existing config so unrelated settings
@@ -18,7 +32,10 @@ export default {
     let config: Record<string, unknown> = {};
     if (existsSync(configPath)) {
       try {
-        config = parseToml(readFileSync(configPath, "utf-8")) as Record<string, unknown>;
+        config = parseToml(readFileSync(configPath, "utf-8")) as Record<
+          string,
+          unknown
+        >;
       } catch {
         config = {};
       }
@@ -57,7 +74,6 @@ export default {
     writeTextAtomic(configPath, stringifyToml(config) + "\n");
 
     // auth.json — Codex reads OPENAI_API_KEY from here when the env var is unset.
-    const authPath = join(homedir(), ".codex", "auth.json");
     backup(authPath);
     const auth = readJson(authPath);
     auth.OPENAI_API_KEY = apiKey;

packages/commands/src/commands/config/agent/writers/hermes.ts

@@ -2,19 +2,30 @@ import { homedir } from "os";
 import { join } from "path";
 import { existsSync, readFileSync } from "fs";
 import yaml from "yaml";
-import { backup, writeTextAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
+import {
+  backup,
+  writeTextAtomic,
+  isAnthropicEndpoint,
+  type AgentDef,
+} from "./utils.ts";
+
+function configPaths(): string[] {
+  return [join(homedir(), ".hermes", "config.yaml")];
+}
 
 export default {
   label: "Hermes Agent",
+  configPaths,
   write({ baseUrl, apiKey, model }) {
-    const configPath = join(homedir(), ".hermes", "config.yaml");
+    const [configPath] = configPaths();
 
     backup(configPath);
 
     let config: Record<string, unknown> = {};
     if (existsSync(configPath)) {
       try {
-        config = (yaml.parse(readFileSync(configPath, "utf-8")) ?? {}) as Record<string, unknown>;
+        config = (yaml.parse(readFileSync(configPath, "utf-8")) ??
+          {}) as Record<string, unknown>;
       } catch {
         config = {};
       }

packages/commands/src/commands/config/agent/writers/openclaw.ts

@@ -1,24 +1,37 @@
 import { homedir } from "os";
 import { join } from "path";
-import { backup, readJson, writeJsonAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
+import {
+  backup,
+  readJson,
+  writeJsonAtomic,
+  isAnthropicEndpoint,
+  type AgentDef,
+} from "./utils.ts";
 
 // Safe default when --context-window is not given: most Model Studio models
 // offer ≥256K context; users can raise it per model via the flag.
 const DEFAULT_CONTEXT_WINDOW = 256000;
 
 const PROVIDER_ID = "bailian-cli";
 
+function configPaths(): string[] {
+  return [join(homedir(), ".openclaw", "openclaw.json")];
+}
+
 function readPrimary(defaults: Record<string, unknown>): string | undefined {
   const model = defaults.model;
   if (!model || typeof model !== "object") return undefined;
   const primary = (model as Record<string, unknown>).primary;
-  return typeof primary === "string" && primary.trim() !== "" ? primary.trim() : undefined;
+  return typeof primary === "string" && primary.trim() !== ""
+    ? primary.trim()
+    : undefined;
 }
 
 export default {
   label: "OpenClaw",
+  configPaths,
   write({ baseUrl, apiKey, model, contextWindow }) {
-    const configPath = join(homedir(), ".openclaw", "openclaw.json");
+    const [configPath] = configPaths();
     const warnings: string[] = [];
     const modelRef = `${PROVIDER_ID}/${model}`;
 
@@ -30,7 +43,9 @@ export default {
     const models = (config.models ?? {}) as Record<string, unknown>;
     models.mode = "merge";
     const providers = (models.providers ?? {}) as Record<string, unknown>;
-    const api = isAnthropicEndpoint(baseUrl) ? "anthropic-messages" : "openai-completions";
+    const api = isAnthropicEndpoint(baseUrl)
+      ? "anthropic-messages"
+      : "openai-completions";
     providers[PROVIDER_ID] = {
       baseUrl,
       apiKey,

packages/commands/src/commands/config/agent/writers/opencode.ts

@@ -1,11 +1,22 @@
 import { homedir } from "os";
 import { join } from "path";
-import { backup, readJsonc, writeJsonAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
+import {
+  backup,
+  readJsonc,
+  writeJsonAtomic,
+  isAnthropicEndpoint,
+  type AgentDef,
+} from "./utils.ts";
+
+function configPaths(): string[] {
+  return [join(homedir(), ".config", "opencode", "opencode.json")];
+}
 
 export default {
   label: "OpenCode",
+  configPaths,
   write({ baseUrl, apiKey, model }) {
-    const configPath = join(homedir(), ".config", "opencode", "opencode.json");
+    const [configPath] = configPaths();
 
     // opencode.json is JSONC — tolerate comments and trailing commas on read.
     backup(configPath);
@@ -14,7 +25,9 @@ export default {
     if (!config.$schema) config.$schema = "https://opencode.ai/config.json";
 
     const provider = (config.provider ?? {}) as Record<string, unknown>;
-    const npm = isAnthropicEndpoint(baseUrl) ? "@ai-sdk/anthropic" : "@ai-sdk/openai-compatible";
+    const npm = isAnthropicEndpoint(baseUrl)
+      ? "@ai-sdk/anthropic"
+      : "@ai-sdk/openai-compatible";
     provider["bailian-cli"] = {
       npm,
       name: "Alibaba Cloud Model Studio",