@artillect/cli 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# `@artillect/cli`
+
+Fourth Artillect client (Studio / Public API / MCP / CLI). Thin Commander binary over Public API v1. The SDK is **bundled** into this package and is not published separately. **No local model list** — `artillect models` is `GET /api/v1/models`.
+
+```bash
+npm i -g @artillect/cli
+# or, without a global install:
+npx @artillect/cli@latest --help
+```
+
+Requires Node.js **≥ 20**. First publish of a scoped package uses `npm publish --access public` (already set in `publishConfig`).
+
+```bash
+artillect auth login          # device flow → ~/.config/artillect/config.json
+# or: export ARTILLECT_API_KEY=art_…
+#     export ARTILLECT_BASE_URL=https://dev.artillect.pro   # optional
+
+artillect balance
+artillect models list
+artillect generate image --prompt "a cat" --wait
+artillect generate video kling-3 --prompt "a cat walks" --start-image ./a.png --wait
+```
+
+`--json` prints the API envelope. `--wait` polls until `status=completed` and downloads media into `--out` (default cwd).
+
+## Updates and hotfixes
+
+npm **does not push** new versions to machines that already ran `npm i -g`. After install, the user keeps that exact tarball until they upgrade.
+
+| Who                   | What happens                                                                                                    |
+| --------------------- | --------------------------------------------------------------------------------------------------------------- |
+| You ship a CLI hotfix | Bump **patch** (`0.1.0` → `0.1.1`), `pnpm --filter @artillect/cli publish`.                                     |
+| You ship a feature    | Bump **minor**. Breaking CLI flags → **major**.                                                                 |
+| API/server hotfix     | Users get it on the next request. No CLI reinstall. Catalog, billing, and generation bugs live on the server.   |
+| SDK change            | SDK is private and inlined in the CLI bundle. Republish `@artillect/cli` — there is no `@artillect/sdk` on npm. |
+
+How a user actually receives a new CLI:
+
+```bash
+npm i -g @artillect/cli@latest
+# or one-shot without touching the global:
+npx @artillect/cli@latest models list
+```
+
+There is no App Store review, no push notification, and no silent auto-update of globals. The CLI prints a **stderr hint at most once a day** when `registry.npmjs.org/@artillect/cli/latest` is newer than the running binary. Disable with `ARTILLECT_NO_UPDATE_CHECK=1`. Announce breaking changes in release notes / Discord / the product changelog — npm will not email end users.
+
+`npx @artillect/cli` without `@latest` may use a cached copy. Prefer `@latest` in docs.
+
+## Repo scripts
+
+```bash
+pnpm --filter @artillect/sdk run build
+pnpm --filter @artillect/cli run build
+pnpm --filter @artillect/cli run pack:check   # tarball + --help/--version
+pnpm --filter @artillect/cli run smoke        # live health + models + device/code
+```
+
+Not in v1: Homebrew, a second catalog, `@artillect/mcp` on npm (MCP is the hosted URL).

package/dist/index.js

@@ -0,0 +1,790 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// ../artillect-sdk/dist/uploadMime.js
+import { basename, isAbsolute, resolve } from "node:path";
+import { access, readFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+function mimeFromFilename(filename) {
+  const ext = String(filename || "").split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "png":
+      return "image/png";
+    case "webp":
+      return "image/webp";
+    case "gif":
+      return "image/gif";
+    case "tif":
+    case "tiff":
+      return "image/tiff";
+    case "mp4":
+      return "video/mp4";
+    case "webm":
+      return "video/webm";
+    case "mov":
+      return "video/quicktime";
+    case "mp3":
+      return "audio/mpeg";
+    case "wav":
+      return "audio/wav";
+    case "m4a":
+      return "audio/mp4";
+    case "ogg":
+      return "audio/ogg";
+    default:
+      return null;
+  }
+}
+function mimeFromMagicBytes(bytes) {
+  if (!bytes || bytes.length < 4)
+    return null;
+  if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+    return "image/jpeg";
+  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) {
+    return "image/png";
+  }
+  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70)
+    return "image/gif";
+  if (bytes.length >= 12 && bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80) {
+    return "image/webp";
+  }
+  if (bytes[0] === 73 && bytes[1] === 68 && bytes[2] === 51)
+    return "audio/mpeg";
+  if (bytes[0] === 255 && (bytes[1] & 224) === 224)
+    return "audio/mpeg";
+  if (bytes.length >= 12 && bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 65 && bytes[10] === 86 && bytes[11] === 69) {
+    return "audio/wav";
+  }
+  if (bytes.length >= 8 && bytes[4] === 102 && bytes[5] === 116 && bytes[6] === 121 && bytes[7] === 112) {
+    return "video/mp4";
+  }
+  if (bytes[0] === 26 && bytes[1] === 69 && bytes[2] === 223 && bytes[3] === 163) {
+    return "video/webm";
+  }
+  return null;
+}
+function resolveUploadContentType(opts) {
+  const declared = String(opts.declaredType || "").split(";")[0].trim().toLowerCase();
+  if (declared && declared !== "application/octet-stream" && (declared.startsWith("image/") || declared.startsWith("video/") || declared.startsWith("audio/"))) {
+    return { contentType: declared, source: "declared" };
+  }
+  const fromName = mimeFromFilename(opts.filename || "");
+  if (fromName)
+    return { contentType: fromName, source: "filename" };
+  const fromMagic = opts.bytes ? mimeFromMagicBytes(opts.bytes) : null;
+  if (fromMagic)
+    return { contentType: fromMagic, source: "magic" };
+  return { contentType: declared || "application/octet-stream", source: "unknown" };
+}
+async function resolveLocalUploadPath(filePath) {
+  const raw = String(filePath || "").trim();
+  if (!raw)
+    throw new Error("file_path is empty");
+  const tried = [];
+  const candidates = [];
+  if (isAbsolute(raw)) {
+    candidates.push(raw);
+  } else {
+    candidates.push(resolve(process.cwd(), raw));
+    const uploadCwd = String(process.env.ARTILLECT_UPLOAD_CWD || "").trim();
+    if (uploadCwd)
+      candidates.push(resolve(uploadCwd, raw));
+    const workspace = String(process.env.CURSOR_WORKSPACE || process.env.PWD || "").trim();
+    if (workspace)
+      candidates.push(resolve(workspace, raw));
+  }
+  for (const p of candidates) {
+    if (tried.includes(p))
+      continue;
+    tried.push(p);
+    try {
+      await access(p, fsConstants.R_OK);
+      return { path: p, tried };
+    } catch {
+    }
+  }
+  const err = new Error(`ENOENT: file not found. On stdio MCP pass an absolute path; on remote/hosted MCP use file_base64 + filename instead. Tried: ${tried.join(" | ")}`);
+  err.code = "ENOENT";
+  err.tried = tried;
+  throw err;
+}
+async function readLocalUploadFile(filePath) {
+  const { path: resolved } = await resolveLocalUploadPath(filePath);
+  const buf = await readFile(resolved);
+  const bytes = new Uint8Array(buf);
+  const filename = basename(resolved);
+  const { contentType } = resolveUploadContentType({ filename, bytes });
+  return { bytes, filename, contentType };
+}
+
+// ../artillect-sdk/dist/http.js
+var JOB_SUFFIX_KIND = [
+  ["-api-image", "image"],
+  ["-api-video", "video"],
+  ["-api-upscale", "upscale"],
+  ["-api-switchx", "switchx"],
+  ["-api-audio", "audio"],
+  ["-api-mesh", "mesh"],
+  ["-api-chat", "chat"]
+];
+function inferJobKind(taskId) {
+  const id = taskId.toLowerCase();
+  for (const [suffix, kind] of JOB_SUFFIX_KIND) {
+    if (id.endsWith(suffix))
+      return kind;
+  }
+  return "unknown";
+}
+function resolvePollPath(taskId, _kind) {
+  const inferred = inferJobKind(taskId);
+  if (inferred === "unknown") {
+    return `/api/v1/generations/${encodeURIComponent(taskId)}`;
+  }
+  switch (inferred) {
+    case "image":
+      return `/api/v1/images/generations/${encodeURIComponent(taskId)}`;
+    case "video":
+      return `/api/v1/videos/generations/${encodeURIComponent(taskId)}`;
+    case "upscale":
+      return `/api/v1/upscale/generations/${encodeURIComponent(taskId)}`;
+    case "switchx":
+      return `/api/v1/switchx/generations/${encodeURIComponent(taskId)}`;
+    case "audio":
+      return `/api/v1/audio/generations/${encodeURIComponent(taskId)}`;
+    case "mesh":
+      return `/api/v1/mesh/generations/${encodeURIComponent(taskId)}`;
+    default:
+      return `/api/v1/generations/${encodeURIComponent(taskId)}`;
+  }
+}
+function joinUrl(baseUrl, path) {
+  const p = path.startsWith("/") ? path : `/${path}`;
+  const suffixIndex = p.search(/[?#]/);
+  const pathname = suffixIndex === -1 ? p : p.slice(0, suffixIndex);
+  const suffix = suffixIndex === -1 ? "" : p.slice(suffixIndex);
+  const withSlash = pathname.endsWith("/") ? pathname : `${pathname}/`;
+  return `${baseUrl.replace(/\/+$/, "")}${withSlash}${suffix}`;
+}
+async function publicApiFetch(config, method, path, body, extraHeaders) {
+  const url = joinUrl(config.baseUrl, path);
+  const headers = {
+    Authorization: `Bearer ${config.apiKey}`,
+    Accept: "application/json"
+  };
+  let payload;
+  if (body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    payload = JSON.stringify(body);
+  }
+  Object.assign(headers, extraHeaders);
+  const res = await fetch(url, { method, headers, body: payload });
+  return parseApiResponse(res);
+}
+async function publicApiUploadFile(config, file) {
+  const url = joinUrl(config.baseUrl, "/api/v1/files");
+  const { contentType } = resolveUploadContentType({
+    declaredType: file.contentType,
+    filename: file.filename,
+    bytes: file.bytes
+  });
+  const form = new FormData();
+  const blob = new Blob([Buffer.from(file.bytes)], { type: contentType });
+  form.append("file", blob, file.filename);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      Accept: "application/json"
+    },
+    body: form
+  });
+  return parseApiResponse(res);
+}
+function listQueryPath(basePath, params) {
+  const search = new URLSearchParams();
+  if (params?.limit != null)
+    search.set("limit", String(params.limit));
+  if (params?.cursor)
+    search.set("cursor", params.cursor);
+  if (params?.status)
+    search.set("status", params.status);
+  if (params?.job_id)
+    search.set("job_id", params.job_id);
+  if (params?.kind)
+    search.set("kind", params.kind);
+  if (params?.kinds)
+    search.set("kinds", params.kinds);
+  if (params?.source)
+    search.set("source", params.source);
+  if (params?.date)
+    search.set("date", params.date);
+  if (params?.date_from)
+    search.set("date_from", params.date_from);
+  if (params?.date_to)
+    search.set("date_to", params.date_to);
+  if (params?.before_created_at)
+    search.set("before_created_at", params.before_created_at);
+  if (params?.q)
+    search.set("q", params.q);
+  if (params?.mine_only)
+    search.set("mine_only", "1");
+  if (params?.actor_user_id != null)
+    search.set("actor_user_id", String(params.actor_user_id));
+  if (params?.tag_ids)
+    search.set("tag_ids", params.tag_ids);
+  if (params?.service)
+    search.set("service", params.service);
+  const qs = search.toString();
+  return qs ? `${basePath}?${qs}` : basePath;
+}
+async function parseApiResponse(res) {
+  const text = await res.text();
+  let parsed = null;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+  }
+  if (!res.ok) {
+    const obj = parsed && typeof parsed === "object" ? parsed : null;
+    const retryHeader = res.headers.get("Retry-After") ?? res.headers.get("retry-after");
+    let body = parsed;
+    if (res.status === 429 && retryHeader && obj && obj.retry_after_sec == null) {
+      const n = Number(retryHeader);
+      if (Number.isFinite(n)) {
+        body = { ...obj, retry_after_sec: Math.max(1, Math.trunc(n)) };
+      }
+    }
+    return {
+      ok: false,
+      status: res.status,
+      error: String(obj?.error ?? (text || res.statusText)),
+      code: obj?.code != null ? String(obj.code) : void 0,
+      // Every public-API error envelope carries request_id; dropping it here left
+      // the agent-visible message unsearchable in our logs.
+      requestId: obj?.request_id != null ? String(obj.request_id) : res.headers.get("X-Request-Id") ?? void 0,
+      body
+    };
+  }
+  return { ok: true, status: res.status, body: parsed };
+}
+
+// ../artillect-sdk/dist/client.js
+function createClient(opts) {
+  const apiKey = String(opts.apiKey || "").trim();
+  if (!apiKey)
+    throw new Error("apiKey is required");
+  const baseUrl = String(opts.baseUrl || "https://app.artillect.pro").trim().replace(/\/+$/, "");
+  const config = { apiKey, baseUrl };
+  return {
+    config,
+    getHealth: () => publicApiFetch(config, "GET", "/api/v1/health"),
+    getMe: () => publicApiFetch(config, "GET", "/api/v1/me"),
+    getBalance: () => publicApiFetch(config, "GET", "/api/v1/balance"),
+    listModels: () => publicApiFetch(config, "GET", "/api/v1/models"),
+    estimate: (body) => publicApiFetch(config, "POST", "/api/v1/estimate", body),
+    uploadFile: (file) => publicApiUploadFile(config, file),
+    generateImage: (body) => publicApiFetch(config, "POST", "/api/v1/images/generations", body),
+    getImageGeneration: (id) => publicApiFetch(config, "GET", `/api/v1/images/generations/${encodeURIComponent(id)}`),
+    listImageGenerations: (params) => publicApiFetch(config, "GET", listQueryPath("/api/v1/images/generations", params)),
+    cancelImageGeneration: (id) => publicApiFetch(config, "POST", `/api/v1/images/generations/${encodeURIComponent(id)}/cancel`),
+    generateVideo: (body) => publicApiFetch(config, "POST", "/api/v1/videos/generations", body),
+    getVideoGeneration: (id) => publicApiFetch(config, "GET", `/api/v1/videos/generations/${encodeURIComponent(id)}`),
+    listVideoGenerations: (params) => publicApiFetch(config, "GET", listQueryPath("/api/v1/videos/generations", params)),
+    cancelVideoGeneration: (id) => publicApiFetch(config, "POST", `/api/v1/videos/generations/${encodeURIComponent(id)}/cancel`),
+    generateUpscale: (body) => publicApiFetch(config, "POST", "/api/v1/upscale/generations", body),
+    getUpscaleGeneration: (id) => publicApiFetch(config, "GET", `/api/v1/upscale/generations/${encodeURIComponent(id)}`),
+    listUpscaleGenerations: (params) => publicApiFetch(config, "GET", listQueryPath("/api/v1/upscale/generations", params)),
+    cancelUpscaleGeneration: (id) => publicApiFetch(config, "POST", `/api/v1/upscale/generations/${encodeURIComponent(id)}/cancel`),
+    generateSwitchx: (body) => publicApiFetch(config, "POST", "/api/v1/switchx/generations", body),
+    getSwitchxGeneration: (id) => publicApiFetch(config, "GET", `/api/v1/switchx/generations/${encodeURIComponent(id)}`),
+    listSwitchxGenerations: (params) => publicApiFetch(config, "GET", listQueryPath("/api/v1/switchx/generations", params)),
+    cancelSwitchxGeneration: (id) => publicApiFetch(config, "POST", `/api/v1/switchx/generations/${encodeURIComponent(id)}/cancel`),
+    generateMesh: (body) => publicApiFetch(config, "POST", "/api/v1/mesh/generations", body),
+    getMeshGeneration: (id) => publicApiFetch(config, "GET", `/api/v1/mesh/generations/${encodeURIComponent(id)}`),
+    listMeshGenerations: (params) => publicApiFetch(config, "GET", listQueryPath("/api/v1/mesh/generations", params)),
+    cancelMeshGeneration: (id) => publicApiFetch(config, "POST", `/api/v1/mesh/generations/${encodeURIComponent(id)}/cancel`),
+    chatCompletion: (body) => publicApiFetch(config, "POST", "/api/v1/chat/completions", body),
+    getTask: (id, kind) => publicApiFetch(config, "GET", resolvePollPath(id, kind)),
+    getWebhook: () => publicApiFetch(config, "GET", "/api/v1/webhooks"),
+    upsertWebhook: (body) => publicApiFetch(config, "POST", "/api/v1/webhooks", body),
+    deleteWebhook: () => publicApiFetch(config, "DELETE", "/api/v1/webhooks"),
+    rotateWebhookSecret: () => publicApiFetch(config, "POST", "/api/v1/webhooks/rotate-secret"),
+    listWebhookDeliveries: (params) => publicApiFetch(config, "GET", listQueryPath("/api/v1/webhooks/deliveries", params)),
+    getWebhookDelivery: (eventId) => publicApiFetch(config, "GET", `/api/v1/webhooks/deliveries/${encodeURIComponent(eventId)}`)
+  };
+}
+
+// src/config.ts
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var DEFAULT_BASE = "https://app.artillect.pro";
+function configPath() {
+  const xdg = String(process.env.XDG_CONFIG_HOME || "").trim();
+  if (xdg) return join(xdg, "artillect", "config.json");
+  if (process.platform === "win32") {
+    const appData = String(process.env.APPDATA || "").trim();
+    if (appData) return join(appData, "artillect", "config.json");
+  }
+  return join(homedir(), ".config", "artillect", "config.json");
+}
+function readFileConfig() {
+  try {
+    const raw = readFileSync(configPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+function loadCliConfig() {
+  const file = readFileConfig();
+  const apiKey = String(process.env.ARTILLECT_API_KEY || file.apiKey || "").trim();
+  const baseUrl = String(process.env.ARTILLECT_BASE_URL || file.baseUrl || DEFAULT_BASE).trim().replace(/\/+$/, "");
+  return { apiKey, baseUrl };
+}
+function requireApiKey() {
+  const cfg = loadCliConfig();
+  if (!cfg.apiKey) {
+    throw new Error("Not logged in. Run `artillect auth login` or set ARTILLECT_API_KEY.");
+  }
+  return cfg;
+}
+function saveCliConfig(cfg) {
+  const path = configPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    `${JSON.stringify({ apiKey: cfg.apiKey, baseUrl: cfg.baseUrl }, null, 2)}
+`,
+    { mode: 384 }
+  );
+  return path;
+}
+function clearCliConfig() {
+  try {
+    rmSync(configPath());
+  } catch {
+  }
+}
+
+// src/httpAnon.ts
+async function getJson(baseUrl, path, extraHeaders) {
+  const url = joinUrl(baseUrl, path);
+  const res = await fetch(url, {
+    method: "GET",
+    headers: { Accept: "application/json", ...extraHeaders }
+  });
+  let json = {};
+  try {
+    json = await res.json();
+  } catch {
+    json = { error: `HTTP ${res.status}` };
+  }
+  return { status: res.status, json };
+}
+async function postJson(baseUrl, path, body) {
+  const url = joinUrl(baseUrl, path);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  let json = {};
+  try {
+    json = await res.json();
+  } catch {
+    json = { error: `HTTP ${res.status}` };
+  }
+  return { status: res.status, json };
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/auth.ts
+async function authLogin() {
+  const { baseUrl } = loadCliConfig();
+  const started = await postJson(baseUrl, "/api/v1/device/code", {});
+  if (started.status >= 400) {
+    throw new Error(String(started.json.error || `device code failed (${started.status})`));
+  }
+  const deviceCode = String(started.json.device_code || "");
+  const userCode = String(started.json.user_code || "");
+  const verificationUrl = String(started.json.verification_url || "");
+  const intervalSec = Math.max(1, Number(started.json.interval) || 5);
+  const expiresIn = Number(started.json.expires_in) || 600;
+  if (!deviceCode || !verificationUrl) {
+    throw new Error("Device authorization response missing device_code/verification_url");
+  }
+  console.log("Open this URL in a browser where you are logged into Artillect:");
+  console.log(`  ${verificationUrl}`);
+  if (userCode) console.log(`Confirm code: ${userCode}`);
+  console.log("Waiting for approval\u2026");
+  const deadline = Date.now() + expiresIn * 1e3;
+  while (Date.now() < deadline) {
+    await sleep(intervalSec * 1e3);
+    const polled = await postJson(baseUrl, "/api/v1/device/token", { device_code: deviceCode });
+    const status = String(polled.json.status || "");
+    if (status === "pending") continue;
+    if (status === "expired" || polled.status === 410) {
+      throw new Error("Device code expired. Run `artillect auth login` again.");
+    }
+    const apiKey = String(polled.json.api_key || "");
+    if (status === "completed" && apiKey) {
+      const path = saveCliConfig({ apiKey, baseUrl });
+      console.log(`Logged in. Key saved to ${path}`);
+      return;
+    }
+    throw new Error(String(polled.json.error || `login failed (${polled.status})`));
+  }
+  throw new Error("Timed out waiting for browser approval.");
+}
+async function authLogout() {
+  clearCliConfig();
+  console.log("Logged out.");
+}
+async function authStatus() {
+  const envKey = Boolean(String(process.env.ARTILLECT_API_KEY || "").trim());
+  try {
+    const cfg = requireApiKey();
+    const client = createClient({ apiKey: cfg.apiKey, baseUrl: cfg.baseUrl });
+    const me = await client.getMe();
+    if (!me.ok) {
+      console.log(
+        `Configured (${envKey ? "ARTILLECT_API_KEY" : configPath()}), but /me failed: ${me.error}`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const body = me.body;
+    console.log(`Logged in as ${body.email ?? body.user_id ?? "ok"}`);
+    console.log(`Base URL: ${cfg.baseUrl}`);
+  } catch (err) {
+    console.log(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}
+
+// src/generate.ts
+import { createWriteStream } from "node:fs";
+import { basename as basename2 } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+// src/modelsFormat.ts
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function formatModelsList(body, kind) {
+  const groups = [
+    ["images", "Images"],
+    ["video", "Video"],
+    ["chat", "Chat"],
+    ["audio", "Audio"],
+    ["upscale", "Upscale"],
+    ["mesh", "Mesh"],
+    ["switchx", "SwitchX"]
+  ];
+  const lines = [];
+  for (const [key, label] of groups) {
+    if (kind && key !== kind && !(kind === "image" && key === "images")) continue;
+    const group = asRecord(body[key]);
+    const models2 = Array.isArray(group.models) ? group.models : [];
+    if (!models2.length) continue;
+    lines.push(`${label}:`);
+    for (const raw of models2) {
+      const m = asRecord(raw);
+      const slug = String(m.slug || "");
+      const name = String(m.display_name || slug);
+      lines.push(`  ${slug.padEnd(24)} ${name}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/generate.ts
+function fail(result) {
+  if (result.ok) throw new Error("expected error result");
+  const extra = result.requestId ? ` (request_id ${result.requestId})` : "";
+  throw new Error(`${result.error}${extra}`);
+}
+async function uploadLocal(client, filePath) {
+  const file = await readLocalUploadFile(filePath);
+  const up = await client.uploadFile({ bytes: file.bytes, filename: file.filename });
+  if (!up.ok) fail(up);
+  const url = String(asRecord(up.body).url || "").trim();
+  if (!url) throw new Error(`Upload of ${basename2(filePath)} returned no url`);
+  return url;
+}
+function mediaUrls(body) {
+  const images = Array.isArray(body.images) ? body.images : [];
+  const videos = Array.isArray(body.videos) ? body.videos : [];
+  const fromSlots = [...images, ...videos].map((item) => item && typeof item === "object" ? String(asRecord(item).url || "") : "").filter(Boolean);
+  if (fromSlots.length) return fromSlots;
+  const media = Array.isArray(body.media_urls) ? body.media_urls : [];
+  return media.map((u) => String(u || "")).filter(Boolean);
+}
+function terminalStatus(body) {
+  const status = String(body.status || "").toLowerCase();
+  if (status === "completed" || status === "failed" || status === "cancelled") {
+    return status;
+  }
+  if (body.done === true) return String(body.error || "") ? "failed" : "completed";
+  return null;
+}
+async function waitForTask(client, taskId, jsonMode) {
+  const started = Date.now();
+  const timeoutMs = 20 * 60 * 1e3;
+  while (Date.now() - started < timeoutMs) {
+    const poll = await client.getTask(taskId);
+    if (!poll.ok) fail(poll);
+    const body = asRecord(poll.body);
+    const term = terminalStatus(body);
+    if (term) {
+      if (term !== "completed") {
+        throw new Error(String(body.error || `generation ${term}`));
+      }
+      return body;
+    }
+    const interval = Math.max(2, Number(body.recommended_poll_interval_sec) || 3);
+    if (!jsonMode) {
+      const progress = body.progress != null ? ` ${body.progress}%` : "";
+      process.stderr.write(`\r${String(body.status || "queued")}${progress}   `);
+    }
+    await sleep(interval * 1e3);
+  }
+  throw new Error("Timed out waiting for generation");
+}
+async function downloadAll(urls, outDir) {
+  const saved = [];
+  for (const [i, url] of urls.entries()) {
+    const res = await fetch(url);
+    if (!res.ok || !res.body) throw new Error(`download failed HTTP ${res.status}`);
+    const extGuess = url.includes(".mp4") ? "mp4" : url.includes(".webm") ? "webm" : "png";
+    const dest = `${outDir.replace(/\/+$/, "") || "."}/artillect-${Date.now()}-${i + 1}.${extGuess}`;
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+    saved.push(dest);
+  }
+  return saved;
+}
+function printOrJson(jsonMode, payload, lines) {
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  for (const line of lines) console.log(line);
+}
+async function cmdBalance(jsonMode) {
+  const cfg = requireApiKey();
+  const client = createClient(cfg);
+  const res = await client.getBalance();
+  if (!res.ok) fail(res);
+  const body = asRecord(res.body);
+  printOrJson(jsonMode, body, [`Balance: ${body.token_balance ?? 0} tokens`]);
+}
+async function cmdModels(kind, jsonMode) {
+  const cfg = loadCliConfig();
+  const headers = {};
+  if (cfg.apiKey) headers.Authorization = `Bearer ${cfg.apiKey}`;
+  const res = await getJson(cfg.baseUrl, "/api/v1/models", headers);
+  if (res.status >= 400) {
+    throw new Error(String(res.json.error || `GET /api/v1/models failed (${res.status})`));
+  }
+  if (jsonMode) {
+    console.log(JSON.stringify(kind ? res.json[kind] ?? res.json : res.json, null, 2));
+    return;
+  }
+  const text = formatModelsList(res.json, kind);
+  if (text) process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+}
+async function cmdGenerateImage(opts) {
+  const cfg = requireApiKey();
+  const client = createClient(cfg);
+  const inputUrls = [];
+  for (const path of opts.input ?? []) {
+    inputUrls.push(await uploadLocal(client, path));
+  }
+  const res = await client.generateImage({
+    prompt: opts.prompt,
+    ...opts.model ? { model: opts.model } : {},
+    ...inputUrls.length ? { input_urls: inputUrls } : {}
+  });
+  if (!res.ok) fail(res);
+  const body = asRecord(res.body);
+  const taskId = String(body.task_id || body.id || "");
+  if (!opts.wait) {
+    printOrJson(opts.json, body, [`Submitted ${taskId || "(no task_id)"}`]);
+    return;
+  }
+  if (!taskId) throw new Error("submit returned no task_id");
+  const done = await waitForTask(client, taskId, opts.json);
+  const urls = mediaUrls(done);
+  const saved = urls.length ? await downloadAll(urls, opts.out) : [];
+  printOrJson(opts.json, { ...done, saved }, [
+    `Completed ${taskId}`,
+    ...saved.map((p) => `Saved ${p}`),
+    ...!saved.length ? urls.map((u) => u) : []
+  ]);
+}
+async function cmdGenerateVideo(opts) {
+  const cfg = requireApiKey();
+  const client = createClient(cfg);
+  const body = { model: opts.model, prompt: opts.prompt };
+  if (opts.startImage) body.start_image_url = await uploadLocal(client, opts.startImage);
+  if (opts.endImage) body.end_image_url = await uploadLocal(client, opts.endImage);
+  const res = await client.generateVideo(body);
+  if (!res.ok) fail(res);
+  const submitted = asRecord(res.body);
+  const taskId = String(submitted.task_id || submitted.id || "");
+  if (!opts.wait) {
+    printOrJson(opts.json, submitted, [`Submitted ${taskId || "(no task_id)"}`]);
+    return;
+  }
+  if (!taskId) throw new Error("submit returned no task_id");
+  const done = await waitForTask(client, taskId, opts.json);
+  const urls = mediaUrls(done);
+  const saved = urls.length ? await downloadAll(urls, opts.out) : [];
+  printOrJson(opts.json, { ...done, saved }, [
+    `Completed ${taskId}`,
+    ...saved.map((p) => `Saved ${p}`),
+    ...!saved.length ? urls.map((u) => u) : []
+  ]);
+}
+
+// src/updateCheck.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+
+// src/version.ts
+function compareSemver(a, b) {
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+function parse(raw) {
+  const m = String(raw || "").trim().replace(/^v/i, "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function cliVersion() {
+  return String("0.1.0");
+}
+function updateAvailableMessage(local, latest) {
+  return `A new version of @artillect/cli is available (${latest}; you have ${local}).
+Update: npm i -g @artillect/cli@latest`;
+}
+
+// src/updateCheck.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function cachePath() {
+  return join2(dirname2(configPath()), "update-check.json");
+}
+function shouldSkip() {
+  if (process.env.ARTILLECT_NO_UPDATE_CHECK === "1") return true;
+  if (process.env.CI === "true" || process.env.CI === "1") return true;
+  return false;
+}
+function readLastCheck() {
+  try {
+    const raw = JSON.parse(readFileSync2(cachePath(), "utf8"));
+    return Number(raw.checkedAt) || 0;
+  } catch {
+    return 0;
+  }
+}
+function writeLastCheck() {
+  try {
+    mkdirSync2(dirname2(cachePath()), { recursive: true });
+    writeFileSync2(cachePath(), `${JSON.stringify({ checkedAt: Date.now() })}
+`);
+  } catch {
+  }
+}
+async function maybeNotifyUpdate() {
+  if (shouldSkip()) return;
+  if (Date.now() - readLastCheck() < DAY_MS) return;
+  writeLastCheck();
+  const local = cliVersion();
+  try {
+    const res = await fetch("https://registry.npmjs.org/@artillect/cli/latest", {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(2500)
+    });
+    if (!res.ok) return;
+    const body = await res.json();
+    const latest = String(body.version || "").trim();
+    if (!latest || compareSemver(latest, local) <= 0) return;
+    process.stderr.write(`${updateAvailableMessage(local, latest)}
+`);
+  } catch {
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("artillect").description(
+  "Artillect CLI \u2014 same Public API v1 as Studio, REST, and MCP. Models come from GET /api/v1/models."
+).version(cliVersion());
+program.hook("preAction", async () => {
+  await maybeNotifyUpdate();
+});
+var auth = program.command("auth").description("Device-flow login (or ARTILLECT_API_KEY)");
+auth.command("login").description("Open /connect, poll until an API key is issued").action(authLogin);
+auth.command("logout").description("Remove the saved API key").action(authLogout);
+auth.command("status").description("Show who the current key belongs to").action(authStatus);
+program.command("balance").description("Show token balance").option("--json", "print raw JSON", false).action(async (opts) => {
+  await cmdBalance(Boolean(opts.json));
+});
+var models = program.command("models").description("Discovery from GET /api/v1/models (no local catalog)");
+models.command("list").description("List public model slugs").option("-k, --kind <kind>", "images | video | chat | audio | upscale | mesh").option("--json", "print raw JSON", false).action(async (opts) => {
+  await cmdModels(opts.kind, Boolean(opts.json));
+});
+var generate = program.command("generate").description("Submit a generation");
+generate.command("image").description("Text-to-image or image edit").requiredOption("-p, --prompt <text>", "prompt").option("-m, --model <slug>", "public image slug (default: gpt-image-2)").option("-i, --input <file...>", "local image files to upload as input_urls").option("-w, --wait", "poll until complete and download results", false).option("-o, --out <dir>", "directory for downloads", ".").option("--json", "print raw JSON", false).action(
+  async (opts) => {
+    await cmdGenerateImage({
+      prompt: opts.prompt,
+      model: opts.model,
+      input: opts.input,
+      wait: Boolean(opts.wait),
+      json: Boolean(opts.json),
+      out: opts.out
+    });
+  }
+);
+generate.command("video").description("Text/image-to-video").argument("[model]", "public video slug (default: kling-3-turbo)").requiredOption("-p, --prompt <text>", "prompt").option("-m, --model <slug>", "public video slug (overrides the positional model)").option("--start-image <file>", "local start-frame image").option("--end-image <file>", "local end-frame image").option("-w, --wait", "poll until complete and download results", false).option("-o, --out <dir>", "directory for downloads", ".").option("--json", "print raw JSON", false).action(
+  async (positionalModel, opts) => {
+    const model = String(opts.model || positionalModel || "kling-3-turbo").trim();
+    await cmdGenerateVideo({
+      model,
+      prompt: opts.prompt,
+      startImage: opts.startImage,
+      endImage: opts.endImage,
+      wait: Boolean(opts.wait),
+      json: Boolean(opts.json),
+      out: opts.out
+    });
+  }
+);
+program.parseAsync(process.argv).catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@artillect/cli",
+  "version": "0.1.0",
+  "description": "Artillect CLI — generate images and video via Public API v1.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "artillect": "./dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://git.krem.digital/diffusionbooth/artillect.git",
+    "directory": "packages/artillect-cli"
+  },
+  "homepage": "https://app.artillect.pro/docs",
+  "bugs": {
+    "url": "https://app.artillect.pro/feedback"
+  },
+  "keywords": [
+    "artillect",
+    "cli",
+    "ai",
+    "image-generation",
+    "video-generation"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.8.0",
+    "@artillect/sdk": "0.1.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pack:check": "node scripts/pack-check.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  }
+}