feat: Add config file support for API key persistence

Allow storing the API key in ~/.config/codize/config.json so users
don't need to pass --api-key or set CODIZE_API_KEY on every invocation.
Adds `codize config` command with set/get/list/path subcommands.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: koki-develop

CLAUDE.md

@@ -35,15 +35,17 @@ npx prettier --check .
 ## Architecture
 
 ```
-src/index.ts          — Entry point: sets up Commander program, registers commands, handles top-level errors
-src/error.ts          — CliError class (extends Error with exitCode)
-src/commands/run.ts   — `codize run` command: reads files, calls CodizeClient.sandbox.execute(), outputs results
-scripts/build.ts      — Build script using Bun.build API
+src/index.ts            — Entry point: sets up Commander program, registers commands, handles top-level errors
+src/error.ts            — CliError class (extends Error with exitCode)
+src/config.ts           — Config file read/write (path resolution, JSON parsing, validation)
+src/commands/run.ts     — `codize run` command: reads files, calls CodizeClient.sandbox.execute(), outputs results
+src/commands/config.ts  — `codize config` command: set/get/list/path subcommands for CLI configuration
+scripts/build.ts        — Build script using Bun.build API
 ```
 
 ### Command Registration Pattern
 
-Each command is defined in `src/commands/` and exports a `register*Command(program)` function that is called from `src/index.ts`. The `run` command is currently the only command.
+Each command is defined in `src/commands/` and exports a `register*Command(program)` function that is called from `src/index.ts`.
 
 ### Error Handling
 

README.md

@@ -17,14 +17,24 @@ $ npx @codize/cli --help
 
 ## Usage
 
-### Authentication
+### Configuration
 
-Generate your API key at [codize.dev/settings/api-keys](https://codize.dev/settings/api-keys), then set the `CODIZE_API_KEY` environment variable or pass the `--api-key` flag:
+Generate your API key at [codize.dev/settings/api-keys](https://codize.dev/settings/api-keys), then configure it using one of the following methods (listed in priority order):
+
+1. **CLI flag:** `--api-key`
+2. **Environment variable:** `CODIZE_API_KEY`
+3. **Config file:** `codize config set api-key <key>`
 
 ```bash
+# Save API key to config file (recommended)
+$ codize config set api-key cdz_YourApiKeyHere
+
+# Or use an environment variable
 $ export CODIZE_API_KEY="cdz_YourApiKeyHere"
 ```
 
+The config file is stored at `$XDG_CONFIG_HOME/codize/config.json` (defaults to `~/.config/codize/config.json`).
+
 ### Running a File
 
 ```bash

src/commands/config.ts

@@ -0,0 +1,67 @@
+import type { Command } from "commander";
+import type { Config } from "../config.ts";
+import {
+  CONFIG_KEY_MAP,
+  getConfigFilePath,
+  readConfig,
+  writeConfig,
+} from "../config.ts";
+import { CliError } from "../error.ts";
+
+function resolveConfigKey(key: string): keyof Config {
+  const prop = CONFIG_KEY_MAP[key];
+  if (prop == null) {
+    throw new CliError(
+      `Unknown config key '${key}'. Valid keys: ${Object.keys(CONFIG_KEY_MAP).join(", ")}.`,
+    );
+  }
+  return prop;
+}
+
+export function registerConfigCommand(program: Command): void {
+  const configCmd = program
+    .command("config")
+    .description("Manage CLI configuration");
+
+  configCmd
+    .command("set <key> <value>")
+    .description("Set a config value")
+    .action((key: string, value: string) => {
+      const prop = resolveConfigKey(key);
+      const config = readConfig();
+      config[prop] = value;
+      writeConfig(config);
+      process.stdout.write(`Set ${key}.\n`);
+    });
+
+  configCmd
+    .command("get <key>")
+    .description("Get a config value")
+    .action((key: string) => {
+      const prop = resolveConfigKey(key);
+      const config = readConfig();
+      const val = config[prop];
+      if (val == null) {
+        throw new CliError(`Config key '${key}' is not set.`);
+      }
+      process.stdout.write(`${val}\n`);
+    });
+
+  configCmd
+    .command("list")
+    .description("List all config values")
+    .action(() => {
+      const config = readConfig();
+      for (const [cliKey, prop] of Object.entries(CONFIG_KEY_MAP)) {
+        const val = config[prop];
+        process.stdout.write(`${cliKey}=${val ?? "(not set)"}\n`);
+      }
+    });
+
+  configCmd
+    .command("path")
+    .description("Show the config file path")
+    .action(() => {
+      process.stdout.write(`${getConfigFilePath()}\n`);
+    });
+}

src/commands/run.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { basename, extname } from "node:path";
 import { CodizeApiError, CodizeClient } from "@codize/sdk";
 import type { Command } from "commander";
+import { readConfig } from "../config.ts";
 import { CliError } from "../error.ts";
 
 const EXTENSION_TO_LANGUAGE: Record<string, string> = {
@@ -94,10 +95,12 @@ export function registerRunCommand(program: Command): void {
           );
         }
 
-        const apiKey = options.apiKey ?? process.env["CODIZE_API_KEY"];
+        const config = readConfig();
+        const apiKey =
+          options.apiKey ?? process.env["CODIZE_API_KEY"] ?? config.apiKey;
         if (!apiKey) {
           throw new CliError(
-            "API key is required. Set CODIZE_API_KEY or use --api-key.",
+            "API key is required. Use --api-key, set CODIZE_API_KEY, or run `codize config set api-key <key>`.",
           );
         }
 

src/config.ts

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CliError } from "./error.ts";
+
+export interface Config {
+  apiKey?: string;
+}
+
+/** Maps CLI key names (e.g. "api-key") to Config property names (e.g. "apiKey"). */
+export const CONFIG_KEY_MAP: Record<string, keyof Config> = {
+  "api-key": "apiKey",
+};
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export function getConfigFilePath(): string {
+  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
+  const base =
+    xdgConfigHome != null && xdgConfigHome !== ""
+      ? xdgConfigHome
+      : join(homedir(), ".config");
+  return join(base, "codize", "config.json");
+}
+
+export function readConfig(): Config {
+  const filePath = getConfigFilePath();
+  if (!existsSync(filePath)) {
+    return {};
+  }
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    throw new CliError(
+      `Cannot read config file '${filePath}': ${errorMessage(err)}`,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError(
+      `Config file '${filePath}' contains invalid JSON. Fix or delete it to continue.`,
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new CliError(
+      `Config file '${filePath}' must be a JSON object. Fix or delete it to continue.`,
+    );
+  }
+  const obj = parsed as Record<string, unknown>;
+  const config: Config = {};
+  if ("apiKey" in obj && typeof obj["apiKey"] !== "string") {
+    throw new CliError(
+      `Config file '${filePath}': 'apiKey' must be a string, got ${typeof obj["apiKey"]}. Fix or delete it to continue.`,
+    );
+  }
+  if (typeof obj["apiKey"] === "string") {
+    config.apiKey = obj["apiKey"];
+  }
+  return config;
+}
+
+export function writeConfig(config: Config): void {
+  const filePath = getConfigFilePath();
+  const dir = dirname(filePath);
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    throw new CliError(
+      `Cannot create config directory '${dir}': ${errorMessage(err)}`,
+    );
+  }
+  const json = JSON.stringify(config, null, 2) + "\n";
+  try {
+    writeFileSync(filePath, json, "utf-8");
+  } catch (err) {
+    throw new CliError(
+      `Cannot write config file '${filePath}': ${errorMessage(err)}`,
+    );
+  }
+}

src/index.ts

@@ -1,7 +1,8 @@
 import { Command } from "commander";
 import packageJson from "../package.json" with { type: "json" };
-import { CliError } from "./error.ts";
+import { registerConfigCommand } from "./commands/config.ts";
 import { registerRunCommand } from "./commands/run.ts";
+import { CliError } from "./error.ts";
 
 const program = new Command();
 
@@ -11,6 +12,7 @@ program
   .version(packageJson.version);
 
 registerRunCommand(program);
+registerConfigCommand(program);
 
 program.parseAsync(process.argv).catch((err: unknown) => {
   const message =