cutsio 0.1.0 → 0.2.1

package/README.md

@@ -19,10 +19,13 @@ Create an **organization** API key in Cutsio: Settings → Organization → API
 ```bash
 cutsio login --url https://studio.cutsio.com --key ak_...
 cutsio whoami
+cutsio logout          # removes the stored key
+cutsio welcome         # replay the first-run banner
 ```
 
-Config is stored at `~/.cutsio/config.json` with mode `600`. You can also skip
-the config file entirely:
+On macOS the key goes into the **Keychain**; elsewhere it is written to
+`~/.cutsio/config.json` with mode `600`. You can also skip the config file
+entirely:
 
 ```bash
 export CUTSIO_API_URL=https://studio.cutsio.com
@@ -35,9 +38,13 @@ export CUTSIO_API_KEY=ak_...
 npm install
 npm run dev -- whoami      # runs src/index.ts directly (Node 23.6+)
 npm run typecheck
+npm test                   # selection, paths, and state
 npm run build              # bundles src -> dist/index.js
 ```
 
+Set `NO_COLOR=1` to disable color and `CUTSIO_NO_ANIM=1` to disable the
+first-run banner and live progress. Both are automatic when output is piped.
+
 ## List and select
 
 `sync` never downloads the whole workspace unless you ask for it. Start by

package/dist/index.js

@@ -1,23 +1,82 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
 import process2 from "node:process";
 
 // src/config.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+
+// src/secrets.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var SERVICE = "cutsio-cli";
+var ACCOUNT = "api-key";
+function keychainAvailable() {
+  return process.platform === "darwin";
+}
+async function getStoredKey() {
+  if (!keychainAvailable()) return null;
+  try {
+    const { stdout: stdout3 } = await run("security", [
+      "find-generic-password",
+      "-a",
+      ACCOUNT,
+      "-s",
+      SERVICE,
+      "-w"
+    ]);
+    const value = stdout3.trim();
+    return value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+async function setStoredKey(key) {
+  await run("security", [
+    "add-generic-password",
+    "-U",
+    "-a",
+    ACCOUNT,
+    "-s",
+    SERVICE,
+    "-w",
+    key
+  ]);
+}
+async function clearStoredKey() {
+  if (!keychainAvailable()) return;
+  try {
+    await run("security", ["delete-generic-password", "-a", ACCOUNT, "-s", SERVICE]);
+  } catch {
+  }
+}
+
+// src/config.ts
 var DEFAULT_API_URL = "https://studio.cutsio.com";
+function configDir() {
+  return join(homedir(), ".cutsio");
+}
 function configPath() {
-  return join(homedir(), ".cutsio", "config.json");
+  return join(configDir(), "config.json");
+}
+function keyStorageDescription() {
+  return keychainAvailable() ? "macOS Keychain" : `${configPath()} (mode 600)`;
 }
 function readConfig() {
   const path = configPath();
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof parsed.apiUrl !== "string" || typeof parsed.apiKey !== "string") return null;
-    return { apiUrl: parsed.apiUrl, apiKey: parsed.apiKey };
+    if (typeof parsed.apiUrl !== "string") return null;
+    return {
+      apiUrl: parsed.apiUrl,
+      ...typeof parsed.apiKey === "string" && parsed.apiKey.length > 0 ? { apiKey: parsed.apiKey } : {}
+    };
   } catch {
     return null;
   }
@@ -25,15 +84,48 @@ function readConfig() {
 function writeConfig(config) {
   const path = configPath();
   mkdirSync(dirname(path), { recursive: true, mode: 448 });
-  writeFileSync(path, JSON.stringify(config, null, 2), { mode: 384 });
+  const payload = config.apiKey ? { apiUrl: config.apiUrl, apiKey: config.apiKey } : { apiUrl: config.apiUrl };
+  writeFileSync(path, JSON.stringify(payload, null, 2), { mode: 384 });
   chmodSync(path, 384);
 }
 function resolveApiUrl(flag) {
   return flag || process.env.CUTSIO_API_URL || readConfig()?.apiUrl || DEFAULT_API_URL;
 }
-function resolveApiKey() {
-  const key = process.env.CUTSIO_API_KEY || readConfig()?.apiKey;
-  return key && key.length > 0 ? key : null;
+async function resolveApiKey() {
+  const fromEnv = process.env.CUTSIO_API_KEY;
+  if (fromEnv && fromEnv.length > 0) return { apiKey: fromEnv, migrated: false };
+  const stored = await getStoredKey();
+  if (stored) return { apiKey: stored, migrated: false };
+  const config = readConfig();
+  const legacy = config?.apiKey;
+  if (!legacy) return { apiKey: null, migrated: false };
+  if (keychainAvailable()) {
+    try {
+      await setStoredKey(legacy);
+      writeConfig({ apiUrl: config?.apiUrl ?? DEFAULT_API_URL });
+      return { apiKey: legacy, migrated: true };
+    } catch {
+    }
+  }
+  return { apiKey: legacy, migrated: false };
+}
+async function saveCredentials(apiUrl, apiKey) {
+  if (keychainAvailable()) {
+    await setStoredKey(apiKey);
+    writeConfig({ apiUrl });
+    return;
+  }
+  writeConfig({ apiUrl, apiKey });
+}
+async function clearCredentials() {
+  const stored = await getStoredKey();
+  const config = readConfig();
+  const hadFileKey = Boolean(config?.apiKey);
+  await clearStoredKey();
+  if (config) {
+    writeConfig({ apiUrl: config.apiUrl });
+  }
+  return Boolean(stored) || hadFileKey;
 }
 
 // src/core/client.ts
@@ -260,7 +352,8 @@ function resolveSelection(manifest, selection) {
 
 // src/commands/list.ts
 async function listCommand(flags) {
-  const apiKey = resolveApiKey();
+  const { apiKey, migrated } = await resolveApiKey();
+  if (migrated) console.error("Moved your API key into the macOS Keychain.");
   if (!apiKey) {
     console.error("No API key. Run `cutsio login` or set CUTSIO_API_KEY.");
     return 1;
@@ -358,10 +451,10 @@ async function loginCommand(flags) {
         console.error("That key is not attached to an organization. Create an organization API key.\n");
         continue;
       }
-      writeConfig({ apiUrl, apiKey });
+      await saveCredentials(apiUrl, apiKey);
       console.log(`
 Saved. Organization ${who.orgId}${who.name ? ` (key "${who.name}")` : ""}.`);
-      console.log(`Config: ${configPath()}
+      console.log(`Key stored in ${keyStorageDescription()}.
 `);
       console.log("Next:");
       console.log("  cutsio list");
@@ -449,6 +542,20 @@ async function promptSecret(question) {
   });
 }
 
+// src/commands/logout.ts
+async function logoutCommand() {
+  const hadCredentials = await clearCredentials();
+  if (!hadCredentials) {
+    console.log("No saved credentials.");
+  } else {
+    console.log(`Signed out. The API key was removed from ${keyStorageDescription()}.`);
+  }
+  if (process.env.CUTSIO_API_KEY) {
+    console.log("CUTSIO_API_KEY is still set in this shell \u2014 unset it to finish signing out.");
+  }
+  return 0;
+}
+
 // src/core/sync.ts
 import { existsSync as existsSync4, statSync as statSync2 } from "node:fs";
 import { join as join2 } from "node:path";
@@ -460,35 +567,54 @@ import { dirname as dirname2 } from "node:path";
 function partPathFor(destPath) {
   return `${destPath}.part`;
 }
-async function downloadResumable(url, destPath) {
+async function downloadResumable(url, destPath, onProgress) {
   mkdirSync2(dirname2(destPath), { recursive: true });
   const part = partPathFor(destPath);
   const resumedFrom = existsSync2(part) ? statSync(part).size : 0;
-  const { code, stderr } = await runCurl([
-    "-sS",
-    "--fail",
-    "--location",
-    "--retry",
-    "5",
-    "--retry-delay",
-    "2",
-    "--retry-all-errors",
-    "--connect-timeout",
-    "30",
-    "-C",
-    "-",
-    "-o",
-    part,
-    url
-  ]);
+  const total = await remoteSize(url);
+  let timer = null;
+  if (onProgress) {
+    onProgress(resumedFrom, total);
+    timer = setInterval(() => {
+      try {
+        onProgress(statSync(part).size, total);
+      } catch {
+      }
+    }, 200);
+  }
+  let code;
+  let stderr;
+  try {
+    ({ code, stderr } = await runCurl([
+      "-sS",
+      "--fail",
+      "--location",
+      "--retry",
+      "5",
+      "--retry-delay",
+      "2",
+      "--retry-all-errors",
+      "--connect-timeout",
+      "30",
+      "-C",
+      "-",
+      "-o",
+      part,
+      url
+    ]));
+  } finally {
+    if (timer) clearInterval(timer);
+  }
   if (code === 0) {
+    const bytes = statSync(part).size;
+    onProgress?.(bytes, total ?? bytes);
     renameSync(part, destPath);
     return { ok: true, bytes: statSync(destPath).size, resumedFrom };
   }
-  const remote = await remoteSize(url);
-  if (remote !== null && existsSync2(part) && statSync(part).size === remote) {
+  if (total !== null && existsSync2(part) && statSync(part).size === total) {
+    onProgress?.(total, total);
     renameSync(part, destPath);
-    return { ok: true, bytes: remote, resumedFrom };
+    return { ok: true, bytes: total, resumedFrom };
   }
   const lastLine = stderr.trim().split("\n").filter(Boolean).at(-1);
   return { ok: false, error: `curl exited ${code}${lastLine ? `: ${lastLine}` : ""}` };
@@ -664,6 +790,12 @@ async function sync(client, options) {
     }
     if (ready.length > 0) {
       prepareDelayMs = INITIAL_PREPARE_DELAY_MS;
+      onEvent({
+        type: "status",
+        preparing: Math.max(0, queue.size - ready.length),
+        downloading: ready.length,
+        queued: queue.size
+      });
       await runPool(ready, options.concurrency, async ({ id, url }) => {
         const item = queue.get(id);
         if (!item) return;
@@ -674,11 +806,12 @@ async function sync(client, options) {
           path: item.relPath,
           resuming: item.resuming
         });
-        let result = await downloadResumable(url, item.absPath);
+        const report = (bytes, total) => onEvent({ type: "file-progress", id, bytes, total });
+        let result = await downloadResumable(url, item.absPath, report);
         if (!result.ok) {
           const [refreshed] = await client.prepare([id]);
           if (refreshed?.status === "ready" && refreshed.url) {
-            result = await downloadResumable(refreshed.url, item.absPath);
+            result = await downloadResumable(refreshed.url, item.absPath, report);
           }
         }
         if (result.ok) {
@@ -699,6 +832,12 @@ async function sync(client, options) {
       });
     }
     if (queue.size === 0) break;
+    onEvent({
+      type: "status",
+      preparing: queue.size,
+      downloading: 0,
+      queued: queue.size
+    });
     if (Date.now() > deadline) {
       for (const item of queue.values()) {
         failed += 1;
@@ -735,6 +874,176 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/ui/format.ts
+function formatBytes(bytes) {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+// src/ui/theme.ts
+var colorEnabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+function paint(code) {
+  return colorEnabled ? (text) => `\x1B[${code}m${text}\x1B[0m` : (text) => text;
+}
+var color = {
+  dim: paint(2),
+  bold: paint(1),
+  red: paint(31),
+  green: paint(32),
+  yellow: paint(33),
+  blue: paint(34),
+  magenta: paint(35),
+  cyan: paint(36)
+};
+var isInteractive = colorEnabled;
+var animationsEnabled = colorEnabled && process.env.CUTSIO_NO_ANIM !== "1";
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/ui/progress.ts
+var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var BAR_WIDTH = 22;
+var ProgressView = class {
+  active = /* @__PURE__ */ new Map();
+  interactive = isInteractive;
+  statusLine = null;
+  renderedLines = 0;
+  frame = 0;
+  timer = null;
+  dirty = false;
+  constructor() {
+    if (!this.interactive) return;
+    this.timer = setInterval(() => {
+      if (this.active.size === 0) return;
+      this.frame += 1;
+      this.render();
+    }, 120);
+    this.timer.unref();
+  }
+  status(text) {
+    if (!this.interactive) return;
+    this.statusLine = text;
+    this.dirty = true;
+  }
+  /** Print a line above the live area without tearing it. */
+  log(message) {
+    if (!this.interactive) {
+      console.log(message);
+      return;
+    }
+    this.clear();
+    process.stdout.write(`${message}
+`);
+    this.render();
+  }
+  error(message) {
+    if (!this.interactive) {
+      console.error(message);
+      return;
+    }
+    this.clear();
+    process.stderr.write(`${message}
+`);
+    this.render();
+  }
+  start(id, label) {
+    if (!this.interactive) {
+      console.log(`  fetch   ${label}`);
+      return;
+    }
+    const now = Date.now();
+    this.active.set(id, {
+      label,
+      bytes: 0,
+      total: null,
+      lastBytes: 0,
+      lastAt: now,
+      speed: 0
+    });
+    this.dirty = true;
+    this.render();
+  }
+  progress(id, bytes, total) {
+    if (!this.interactive) return;
+    const item = this.active.get(id);
+    if (!item) return;
+    const now = Date.now();
+    const elapsed = (now - item.lastAt) / 1e3;
+    if (elapsed >= 0.3) {
+      const delta = bytes - item.lastBytes;
+      if (delta >= 0) item.speed = delta / elapsed;
+      item.lastBytes = bytes;
+      item.lastAt = now;
+    }
+    item.bytes = bytes;
+    if (total !== null) item.total = total;
+    this.dirty = true;
+  }
+  finish(id, ok, text) {
+    if (!this.interactive) {
+      if (ok) console.log(`  done    ${text}`);
+      else console.error(`  FAILED  ${text}`);
+      return;
+    }
+    this.clear();
+    const line = ok ? `  ${color.green("\u2713")} ${text}` : `  ${color.red("\u2717")} ${text}`;
+    (ok ? process.stdout : process.stderr).write(`${line}
+`);
+    this.active.delete(id);
+    this.render();
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    if (!this.interactive) return;
+    this.clear();
+    this.active.clear();
+    this.statusLine = null;
+  }
+  clear() {
+    if (this.renderedLines === 0) return;
+    process.stdout.write(`\x1B[${this.renderedLines}A\x1B[J`);
+    this.renderedLines = 0;
+  }
+  render() {
+    if (!this.interactive) return;
+    if (this.active.size === 0 && !this.statusLine) {
+      this.clear();
+      return;
+    }
+    const lines = [];
+    if (this.statusLine) {
+      const spinner = FRAMES[this.frame % FRAMES.length] ?? FRAMES[0];
+      lines.push(`  ${color.cyan(spinner ?? "")} ${color.dim(this.statusLine)}`);
+    }
+    for (const item of this.active.values()) {
+      lines.push(`    ${color.bold(item.label)}`);
+      lines.push(`    ${this.bar(item)}`);
+    }
+    this.clear();
+    process.stdout.write(`${lines.join("\n")}
+`);
+    this.renderedLines = lines.length;
+    this.dirty = false;
+  }
+  bar(item) {
+    const ratio = item.total && item.total > 0 ? Math.min(1, item.bytes / item.total) : null;
+    const filled = ratio === null ? 0 : Math.round(ratio * BAR_WIDTH);
+    const track = color.cyan("\u2588".repeat(filled)) + color.dim("\u2591".repeat(BAR_WIDTH - filled));
+    const percent = ratio === null ? "  ? " : `${Math.floor(ratio * 100)}%`.padStart(4);
+    const size = item.total ? `${formatBytes(item.bytes)} / ${formatBytes(item.total)}` : formatBytes(item.bytes);
+    const speed = item.speed > 0 ? `${formatBytes(item.speed)}/s` : "";
+    return `${track} ${percent}  ${size}  ${color.dim(speed)}`.trimEnd();
+  }
+};
+
 // src/commands/selection-prompt.ts
 import { stdin as stdin2, stdout as stdout2 } from "node:process";
 import { createInterface } from "node:readline/promises";
@@ -806,34 +1115,48 @@ async function promptSelection(manifest) {
 
 // src/commands/sync.ts
 async function syncCommand(flags) {
-  const apiKey = resolveApiKey();
+  const { apiKey, migrated } = await resolveApiKey();
+  if (migrated) console.error("Moved your API key into the macOS Keychain.");
   if (!apiKey) {
     console.error("No API key. Run `cutsio login` or set CUTSIO_API_KEY.");
     return 1;
   }
   const client = new CutsioClient(resolveApiUrl(flags.url), apiKey);
+  const view = new ProgressView();
   const onEvent = (event) => {
     switch (event.type) {
       case "manifest":
-        console.log(`Manifest: ${event.videos} videos, ${event.folders} folders (${event.orgId})`);
+        view.log(
+          `${color.dim("workspace")} ${event.orgId}  ${color.dim("\xB7")}  ${event.videos} videos  ${color.dim("\xB7")}  ${event.folders} folders`
+        );
         break;
       case "planned":
-        console.log(`Selected ${event.total}, pending ${event.pending}, unchanged ${event.unchanged}`);
+        view.log(
+          `${color.dim("selected")} ${event.total}  ${color.dim("\xB7")}  pending ${event.pending}  ${color.dim("\xB7")}  unchanged ${event.unchanged}`
+        );
+        break;
+      case "status":
+        view.status(
+          `${event.downloading} downloading \xB7 ${event.preparing} preparing \xB7 ${event.queued} remaining`
+        );
         break;
       case "file-start":
-        console.log(`  ${event.resuming ? "resume " : "fetch  "} ${event.path}`);
+        view.start(event.id, `${event.resuming ? "resuming " : ""}${event.path}`);
+        break;
+      case "file-progress":
+        view.progress(event.id, event.bytes, event.total);
         break;
       case "file-done":
-        console.log(`  done    ${event.path} (${formatBytes(event.bytes)})`);
+        view.finish(event.id, true, `${event.path} (${formatBytes(event.bytes)})`);
         break;
       case "file-skipped":
-        console.log(`  skip    ${event.title} \u2014 ${event.reason}`);
+        view.log(`  ${color.yellow("skip")}    ${event.title} \u2014 ${event.reason}`);
         break;
       case "file-failed":
-        console.error(`  FAILED  ${event.title} \u2014 ${event.error}`);
+        view.finish(event.id, false, `${event.title} \u2014 ${event.error}`);
         break;
       case "warning":
-        console.warn(`warning: ${event.message}`);
+        view.log(`  ${color.yellow("warning")} ${event.message}`);
         break;
     }
   };
@@ -848,6 +1171,7 @@ async function syncCommand(flags) {
   let manifest;
   try {
     if (flags.interactive === "true") {
+      view.stop();
       manifest = await client.fetchManifest();
       const prompted = await promptSelection(manifest);
       if (!prompted) {
@@ -878,12 +1202,14 @@ async function syncCommand(flags) {
       manifest,
       onEvent
     });
-    console.log(
-      `
-Downloaded ${summary.downloaded}, unchanged ${summary.unchanged}, skipped ${summary.skipped}, failed ${summary.failed}.`
-    );
-    return summary.failed > 0 ? 1 : 0;
+    view.stop();
+    const failing = summary.failed > 0;
+    const summaryLine = `${summary.downloaded} downloaded \xB7 ${summary.unchanged} unchanged \xB7 ${summary.skipped} skipped \xB7 ${summary.failed} failed`;
+    console.log(`
+${failing ? color.red(summaryLine) : color.green(summaryLine)}`);
+    return failing ? 1 : 0;
   } catch (error) {
+    view.stop();
     console.error(error instanceof Error ? error.message : String(error));
     return 1;
   }
@@ -906,20 +1232,49 @@ function positiveInt(value, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
 }
-function formatBytes(bytes) {
-  const units = ["B", "KB", "MB", "GB", "TB"];
-  let value = bytes;
-  let unit = 0;
-  while (value >= 1024 && unit < units.length - 1) {
-    value /= 1024;
-    unit += 1;
+
+// src/ui/banner.ts
+var WORDMARK = [
+  " \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 ",
+  "\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551   \u2588\u2588\u2551\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557",
+  "\u2588\u2588\u2551     \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551",
+  "\u2588\u2588\u2551     \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551   \u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551",
+  "\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D   \u2588\u2588\u2551   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D",
+  " \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D    \u255A\u2550\u255D   \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D "
+];
+var SHADES = [96, 96, 36, 36, 34, 34];
+function shade(line, index) {
+  if (!animationsEnabled) return line;
+  const code = SHADES[index] ?? 36;
+  return `\x1B[${code}m${line}\x1B[0m`;
+}
+async function revealBanner() {
+  process.stdout.write("\n");
+  for (let index = 0; index < WORDMARK.length; index += 1) {
+    process.stdout.write(`${shade(WORDMARK[index] ?? "", index)}
+`);
+    if (animationsEnabled) await sleep2(38);
   }
-  return `${value.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
+  process.stdout.write(`${color.dim("  mezzanine sync for your Mac")}
+
+`);
+  if (animationsEnabled) await sleep2(60);
+}
+
+// src/commands/welcome.ts
+async function welcomeCommand() {
+  await revealBanner();
+  console.log(`  ${color.dim("login")}    cutsio login`);
+  console.log(`  ${color.dim("browse")}   cutsio list`);
+  console.log(`  ${color.dim("sync")}     cutsio sync --out ~/Cutsio --interactive`);
+  console.log();
+  return 0;
 }
 
 // src/commands/whoami.ts
 async function whoamiCommand(flags) {
-  const apiKey = resolveApiKey();
+  const { apiKey, migrated } = await resolveApiKey();
+  if (migrated) console.error("Moved your API key into the macOS Keychain.");
   if (!apiKey) {
     console.error("No API key. Run `cutsio login` or set CUTSIO_API_KEY.");
     return 1;
@@ -964,6 +1319,8 @@ function printHelp() {
 
 Usage:
   cutsio login [--url URL] [--key KEY]
+  cutsio logout
+  cutsio welcome
   cutsio whoami [--url URL]
   cutsio list [--videos] [--search TERM] [--json] [--url URL]
   cutsio sync [--all | --folder REFS | --collection REFS | --video IDS | --search TERMS | --unfiled | --interactive]
@@ -977,14 +1334,41 @@ Selection:
 
 Environment:
   CUTSIO_API_URL   API base URL (default ${DEFAULT_API_URL})
-  CUTSIO_API_KEY   Organization API key`);
+  CUTSIO_API_KEY   Organization API key
+  NO_COLOR         Disable color
+  CUTSIO_NO_ANIM=1 Disable the banner and live progress`);
+}
+async function maybeWelcome() {
+  if (!animationsEnabled) return;
+  const marker = join3(configDir(), ".welcomed");
+  if (existsSync5(marker)) return;
+  await revealBanner();
+  try {
+    mkdirSync4(configDir(), { recursive: true, mode: 448 });
+    writeFileSync3(marker, "");
+  } catch {
+  }
 }
 async function main() {
   const [, , command, ...rest] = process2.argv;
   const flags = parseFlags(rest);
+  switch (command) {
+    case "login":
+    case "whoami":
+    case "list":
+    case "sync":
+      await maybeWelcome();
+      break;
+    default:
+      break;
+  }
   switch (command) {
     case "login":
       return loginCommand(flags);
+    case "logout":
+      return logoutCommand();
+    case "welcome":
+      return welcomeCommand();
     case "whoami":
       return whoamiCommand(flags);
     case "list":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cutsio",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Sync Cutsio mezzanine masters to a local folder",
   "type": "module",
   "bin": {
@@ -26,7 +26,8 @@
     "start": "node dist/index.js",
     "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "test": "node --test tests/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",