videodraft 0.2.0 → 0.3.0

package/README.md

@@ -30,18 +30,9 @@ export VIDEODRAFT_API_KEY=vd_mcp_…  # headless / CI — no login command neede
 
 Credentials are stored in `~/.config/videodraft/config.json` (0600). `videodraft logout` revokes and clears them.
 
-## The pipeline
+## Asset generation first
 
-```bash
-videodraft credits                              # know your budget
-videodraft create "<idea>" --ar 9:16            # idea → script → visual assets → storyboard
-videodraft shots <project> --grid --estimate    # preview the cost…
-videodraft shots <project> --grid               # …then batch-generate every shot image
-videodraft produce <project>                    # voiceovers + captions + production timeline
-videodraft export <project> --download final.mp4
-```
-
-Single assets don't need a project:
+Standalone images, clips and audio are complete deliverables. They do not need a VideoDraft project unless you want to attach them to an existing project or turn them into a multi-scene production.
 
 ```bash
 videodraft generate image "isometric workspace, warm light" --num 4 --download "./out/{job_id}_{index}.{ext}"
@@ -56,6 +47,32 @@ videodraft upscale image ./photo.png --scale 4x --download ./photo-4x.png
 videodraft avatar create ./founder.jpg --script "$(videodraft avatar script 'our launch' --json | jq -r .script)"
 ```
 
+Discover the full asset lane:
+
+```bash
+videodraft tools list
+videodraft tools list --lane assets
+videodraft tools list --lane asset_io
+videodraft models image
+videodraft models video
+videodraft models audio
+```
+
+Asset I/O is part of the asset workflow: `videodraft upload`, `videodraft download`, generation `--download`, and local refs like `--ref ./image.png` make files usable by agents and visible in local workspaces.
+
+## The project pipeline
+
+Use projects when the user asks for a story, storyboard, editable web project, timeline, production flow, or exported MP4.
+
+```bash
+videodraft credits                              # know your budget
+videodraft create "<idea>" --ar 9:16            # idea → script → visual assets → storyboard
+videodraft shots <project> --grid --estimate    # preview the cost…
+videodraft shots <project> --grid               # …then batch-generate every shot image
+videodraft produce <project>                    # voiceovers + captions + production timeline
+videodraft export <project> --download final.mp4
+```
+
 ## Commands
 
 | Group | Commands |
@@ -67,7 +84,7 @@ videodraft avatar create ./founder.jpg --script "$(videodraft avatar script 'our
 | Generate | `generate image/video/voiceover/music/sound-effect/dialogue/voice-changer/dub` `upscale image/video` `avatar script/create/render/get/list` |
 | Jobs | `status <job>` `wait <job>` `generations` |
 | Media | `upload <file>` `media list` `describe <url\|file>` `download <url>` |
-| Everything else | `tools list` `tools schema <name>` `call <tool> --args '<json>'` |
+| Everything else | `tools list [--lane assets\|asset_io\|project_data\|production]` `tools schema <name>` `call <tool> --args '<json>'` |
 | Agents | `skills install [--agent claude\|codex\|cursor]` `skills path` |
 | Utility | `config get/set/path` `completion bash\|zsh` `docs` `--version` |
 

package/dist/client.d.ts

@@ -38,6 +38,13 @@ declare class VideoDraftClient {
     get endpoint(): string;
     rpc<T = any>(method: string, params?: unknown): Promise<T>;
     private post;
+    /**
+     * Make an authenticated REST request to a non-MCP API route (e.g.
+     * /api/elevenlabs-key, which manages the user's BYOK ElevenLabs key and has no
+     * MCP tool by design). Uses the same bearer token + 401 refresh as rpc().
+     * Returns the parsed JSON body; throws on non-2xx with the server's error.
+     */
+    restRequest<T = any>(method: string, path: string, body?: unknown): Promise<T>;
     /**
      * Batch several JSON-RPC requests into ONE HTTP round trip (the server
      * implements JSON-RPC 2.0 batching). With N concurrent jobs this turns N

package/dist/client.js

@@ -264,6 +264,43 @@ var VideoDraftClient = class {
       signal: AbortSignal.timeout(this.requestTimeoutMs)
     });
   }
+  /**
+   * Make an authenticated REST request to a non-MCP API route (e.g.
+   * /api/elevenlabs-key, which manages the user's BYOK ElevenLabs key and has no
+   * MCP tool by design). Uses the same bearer token + 401 refresh as rpc().
+   * Returns the parsed JSON body; throws on non-2xx with the server's error.
+   */
+  async restRequest(method, path4, body) {
+    const doFetch = (token2) => this.fetchImpl(`${this.baseUrl}${path4}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${token2}`,
+        "user-agent": this.userAgent
+      },
+      ...body === void 0 ? {} : { body: JSON.stringify(body) },
+      signal: AbortSignal.timeout(this.requestTimeoutMs)
+    });
+    const token = await this.tokenProvider.getAccessToken();
+    let response = await doFetch(token);
+    if (response.status === 401 && this.tokenProvider.onUnauthorized) {
+      const fresh = await this.tokenProvider.onUnauthorized();
+      if (fresh) response = await doFetch(fresh);
+    }
+    if (response.status === 401) {
+      throw new AuthError("Token is invalid, expired, or revoked.");
+    }
+    let parsed = null;
+    try {
+      parsed = await response.json();
+    } catch {
+    }
+    if (!response.ok) {
+      const detail = parsed?.error?.message ?? parsed?.error ?? `HTTP ${response.status}`;
+      throw new RpcError(response.status, detail);
+    }
+    return parsed;
+  }
   /**
    * Batch several JSON-RPC requests into ONE HTTP round trip (the server
    * implements JSON-RPC 2.0 batching). With N concurrent jobs this turns N

package/dist/index.js

@@ -24,8 +24,8 @@ function readVersionFromDisk() {
   }
 }
 function resolveVersion() {
-  if ("0.2.0") {
-    return "0.2.0";
+  if ("0.3.0") {
+    return "0.3.0";
   }
   return readVersionFromDisk();
 }
@@ -691,6 +691,43 @@ var VideoDraftClient = class {
       signal: AbortSignal.timeout(this.requestTimeoutMs)
     });
   }
+  /**
+   * Make an authenticated REST request to a non-MCP API route (e.g.
+   * /api/elevenlabs-key, which manages the user's BYOK ElevenLabs key and has no
+   * MCP tool by design). Uses the same bearer token + 401 refresh as rpc().
+   * Returns the parsed JSON body; throws on non-2xx with the server's error.
+   */
+  async restRequest(method, path5, body) {
+    const doFetch = (token2) => this.fetchImpl(`${this.baseUrl}${path5}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${token2}`,
+        "user-agent": this.userAgent
+      },
+      ...body === void 0 ? {} : { body: JSON.stringify(body) },
+      signal: AbortSignal.timeout(this.requestTimeoutMs)
+    });
+    const token = await this.tokenProvider.getAccessToken();
+    let response = await doFetch(token);
+    if (response.status === 401 && this.tokenProvider.onUnauthorized) {
+      const fresh = await this.tokenProvider.onUnauthorized();
+      if (fresh) response = await doFetch(fresh);
+    }
+    if (response.status === 401) {
+      throw new AuthError("Token is invalid, expired, or revoked.");
+    }
+    let parsed = null;
+    try {
+      parsed = await response.json();
+    } catch {
+    }
+    if (!response.ok) {
+      const detail = parsed?.error?.message ?? parsed?.error ?? `HTTP ${response.status}`;
+      throw new RpcError(response.status, detail);
+    }
+    return parsed;
+  }
   /**
    * Batch several JSON-RPC requests into ONE HTTP round trip (the server
    * implements JSON-RPC 2.0 batching). With N concurrent jobs this turns N
@@ -1057,6 +1094,127 @@ ${fmt.bold(ctxOut, "Open this URL to log in:")}
       ]);
     });
   });
+  const el = program.command("elevenlabs").description("Manage your ElevenLabs API key (BYOK) \u2014 use your cloned voices");
+  el.command("status").description("Show whether your ElevenLabs key is connected and active").action(async function() {
+    const ctx = buildContext(this);
+    const st = await ctx.client.restRequest("GET", "/api/elevenlabs-key");
+    emit(ctx.out, st, (o) => {
+      kv(o, [
+        ["Connected", st?.hasKey ? `yes (\u2022\u2022\u2022\u2022${st.hint ?? ""})` : "no"],
+        ["Active", st?.enabled ? "yes" : "no"],
+        ["Server", ctx.baseUrl]
+      ]);
+      if (!st?.hasKey) {
+        note(
+          o,
+          fmt.dim(o, "Connect one: videodraft elevenlabs set --key <xi-...>")
+        );
+      }
+    });
+  });
+  el.command("set").description("Connect (or replace) your ElevenLabs API key and activate it").option("--key <key>", "your ElevenLabs API key (xi-...)").option("--no-enable", "store the key without turning it on").action(async function() {
+    const opts = this.opts();
+    const ctx = buildContext(this);
+    let key = opts.key?.trim();
+    if (!key && !process.stdin.isTTY) key = (await readStdin()).trim();
+    if (!key) {
+      throw new CliError(
+        "Provide your key with --key <xi-...> (or pipe it via stdin).",
+        EXIT.USAGE
+      );
+    }
+    const spin = spinner(ctx.out, "Validating key with ElevenLabs\u2026");
+    try {
+      const res = await ctx.client.restRequest(
+        "POST",
+        "/api/elevenlabs-key",
+        { key, enabled: opts.enable !== false }
+      );
+      spin.stop();
+      capture("cli_elevenlabs_set");
+      emit(
+        ctx.out,
+        res,
+        (o) => note(
+          o,
+          fmt.green(
+            o,
+            `ElevenLabs key saved (\u2022\u2022\u2022\u2022${res.hint ?? ""})${res.enabled ? " and active \u2014 your cloned voices are ready." : " \u2014 run `videodraft elevenlabs enable` to turn it on."}`
+          )
+        )
+      );
+    } catch (e) {
+      spin.stop();
+      throw e;
+    }
+  });
+  el.command("enable").description("Turn your ElevenLabs key on").action(async function() {
+    const ctx = buildContext(this);
+    const res = await ctx.client.restRequest(
+      "PATCH",
+      "/api/elevenlabs-key",
+      { enabled: true }
+    );
+    emit(
+      ctx.out,
+      res,
+      (o) => note(o, fmt.green(o, "ElevenLabs key is now active."))
+    );
+  });
+  el.command("disable").description("Turn your ElevenLabs key off (use VideoDraft credits again)").action(async function() {
+    const ctx = buildContext(this);
+    const res = await ctx.client.restRequest(
+      "PATCH",
+      "/api/elevenlabs-key",
+      { enabled: false }
+    );
+    emit(
+      ctx.out,
+      res,
+      (o) => note(
+        o,
+        "ElevenLabs key disabled. ElevenLabs generations use the VideoDraft path."
+      )
+    );
+  });
+  el.command("remove").description("Delete your stored ElevenLabs API key").action(async function() {
+    const ctx = buildContext(this);
+    const res = await ctx.client.restRequest(
+      "DELETE",
+      "/api/elevenlabs-key"
+    );
+    capture("cli_elevenlabs_remove");
+    emit(
+      ctx.out,
+      res ?? { ok: true },
+      (o) => note(o, "ElevenLabs key removed.")
+    );
+  });
+  el.command("voices").description("List your ElevenLabs cloned/professional voices").action(async function() {
+    const ctx = buildContext(this);
+    const res = await ctx.client.callTool("list_cloned_voices");
+    emit(ctx.out, res, (o) => {
+      if (!res?.byok_active) {
+        note(
+          o,
+          fmt.dim(
+            o,
+            res?.hint ?? "Connect your ElevenLabs key first: videodraft elevenlabs set --key <xi-...>"
+          )
+        );
+        return;
+      }
+      const voices = res?.voices ?? [];
+      if (!voices.length) {
+        note(o, "No cloned voices in your ElevenLabs account yet.");
+        return;
+      }
+      kv(
+        o,
+        voices.map((v) => [v.name, v.id])
+      );
+    });
+  });
 }
 
 // src/commands/account.ts
@@ -2576,19 +2734,97 @@ function parseKeyValueArgs(pairs) {
   }
   return args;
 }
+var CATEGORY_ORDER = [
+  "asset_generation",
+  "asset_io",
+  "asset_library",
+  "project_creation",
+  "project_data",
+  "production",
+  "account_models_costs",
+  "jobs",
+  "danger_zone",
+  "raw"
+];
+var LANE_ORDER = [
+  "assets",
+  "asset_io",
+  "projects",
+  "project_data",
+  "production",
+  "library",
+  "account",
+  "danger",
+  "raw"
+];
+function firstSentence(description) {
+  return description.split(/[.!]\s/)[0].slice(0, 90);
+}
 function registerToolCommands(program) {
   const tools = program.command("tools").description("Inspect the full MCP tool catalog");
-  tools.command("list", { isDefault: true }).description("List every available tool").action(async function() {
+  tools.command("list", { isDefault: true }).description("List the grouped VideoDraft tool catalog").option(
+    "--lane <lane>",
+    "filter by lane: assets | asset_io | projects | project_data | production | library | account | danger | raw"
+  ).option(
+    "--category <category>",
+    "filter by category, e.g. asset_generation, asset_io, project_data, or production"
+  ).action(async function() {
     const ctx = buildContext(this);
-    const list = await ctx.client.listTools();
-    emit(ctx.out, list.map((t) => ({ name: t.name, description: t.description })), (o) => {
-      table(
+    const opts = this.opts();
+    if (opts.lane && !LANE_ORDER.includes(opts.lane)) {
+      throw new CliError(
+        `Unknown lane "${opts.lane}". Expected one of: ${LANE_ORDER.join(", ")}`,
+        EXIT.USAGE
+      );
+    }
+    if (opts.category && !CATEGORY_ORDER.includes(opts.category)) {
+      throw new CliError(
+        `Unknown category "${opts.category}". Expected one of: ${CATEGORY_ORDER.join(", ")}`,
+        EXIT.USAGE
+      );
+    }
+    let summary;
+    const catalog = await ctx.client.callTool(
+      "get_tool_catalog",
+      compact({ lane: opts.lane, category: opts.category })
+    );
+    summary = catalog?.tools ?? [];
+    emit(ctx.out, summary, (o) => {
+      const categories = Array.from(
+        new Set(summary.map((tool) => tool.category))
+      ).sort((a, b) => {
+        const ai = CATEGORY_ORDER.indexOf(a);
+        const bi = CATEGORY_ORDER.indexOf(b);
+        return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi) || a.localeCompare(b);
+      });
+      if (categories.length === 0) {
+        table(o, ["name", "type", "risk", "description"], []);
+      }
+      for (const category of categories) {
+        const rows = summary.filter((tool) => tool.category === category);
+        process.stdout.write(`
+${fmt.bold(o, category)}
+`);
+        table(
+          o,
+          ["name", "type", "risk", "description"],
+          rows.map((tool) => [
+            tool.name,
+            tool.subcategory ?? "",
+            tool.risks.join(","),
+            firstSentence(tool.description)
+          ])
+        );
+      }
+      const suffix = opts.lane ? ` in lane "${opts.lane}"` : opts.category ? ` in category "${opts.category}"` : "";
+      note(
         o,
-        ["name", "description"],
-        list.map((t) => [t.name, t.description.split(/[.!]\s/)[0].slice(0, 90)])
+        fmt.dim(
+          o,
+          `
+${summary.length} tools${suffix}. Inspect one: videodraft tools schema <name>`
+        )
       );
-      note(o, fmt.dim(o, `
-${list.length} tools. Inspect one: videodraft tools schema <name>`));
     });
   });
   tools.command("schema <name>").description("Show a tool's description and JSON input schema").action(async function(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "videodraft",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official VideoDraft CLI — create AI videos, images and audio from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
   "license": "MIT",
   "type": "module",

package/skills/videodraft/SKILL.md

@@ -5,7 +5,11 @@ description: Create AI videos, images, voiceovers, music, sound effects, dialogu
 
 # VideoDraft
 
-VideoDraft is an AI video creation platform: idea → script → storyboard (scenes + shot images) → production (voiceover, captions, motion clips, music) → exported MP4. You can drive all of it from this environment.
+VideoDraft is an AI video creation platform where asset generation is the priority lane:
+
+- **Asset generation**: standalone images, video clips, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.
+- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.
+- **Project production**: idea → script → storyboard (scenes + shot images) → project data → production timeline → exported MP4. Use this only when the user asks for a story, storyboard, editable project, timeline, or final video.
 
 ## How to connect
 
@@ -17,15 +21,18 @@ Two equivalent surfaces (same backend, same credits, same projects):
      • HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).
      • SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat — use browser `login` or the env var so the token never lands in the transcript.
    - Every command accepts `--json` (parse this, don't scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (→ tell the user, don't retry).
-   - Full API access: `videodraft tools list`, `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
+   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.
+   - Asset lane: `videodraft generate image|video|voiceover|music|sound-effect|dialogue|voice-changer|dub`, `videodraft upload`, and `videodraft download`.
+   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
 2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly — the CLI's curated commands map 1:1 onto these tools.
 
-## First decision: asset or video?
+## First decision: asset or project?
 
-- **One standalone asset** (a single image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, or dubbed media file, no story): generate it directly. Do NOT create a project.
+- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.
   - `videodraft generate image "a red fox in snow, cinematic" --ar 16:9 --download ./out/`
   - `videodraft generate video "slow dolly over a misty lake" --model google-veo3.1 --duration 6 --download ./out/`
-- **A video / ad / explainer / anything multi-scene**: create a project so the work stays organized, editable in the web app, and exportable.
+- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations, but do not make a storyboard/project unless the user asks for one.
+- **A multi-scene video / ad / explainer, storyboard, timeline, or final exported video**: create a project so the work stays organized, editable in the web app, and exportable.
   - `videodraft create "30s launch video for our espresso machine" --ar 9:16`
 - **Just a script** (no video asked for): `videodraft create "..." --script-only`. Stop at the script — do not build a storyboard the user didn't ask for.
 - **Iterating on existing work**: find it first (`videodraft projects list`) and reuse that project. Never create a new project to change an existing one.