@nsketch/cli 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @nsketch/cli
+
+Generate images, videos, voice, motion transfer, and more with [Nsketch AI](https://nsketch.ai) from your terminal — or let your AI agent (Claude Code, Codex, Cursor) do it for you.
+
+## Install
+
+```bash
+npm install -g @nsketch/cli
+```
+
+## Sign in
+
+```bash
+nsketch auth login
+```
+
+Opens a browser, takes 5 seconds. Credentials are stored in `~/.config/nsketch/credentials.json`.
+
+## Usage
+
+```bash
+# What can I use?
+nsketch models list --type image
+nsketch account status
+
+# Generate an image and wait for the result URL
+nsketch generate image --prompt "a corgi surfing at golden hour" --wait
+
+# Image-to-video (local files are auto-uploaded)
+nsketch generate video --prompt "the corgi rides a wave" --image ./corgi.png --wait
+
+# Voice, lipsync, motion transfer, upscaling
+nsketch generate voice --script "Hello world"
+nsketch generate lipsync --video ./clip.mp4 --audio ./voice.mp3
+nsketch generate motion-transfer --image ./character.png --video ./dance.mp4 --wait
+nsketch generate upscale --image ./photo.jpg --mode crystal
+
+# Check an async job later
+nsketch status <request-id> --type video --model <model-id>
+
+# Upload a file and get a hosted URL
+nsketch upload ./photo.jpg
+```
+
+Global flags: `--json` (machine-readable output on stdout), `--wait`, `--wait-timeout 10m`, `--wait-interval 3s`, `--api-url` (override the API base URL).
+
+## For AI agents
+
+All commands support `--json`. Generations consume account credits; check `nsketch account status` first. Async jobs return a request id — prefer `--wait` so the CLI handles polling.

package/dist/index.js

@@ -0,0 +1,671 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/auth.ts
+import crypto from "crypto";
+import http from "http";
+import open from "open";
+
+// src/config.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var DEFAULT_API_URL = "https://nsketch.ai";
+var CONFIG_DIR = path.join(os.homedir(), ".config", "nsketch");
+var CREDENTIALS_PATH = path.join(CONFIG_DIR, "credentials.json");
+var CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJson(file, data, mode) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2), mode ? { mode } : void 0);
+  if (mode) fs.chmodSync(file, mode);
+}
+function loadCredentials() {
+  return readJson(CREDENTIALS_PATH);
+}
+function saveCredentials(credentials) {
+  writeJson(CREDENTIALS_PATH, credentials, 384);
+}
+function clearCredentials() {
+  try {
+    fs.unlinkSync(CREDENTIALS_PATH);
+  } catch {
+  }
+}
+function loadConfig() {
+  return readJson(CONFIG_PATH) ?? {};
+}
+function saveConfig(config) {
+  writeJson(CONFIG_PATH, config);
+}
+function resolveApiUrl(flagValue) {
+  return (flagValue || process.env.NSKETCH_API_URL || loadConfig().apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
+}
+function resolveClientId(flagValue) {
+  return flagValue || process.env.NSKETCH_OAUTH_CLIENT_ID || loadConfig().clientId || null;
+}
+
+// src/auth.ts
+var LOOPBACK_PORTS = [9789, 9790, 9791];
+async function discoverAuthServer(apiUrl2) {
+  const resourceRes = await fetch(`${apiUrl2}/.well-known/oauth-protected-resource/mcp`);
+  if (!resourceRes.ok) {
+    throw new Error(`Failed to discover auth server from ${apiUrl2} (HTTP ${resourceRes.status})`);
+  }
+  const resource = await resourceRes.json();
+  const authServer = resource.authorization_servers?.[0];
+  if (!authServer) throw new Error("No authorization server advertised by the API");
+  const metadataRes = await fetch(
+    `${authServer.replace(/\/$/, "")}/.well-known/oauth-authorization-server`
+  );
+  if (!metadataRes.ok) {
+    throw new Error(`Failed to fetch authorization server metadata (HTTP ${metadataRes.status})`);
+  }
+  const metadata = await metadataRes.json();
+  if (!metadata.authorization_endpoint || !metadata.token_endpoint) {
+    throw new Error("Authorization server metadata is missing endpoints");
+  }
+  return metadata;
+}
+function base64url(buffer) {
+  return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function listenOnFirstFreePort(server) {
+  return new Promise((resolve, reject) => {
+    const tryPort = (index) => {
+      if (index >= LOOPBACK_PORTS.length) {
+        reject(new Error(`Ports ${LOOPBACK_PORTS.join(", ")} are all in use`));
+        return;
+      }
+      const port = LOOPBACK_PORTS[index];
+      server.once("error", () => tryPort(index + 1));
+      server.listen(port, "127.0.0.1", () => {
+        server.removeAllListeners("error");
+        resolve(port);
+      });
+    };
+    tryPort(0);
+  });
+}
+function waitForCallback(server, expectedState) {
+  return new Promise((resolve, reject) => {
+    server.on("request", (req, res) => {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      const error = url.searchParams.get("error");
+      res.writeHead(200, { "content-type": "text/html" });
+      res.end(
+        error ? `<h2>Sign-in failed: ${error}</h2><p>You can close this tab.</p>` : "<h2>Signed in to Nsketch.</h2><p>You can close this tab and return to your terminal.</p>"
+      );
+      if (error) reject(new Error(`Authorization failed: ${error}`));
+      else if (state !== expectedState) reject(new Error("State mismatch in OAuth callback"));
+      else if (!code) reject(new Error("No authorization code in callback"));
+      else resolve(code);
+    });
+  });
+}
+function toCredentials(tokens, tokenEndpoint, clientId) {
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    expiresAt: tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0,
+    tokenEndpoint,
+    clientId
+  };
+}
+async function login(opts) {
+  const { authorization_endpoint, token_endpoint } = await discoverAuthServer(opts.apiUrl);
+  const verifier = base64url(crypto.randomBytes(32));
+  const challenge = base64url(crypto.createHash("sha256").update(verifier).digest());
+  const state = base64url(crypto.randomBytes(16));
+  const server = http.createServer();
+  const port = await listenOnFirstFreePort(server);
+  const redirectUri = `http://localhost:${port}/callback`;
+  const authorizeUrl = new URL(authorization_endpoint);
+  authorizeUrl.searchParams.set("client_id", opts.clientId);
+  authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("scope", "profile email");
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  authorizeUrl.searchParams.set("state", state);
+  process.stderr.write(`Opening browser to sign in...
+If it doesn't open, visit:
+${authorizeUrl}
+`);
+  await open(authorizeUrl.toString()).catch(() => {
+  });
+  try {
+    const code = await waitForCallback(server, state);
+    const tokenRes = await fetch(token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        client_id: opts.clientId,
+        code_verifier: verifier
+      })
+    });
+    if (!tokenRes.ok) {
+      throw new Error(`Token exchange failed (HTTP ${tokenRes.status}): ${await tokenRes.text()}`);
+    }
+    const credentials = toCredentials(
+      await tokenRes.json(),
+      token_endpoint,
+      opts.clientId
+    );
+    saveCredentials(credentials);
+    const config = loadConfig();
+    saveConfig({ ...config, clientId: opts.clientId });
+    return credentials;
+  } finally {
+    server.close();
+  }
+}
+async function refreshAccessToken(credentials) {
+  if (!credentials.refreshToken) return null;
+  const res = await fetch(credentials.tokenEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: credentials.refreshToken,
+      client_id: credentials.clientId
+    })
+  });
+  if (!res.ok) return null;
+  const refreshed = toCredentials(
+    await res.json(),
+    credentials.tokenEndpoint,
+    credentials.clientId
+  );
+  refreshed.refreshToken ??= credentials.refreshToken;
+  saveCredentials(refreshed);
+  return refreshed;
+}
+function logout() {
+  clearCredentials();
+}
+function currentCredentials() {
+  return loadCredentials();
+}
+
+// src/api.ts
+var ApiError = class extends Error {
+  constructor(status, payload) {
+    super(typeof payload.error === "string" ? payload.error : `HTTP ${status}`);
+    this.status = status;
+    this.payload = payload;
+  }
+};
+async function rawRequest(apiUrl2, credentials, method, path3, opts = {}) {
+  const url = new URL(path3, apiUrl2);
+  for (const [key, value] of Object.entries(opts.query ?? {})) {
+    if (value !== void 0) url.searchParams.set(key, value);
+  }
+  const res = await fetch(url, {
+    method,
+    headers: {
+      ...credentials ? { authorization: `Bearer ${credentials.accessToken}` } : {},
+      ...opts.body !== void 0 ? { "content-type": "application/json" } : {}
+    },
+    body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+  });
+  const json = await res.json().catch(() => ({})) ?? {};
+  return { status: res.status, json };
+}
+async function apiRequest(apiUrl2, method, path3, opts = {}) {
+  let credentials = currentCredentials();
+  if (!credentials) {
+    if (opts.requireAuth === false) {
+      const result2 = await rawRequest(apiUrl2, null, method, path3, opts);
+      if (result2.status >= 400) throw new ApiError(result2.status, result2.json);
+      return result2;
+    }
+    throw new Error("Not authenticated. Run: nsketch auth login");
+  }
+  if (credentials.expiresAt && credentials.expiresAt < Date.now() + 3e4) {
+    credentials = await refreshAccessToken(credentials) ?? credentials;
+  }
+  let result = await rawRequest(apiUrl2, credentials, method, path3, opts);
+  if (result.status === 401) {
+    const refreshed = await refreshAccessToken(credentials);
+    if (refreshed) {
+      result = await rawRequest(apiUrl2, refreshed, method, path3, opts);
+    }
+  }
+  if (result.status === 401) {
+    throw new Error("Session expired. Run: nsketch auth login");
+  }
+  if (result.status >= 400) {
+    throw new ApiError(result.status, result.json);
+  }
+  return result;
+}
+
+// src/output.ts
+var jsonMode = false;
+function setJsonMode(enabled) {
+  jsonMode = enabled;
+}
+function info(message) {
+  process.stderr.write(`${message}
+`);
+}
+function emit(data, humanText) {
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+  } else {
+    process.stdout.write(`${humanText ?? JSON.stringify(data, null, 2)}
+`);
+  }
+}
+function fail(message, data) {
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify({ error: message, ...data ? { details: data } : {} })}
+`);
+  } else {
+    process.stderr.write(`Error: ${message}
+`);
+    if (data) process.stderr.write(`${JSON.stringify(data, null, 2)}
+`);
+  }
+  process.exit(1);
+}
+
+// src/media.ts
+import fs2 from "fs";
+import path2 from "path";
+var CONTENT_TYPES = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".m4a": "audio/mp4",
+  ".ogg": "audio/ogg"
+};
+async function uploadFile(apiUrl2, filePath) {
+  const absolute = path2.resolve(filePath);
+  const bytes = fs2.readFileSync(absolute);
+  const extension = path2.extname(absolute).toLowerCase();
+  const contentType = CONTENT_TYPES[extension] ?? "application/octet-stream";
+  const presign = await apiRequest(apiUrl2, "POST", "/api/mobile/r2-presign", {
+    body: {
+      contentType,
+      fileName: path2.basename(absolute),
+      fileSize: bytes.byteLength
+    }
+  });
+  const uploadUrl = presign.json.uploadUrl;
+  const cacheControl = presign.json.cacheControl;
+  const put = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: {
+      "content-type": contentType,
+      ...cacheControl ? { "cache-control": cacheControl } : {}
+    },
+    body: bytes
+  });
+  if (!put.ok) {
+    throw new Error(`Upload failed with HTTP ${put.status}`);
+  }
+  return presign.json.url;
+}
+async function resolveMedia(apiUrl2, value) {
+  if (!value) return void 0;
+  if (/^https?:\/\//.test(value)) return value;
+  if (!fs2.existsSync(value)) {
+    throw new Error(`Media not found (not a URL and not a local file): ${value}`);
+  }
+  info(`Uploading ${value}...`);
+  return uploadFile(apiUrl2, value);
+}
+
+// src/poll.ts
+function parseDuration(value) {
+  const match = /^(\d+)(ms|s|m|h)?$/.exec(value.trim());
+  if (!match) throw new Error(`Invalid duration: ${value} (use e.g. "90s", "10m")`);
+  const amount = Number(match[1]);
+  const unit = match[2] ?? "s";
+  return amount * { ms: 1, s: 1e3, m: 6e4, h: 36e5 }[unit];
+}
+async function fetchStatus(apiUrl2, target) {
+  if (target.type === "image") {
+    return apiRequest(apiUrl2, "GET", "/api/mobile/generate-images/status", {
+      query: { requestId: target.requestId, modelId: target.model }
+    });
+  }
+  if (target.type === "video") {
+    return apiRequest(apiUrl2, "GET", "/api/mobile/generate-video/status", {
+      query: {
+        requestId: target.requestId,
+        modelId: target.model,
+        endpoint: target.endpoint
+      }
+    });
+  }
+  return apiRequest(apiUrl2, "GET", "/api/mobile/generation-status", {
+    query: { requestId: target.requestId }
+  });
+}
+async function waitForCompletion(apiUrl2, target, opts) {
+  const deadline = Date.now() + opts.timeoutMs;
+  let dots = 0;
+  for (; ; ) {
+    const result = await fetchStatus(apiUrl2, target);
+    if (result.status !== 202) return result;
+    if (Date.now() + opts.intervalMs > deadline) {
+      throw new Error(
+        `Timed out waiting for ${target.requestId}. Check later with: nsketch status ${target.requestId} --type ${target.type}`
+      );
+    }
+    if (process.stderr.isTTY) {
+      dots = (dots + 1) % 4;
+      process.stderr.write(`\rGenerating${".".repeat(dots)}   `);
+    }
+    await new Promise((resolve) => setTimeout(resolve, opts.intervalMs));
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("nsketch").description("Nsketch AI \u2014 generate images, videos, voice, and more from your terminal.").version("0.1.0").option("--json", "machine-readable JSON output on stdout").option("--api-url <url>", "API base URL (default: https://nsketch.ai)").hook("preAction", (thisCommand) => {
+  setJsonMode(Boolean(thisCommand.opts().json));
+});
+var apiUrl = () => resolveApiUrl(program.opts().apiUrl);
+function addWaitOptions(command) {
+  return command.option("--wait", "block until the generation finishes and print the result").option("--wait-timeout <duration>", 'max time to wait, e.g. "10m"', "10m").option("--wait-interval <duration>", 'poll interval, e.g. "3s"', "3s");
+}
+async function finishGeneration(submitJson, target, opts) {
+  if (!opts.wait) {
+    emit(
+      submitJson,
+      `Submitted. Request id: ${target.requestId}
+Check with: nsketch status ${target.requestId} --type ${target.type}${"model" in target && target.model ? ` --model ${target.model}` : ""}${"endpoint" in target && target.endpoint ? ` --endpoint ${target.endpoint}` : ""}`
+    );
+    return;
+  }
+  const result = await waitForCompletion(apiUrl(), target, {
+    timeoutMs: parseDuration(opts.waitTimeout),
+    intervalMs: parseDuration(opts.waitInterval)
+  });
+  if (process.stderr.isTTY) process.stderr.write("\r");
+  const urls = extractResultUrls(result.json);
+  emit(
+    { ...result.json, requestId: target.requestId },
+    urls.length ? urls.join("\n") : JSON.stringify(result.json, null, 2)
+  );
+}
+function extractResultUrls(json) {
+  const urls = [];
+  if (Array.isArray(json.images)) {
+    for (const image of json.images) {
+      if (typeof image === "string") urls.push(image);
+      else if (image && typeof image.url === "string")
+        urls.push(image.url);
+    }
+  }
+  if (Array.isArray(json.videos)) {
+    for (const video of json.videos) {
+      if (typeof video === "string") urls.push(video);
+      else if (video && typeof video.url === "string")
+        urls.push(video.url);
+    }
+  }
+  for (const key of ["videoUrl", "audioUrl", "url", "resultVideoUrl"]) {
+    if (typeof json[key] === "string") urls.push(json[key]);
+  }
+  return urls;
+}
+var auth = program.command("auth").description("Authentication");
+auth.command("login").description("Sign in with your Nsketch account (opens a browser)").option("--client-id <id>", "OAuth client id (or set NSKETCH_OAUTH_CLIENT_ID)").action(async (opts) => {
+  const clientId = resolveClientId(opts.clientId);
+  if (!clientId) {
+    fail(
+      'Missing OAuth client id. Pass --client-id or set NSKETCH_OAUTH_CLIENT_ID (from the "Nsketch CLI" OAuth app in Clerk).'
+    );
+  }
+  await login({ apiUrl: apiUrl(), clientId });
+  const me = await apiRequest(apiUrl(), "GET", "/api/mobile/me");
+  emit(me.json, `Signed in as ${me.json.email} \u2014 ${me.json.plan} plan, ${me.json.totalCredits} credits`);
+});
+auth.command("logout").description("Remove saved credentials").action(() => {
+  logout();
+  emit({ success: true }, "Logged out.");
+});
+auth.command("status").description("Show authentication status").action(async () => {
+  if (!currentCredentials()) {
+    fail("Not authenticated. Run: nsketch auth login");
+  }
+  const me = await apiRequest(apiUrl(), "GET", "/api/mobile/me");
+  emit(me.json, `Signed in as ${me.json.email} \u2014 ${me.json.plan} plan, ${me.json.totalCredits} credits`);
+});
+program.command("account").description("Account info").command("status").description("Show credits and plan").action(async () => {
+  const me = await apiRequest(apiUrl(), "GET", "/api/mobile/me");
+  emit(
+    me.json,
+    `${me.json.email} \u2014 ${me.json.plan} plan
+Credits: ${me.json.credits} plan + ${me.json.additionalCredits} additional = ${me.json.totalCredits}`
+  );
+});
+var models = program.command("models").description("Model catalog");
+models.command("list").description("List available models").option("--type <type>", "image | video | voice").action(async (opts) => {
+  const result = await apiRequest(apiUrl(), "GET", "/api/mobile/models", {
+    query: { type: opts.type },
+    requireAuth: false
+  });
+  const list = result.json.models ?? [];
+  emit(result.json, list.map((m) => `${m.id.padEnd(36)} ${m.type.padEnd(6)} ${m.label}`).join("\n"));
+});
+var generate = program.command("generate").description("Create generations");
+addWaitOptions(
+  generate.command("image").description("Generate images from a prompt").requiredOption("--prompt <text>", "text prompt").option("--model <id>", "model id (see: nsketch models list --type image)").option("--aspect-ratio <ratio>", "e.g. 1:1, 16:9, 9:16").option("--num <count>", "number of images (1-4)").option("--image <pathOrUrl...>", "reference images for edit models (local path or URL)")
+).action(
+  async (opts) => {
+    const imageUrls = opts.image ? await Promise.all(opts.image.map((value) => resolveMedia(apiUrl(), value))) : void 0;
+    const result = await apiRequest(apiUrl(), "POST", "/api/mobile/generate-images", {
+      body: {
+        prompt: opts.prompt,
+        model: opts.model,
+        aspectRatio: opts.aspectRatio,
+        numImages: opts.num ? Number(opts.num) : void 0,
+        attachmentImages: imageUrls?.map((url) => ({ url }))
+      }
+    });
+    if (result.json.images) {
+      emit(result.json, extractResultUrls(result.json).join("\n"));
+      return;
+    }
+    await finishGeneration(
+      result.json,
+      {
+        type: "image",
+        requestId: String(result.json.requestId),
+        model: String(result.json.modelId ?? opts.model ?? "")
+      },
+      opts
+    );
+  }
+);
+addWaitOptions(
+  generate.command("video").description("Generate a video from a prompt (optionally image-to-video)").requiredOption("--prompt <text>", "text prompt").option("--model <id>", "model id (see: nsketch models list --type video)").option("--image <pathOrUrl>", "source image for image-to-video").option("--start-frame <pathOrUrl>").option("--end-frame <pathOrUrl>").option("--duration <seconds>").option("--resolution <res>", "e.g. 720p, 1080p").option("--aspect-ratio <ratio>").option("--audio", "generate audio where supported")
+).action(
+  async (opts) => {
+    const result = await apiRequest(apiUrl(), "POST", "/api/mobile/generate-video", {
+      body: {
+        prompt: opts.prompt,
+        model: opts.model,
+        imageUrl: await resolveMedia(apiUrl(), opts.image),
+        startFrameImageUrl: await resolveMedia(apiUrl(), opts.startFrame),
+        endFrameImageUrl: await resolveMedia(apiUrl(), opts.endFrame),
+        duration: opts.duration ? Number(opts.duration) : void 0,
+        resolution: opts.resolution,
+        aspectRatio: opts.aspectRatio,
+        generateAudio: opts.audio
+      }
+    });
+    await finishGeneration(
+      result.json,
+      {
+        type: "video",
+        requestId: String(result.json.requestId ?? result.json.taskId),
+        model: String(result.json.modelId ?? opts.model ?? ""),
+        endpoint: typeof result.json.endpoint === "string" ? result.json.endpoint : void 0
+      },
+      opts
+    );
+  }
+);
+generate.command("voice").description("Generate speech from a script (text-to-speech)").requiredOption("--script <text>").option("--voice <preset>", "preset voice name").option("--voice-id <id>", "cloned voice id").option("--model <id>", "voice model id").option("--language <lang>").action(
+  async (opts) => {
+    const result = await apiRequest(apiUrl(), "POST", "/api/generate-voice", {
+      body: {
+        script: opts.script,
+        voicePreset: opts.voice,
+        voiceId: opts.voiceId,
+        modelId: opts.model,
+        language: opts.language
+      }
+    });
+    emit(result.json, extractResultUrls(result.json).join("\n") || JSON.stringify(result.json, null, 2));
+  }
+);
+generate.command("clone-voice").description("Clone a voice from an audio sample").requiredOption("--audio <pathOrUrl>").requiredOption("--name <name>").option("--gender <gender>").option("--language <lang>", "source language").action(async (opts) => {
+  const result = await apiRequest(apiUrl(), "POST", "/api/clone-voice-sonic", {
+    body: {
+      audioUrl: await resolveMedia(apiUrl(), opts.audio),
+      name: opts.name,
+      gender: opts.gender,
+      sourceLanguage: opts.language
+    }
+  });
+  emit(result.json);
+});
+addWaitOptions(
+  generate.command("motion-transfer").description("Transfer motion from a reference video onto a character image").requiredOption("--image <pathOrUrl>", "character image").requiredOption("--video <pathOrUrl>", "reference video").option("--prompt <text>").option("--mode <mode>", "standard | pro").option("--aspect-ratio <ratio>", "default 9:16")
+).action(
+  async (opts) => {
+    const result = await apiRequest(apiUrl(), "POST", "/api/mobile/motion-transfer", {
+      body: {
+        imageUrl: await resolveMedia(apiUrl(), opts.image),
+        videoUrl: await resolveMedia(apiUrl(), opts.video),
+        prompt: opts.prompt,
+        mode: opts.mode,
+        aspectRatio: opts.aspectRatio
+      }
+    });
+    await finishGeneration(
+      result.json,
+      { type: "generic", requestId: String(result.json.taskId) },
+      opts
+    );
+  }
+);
+generate.command("lipsync").description("Lipsync a video (or animate a photo) to audio").requiredOption("--audio <pathOrUrl>").option("--video <pathOrUrl>", "video to lipsync").option("--image <pathOrUrl>", "photo to animate (talking photo)").option("--mode <mode>", "standard | pro").action(
+  async (opts) => {
+    if (!opts.video && !opts.image) fail("Provide --video or --image");
+    const audioUrl = await resolveMedia(apiUrl(), opts.audio);
+    const result = opts.video ? await apiRequest(apiUrl(), "POST", "/api/video-lipsync", {
+      body: {
+        videoUrl: await resolveMedia(apiUrl(), opts.video),
+        audioUrl,
+        mode: opts.mode
+      }
+    }) : await apiRequest(apiUrl(), "POST", "/api/talking-photo", {
+      body: {
+        imageUrl: await resolveMedia(apiUrl(), opts.image),
+        audioUrl,
+        mode: opts.mode,
+        mediaType: "image"
+      }
+    });
+    emit(result.json);
+  }
+);
+generate.command("upscale").description("Upscale/enhance an image").requiredOption("--image <pathOrUrl>").option("--mode <mode>", "magic | crystal | 4k", "magic").option("--scale <factor>").option("--prompt <text>", "only used by magic mode").action(
+  async (opts) => {
+    const imageUrl = await resolveMedia(apiUrl(), opts.image);
+    const path3 = opts.mode === "4k" ? "/api/mobile/4k-enhancer" : opts.mode === "crystal" ? "/api/crystal-upscale" : "/api/magic-upscale";
+    const result = await apiRequest(apiUrl(), "POST", path3, {
+      body: {
+        imageUrl,
+        scaleFactor: opts.scale ? Number(opts.scale) : void 0,
+        ...opts.mode === "magic" ? { prompt: opts.prompt } : {}
+      }
+    });
+    emit(result.json, extractResultUrls(result.json).join("\n") || JSON.stringify(result.json, null, 2));
+  }
+);
+generate.command("remove-bg").description("Remove the background from an image").requiredOption("--image <pathOrUrl>").action(async (opts) => {
+  const result = await apiRequest(apiUrl(), "POST", "/api/background-remove", {
+    body: { imageUrl: await resolveMedia(apiUrl(), opts.image) }
+  });
+  emit(result.json, extractResultUrls(result.json).join("\n") || JSON.stringify(result.json, null, 2));
+});
+addWaitOptions(
+  generate.command("reshoot").description("Place a character (soul) into a source photo").requiredOption("--source <pathOrUrl>", "source photo/scene").option("--soul <id>", "existing soul/character id").option("--reference <pathOrUrl>", "character reference image").option("--aspect-ratio <ratio>").option("--num <count>")
+).action(
+  async (opts) => {
+    const result = await apiRequest(apiUrl(), "POST", "/api/mobile/reshoot", {
+      body: {
+        sourceUrl: await resolveMedia(apiUrl(), opts.source),
+        soulId: opts.soul,
+        referenceImageUrl: await resolveMedia(apiUrl(), opts.reference),
+        aspectRatio: opts.aspectRatio,
+        numImages: opts.num ? Number(opts.num) : void 0
+      }
+    });
+    const requestId = result.json.requestId ?? result.json.clientRequestId;
+    if (!requestId) {
+      emit(result.json);
+      return;
+    }
+    await finishGeneration(result.json, { type: "generic", requestId: String(requestId) }, opts);
+  }
+);
+program.command("status <requestId>").description("Check a generation by request id").option("--type <type>", "image | video | generic", "generic").option("--model <id>", "model id from the submit response").option("--endpoint <endpoint>", "endpoint from the video submit response").option("--wait", "block until finished").option("--wait-timeout <duration>", "max time to wait", "10m").option("--wait-interval <duration>", "poll interval", "3s").action(
+  async (requestId, opts) => {
+    const target = { type: opts.type, requestId, model: opts.model, endpoint: opts.endpoint };
+    const result = opts.wait ? await waitForCompletion(apiUrl(), target, {
+      timeoutMs: parseDuration(opts.waitTimeout),
+      intervalMs: parseDuration(opts.waitInterval)
+    }) : await fetchStatus(apiUrl(), target);
+    const urls = extractResultUrls(result.json);
+    emit(
+      { http_status: result.status, ...result.json },
+      result.status === 202 ? "Still processing." : urls.join("\n") || JSON.stringify(result.json, null, 2)
+    );
+  }
+);
+program.command("upload <file>").description("Upload a local file to Nsketch media storage; prints the hosted URL").action(async (file) => {
+  const url = await uploadFile(apiUrl(), file);
+  emit({ url }, url);
+});
+program.parseAsync().catch((err) => {
+  if (err instanceof ApiError) {
+    fail(err.message, err.payload);
+  }
+  fail(err instanceof Error ? err.message : String(err));
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nsketch/cli",
+  "version": "0.1.0",
+  "description": "Nsketch AI CLI — generate images, videos, voice, and more from your terminal or AI agent.",
+  "license": "MIT",
+  "homepage": "https://github.com/Nsketch-AI/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nsketch-AI/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nsketch-AI/cli/issues"
+  },
+  "type": "module",
+  "bin": {
+    "nsketch": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "open": "^10.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2"
+  },
+  "keywords": [
+    "nsketch",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "cli"
+  ]
+}