stoaken 0.1.0 → 0.3.0

package/README.md

@@ -1,39 +1,85 @@
-# stoaken
-
-The official CLI for [Stoaken](https://stoaken.com) -- a design token management platform (Brands, Token Sets, Themes, DTCG-conformant token storage, versioned Releases with an approval gate) that AI coding agents and MCP-capable tools can read and propose changes to directly.
-
-## Quickstart
-
-```
-npx stoaken init
-```
-
-Run it in the root of the project you want connected to a Stoaken Brand. It will:
-
-1. Ask how you'd like to sign in -- open your browser for a real OAuth 2.1 login, or let you paste an API key you've already created at `/settings/api-keys`.
-2. List the real Brands your account can see, and let you pick one.
-3. Write `stoaken.config.json` (which Brand, which server -- safe to commit, holds no secret) and `.stoaken/credentials.json` (your bearer credential, `chmod 600`, automatically added to `.gitignore`).
-4. Generate `.stoaken/SKILL.md` -- a short brief for AI coding agents (Claude Code, Cursor) explaining how to connect to this project's Stoaken MCP server and what its tools do.
-
-Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or re-authenticate.
-
-## Authentication
-
-Two paths, both landing on the same bearer credential:
-
-- **Log in with browser** -- a real OAuth 2.1 Authorization Code + PKCE flow. The CLI discovers Stoaken's Authorization Server automatically (via its `/.well-known/oauth-protected-resource` metadata), registers itself as an OAuth client on first run, and opens your browser to sign in.
-- **Paste an API key** -- for CI, scripts, or anywhere a browser isn't available. Create one at `/settings/api-keys` in the Stoaken app.
-
-## What this connects to
-
-Once set up, any MCP-capable client (Claude Code, Cursor, Claude Desktop) or a direct HTTP client can use the credential in `.stoaken/credentials.json` as a Bearer token against Stoaken's MCP server, which exposes four tools:
-
-- `list_brands` -- every Brand you hold at least Viewer on.
-- `get_theme_tokens(themeId)` -- a Theme's cascade-merged token tree.
-- `list_releases(themeId)` -- a Theme's Releases with version, status, and change summary.
-- `propose_token_change(themeId, tokenSetId, document, version, versionType)` -- proposes a token change and submits it for approval. **This never publishes.** A human reviewer always approves through the Stoaken Command Center before it goes live.
-
-## Links
-
-- [Stoaken on GitHub](https://github.com/craig-astravale/stoaken)
-- [Report an issue](https://github.com/craig-astravale/stoaken/issues)
+# stoaken
+
+The official CLI for [Stoaken](https://www.stoaken.com) -- a design token management platform (Brands, Token Sets, Themes, DTCG-conformant token storage, versioned Releases with an approval gate) that AI coding agents and MCP-capable tools can read and propose changes to directly.
+
+## Quickstart
+
+```
+npx stoaken init
+```
+
+Run it in the root of the project you want connected to a Stoaken Brand. It will:
+
+1. Ask how you'd like to sign in -- open your browser for a real OAuth 2.1 login, or let you paste an API key you've already created at `/settings/api-keys`.
+2. List the real Brands your account can see, and let you pick one.
+3. Write `stoaken.config.json` (which Brand, which server -- safe to commit, holds no secret) and `.stoaken/credentials.json` (your bearer credential, `chmod 600`, automatically added to `.gitignore`).
+4. Generate `.stoaken/SKILL.md` -- a short brief for AI coding agents (Claude Code, Cursor) explaining how to connect to this project's Stoaken MCP server and what its tools do.
+
+Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or re-authenticate.
+
+## Authentication
+
+Two paths, both landing on the same bearer credential:
+
+- **Log in with browser** -- a real OAuth 2.1 Authorization Code + PKCE flow. The CLI discovers Stoaken's Authorization Server automatically (via its `/.well-known/oauth-protected-resource` metadata), registers itself as an OAuth client on first run, and opens your browser to sign in.
+- **Paste an API key** -- for CI, scripts, or anywhere a browser isn't available. Create one at `/settings/api-keys` in the Stoaken app.
+
+## Export your tokens as code
+
+`stoaken export` writes a theme's live release as a file: CSS variables, W3C JSON, Style
+Dictionary v4 JSON, or a JS/TS module. There are no timestamps in the output, so committed files
+give clean diffs.
+
+```sh
+npx stoaken export --theme Default --format css --out src/styles/tokens.css
+npx stoaken export --theme Default --format json-dtcg --mode color-scheme:dark --out tokens/dark.json
+npx stoaken export --theme Default --format ts --out src/tokens.ts
+npx stoaken export --theme Default --out -        # to stdout
+```
+
+| Option | |
+| --- | --- |
+| `--theme <name\|id>` | Which theme (needed when the Brand has more than one) |
+| `--format` | `css` (default), `json-dtcg`, `json-sd4`, `js`, `ts` |
+| `--mode <key>` | A mode combination for the one-mode formats; CSS includes every mode |
+| `--prefix <prefix>` | CSS only: a prefix for every variable name |
+| `--release <id>` | One release (e.g. one still in review) instead of the live one |
+| `--out <file\|->` | Where to write; default is the server's file name |
+| `--check` | Write nothing; exit 1 if the file on disk is out of date |
+
+Save your targets in `stoaken.config.json` and a plain `npx stoaken export` runs them all
+(`npx stoaken export --check` checks them all):
+
+```json
+{
+  "brandId": "…",
+  "brandName": "Acme",
+  "serverUrl": "https://www.stoaken.com",
+  "exports": [
+    { "theme": "Default", "format": "css", "out": "src/styles/tokens.css" },
+    { "theme": "Default", "format": "ts", "out": "src/tokens.ts" }
+  ]
+}
+```
+
+**In CI**, set `STOAKEN_TOKEN` to an API key (Settings > API keys); it's used instead of the
+sign-in saved by `stoaken init`. For example, to fail a build when the committed tokens are behind
+the live release:
+
+```sh
+STOAKEN_TOKEN=${{ secrets.STOAKEN_TOKEN }} npx stoaken export --check
+```
+
+## What this connects to
+
+Once set up, any MCP-capable client (Claude Code, Cursor, Claude Desktop) or a direct HTTP client can use the credential in `.stoaken/credentials.json` as a Bearer token against Stoaken's MCP server, which exposes four tools:
+
+- `list_brands` -- every Brand you hold at least Viewer on.
+- `get_theme_tokens(themeId)` -- a Theme's cascade-merged token tree.
+- `list_releases(themeId)` -- a Theme's Releases with version, status, and change summary.
+- `propose_token_change(themeId, tokenSetId, document, version, versionType)` -- proposes a token change and submits it for approval. **This never publishes.** A human reviewer always approves through the Stoaken Command Center before it goes live.
+
+## Links
+
+- [Stoaken on GitHub](https://github.com/craig-astravale/stoaken)
+- [Report an issue](https://github.com/craig-astravale/stoaken/issues)

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import * as p3 from "@clack/prompts";
+import * as p4 from "@clack/prompts";
 
 // src/commands/init.ts
 import * as p2 from "@clack/prompts";
@@ -44,6 +44,14 @@ async function writeCredentials(cwd, credentials) {
   await writeFile(path, `${JSON.stringify(credentials, null, 2)}
 `, { encoding: "utf8", mode: 384 });
 }
+async function readCredentials(cwd) {
+  try {
+    const raw = await readFile(join(cwd, CREDENTIALS_FILE), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 async function readOAuthClient(cwd) {
   try {
     const raw = await readFile(join(cwd, OAUTH_CLIENT_FILE), "utf8");
@@ -121,7 +129,7 @@ function generatePkce() {
   return { verifier, challenge };
 }
 function waitForCallback() {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const server = createServer((req, res) => {
       const url = new URL(req.url ?? "/", REDIRECT_URI);
       if (url.pathname !== "/callback") {
@@ -140,7 +148,7 @@ function waitForCallback() {
       } else if (!code) {
         reject(new Error("No authorization code in the callback"));
       } else {
-        resolve(code);
+        resolve2(code);
       }
     });
     server.on("error", reject);
@@ -189,8 +197,8 @@ async function promptForApiKey() {
   const key = await p.password({
     message: "Paste your Stoaken API key (from /settings/api-keys):",
     validate: (value) => {
-      if (!value?.startsWith("twk_")) {
-        return "That doesn't look like a Stoaken API key (should start with twk_)";
+      if (!value?.startsWith("stk_") && !value?.startsWith("twk_")) {
+        return "That doesn't look like a Stoaken API key (should start with stk_)";
       }
     }
   });
@@ -207,7 +215,7 @@ async function listBrands(serverUrl, credential) {
   const transport = new StreamableHTTPClientTransport(new URL("/mcp", serverUrl), {
     requestInit: { headers: { Authorization: `Bearer ${credential}` } }
   });
-  const client = new Client({ name: "stoaken-cli", version: "0.1.0" });
+  const client = new Client({ name: "stoaken-cli", version: "0.3.0" });
   await client.connect(transport);
   try {
     const result = await client.callTool({ name: "list_brands", arguments: {} });
@@ -227,14 +235,19 @@ function generateSkillFile(config) {
 
 This project is connected to the **${config.brandName}** Brand on Stoaken (\`${config.serverUrl}\`).
 
-Stoaken's MCP server exposes four tools. Connect to it at \`${config.serverUrl}/mcp\` using
+Stoaken's MCP server exposes the tools below. Connect to it at \`${config.serverUrl}/mcp\` using
 the credential in \`.stoaken/credentials.json\` as a Bearer token (never commit that file --
 it's already in \`.gitignore\`).
 
 ## Tools
 
 - **list_brands** -- every Brand you hold at least Viewer on.
-- **get_theme_tokens(themeId)** -- a Theme's cascade-merged token tree.
+- **get_theme_tokens(themeId)** -- a Theme's cascade-merged token tree (aliases left raw).
+- **get_resolved_theme_tokens(themeId, mode?)** -- a Theme's fully resolved tokens (aliases followed,
+  inheritance applied) for every mode-combination, or just \`mode\`.
+- **list_deprecated_tokens(themeId, mode?)** -- deprecated tokens, each with its notice, its named
+  replacement, and the tokens still referencing it. **Don't use a deprecated token in new code --
+  use its replacement.** A resolved token carrying \`$deprecated\` is deprecated.
 - **list_releases(themeId)** -- a Theme's Releases with version, status, and change summary.
 - **propose_token_change(themeId, tokenSetId, document, version, versionType)** -- updates a Token
   Set's document and submits a new Release for approval. **This never publishes.** The Release
@@ -242,6 +255,16 @@ it's already in \`.gitignore\`).
   Command Center before it goes live -- exactly the same gate a person editing through the UI
   goes through. There is no tool that publishes a Release; propose changes, then ask a human to
   review them.
+- **list_webhooks / create_webhook / update_webhook / rotate_webhook_secret / ping_webhook** -- manage a Brand's webhooks (Admin on the Brand; Team plan). A created or rotated secret is returned once; after a rotation the old secret keeps signing for 24 hours.
+- **create_theme / update_theme / delete_theme** -- manage a Brand's themes: which token sets they stack and in what order (Editor on the Brand; Team plan). create_theme can copy another theme's modes. Settings, not token changes: no release needed. Only never-released themes can be deleted.
+- **export_tokens(themeId | releaseId, format, mode?, prefix?)** -- read-only: a live release as a file (css, css-auto, scss, tailwind, tailwind4, swift, android, compose, json-dtcg, json-sd4, js, ts). Use it to update a project's committed token file.
+- **propose_token_edits(themeId, tokenSetId, operations, version, versionType, baseHash?)** -- the
+  same review gate, but with targeted edits instead of a whole document: \`set\`, \`add\`,
+  \`rename\` (references follow), \`delete\`, \`rename_group\` and \`describe\`, applied all or
+  nothing. Prefer it to propose_token_change for small changes.
+- **propose_token_deprecation(themeId, tokenPath, action, replacement?, note?, version)** --
+  deprecates (or un-deprecates) one token, naming its replacement, and submits a Release for review
+  the same way. Deprecation is a reviewed change, never a silent edit.
 
 ## This Brand
 
@@ -249,12 +272,18 @@ it's already in \`.gitignore\`).
 - Brand name: ${config.brandName}
 - Server: ${config.serverUrl}
 
+## Tokens as code
+
+\`npx stoaken export --theme <name> --format css|css-auto|scss|tailwind|tailwind4|swift|android|compose|json-dtcg|json-sd4|js|ts --out <file>\` writes a
+theme's live release as a file (no timestamps, so diffs stay clean). \`--check\` fails when the
+committed file is out of date. In CI, set \`STOAKEN_TOKEN\` to an API key.
+
 Re-run \`stoaken init\` if you need to switch Brands or re-authenticate.
 `;
 }
 
 // src/commands/init.ts
-var DEFAULT_SERVER_URL = "https://stoaken.com";
+var DEFAULT_SERVER_URL = "https://www.stoaken.com";
 async function runInit(options) {
   const cwd = process.cwd();
   const serverUrl = options.server ?? DEFAULT_SERVER_URL;
@@ -340,13 +369,314 @@ async function runInit(options) {
     await writeCredentials(cwd, { kind: credentialKind, token: credential });
     skipToWrite = { brandId: brand.id, brandName: brand.name };
   }
-  const config = { brandId: skipToWrite.brandId, brandName: skipToWrite.brandName, serverUrl };
+  const keepExports = existing?.brandId === skipToWrite.brandId && existing.exports !== void 0;
+  const config = {
+    brandId: skipToWrite.brandId,
+    brandName: skipToWrite.brandName,
+    serverUrl,
+    ...keepExports ? { exports: existing.exports } : {}
+  };
   await writeConfig(cwd, config);
   await ensureGitignored(cwd);
   await writeSkillFile(cwd, generateSkillFile(config));
   p2.outro(`Done -- this project is set up for ${config.brandName}.`);
 }
 
+// src/commands/export.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { dirname, relative, resolve } from "path";
+import * as p3 from "@clack/prompts";
+
+// src/api.ts
+var ApiProblem = class extends Error {
+  constructor(problem) {
+    super(problem.detail ?? problem.title ?? `HTTP ${problem.status}`);
+    this.problem = problem;
+    this.name = "ApiProblem";
+  }
+  problem;
+};
+async function call(serverUrl, token, path) {
+  let response;
+  try {
+    response = await fetch(new URL(path, serverUrl), {
+      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.3.0" }
+    });
+  } catch (error) {
+    throw new Error(`Couldn't reach ${serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!response.ok) {
+    let body = {};
+    try {
+      body = await response.json();
+    } catch {
+    }
+    throw new ApiProblem({ ...body, status: response.status });
+  }
+  return response;
+}
+async function listThemes(serverUrl, token, brandId) {
+  const themes = [];
+  let cursor = null;
+  for (let page = 0; page < 50; page++) {
+    const query = new URLSearchParams({ limit: "100" });
+    if (cursor) query.set("cursor", cursor);
+    const response = await call(serverUrl, token, `/api/brands/${encodeURIComponent(brandId)}/themes?${query}`);
+    const body = await response.json();
+    themes.push(...body.data.map((t) => ({ id: t.id, name: t.name })));
+    cursor = body.next_cursor;
+    if (!cursor) break;
+  }
+  return themes;
+}
+async function fetchExport(serverUrl, token, target) {
+  const query = new URLSearchParams({ format: target.format });
+  if (target.mode) query.set("mode", target.mode);
+  if (target.prefix) query.set("prefix", target.prefix);
+  const path = target.releaseId ? `/api/releases/${encodeURIComponent(target.releaseId)}/export?${query}` : `/api/themes/${encodeURIComponent(target.themeId ?? "")}/export?${query}`;
+  const response = await call(serverUrl, token, path);
+  return {
+    text: await response.text(),
+    filename: response.headers.get("content-disposition"),
+    warnings: Number(response.headers.get("stoaken-export-warnings") ?? 0) || 0
+  };
+}
+
+// src/export-plan.ts
+var EXPORT_FORMATS = ["css", "css-auto", "json-dtcg", "json-sd4", "js", "ts", "scss", "tailwind", "swift", "android", "tailwind4", "compose"];
+var ExportUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ExportUsageError";
+  }
+};
+var VALUE_FLAGS = ["theme", "format", "mode", "prefix", "release", "out", "server"];
+function isExportFormat(value) {
+  return typeof value === "string" && EXPORT_FORMATS.includes(value);
+}
+function parseExportArgs(argv) {
+  const values = {};
+  let check = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--check") {
+      check = true;
+      continue;
+    }
+    const match = /^--([a-z]+)(?:=(.*))?$/.exec(arg);
+    const name = match?.[1];
+    if (!match || !name || !VALUE_FLAGS.includes(name)) {
+      throw new ExportUsageError(`Unknown option: ${arg}. Run "stoaken export --help" for the options.`);
+    }
+    let value = match[2];
+    if (value === void 0) {
+      value = argv[i + 1];
+      i++;
+    }
+    if (value === void 0 || value.startsWith("--") && value !== "-") {
+      throw new ExportUsageError(`--${name} needs a value.`);
+    }
+    values[name] = value;
+  }
+  if (values.format !== void 0 && !isExportFormat(values.format)) {
+    throw new ExportUsageError(`Unknown format "${values.format}". Use one of: ${EXPORT_FORMATS.join(", ")}.`);
+  }
+  const hasTarget = ["theme", "format", "mode", "prefix", "release", "out"].some((k) => values[k] !== void 0);
+  return {
+    check,
+    server: values.server,
+    target: hasTarget ? {
+      theme: values.theme,
+      format: values.format ?? "css",
+      mode: values.mode,
+      prefix: values.prefix,
+      release: values.release,
+      out: values.out
+    } : null
+  };
+}
+function readSavedTargets(exportsValue) {
+  if (exportsValue === void 0 || exportsValue === null) return [];
+  if (!Array.isArray(exportsValue)) throw new ExportUsageError('"exports" in stoaken.config.json must be a list.');
+  return exportsValue.map((raw, i) => {
+    const where = `"exports" item ${i + 1} in stoaken.config.json`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new ExportUsageError(`${where} must be an object.`);
+    const item = raw;
+    for (const key of Object.keys(item)) {
+      if (!["theme", "format", "mode", "prefix", "release", "out"].includes(key)) {
+        throw new ExportUsageError(`${where} has an unknown field "${key}".`);
+      }
+      if (typeof item[key] !== "string" || item[key] === "") throw new ExportUsageError(`${where}: "${key}" must be text.`);
+    }
+    const format = item.format ?? "css";
+    if (!isExportFormat(format)) throw new ExportUsageError(`${where}: unknown format "${String(format)}". Use one of: ${EXPORT_FORMATS.join(", ")}.`);
+    return {
+      theme: item.theme,
+      format,
+      mode: item.mode,
+      prefix: item.prefix,
+      release: item.release,
+      out: item.out
+    };
+  });
+}
+function chooseTheme(themes, wanted, brandName, interactive) {
+  const names = themes.map((t) => t.name).join(", ");
+  if (themes.length === 0) throw new ExportUsageError(`${brandName} has no themes yet.`);
+  if (wanted !== void 0) {
+    const byId = themes.find((t) => t.id === wanted);
+    if (byId) return { kind: "theme", theme: byId };
+    const byName = themes.filter((t) => t.name.trim().toLowerCase() === wanted.trim().toLowerCase());
+    if (byName.length === 1) return { kind: "theme", theme: byName[0] };
+    if (byName.length > 1) throw new ExportUsageError(`More than one theme is called "${wanted}". Use its id instead.`);
+    throw new ExportUsageError(`${brandName} has no theme called "${wanted}". Themes: ${names}.`);
+  }
+  if (themes.length === 1) return { kind: "theme", theme: themes[0] };
+  if (interactive) return { kind: "ask", themes };
+  throw new ExportUsageError(`${brandName} has ${themes.length} themes, so name one with --theme. Themes: ${names}.`);
+}
+function filenameFrom(disposition, fallback) {
+  const match = disposition ? /filename="?([^";]+)"?/i.exec(disposition) : null;
+  const name = (match?.[1] ?? fallback).replace(/[/\\]/g, "-").replace(/^\.+/, "");
+  return name || fallback;
+}
+function problemMessage(problem, context) {
+  const what = context.themeName ? `"${context.themeName}"` : "this theme";
+  switch (problem.status) {
+    case 401:
+      return context.usingEnvToken ? "Stoaken didn't accept STOAKEN_TOKEN. Check it's a current API key (Settings > API keys)." : `Stoaken didn't accept your saved sign-in. Run "stoaken init" again, or set STOAKEN_TOKEN to an API key.`;
+    case 403:
+    case 404:
+      return `You can't see ${what}, or it doesn't exist. Check the Brand in stoaken.config.json and your access.`;
+    case 409:
+      return problem.detail ? `${context.themeName ? `"${context.themeName}": ` : ""}${problem.detail}` : `${context.themeName ? `"${context.themeName}" has` : "This has"} nothing to export yet: approve a release first.`;
+    case 400: {
+      const modes = problem.available_modes?.filter((m) => m !== "");
+      if (problem.available_modes && modes?.length === 0) return "This theme has no modes, so leave out --mode.";
+      const extra = modes?.length ? ` Modes: ${modes.join(", ")}.` : problem.available_formats?.length ? ` Formats: ${problem.available_formats.join(", ")}.` : "";
+      return `${problem.detail ?? problem.title ?? "Stoaken refused the request."}${extra}`;
+    }
+    case 429:
+      return "Too many requests. Wait a minute and try again.";
+    default:
+      return `Stoaken answered ${problem.status}${problem.detail ? `: ${problem.detail}` : problem.title ? `: ${problem.title}` : "."}`;
+  }
+}
+function formatBytes(n) {
+  return n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`;
+}
+
+// src/commands/export.ts
+var EXPORT_HELP = [
+  "stoaken export -- write your tokens as code",
+  "",
+  "Usage:",
+  "  stoaken export [options]",
+  "",
+  "Options:",
+  "  --theme <name|id>   Which theme (needed when the Brand has more than one)",
+  `  --format <format>   ${EXPORT_FORMATS.join(", ")} (default css)`,
+  "  --mode <key>        A mode combination for the one-mode formats, e.g. color-scheme:dark",
+  "  --prefix <prefix>   CSS only: a prefix for every variable name",
+  "  --release <id>      Export one release instead of the theme's live one",
+  "  --out <file|->      Where to write it (- for stdout); default: the server's file name",
+  "  --check             Write nothing; fail if the file on disk is out of date",
+  "  --server <url>      Override the server in stoaken.config.json",
+  "",
+  `With no options, every target in stoaken.config.json's "exports" list runs.`,
+  'Credentials: STOAKEN_TOKEN (an API key, for CI), else the sign-in from "stoaken init".'
+].join("\n");
+var say = (text) => process.stderr.write(`${text}
+`);
+async function runExport(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    say(EXPORT_HELP);
+    return 0;
+  }
+  const cwd = process.cwd();
+  try {
+    const args = parseExportArgs(argv);
+    const config = await readConfig(cwd);
+    if (!config) throw new ExportUsageError('No stoaken.config.json here. Run "stoaken init" in your project first.');
+    const serverUrl = args.server ?? config.serverUrl;
+    const envToken = process.env.STOAKEN_TOKEN?.trim();
+    const token = envToken || (await readCredentials(cwd))?.token;
+    if (!token) throw new ExportUsageError('No credentials. Run "stoaken init", or set STOAKEN_TOKEN to an API key.');
+    const targets = args.target ? [args.target] : readSavedTargets(config.exports);
+    if (targets.length === 0) targets.push({ format: "css" });
+    let themes = null;
+    let failed = 0;
+    for (const target of targets) {
+      let themeName;
+      try {
+        let themeId;
+        if (!target.release) {
+          themes ??= await listThemes(serverUrl, token, config.brandId);
+          const choice = chooseTheme(themes, target.theme, config.brandName, Boolean(process.stdin.isTTY && process.stderr.isTTY));
+          const theme = choice.kind === "theme" ? choice.theme : await askForTheme(choice.themes);
+          if (!theme) return 1;
+          themeId = theme.id;
+          themeName = theme.name;
+        }
+        await exportOne(serverUrl, token, target, { themeId, themeName }, args.check, cwd);
+      } catch (error) {
+        failed++;
+        say(`\u2716 ${describe(error, themeName, Boolean(envToken))}`);
+      }
+    }
+    return failed > 0 ? 1 : 0;
+  } catch (error) {
+    say(`\u2716 ${describe(error, void 0, Boolean(process.env.STOAKEN_TOKEN?.trim()))}`);
+    return 1;
+  }
+}
+async function askForTheme(themes) {
+  const choice = await p3.select({ message: "Which theme?", options: themes.map((t) => ({ value: t.id, label: t.name })) });
+  if (p3.isCancel(choice)) {
+    p3.cancel("Cancelled.");
+    return null;
+  }
+  return themes.find((t) => t.id === choice) ?? null;
+}
+async function exportOne(serverUrl, token, target, theme, check, cwd) {
+  const file = await fetchExport(serverUrl, token, {
+    themeId: theme.themeId,
+    releaseId: target.release,
+    format: target.format,
+    mode: target.mode,
+    prefix: target.prefix
+  });
+  const label = theme.themeName ?? `release ${target.release}`;
+  const warnings = file.warnings > 0 ? ` (${file.warnings} warning${file.warnings === 1 ? "" : "s"}: some values can't be written in this format)` : "";
+  if (target.out === "-") {
+    if (check) throw new ExportUsageError("--check needs a file to compare with, not --out -.");
+    process.stdout.write(file.text);
+    if (warnings) say(`! ${label}${warnings}`);
+    return;
+  }
+  const path = resolve(cwd, target.out ?? filenameFrom(file.filename, `tokens.${target.format}`));
+  const shown = relative(cwd, path) || path;
+  if (check) {
+    let current = null;
+    try {
+      current = await readFile2(path, "utf8");
+    } catch {
+    }
+    if (current !== file.text) {
+      throw new ExportUsageError(`${shown} is out of date with ${label}${current === null ? " (it doesn't exist)" : ""}. Run "stoaken export" and commit the result.`);
+    }
+    say(`\u2714 ${shown} is up to date with ${label}`);
+    return;
+  }
+  await mkdir2(dirname(path), { recursive: true });
+  await writeFile2(path, file.text, "utf8");
+  say(`\u2714 ${label} \u2192 ${shown} (${target.format}, ${formatBytes(Buffer.byteLength(file.text))})${warnings}`);
+}
+function describe(error, themeName, usingEnvToken) {
+  if (error instanceof ApiProblem) return problemMessage(error.problem, { themeName, usingEnvToken });
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/index.ts
 var [command, ...rest] = process.argv.slice(2);
 function flagValue(args, name) {
@@ -357,19 +687,23 @@ switch (command) {
   case "init":
     await runInit({ server: flagValue(rest, "server") });
     break;
+  case "export":
+    process.exitCode = await runExport(rest);
+    break;
   case void 0:
   case "--help":
   case "-h":
-    p3.log.message(
+    p4.log.message(
       [
         "stoaken -- Stoaken CLI",
         "",
         "Usage:",
-        "  stoaken init [--server <url>]   Authenticate, pick a Brand, and set up this project"
+        "  stoaken init [--server <url>]   Authenticate, pick a Brand, and set up this project",
+        "  stoaken export [options]        Write your tokens as code (stoaken export --help)"
       ].join("\n")
     );
     break;
   default:
-    p3.log.error(`Unknown command: ${command}`);
+    p4.log.error(`Unknown command: ${command}`);
     process.exitCode = 1;
 }

package/package.json

@@ -1,51 +1,51 @@
-{
-  "name": "stoaken",
-  "version": "0.1.0",
-  "description": "Stoaken CLI -- authenticate, pick a Brand, and get set up for MCP/API access in one command.",
-  "license": "UNLICENSED",
-  "type": "module",
-  "bin": {
-    "stoaken": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/craig-astravale/stoaken.git",
-    "directory": "cli"
-  },
-  "bugs": {
-    "url": "https://github.com/craig-astravale/stoaken/issues"
-  },
-  "homepage": "https://github.com/craig-astravale/stoaken/tree/main/cli#readme",
-  "keywords": [
-    "design-tokens",
-    "dtcg",
-    "mcp",
-    "model-context-protocol",
-    "cli",
-    "design-system"
-  ],
-  "author": "Stoaken",
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --clean --shims",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.8.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "open": "^11.0.2"
-  },
-  "devDependencies": {
-    "@types/node": "^26.5.0",
-    "tsup": "^8.5.1",
-    "tsx": "^4.23.13",
-    "typescript": "^7.0.2"
-  }
-}
+{
+  "name": "stoaken",
+  "version": "0.3.0",
+  "description": "Stoaken CLI -- set up a project for MCP/API access, and export your design tokens as code.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "stoaken": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/craig-astravale/stoaken.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/craig-astravale/stoaken/issues"
+  },
+  "homepage": "https://github.com/craig-astravale/stoaken/tree/main/cli#readme",
+  "keywords": [
+    "design-tokens",
+    "dtcg",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "design-system"
+  ],
+  "author": "Stoaken",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --shims",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "open": "^11.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  }
+}