@thenewblack/cli 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @thenewblack/cli — `tnb`
+
+[The New Black AI](https://thenewblack.ai) from the command line: every fashion workflow of the studio (design, product-to-model, virtual try-on, fabric, sketch, video, HD), your creations, tech packs, publishing to Shopify and social accounts, and the account's AI agents. One command each, JSON out. Made for AI coding agents (Claude Code, Codex, Cursor…), scripts, crons and CI.
+
+```sh
+npx @thenewblack/cli --help          # nothing to install
+npm install -g @thenewblack/cli      # or keep it: `tnb`
+```
+
+Node 18.17 or newer. No dependencies.
+
+## The key
+
+```sh
+tnb login                     # opens your profile's API tab, asks for the key, keeps it (config dir, mode 600)
+export TNB_API_KEY=tnb_live_… # or: the environment wins — for a cron, a CI job, a container
+tnb whoami
+```
+
+Keys are created in your profile, API tab (up to three, each with scopes: `read`, `generate`, `publish`, `agents`). Without a key, `tnb workflows` and every `--help` still work.
+
+## Generate
+
+```sh
+tnb workflows                                  # every workflow, with prices — read live from the catalogue
+tnb generate virtual_try_on --help             # the flags of one workflow, read live
+tnb generate virtual_try_on \
+  --product_images dress.jpg belt.jpg --model_image model.jpg \
+  --seg_camera slightly_above --ratio 4:5 --tier pro \
+  --wait --out ./renders/
+# → {"generation_id":"…","status":"succeeded","workflow":"virtual_try_on","url":"https://…","type":"image","file":"renders/dress-virtual_try_on.webp"}
+```
+
+- Pictures are **local files or https urls**. A local file is uploaded once and remembered (path, size, date), so tomorrow's run re-uploads nothing.
+- `--wait` polls until the generation settles; `--out dir/` saves the result with a readable name (`<first input>-<workflow>.<ext>`), `--out file.webp` saves it there. Without `--wait`, the answer is the id and `tnb status <id> --wait` picks it up later.
+- Results live 48 hours on our url. Save them.
+- Credits are debited at submission and refunded on failure; `402 insufficient_credits` means the account needs topping up.
+- Text-only workflows take `--prompt`; guided ones take the catalogue's `--<field>` flags; video ones take `--duration` and, for some, `--end-image`.
+
+A folder, one line each:
+
+```sh
+for f in ./products/*.jpg; do tnb generate product_to_model --product_images "$f" --prompt "studio light, neutral background" --wait --out ./renders/; done
+```
+
+## Everything else
+
+```
+tnb credits · account · ledger · brand-dna [read <id>]
+tnb media [--project id] · elements · projects · upload <files…>
+tnb techpacks · techpack <id> · techpack pdf <id> · techpack rename <id> --name …
+tnb techpack add-section <id> --page <page_id> --kind bom [--at 0]
+tnb techpack write-section <id> <section_id> --data '<json>' | --data @file.json
+tnb techpack from-photos front.jpg [--back back.jpg] [--sketch front] [--size-range XS-XL] [--unit cm]
+tnb moodboards · moodboard pdf <id>
+tnb shopify products · shopify publish --product <id> --media <media_id>
+tnb publish accounts · publish --account <connection_id> --placement <placement> --media <media_id> [--caption …] · post <id>
+tnb agents · agent send <id> "message" [--media …] · agent thread <id> [--since …] · agent stop <id>
+tnb agent schedules <id> · agent schedule <id> "request" --kind single --date 2026-10-01 --time 09:30 · agent unschedule <id> <schedule_id>
+tnb files [--query …] · file <id|path> [--page 2] · file describe <id> --description "…"
+```
+
+`tnb <command> --help` prints the flags; `--pretty` indents the JSON. Exit codes: `0` done, `1` the platform or the network refused (the JSON error is on stderr, with the platform's own `code`), `2` the command line was wrong.
+
+## For an AI agent
+
+Install it, run `tnb --help`, then `tnb generate <key> --help` for the workflow you need — the help is the live contract. Read the JSON, keep the ids, save the files. The full API reference is at https://thenewblack.ai/clothing_fashion_api_integrations and the Claude skill at https://github.com/newblackai/claude-skill.
+
+## Configuration
+
+| Variable | Meaning |
+|---|---|
+| `TNB_API_KEY` | The key; wins over the one kept by `tnb login`. |
+| `TNB_API_URL` | The API base (default `https://thenewblack.ai/api/v1`). |
+| `TNB_CONFIG_DIR` | Where the key is kept (default `~/.config/tnb`, `%APPDATA%\tnb` on Windows). |
+| `TNB_CACHE_DIR` | Where uploaded files are remembered (default `~/.cache/tnb`). |
+
+MIT.

package/bin/tnb.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from "../lib/main.js";
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (e) => {
+    process.stderr.write(JSON.stringify({ error: { code: "cli_crash", message: e instanceof Error ? e.message : String(e) } }) + "\n");
+    process.exit(1);
+  },
+);

package/lib/api.js

@@ -0,0 +1,55 @@
+import { createRequire } from "node:module";
+import { BASE_URL, NO_KEY, apiKey } from "./config.js";
+
+const { version } = createRequire(import.meta.url)("../package.json");
+export const VERSION = version;
+
+/* ONE CALL, ONE SHAPE (2026-09-12). Every command goes through here:
+   the bearer key, the client header the platform counts doors by, the
+   JSON body, and the platform's own { error: { code, message } } handed
+   back as a thrown ApiError so the command prints it and exits 1. The
+   CLI never invents an error the API did not say. */
+
+export class ApiError extends Error {
+  constructor(code, message, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+export async function call(method, path, { body, form, query, headers: extra, auth = true } = {}) {
+  const url = new URL(BASE_URL + path);
+  for (const [k, v] of Object.entries(query ?? {})) if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+  const headers = { accept: "application/json", "user-agent": `tnb-cli/${VERSION}`, "x-tnb-client": "cli", ...(extra ?? {}) };
+  if (auth) {
+    const k = await apiKey();
+    if (!k) throw new ApiError(NO_KEY.code, NO_KEY.message, 0);
+    headers.authorization = `Bearer ${k.key}`;
+  }
+  let payload;
+  if (form) payload = form;
+  else if (body !== undefined) { headers["content-type"] = "application/json"; payload = JSON.stringify(body); }
+  let res;
+  try {
+    res = await fetch(url, { method, headers, body: payload });
+  } catch (e) {
+    throw new ApiError("network", `Could not reach ${url.host}: ${e instanceof Error ? e.message : String(e)}`, 0);
+  }
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text.slice(0, 400) }; }
+  if (!res.ok) {
+    const err = data && typeof data === "object" && data.error;
+    if (err && typeof err === "object") throw new ApiError(err.code ?? `http_${res.status}`, err.message ?? `HTTP ${res.status}`, res.status, err.details);
+    throw new ApiError(`http_${res.status}`, typeof err === "string" ? err : `HTTP ${res.status} from ${path}`, res.status);
+  }
+  return data;
+}
+
+export const get = (path, query) => call("GET", path, { query });
+export const post = (path, body) => call("POST", path, { body });
+export const patch = (path, body) => call("PATCH", path, { body });
+export const put = (path, body) => call("PUT", path, { body });
+export const del = (path) => call("DELETE", path);

package/lib/args.js

@@ -0,0 +1,59 @@
+/* THE COMMAND LINE, READ ONCE (2026-09-12).
+ *
+ *   tnb <words…> [positionals…] [--flag value] [--flag=value] [--switch] [--no-switch]
+ *
+ * A flag given twice becomes a list — that is how a multiple image slot
+ * takes several files: `--product_images a.jpg --product_images b.jpg`,
+ * or in one go: `--product_images a.jpg b.jpg` (values keep attaching to
+ * the last flag until the next `--`). Dashes and underscores are the
+ * same flag: `--model-image` and `--model_image` both name the
+ * catalogue's `model_image`. `--` ends the flags. No dependency: the
+ * whole CLI must install in a second with `npx`. */
+
+/**
+ * @param {string[]} argv
+ * @returns {{ positionals: string[], flags: Record<string, any> }}
+ */
+export function parse(argv) {
+  /** @type {string[]} */
+  const positionals = [];
+  /** @type {Record<string, any>} */
+  const flags = {};
+  let last = null;
+  let raw = false;
+  const push = (name, value) => {
+    const k = name.replace(/-/g, "_");
+    if (k in flags) flags[k] = Array.isArray(flags[k]) ? [...flags[k], value] : [flags[k], value];
+    else flags[k] = value;
+  };
+  for (const a of argv) {
+    if (raw) { positionals.push(a); continue; }
+    if (a === "--") { raw = true; last = null; continue; }
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq > 0) { push(a.slice(2, eq), a.slice(eq + 1)); last = null; continue; }
+      const name = a.slice(2);
+      if (name.startsWith("no-") || name.startsWith("no_")) { push(name.slice(3), false); last = null; continue; }
+      push(name, true);
+      last = name;
+      continue;
+    }
+    if (a === "-h") { push("help", true); last = null; continue; }
+    if (last) {
+      /* The value of the last flag: `true` was a placeholder. */
+      const k = last.replace(/-/g, "_");
+      if (flags[k] === true) flags[k] = a;
+      else if (Array.isArray(flags[k]) && flags[k][flags[k].length - 1] === true) flags[k][flags[k].length - 1] = a;
+      else push(last, a);
+      continue;
+    }
+    positionals.push(a);
+  }
+  return { positionals, flags };
+}
+
+/** One value or undefined, never a list. */
+export const one = (v) => (Array.isArray(v) ? v[v.length - 1] : v);
+
+/** A list, possibly empty; `true` (a flag with no value) counts as nothing. */
+export const many = (v) => (v === undefined || v === true ? [] : Array.isArray(v) ? v.filter((x) => x !== true) : [v]);

package/lib/catalog.js

@@ -0,0 +1,44 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { call } from "./api.js";
+
+/* THE CATALOGUE, READ LIVE (owner, 2026-09-12: "un workflow ajouté hier
+   est dans l'aide aujourd'hui, sans version nouvelle"). Public, no key.
+   Cached five minutes in the temp directory — the platform's own CDN
+   cadence — so `tnb workflows` twice in a row costs one request. */
+
+const TTL_MS = 5 * 60 * 1000;
+const cacheFile = () => path.join(os.tmpdir(), `tnb-catalog-${process.getuid?.() ?? "u"}.json`);
+
+export async function catalog({ fresh = false } = {}) {
+  if (!fresh) {
+    try {
+      const st = await fs.stat(cacheFile());
+      if (Date.now() - st.mtimeMs < TTL_MS) return JSON.parse(await fs.readFile(cacheFile(), "utf8"));
+    } catch { /* no cache, or stale */ }
+  }
+  const data = await call("GET", "/catalog", { auth: false });
+  try { await fs.writeFile(cacheFile(), JSON.stringify(data)); } catch { /* the cache is a convenience */ }
+  return data;
+}
+
+/** A workflow by key, or by its versioned endpoint name. */
+export async function workflow(name) {
+  const c = await catalog();
+  const want = String(name ?? "").trim();
+  return c.workflows.find((w) => w.key === want || w.endpoint === want) ?? null;
+}
+
+/** The short line of a workflow, for lists. */
+export const line = (w) => ({
+  key: w.key,
+  title: w.title,
+  mode: w.mode,
+  credits: w.credits,
+  prompt: w.takes_prompt,
+  images: w.images.map((i) => i.param + (i.required ? "" : "?") + (i.multiple ? `[${i.max}]` : "")),
+  fields: w.fields.map((f) => f.name),
+  ...(w.variants.length ? { variants: w.variants } : {}),
+  ...(w.requires_plan ? { plan: "required" } : {}),
+});

package/lib/config.js

@@ -0,0 +1,45 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/* WHERE THE KEY LIVES (2026-09-12). `TNB_API_KEY` in the environment
+   wins — a cron, a CI job, a container set it once and never write a
+   file. Otherwise `tnb login` keeps it in the user's config directory,
+   mode 600, like every CLI that holds a token. Never in the project
+   folder, never in a shell history if `tnb login` asked for it. */
+
+export const BASE_URL = (process.env.TNB_API_URL || "https://thenewblack.ai/api/v1").replace(/\/$/, "");
+export const SITE_URL = process.env.TNB_SITE_URL || (BASE_URL.endsWith("/api/v1") ? BASE_URL.slice(0, -"/api/v1".length) : "https://thenewblack.ai");
+export const KEYS_PAGE = `${SITE_URL}/profile?tab=api`;
+
+export function configDir() {
+  if (process.env.TNB_CONFIG_DIR) return process.env.TNB_CONFIG_DIR;
+  if (process.platform === "win32") return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "tnb");
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "tnb");
+}
+const configFile = () => path.join(configDir(), "config.json");
+
+export async function readConfig() {
+  try {
+    return JSON.parse(await fs.readFile(configFile(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export async function writeConfig(cfg) {
+  await fs.mkdir(configDir(), { recursive: true, mode: 0o700 });
+  await fs.writeFile(configFile(), JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  return configFile();
+}
+
+/** The key to use, or null. Says where it came from so `whoami` can tell. */
+export async function apiKey() {
+  const env = (process.env.TNB_API_KEY || "").trim();
+  if (env) return { key: env, from: "TNB_API_KEY" };
+  const cfg = await readConfig();
+  if (typeof cfg.api_key === "string" && cfg.api_key) return { key: cfg.api_key, from: configFile() };
+  return null;
+}
+
+export const NO_KEY = { code: "no_api_key", message: `No API key. Run \`tnb login\` or set TNB_API_KEY. Your key is in your profile, API tab: ${KEYS_PAGE}` };

package/lib/generate.js

@@ -0,0 +1,141 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { get, post } from "./api.js";
+import { many, one } from "./args.js";
+import { resolveImage } from "./upload.js";
+import { UsageError } from "./output.js";
+
+/* ONE COMMAND PER WORKFLOW, GENERATED FROM THE CONTRACT (owner +
+   Strategy, 2026-09-12): `tnb generate <key> --<image_param> file|url …
+   --<field> value … --prompt … --ratio --tier --variant --duration
+   --end-image --webhook --wait --out`. The flags are the catalogue's own
+   names, read at call time; nothing here knows a workflow by heart. The
+   platform validates the call again before any credit moves, with the
+   same words. */
+
+const COMMON = new Set(["prompt", "ratio", "tier", "variant", "duration", "end_image", "webhook", "webhook_url", "wait", "out", "project", "pretty", "help", "timeout", "json"]);
+
+/** The flags a workflow accepts, for the help and for the refusal of a typo. */
+export function flagsOf(w) {
+  const list = [];
+  for (const i of w.images) list.push({ flag: `--${i.param}`, value: i.multiple ? `<file|url> ×${i.max}` : "<file|url>", required: i.required, help: i.label });
+  if (w.end_image) list.push({ flag: "--end-image", value: "<file|url>", required: false, help: "the last frame" });
+  if (w.takes_prompt) list.push({ flag: "--prompt", value: "<text>", required: w.images.every((i) => !i.required), help: w.fields.length ? "the subject's description" : "what to make" });
+  for (const f of w.fields) list.push({ flag: `--${f.name}`, value: f.options?.length ? f.options.join("|") : "<text>", required: !!f.required, help: f.hint ?? f.label });
+  if (w.variants.length) list.push({ flag: "--variant", value: w.variants.map((v) => JSON.stringify(v)).join("|"), required: false, help: "which variant" });
+  if (w.ratios.length) list.push({ flag: "--ratio", value: w.ratios.join("|"), required: false, help: w.mode === "image" ? "portrait 9:16 when nothing is given and no reference" : "the format" });
+  if (w.durations.length) list.push({ flag: "--duration", value: w.durations.join("|"), required: false, help: "seconds" });
+  list.push({ flag: "--tier", value: "standard|pro", required: false, help: `credits ${w.credits.standard} / ${w.credits.pro} ${w.credits.unit}` });
+  list.push({ flag: "--project", value: "<id>", required: false, help: "file the uploads under this project" });
+  list.push({ flag: "--webhook", value: "<url>", required: false, help: "called when the generation settles" });
+  list.push({ flag: "--wait", value: "", required: false, help: "wait for the result and print its url" });
+  list.push({ flag: "--out", value: "<file|dir/>", required: false, help: "with --wait: save the result there (readable name in a dir)" });
+  return list;
+}
+
+/**
+ * The body of POST /generate from the flags — pure, given an image resolver.
+ * @param {any} w the workflow's contract from the catalogue
+ * @param {Record<string, any>} flags
+ * @param {(v: string, opts: { project?: string }) => Promise<{ url: string, file?: string }>} resolve
+ * @returns {Promise<{ body: Record<string, any>, inputs: string[] }>}
+ */
+export async function buildBody(w, flags, resolve) {
+  const known = new Set([...w.images.map((i) => i.param), ...w.fields.map((f) => f.name), ...COMMON]);
+  const unknown = Object.keys(flags).filter((k) => !known.has(k));
+  if (unknown.length) throw new UsageError(`Unknown flag${unknown.length > 1 ? "s" : ""} for ${w.key}: ${unknown.map((k) => `--${k}`).join(", ")}. Run \`tnb generate ${w.key} --help\`.`);
+  /** @type {Record<string, any>} */
+  const body = { workflow: w.endpoint };
+  const inputs = [];
+  const project = one(flags.project);
+  for (const i of w.images) {
+    const vals = many(flags[i.param]);
+    if (!vals.length) { if (i.required) throw new UsageError(`--${i.param} is required (${i.label}).`); continue; }
+    if (!i.multiple && vals.length > 1) throw new UsageError(`--${i.param} takes one picture.`);
+    if (vals.length > i.max) throw new UsageError(`--${i.param} takes ${i.max} pictures at most.`);
+    const urls = [];
+    for (const v of vals) { const r = await resolve(v, { project }); urls.push(r.url); if (r.file) inputs.push(r.file); }
+    body[i.param] = i.multiple ? urls : urls[0];
+  }
+  if (w.end_image && flags.end_image !== undefined) { const r = await resolve(one(flags.end_image), { project }); body.end_image = r.url; }
+  const prompt = one(flags.prompt);
+  if (typeof prompt === "string" && prompt.trim()) {
+    if (!w.takes_prompt) throw new UsageError(`${w.key} takes no prompt.`);
+    body.prompt = prompt.trim();
+  } else if (w.takes_prompt && !w.images.some((i) => body[i.param])) throw new UsageError(`--prompt is required for ${w.key}.`);
+  const fields = {};
+  for (const f of w.fields) {
+    const v = one(flags[f.name]);
+    if (v === undefined || v === true) { if (f.required) throw new UsageError(`--${f.name} is required (${f.label}).`); continue; }
+    if (f.options?.length && !f.options.includes(String(v))) throw new UsageError(`--${f.name} must be one of ${f.options.join(", ")}.`);
+    fields[f.name] = String(v);
+  }
+  if (Object.keys(fields).length) body.fields = fields;
+  for (const k of ["ratio", "tier", "variant", "duration"]) { const v = one(flags[k]); if (typeof v === "string" && v) body[k] = v; }
+  if (body.ratio && w.ratios.length && !w.ratios.includes(body.ratio)) throw new UsageError(`--ratio must be one of ${w.ratios.join(", ")}.`);
+  if (body.duration && w.durations.length && !w.durations.includes(String(body.duration))) throw new UsageError(`--duration must be one of ${w.durations.join(", ")}.`);
+  if (body.tier && !["standard", "pro"].includes(body.tier)) throw new UsageError("--tier is standard or pro.");
+  const hook = one(flags.webhook) ?? one(flags.webhook_url);
+  if (typeof hook === "string" && hook) body.webhook_url = hook;
+  return { body, inputs };
+}
+
+/** Poll a generation until it settles. */
+export async function waitFor(id, { timeoutMs = 10 * 60 * 1000, everyMs = 3000 } = {}) {
+  const started = Date.now();
+  for (;;) {
+    const g = await get(`/generations/${id}`);
+    if (g.status === "succeeded" || g.status === "failed" || g.status === "canceled") return g;
+    if (Date.now() - started > timeoutMs) return { ...g, status: g.status, timed_out: true };
+    await new Promise((r) => setTimeout(r, everyMs));
+  }
+}
+
+const extOf = (url, type) => {
+  const m = /\.(webp|png|jpe?g|mp4|webm|gif|svg|glb)(?:$|\?)/i.exec(url);
+  return m ? m[1].toLowerCase() : type === "video" ? "mp4" : "webp";
+};
+
+/** Save a result url under `out` — a file path, or a directory (readable name from the first input). */
+export async function download(url, out, { inputs = [], workflow = "result", id = "" }, type) {
+  const res = await fetch(url);
+  if (!res.ok) throw Object.assign(new Error(`Could not download the result (${res.status}).`), { code: "download_failed" });
+  const bytes = Buffer.from(await res.arrayBuffer());
+  let target = out;
+  const isDir = out.endsWith("/") || out.endsWith(path.sep) || (await fs.stat(out).then((s) => s.isDirectory()).catch(() => false));
+  if (isDir) {
+    const base = inputs[0] ? path.basename(inputs[0], path.extname(inputs[0])) : id.slice(0, 8);
+    target = path.join(out, `${base}-${workflow}.${extOf(url, type)}`);
+    let n = 1;
+    while (await fs.stat(target).then(() => true).catch(() => false)) target = path.join(out, `${base}-${workflow}-${++n}.${extOf(url, type)}`);
+  }
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, bytes);
+  return target;
+}
+
+/** The whole gesture: build, submit, optionally wait and save. */
+export async function generate(w, flags) {
+  const { body, inputs } = await buildBody(w, flags, resolveImage);
+  const started = await post("/generate", body);
+  const out = { generation_id: started.generation_id, status: started.status, workflow: w.key };
+  if (!flags.wait && !flags.out) return { ...out, poll: `tnb status ${started.generation_id} --wait` };
+  const timeout = Number(one(flags.timeout));
+  const g = await waitFor(started.generation_id, { timeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout * 1000 : undefined, everyMs: w.mode === "video" ? 5000 : 3000 });
+  return settle(g, { inputs, workflow: w.key, out: one(flags.out) });
+}
+
+/** Turn a settled generation into the short answer, saving the file if asked. */
+export async function settle(g, { inputs = [], workflow, out }) {
+  const answer = { generation_id: g.generation_id, status: g.status, workflow: g.workflow ?? workflow };
+  if (g.status === "succeeded" && g.result?.url) {
+    answer.url = g.result.url;
+    answer.type = g.result.type;
+    if (typeof out === "string" && out) answer.file = await download(g.result.url, out, { inputs, workflow: answer.workflow, id: g.generation_id }, g.result.type);
+  } else if (g.status === "failed") {
+    answer.error = g.error ?? { code: "failed", message: "The generation failed — the credits were refunded." };
+  } else if (g.timed_out) {
+    answer.note = "still running; check later with `tnb status <id> --wait`";
+  }
+  return answer;
+}

package/lib/help.js

@@ -0,0 +1,57 @@
+import { VERSION } from "./api.js";
+import { ROUTES } from "./routes.js";
+import { flagsOf } from "./generate.js";
+
+/* THE HELP, HALF WRITTEN HERE, HALF READ LIVE. What never changes is
+   below; what a workflow takes comes from the catalogue at the moment
+   of the call (`tnb generate <key> --help`). Text for a person, on
+   stderr, so a `--help` never pollutes a JSON pipe. */
+
+export function general() {
+  const lines = [
+    `tnb ${VERSION} — The New Black AI from the command line. JSON out; --pretty to indent.`,
+    "",
+    "  tnb login [--key tnb_live_…]        keep your API key (or set TNB_API_KEY)",
+    "  tnb logout                          forget it",
+    "  tnb whoami                          which account, which key",
+    "",
+    "  tnb workflows [--fresh]             every workflow of the studio, with prices",
+    "  tnb workflows <key>                 one workflow's contract",
+    "  tnb generate <key> --help           the flags of one workflow, read live",
+    "  tnb generate <key> [--<image> file|url …] [--<field> value …] [--prompt …] [--wait] [--out dir/]",
+    "  tnb status <generation_id> [--wait] [--out dir/]",
+    "  tnb upload <file…> [--project id]   pictures → urls and media ids",
+    "",
+  ];
+  const width = Math.max(...ROUTES.map((r) => r.words.join(" ").length + (r.args ?? []).map((a) => ` <${a}>`).join("").length)) + 2;
+  for (const r of ROUTES) {
+    if (r.special === "status" || r.special === "upload") continue;
+    const left = (r.words.join(" ") + (r.args ?? []).map((a) => ` <${a}>`).join("")).padEnd(width);
+    lines.push(`  tnb ${left}${r.help}`);
+  }
+  lines.push("", "Keys: https://thenewblack.ai/profile?tab=api · Docs: https://thenewblack.ai/clothing_fashion_api_integrations");
+  return lines.join("\n");
+}
+
+export function forRoute(r) {
+  const flags = Object.entries(r.flags ?? {}).map(([k, s]) => `--${k.replace(/_/g, "-")}${/!/.test(s) ? " (required)" : ""}`);
+  return [
+    `tnb ${r.words.join(" ")}${(r.args ?? []).map((a) => ` <${a}>`).join("")}${flags.length ? " " + flags.join(" ") : ""}`,
+    `  ${r.help}`,
+    `  ${r.method} ${r.path} · scope ${r.scope}`,
+  ].join("\n");
+}
+
+export function forWorkflow(w) {
+  const flags = flagsOf(w);
+  const width = Math.max(...flags.map((f) => `${f.flag} ${f.value}`.length)) + 2;
+  return [
+    `tnb generate ${w.key} — ${w.title} (${w.mode}; ${w.credits.standard} / ${w.credits.pro} credits ${w.credits.unit})`,
+    w.description ? `  ${w.description}` : null,
+    "",
+    ...flags.map((f) => `  ${`${f.flag} ${f.value}`.padEnd(width)}${f.required ? "required — " : ""}${f.help}`),
+    "",
+    "  Pictures are local files (uploaded once) or https urls. Results live 48 hours on our url: --out saves the file.",
+    `  Docs: https://thenewblack.ai/clothing_fashion_api_integrations`,
+  ].filter((l) => l !== null).join("\n");
+}

package/lib/main.js

@@ -0,0 +1,205 @@
+import { promises as fs } from "node:fs";
+import readline from "node:readline";
+import { spawn } from "node:child_process";
+import { parse, one, many } from "./args.js";
+import { ApiError, VERSION, call, get } from "./api.js";
+import { KEYS_PAGE, apiKey, readConfig, writeConfig } from "./config.js";
+import { catalog, line, workflow } from "./catalog.js";
+import { generate, settle, waitFor } from "./generate.js";
+import { ROUTES, match, spec } from "./routes.js";
+import { general, forRoute, forWorkflow } from "./help.js";
+import { UsageError, print, printError, say, setPretty } from "./output.js";
+import { resolveImage, uploadFile } from "./upload.js";
+
+/* THE DISPATCH. Three kinds of command: the key (login, logout, whoami),
+   the workflows (generate, workflows — from the catalogue), and the
+   fixed routes (the table in routes.js). Exit codes: 0 done, 1 refused
+   by the platform or the network, 2 the command line was wrong. */
+
+export async function main(argv) {
+  const { positionals, flags } = parse(argv);
+  setPretty(!!flags.pretty);
+  try {
+    if (flags.version || positionals[0] === "version") { print({ tnb: VERSION }); return 0; }
+    const [cmd] = positionals;
+    if (!cmd || cmd === "help") { say(general()); return flags.help || cmd === "help" ? 0 : 2; }
+    if (cmd === "login") return await login(flags);
+    if (cmd === "logout") return await logout();
+    if (cmd === "whoami") return await whoami();
+    if (cmd === "workflows") return await workflows(positionals[1], flags);
+    if (cmd === "generate") return await runGenerate(positionals[1], flags);
+    const route = match(positionals);
+    if (!route) throw new UsageError(`Unknown command "${positionals.join(" ")}". Run \`tnb --help\`.`);
+    if (flags.help) { say(forRoute(route)); return 0; }
+    const rest = positionals.slice(route.words.length);
+    if (route.special === "status") return await status(rest[0], flags);
+    if (route.special === "upload") return await upload(rest, flags);
+    if (route.special === "from-photos") return await fromPhotos(rest, flags);
+    return await runRoute(route, rest, flags);
+  } catch (e) {
+    if (e instanceof UsageError) { printError("usage", e.message); return 2; }
+    if (e instanceof ApiError) { printError(e.code, e.message, e.details ? { details: e.details } : undefined); return 1; }
+    if (e && typeof e === "object" && "code" in e && typeof e.message === "string") { printError(String(e.code), e.message); return 1; }
+    throw e;
+  }
+}
+
+/* ── the key ─────────────────────────────────────────────────────── */
+
+async function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); return true; } catch { return false; }
+}
+
+async function login(flags) {
+  let key = one(flags.key);
+  if (typeof key !== "string" || !key) {
+    if (flags.browser !== false && process.stdin.isTTY) {
+      say(`Your API key is in your profile, API tab: ${KEYS_PAGE}`);
+      if (!openBrowser(KEYS_PAGE)) say("(open that address in a browser)");
+    } else say(`Your API key is in your profile, API tab: ${KEYS_PAGE}`);
+    if (!process.stdin.isTTY) throw new UsageError("No terminal to ask for the key: run `tnb login --key tnb_live_…` or set TNB_API_KEY.");
+    key = await ask("Paste the key (tnb_live_…): ");
+  }
+  if (!/^tnb_/.test(key)) throw new UsageError("That does not look like a key: it starts with tnb_live_.");
+  print(await verifyAndSave(key));
+  return 0;
+}
+
+/* Verified before it is kept: a mistyped key would fail at the first
+   real command, later, elsewhere. */
+async function verifyAndSave(key) {
+  const before = process.env.TNB_API_KEY;
+  process.env.TNB_API_KEY = key;
+  let c;
+  try { c = await get("/credits"); } finally { if (before === undefined) delete process.env.TNB_API_KEY; else process.env.TNB_API_KEY = before; }
+  const cfg = await readConfig();
+  const file = await writeConfig({ ...cfg, api_key: key });
+  return { ok: true, credits: c.credits, saved_to: file };
+}
+
+async function logout() {
+  const cfg = await readConfig();
+  delete cfg.api_key;
+  const file = await writeConfig(cfg);
+  print({ ok: true, cleared: file });
+  return 0;
+}
+
+async function whoami() {
+  const k = await apiKey();
+  if (!k) { print({ logged_in: false, hint: "tnb login, or TNB_API_KEY" }); return 1; }
+  const a = await get("/account");
+  print({ logged_in: true, key_from: k.from, key_prefix: k.key.slice(0, 14), account: a.id, username: a.username, credits: a.credits, team: a.team?.role });
+  return 0;
+}
+
+/* ── the workflows ───────────────────────────────────────────────── */
+
+async function workflows(key, flags) {
+  if (key) {
+    const w = await workflow(key);
+    if (!w) throw new UsageError(`No workflow "${key}". Run \`tnb workflows\`.`);
+    if (flags.help) { say(forWorkflow(w)); return 0; }
+    print(w);
+    return 0;
+  }
+  const c = await catalog({ fresh: !!flags.fresh });
+  print({ count: c.workflows.length, workflows: c.workflows.map(line) });
+  return 0;
+}
+
+async function runGenerate(key, flags) {
+  if (!key) {
+    const c = await catalog();
+    say(`tnb generate <key> [flags] — one of:\n${c.workflows.map((w) => `  ${w.key.padEnd(34)}${w.title}`).join("\n")}\n\ntnb generate <key> --help shows the flags of one.`);
+    return 2;
+  }
+  const w = await workflow(key);
+  if (!w) throw new UsageError(`No workflow "${key}". Run \`tnb workflows\`.`);
+  if (flags.help) { say(forWorkflow(w)); return 0; }
+  const answer = await generate(w, flags);
+  print(answer);
+  return answer.status === "failed" ? 1 : 0;
+}
+
+async function status(id, flags) {
+  if (!id) throw new UsageError("tnb status <generation_id> [--wait] [--out dir/]");
+  const g = flags.wait || flags.out ? await waitFor(id) : await get(`/generations/${id}`);
+  const answer = await settle(g, { out: one(flags.out) });
+  print(answer);
+  return answer.status === "failed" ? 1 : 0;
+}
+
+async function upload(files, flags) {
+  if (!files.length) throw new UsageError("tnb upload <file…> [--project <id>]");
+  const project = one(flags.project);
+  const out = [];
+  for (const f of files) { const u = await uploadFile(f, { project }); out.push({ file: f, media_id: u.media_id, url: u.url, ...(u.cached ? { cached: true } : {}) }); }
+  print(files.length === 1 ? out[0] : { uploads: out });
+  return 0;
+}
+
+async function fromPhotos(files, flags) {
+  const project = one(flags.project);
+  const images = [];
+  for (const f of files) images.push((await resolveImage(f, { project })).url);
+  if (!images.length) throw new UsageError("tnb techpack from-photos <front.jpg> [more.jpg …] [--back back.jpg] [--sketch none|front|front_back] [--size-range XS-XL] [--unit cm|in] [--description …] [--product …] [--project <id>]");
+  const body = { images };
+  const back = one(flags.back);
+  if (typeof back === "string" && back) body.back = (await resolveImage(back, { project })).url;
+  for (const k of ["description", "product", "size_range", "unit", "sketch"]) { const v = one(flags[k]); if (typeof v === "string" && v) body[k] = v; }
+  if (typeof project === "string" && project) body.project_id = project;
+  const r = await call("POST", "/techpacks/from-photos", { body });
+  print(r);
+  return 0;
+}
+
+/* ── the fixed routes ────────────────────────────────────────────── */
+
+async function jsonArg(v) {
+  const s = String(v);
+  const text = s.startsWith("@") ? await fs.readFile(s.slice(1), "utf8") : s;
+  try { return JSON.parse(text); } catch { throw new UsageError(`Not JSON: ${s.slice(0, 60)}${s.length > 60 ? "…" : ""}`); }
+}
+
+export async function runRoute(route, rest, flags) {
+  const args = route.args ?? [];
+  if (rest.length < args.length) throw new UsageError(`tnb ${route.words.join(" ")}${args.map((a) => ` <${a}>`).join("")} — missing ${args.slice(rest.length).map((a) => `<${a}>`).join(", ")}.`);
+  let path = route.path;
+  const body = {};
+  const query = {};
+  const headers = {};
+  args.forEach((a, i) => { if (path.includes(`{${a}}`)) path = path.replace(`{${a}}`, encodeURIComponent(rest[i])); else body[a] = rest[i]; });
+  const known = new Set(["pretty", "help", "json"]);
+  for (const [flag, s] of Object.entries(route.flags ?? {})) {
+    known.add(flag);
+    const { where, mod, name } = spec(s);
+    const target = name ?? flag;
+    const raw = flags[flag];
+    if (raw === undefined) { if (mod === "!") throw new UsageError(`--${flag.replace(/_/g, "-")} is required. Run \`tnb ${route.words.join(" ")} --help\`.`); continue; }
+    let value;
+    if (mod === "[]") value = many(raw);
+    else if (mod === "?") value = raw !== false && raw !== "false";
+    else if (mod === "#") { value = Number(one(raw)); if (!Number.isInteger(value)) throw new UsageError(`--${flag} must be an integer.`); }
+    else if (mod === "@") value = await jsonArg(one(raw));
+    else { value = one(raw); if (value === true) throw new UsageError(`--${flag.replace(/_/g, "-")} needs a value.`); }
+    if (where === "q") query[target] = value;
+    else if (where === "h") headers[target] = value;
+    else body[target] = value;
+  }
+  const unknown = Object.keys(flags).filter((k) => !known.has(k));
+  if (unknown.length) throw new UsageError(`Unknown flag${unknown.length > 1 ? "s" : ""}: ${unknown.map((k) => `--${k}`).join(", ")}. Run \`tnb ${route.words.join(" ")} --help\`.`);
+  const hasBody = route.method !== "GET" && route.method !== "DELETE";
+  const data = await call(route.method, path, { query, body: hasBody ? body : undefined, headers });
+  print(data);
+  return 0;
+}
+
+export { ROUTES };

package/lib/output.js

@@ -0,0 +1,24 @@
+/* WHAT LEAVES THE COMMAND (owner, 2026-09-12: "une bonne commande rend
+   le moins de texte possible — identifiant, URL, statut, erreur
+   lisible ; pas de bavardage"). JSON, one line, on stdout; `--pretty`
+   indents it for a person. Errors are JSON too, on stderr, and the
+   exit code says it: 0 done, 1 the platform or the network refused,
+   2 the command line was wrong. */
+
+let pretty = false;
+export const setPretty = (v) => { pretty = !!v; };
+
+export function print(value) {
+  process.stdout.write((pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value)) + "\n");
+}
+
+export function printError(code, message, extra) {
+  process.stderr.write(JSON.stringify({ error: { code, message, ...(extra ? extra : {}) } }) + "\n");
+}
+
+/** Text for a person — help and login prompts — never mixed with JSON. */
+export const say = (text) => process.stderr.write(text.endsWith("\n") ? text : text + "\n");
+
+export class UsageError extends Error {
+  constructor(message) { super(message); this.code = "usage"; }
+}

package/lib/routes.js

@@ -0,0 +1,76 @@
+/* ONE COMMAND PER FIXED ROUTE (owner + Strategy, 2026-09-12). The
+ * catalogue gives the workflows their commands at call time; the routes
+ * that do not change with the catalogue — credits, media, projects, tech
+ * packs, moodboards, publishing, Shopify, agents, files — are declared
+ * here, one line each, and one executor runs them all. A command is its
+ * route: the same words, the same JSON back, nothing added. The OpenAPI
+ * document, when it exists, will replace this table.
+ *
+ *   words       what the person types after `tnb`
+ *   args        positional arguments, in order, laid into {path} or the body
+ *   flags       --name → where it goes: q (query), b (body), p (path)
+ *   scope       the key scope the platform demands (for the help only)
+ */
+
+export const ROUTES = [
+  { words: ["credits"], method: "GET", path: "/credits", scope: "read", help: "The account's credit balance." },
+  { words: ["account"], method: "GET", path: "/account", scope: "read", help: "The account in one reading: credits, team, projects, library, tech packs, Visual DNA." },
+  { words: ["ledger"], method: "GET", path: "/ledger", scope: "read", flags: { days: "q", lines: "q" }, help: "What the account spent and received (--days 30 --lines 60)." },
+  { words: ["brand-dna"], method: "GET", path: "/brand-dna", scope: "read", help: "The Visual DNA profiles." },
+  { words: ["brand-dna", "read"], method: "GET", path: "/brand-dna/{id}", scope: "read", args: ["id"], help: "One Visual DNA profile in full, with its analysis." },
+
+  { words: ["media"], method: "GET", path: "/media", scope: "read", flags: { project: "q" }, help: "The account's recent creations (--project <id>)." },
+  { words: ["elements"], method: "GET", path: "/elements", scope: "read", help: "The starred pot: creations, presets, uploads." },
+  { words: ["projects"], method: "GET", path: "/projects", scope: "read", help: "The account's projects." },
+  { words: ["status"], method: "GET", path: "/generations/{id}", scope: "read", args: ["id"], help: "A generation's status and result (--wait, --out <file|dir/>).", special: "status" },
+
+  { words: ["techpacks"], method: "GET", path: "/techpacks", scope: "read", flags: { project: "q" }, help: "The tech packs (--project <id>)." },
+  { words: ["techpack"], method: "GET", path: "/techpacks/{id}", scope: "read", args: ["id"], help: "One tech pack whole: pages, sections, data." },
+  { words: ["techpack", "pdf"], method: "GET", path: "/techpacks/{id}/pdf", scope: "read", args: ["id"], help: "The tech pack as a PDF (a url)." },
+  { words: ["techpack", "rename"], method: "PATCH", path: "/techpacks/{id}", scope: "generate", args: ["id"], flags: { name: "b!" }, help: "Rename a tech pack (--name)." },
+  { words: ["techpack", "add-section"], method: "POST", path: "/techpacks/{id}/sections", scope: "generate", args: ["id"], flags: { page: "b!page_id", kind: "b!", at: "b#at_index" }, help: "Add a section to a page (--page <id> --kind header|descriptions|canvas|size_chart|bom|end_notes [--at 0])." },
+  { words: ["techpack", "write-section"], method: "PUT", path: "/techpacks/{id}/sections/{section}", scope: "generate", args: ["id", "section"], flags: { data: "b@" }, help: "Replace a section's data (--data '<json>' or --data @file.json)." },
+  { words: ["techpack", "from-photos"], method: "POST", path: "/techpacks/from-photos", scope: "generate", special: "from-photos", help: "Start a tech pack with AI from photos: tnb techpack from-photos front.jpg [back.jpg …] [--back <file>] [--description] [--product] [--size-range XS-XL] [--unit cm|in] [--sketch none|front|front_back] [--project <id>]. 1 credit + 1 per sketch." },
+
+  { words: ["moodboards"], method: "GET", path: "/moodboards", scope: "read", flags: { project: "q" }, help: "The moodboards (--project <id>)." },
+  { words: ["moodboard", "pdf"], method: "GET", path: "/moodboards/{id}/pdf", scope: "read", args: ["id"], help: "The moodboard as a PDF (a url)." },
+
+  { words: ["upload"], method: "POST", path: "/media/upload", scope: "generate", special: "upload", help: "Upload pictures (jpg, png, webp) and get their urls and media ids: tnb upload a.jpg b.png [--project <id>]." },
+
+  { words: ["shopify", "products"], method: "GET", path: "/shopify/products", scope: "read", help: "The connected store's products." },
+  { words: ["shopify", "publish"], method: "POST", path: "/shopify/publish", scope: "publish", flags: { product: "b!product_id", media: "b media_id", url: "b", alt: "b" }, help: "Put a creation on a product page (--product <id> --media <media_id> | --url <creation url> [--alt])." },
+
+  { words: ["publish", "accounts"], method: "GET", path: "/publish/accounts", scope: "read", help: "The connected social accounts and the placements each takes." },
+  { words: ["publish"], method: "POST", path: "/publish", scope: "publish", flags: { account: "b!connection_id", placement: "b!", media: "b[]media_ids", caption: "b", collaborators: "b", scheduled_at: "b", board: "b board_id", board_name: "b", title: "b", link: "b", ai: "b?is_ai_generated", tiktok: "b@" }, help: "Post a creation to a connected account (--account <connection_id> --placement <placement> --media <media_id>… [--caption] [--scheduled-at] [--board] [--title] [--link] [--tiktok '<json>'])." },
+  { words: ["post"], method: "GET", path: "/publish/{id}", scope: "read", args: ["id"], help: "A post's state: scheduled, posted with its permalink, failed." },
+
+  { words: ["agents"], method: "GET", path: "/agents", scope: "agents", help: "The account's AI agents." },
+  { words: ["agent", "send"], method: "POST", path: "/agents/{id}/messages", scope: "agents", args: ["id", "message"], flags: { media: "b[]media_ids", idempotency_key: "h Idempotency-Key" }, help: "Say something to an agent: tnb agent send <id> \"message\" [--media <media_id>…] [--idempotency-key <yours>]." },
+  { words: ["agent", "thread"], method: "GET", path: "/agents/{id}/messages", scope: "agents", args: ["id"], flags: { since: "q", limit: "q" }, help: "Read the agent's thread (--since <iso date> --limit 50)." },
+  { words: ["agent", "stop"], method: "POST", path: "/agents/{id}/stop", scope: "agents", args: ["id"], help: "Stop the agent's running task." },
+  { words: ["agent", "schedules"], method: "GET", path: "/agents/{id}/schedules", scope: "agents", args: ["id"], help: "The agent's calendar." },
+  { words: ["agent", "schedule"], method: "POST", path: "/agents/{id}/schedules", scope: "agents", args: ["id", "request"], flags: { kind: "b!", time: "b!", date: "b", every: "b", day_of_week: "b#", day_of_month: "b#", may_publish: "b?" }, help: "Put a request on the agent's calendar: tnb agent schedule <id> \"request\" --kind single|recurring --time HH:MM [--date YYYY-MM-DD | --every daily|weekly|monthly --day-of-week 0-6 --day-of-month 1-31] [--may-publish]." },
+  { words: ["agent", "unschedule"], method: "DELETE", path: "/agents/{id}/schedules/{schedule}", scope: "agents", args: ["id", "schedule"], help: "Take a request off the agent's calendar." },
+
+  { words: ["files"], method: "GET", path: "/files", scope: "agents", flags: { query: "q", folder: "q" }, help: "The account's Files (--query <word> --folder <path>)." },
+  { words: ["file"], method: "GET", path: "/files/{id}", scope: "agents", args: ["id"], flags: { page: "q", sheet: "q", picture: "q" }, help: "One page of a file, by id or path (--page 1 --sheet <name> --picture <inner name>)." },
+  { words: ["file", "describe"], method: "PATCH", path: "/files/{id}", scope: "agents", args: ["id"], flags: { description: "b!" }, help: "Write the one-line description of a file (--description)." },
+];
+
+/** The route whose words start the command line — the longest match wins. */
+export function match(positionals) {
+  let best = null;
+  for (const r of ROUTES) {
+    if (r.words.every((w, i) => positionals[i] === w) && (!best || r.words.length > best.words.length)) best = r;
+  }
+  return best;
+}
+
+/* A flag spec: "<where>[modifier][ name]" — where is q (query), b (body),
+   h (header); modifiers: ! required, # integer, ? boolean, [] list, @ JSON
+   (inline or @file); the name after a space renames it. */
+export function spec(s) {
+  const m = /^([qbh])([!#?@]|\[\])?(?:\s*(\S.*))?$/.exec(s);
+  if (!m) throw new Error(`bad flag spec ${s}`);
+  return { where: m[1], mod: m[2] ?? "", name: m[3] ?? null };
+}

package/lib/upload.js

@@ -0,0 +1,60 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { call } from "./api.js";
+
+/* A LOCAL FILE BECOMES A URL (2026-09-12). The reference scenario is a
+   folder of product photos on the person's machine; the API takes
+   https URLs. Anything that is not a URL is read from disk and sent to
+   POST /media/upload, and the URL the platform answers is what the
+   workflow receives. Uploaded once: the same file (path, size, mtime)
+   is remembered in the user's cache, so "do the same with the new ones"
+   tomorrow re-uploads nothing. */
+
+const isUrl = (v) => /^https?:\/\//i.test(String(v));
+const MIME = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp" };
+
+function cacheFile() {
+  const dir = process.env.TNB_CACHE_DIR || (process.platform === "win32"
+    ? path.join(process.env.LOCALAPPDATA || os.tmpdir(), "tnb")
+    : path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "tnb"));
+  return path.join(dir, "uploads.json");
+}
+
+async function readCache() {
+  try { return JSON.parse(await fs.readFile(cacheFile(), "utf8")); } catch { return {}; }
+}
+async function writeCache(c) {
+  try {
+    await fs.mkdir(path.dirname(cacheFile()), { recursive: true });
+    await fs.writeFile(cacheFile(), JSON.stringify(c));
+  } catch { /* a cache is a convenience */ }
+}
+
+/** Upload one local picture; answers { media_id, url, … }. */
+export async function uploadFile(file, { project } = {}) {
+  const abs = path.resolve(file);
+  const st = await fs.stat(abs).catch(() => null);
+  if (!st || !st.isFile()) throw Object.assign(new Error(`No such file: ${file}`), { code: "no_such_file" });
+  const ext = path.extname(abs).toLowerCase();
+  const mime = MIME[ext];
+  if (!mime) throw Object.assign(new Error(`${file}: only .jpg, .png and .webp pictures can be uploaded.`), { code: "unsupported_file" });
+  const cache = await readCache();
+  const sig = `${abs}|${st.size}|${Math.floor(st.mtimeMs)}|${project ?? ""}`;
+  if (cache[sig]?.url) return { ...cache[sig], cached: true };
+  const bytes = await fs.readFile(abs);
+  const form = new FormData();
+  form.set("file", new Blob([bytes], { type: mime }), path.basename(abs));
+  if (project) form.set("project", project);
+  const out = await call("POST", "/media/upload", { form });
+  cache[sig] = { media_id: out.media_id, url: out.url, name: path.basename(abs) };
+  await writeCache(cache);
+  return { ...cache[sig], cached: false };
+}
+
+/** A URL stays a URL; a path is uploaded. */
+export async function resolveImage(v, opts) {
+  if (isUrl(v)) return { url: String(v) };
+  const up = await uploadFile(String(v), opts);
+  return { url: up.url, media_id: up.media_id, file: String(v) };
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@thenewblack/cli",
+  "version": "0.1.0",
+  "description": "The New Black AI from the command line: every fashion workflow of the studio, your creations, tech packs, publishing and AI agents — one command each, JSON out. Made for AI coding agents and scripts.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "tnb": "bin/tnb.js" },
+  "files": ["bin", "lib", "README.md"],
+  "engines": { "node": ">=18.17" },
+  "keywords": ["fashion", "ai", "cli", "thenewblack", "virtual-try-on", "fashion-design", "agent"],
+  "homepage": "https://thenewblack.ai/clothing_fashion_api_integrations",
+  "repository": { "type": "git", "url": "git+https://github.com/newblackai/tnb-site.git", "directory": "cli" },
+  "bugs": { "url": "https://github.com/newblackai/tnb-site/issues" },
+  "scripts": {
+    "test": "node --test"
+  }
+}