@vargai/sdk 0.1.1

package/cli/commands/find.ts

@@ -0,0 +1,58 @@
+/**
+ * varg find command
+ * fuzzy search by scanning filesystem
+ */
+
+import { defineCommand } from "citty";
+import { search } from "../discover";
+import { box, c, header, separator } from "../ui";
+
+export const findCmd = defineCommand({
+  meta: {
+    name: "find",
+    description: "fuzzy search for models/actions",
+  },
+  args: {
+    query: {
+      type: "positional",
+      description: "search query",
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const query = args.query;
+
+    if (!query) {
+      console.error(`${c.red("error:")} search query required`);
+      console.log(`\nusage: ${c.cyan("varg find <query>")}`);
+      process.exit(1);
+    }
+
+    const results = await search(query);
+
+    if (results.length === 0) {
+      console.log(`\nno matches for "${query}"`);
+      console.log(`\ntry ${c.cyan("varg list")} to see all available actions`);
+      return;
+    }
+
+    const content: string[] = [];
+    content.push("");
+    content.push(header("MATCHES"));
+    content.push("");
+
+    for (const action of results) {
+      content.push(
+        `  ${c.cyan(action.name.padEnd(16))}${action.inputType} → ${action.outputType}`,
+      );
+    }
+
+    content.push("");
+    content.push(separator());
+    content.push("");
+    content.push(`  run ${c.cyan("varg run <name> --help")} for usage`);
+    content.push("");
+
+    console.log(box(`search: "${query}"`, content));
+  },
+});

package/cli/commands/help.ts

@@ -0,0 +1,70 @@
+/**
+ * varg help command
+ */
+
+import { defineCommand } from "citty";
+import { box, c, header, separator } from "../ui";
+
+export const helpCmd = defineCommand({
+  meta: {
+    name: "help",
+    description: "show help",
+  },
+  run() {
+    const content: string[] = [];
+    content.push("");
+    content.push("  AI video infrastructure from your terminal.");
+    content.push("");
+    content.push(separator());
+    content.push("");
+    content.push(header("USAGE"));
+    content.push("");
+    content.push(`  varg ${c.cyan("<command>")} [target] [options]`);
+    content.push("");
+    content.push(separator());
+    content.push("");
+    content.push(header("COMMANDS"));
+    content.push("");
+    content.push(`  ${c.cyan("run".padEnd(12))}run a model or action`);
+    content.push(`  ${c.cyan("list".padEnd(12))}discover what's available`);
+    content.push(
+      `  ${c.cyan("find".padEnd(12))}fuzzy search for models/actions`,
+    );
+    content.push(
+      `  ${c.cyan("which".padEnd(12))}inspect what's behind an action`,
+    );
+    content.push(`  ${c.cyan("help".padEnd(12))}show this help`);
+    content.push("");
+    content.push(separator());
+    content.push("");
+    content.push(header("EXAMPLES"));
+    content.push("");
+    content.push(`  ${c.dim("# generate video from text")}`);
+    content.push(`  varg run kling --prompt "a cat dancing"`);
+    content.push("");
+    content.push(`  ${c.dim("# animate an image")}`);
+    content.push(`  varg run image-to-video --image ./cat.png`);
+    content.push("");
+    content.push(`  ${c.dim("# transcribe audio")}`);
+    content.push(`  varg run transcribe ./video.mp4`);
+    content.push("");
+    content.push(`  ${c.dim("# see what's available")}`);
+    content.push(`  varg list`);
+    content.push("");
+    content.push(separator());
+    content.push("");
+    content.push(header("ENVIRONMENT"));
+    content.push("");
+    content.push(`  ${c.dim("FAL_KEY".padEnd(24))}fal.ai api key`);
+    content.push(
+      `  ${c.dim("REPLICATE_API_TOKEN".padEnd(24))}replicate api key`,
+    );
+    content.push(
+      `  ${c.dim("ELEVENLABS_API_KEY".padEnd(24))}elevenlabs api key`,
+    );
+    content.push(`  ${c.dim("GROQ_API_KEY".padEnd(24))}groq api key`);
+    content.push("");
+
+    console.log(box("varg", content));
+  },
+});

package/cli/commands/list.ts

@@ -0,0 +1,49 @@
+/**
+ * varg list command
+ * discover what's available by scanning filesystem
+ */
+
+import { defineCommand } from "citty";
+import { discoverActions } from "../discover";
+import { box, c, header, separator, table } from "../ui";
+
+export const listCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "discover what's available",
+  },
+  args: {
+    filter: {
+      type: "positional",
+      description: "filter by type",
+      required: false,
+    },
+  },
+  async run() {
+    const actions = await discoverActions();
+
+    const content: string[] = [];
+    content.push("");
+
+    content.push(header("ACTIONS"));
+    content.push("");
+
+    const rows = actions.map((a) => ({
+      name: a.name,
+      description:
+        `${a.inputType} → ${a.outputType}`.padEnd(20) + a.description,
+    }));
+
+    content.push(...table(rows));
+    content.push("");
+
+    content.push(separator());
+    content.push("");
+    content.push(
+      `  ${actions.length} actions · run ${c.cyan("varg run <action> --info")} for details`,
+    );
+    content.push("");
+
+    console.log(box("varg", content));
+  },
+});

package/cli/commands/run.ts

@@ -0,0 +1,237 @@
+/**
+ * varg run command
+ * execute actions by scanning filesystem
+ */
+
+import { existsSync } from "node:fs";
+import { defineCommand } from "citty";
+import { resolve } from "../discover";
+import type { Meta } from "../types";
+import { box, c, runningBox } from "../ui";
+
+interface RunOptions {
+  [key: string]: string | boolean | undefined;
+  info?: boolean;
+  schema?: boolean;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+function parseArgs(args: string[]): { target: string; options: RunOptions } {
+  const options: RunOptions = {};
+  let target = "";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (
+        key === "info" ||
+        key === "schema" ||
+        key === "json" ||
+        key === "quiet"
+      ) {
+        options[key] = true;
+      } else {
+        const value = args[++i];
+        if (value) options[key] = value;
+      }
+    } else if (!target) {
+      target = arg;
+    } else {
+      // positional args - check if it looks like a file
+      if (existsSync(arg) || arg.startsWith("./") || arg.startsWith("/")) {
+        if (!options.image && !options.audio) {
+          options.image = arg;
+        }
+      } else if (!options.prompt && !options.text) {
+        options.prompt = arg;
+      }
+    }
+  }
+
+  return { target, options };
+}
+
+function showHelp(item: Meta) {
+  const content: string[] = [];
+  content.push("");
+  content.push(`  ${item.description}`);
+  content.push("");
+  content.push(c.bold(c.dim("  USAGE")));
+  content.push("");
+
+  const required = item.schema.input.required;
+  const reqArgs = required.map((r) => `--${r} <${r}>`).join(" ");
+  content.push(`    varg run ${item.name} ${reqArgs} [options]`);
+
+  content.push("");
+  content.push(c.bold(c.dim("  OPTIONS")));
+  content.push("");
+
+  for (const [key, prop] of Object.entries(item.schema.input.properties)) {
+    const req = item.schema.input.required.includes(key);
+    const reqTag = req ? c.yellow(" (required)") : "";
+    const defaultVal =
+      prop.default !== undefined ? c.dim(` default: ${prop.default}`) : "";
+    const enumVals = prop.enum ? c.dim(` [${prop.enum.join(", ")}]`) : "";
+
+    content.push(
+      `    --${key.padEnd(12)}${prop.description}${reqTag}${defaultVal}${enumVals}`,
+    );
+  }
+
+  content.push("");
+  content.push(`    --json          output result as json`);
+  content.push(`    --quiet         minimal output`);
+  content.push(`    --info          show this help`);
+  content.push("");
+
+  console.log(box(`action: ${item.name}`, content));
+}
+
+function showSchema(item: Meta) {
+  const schema = {
+    name: item.name,
+    type: item.type,
+    description: item.description,
+    input: item.schema.input,
+    output: item.schema.output,
+  };
+
+  console.log(JSON.stringify(schema, null, 2));
+}
+
+export const runCmd = defineCommand({
+  meta: {
+    name: "run",
+    description: "run a model or action",
+  },
+  args: {
+    target: {
+      type: "positional",
+      description: "action to run",
+      required: false,
+    },
+    info: {
+      type: "boolean",
+      description: "show action info",
+    },
+    schema: {
+      type: "boolean",
+      description: "show action schema as json",
+    },
+    json: {
+      type: "boolean",
+      description: "output result as json",
+    },
+    quiet: {
+      type: "boolean",
+      description: "minimal output",
+    },
+  },
+  async run({ rawArgs }) {
+    // use rawArgs for dynamic action options
+    const { target, options } = parseArgs(rawArgs);
+
+    if (!target) {
+      console.error(`${c.red("error:")} target required`);
+      console.log(`\nusage: ${c.cyan("varg run <action> [options]")}`);
+      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
+      process.exit(1);
+    }
+
+    const item = await resolve(target);
+
+    if (!item) {
+      console.error(`${c.red("error:")} '${target}' not found`);
+      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
+      process.exit(1);
+    }
+
+    if (options.info) {
+      showHelp(item);
+      return;
+    }
+
+    if (options.schema) {
+      showSchema(item);
+      return;
+    }
+
+    // validate required args
+    for (const req of item.schema.input.required) {
+      if (!options[req]) {
+        console.error(`${c.red("error:")} --${req} is required`);
+        console.log(`\nrun ${c.cyan(`varg run ${target} --info`)} for usage`);
+        process.exit(1);
+      }
+    }
+
+    // build params for display
+    const params: Record<string, string> = {};
+    for (const key of Object.keys(item.schema.input.properties)) {
+      if (options[key] && typeof options[key] === "string") {
+        params[key] = options[key] as string;
+      }
+    }
+
+    if (!options.quiet && !options.json) {
+      console.log(runningBox(target, params, "running"));
+    }
+
+    const startTime = Date.now();
+
+    try {
+      const result = await item.run(options);
+      const elapsed = Date.now() - startTime;
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: true, result, time: elapsed }));
+      } else if (options.quiet) {
+        console.log(JSON.stringify(result));
+      } else {
+        // extract url from result if present
+        const resultObj = result as Record<string, unknown> | null;
+        const url =
+          resultObj?.imageUrl || resultObj?.videoUrl || resultObj?.url || null;
+
+        console.log("\x1b[2J\x1b[H");
+        console.log(
+          runningBox(target, params, "done", {
+            output: url ? "saved" : "done",
+            time: elapsed,
+          }),
+        );
+
+        // print url outside box so it's clickable
+        if (url) {
+          console.log(`\n  ${c.cyan("url")}  ${url}\n`);
+        }
+      }
+    } catch (err) {
+      const elapsed = Date.now() - startTime;
+      const errorMsg = err instanceof Error ? err.message : String(err);
+
+      if (options.json) {
+        console.log(
+          JSON.stringify({ success: false, error: errorMsg, time: elapsed }),
+        );
+      } else if (options.quiet) {
+        console.error(errorMsg);
+      } else {
+        console.log("\x1b[2J\x1b[H");
+        console.log(
+          runningBox(target, params, "error", {
+            error: errorMsg,
+            time: elapsed,
+          }),
+        );
+      }
+
+      process.exit(1);
+    }
+  },
+});

package/cli/commands/which.ts

@@ -0,0 +1,66 @@
+/**
+ * varg which command
+ * inspect an action by scanning filesystem
+ */
+
+import { defineCommand } from "citty";
+import { resolve } from "../discover";
+import { box, c, header, separator } from "../ui";
+
+export const whichCmd = defineCommand({
+  meta: {
+    name: "which",
+    description: "inspect what's behind an action",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "action name",
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const name = args.name;
+
+    if (!name) {
+      console.error(`${c.red("error:")} action name required`);
+      console.log(`\nusage: ${c.cyan("varg which <name>")}`);
+      process.exit(1);
+    }
+
+    const item = await resolve(name);
+
+    if (!item) {
+      console.error(`${c.red("error:")} '${name}' not found`);
+      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
+      process.exit(1);
+    }
+
+    const content: string[] = [];
+    content.push("");
+    content.push(`  ${item.description}`);
+    content.push("");
+
+    content.push(header("SCHEMA"));
+    content.push("");
+
+    for (const [key, prop] of Object.entries(item.schema.input.properties)) {
+      const required = item.schema.input.required.includes(key);
+      const reqTag = required ? c.yellow("*") : " ";
+      const defaultVal = prop.default
+        ? c.dim(` (default: ${prop.default})`)
+        : "";
+      content.push(
+        `  ${reqTag}${c.cyan(key.padEnd(12))}${prop.description}${defaultVal}`,
+      );
+    }
+
+    content.push("");
+    content.push(separator());
+    content.push("");
+    content.push(`  run ${c.cyan(`varg run ${name} --info`)} for full options`);
+    content.push("");
+
+    console.log(box(`action: ${name}`, content));
+  },
+});

package/cli/discover.ts

@@ -0,0 +1,66 @@
+/**
+ * filesystem-based discovery for varg cli
+ * scans action/ directory for modules with meta exports
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ActionMeta, Meta } from "./types";
+
+const ACTION_DIR = join(import.meta.dir, "..", "action");
+
+let cachedActions: ActionMeta[] | null = null;
+
+export async function discoverActions(): Promise<ActionMeta[]> {
+  if (cachedActions) return cachedActions;
+
+  const actions: ActionMeta[] = [];
+  const dirs = await readdir(ACTION_DIR);
+
+  for (const dir of dirs) {
+    try {
+      const mod = await import(`../action/${dir}`);
+      if (mod.meta && mod.meta.type === "action") {
+        actions.push(mod.meta);
+      }
+    } catch {
+      // skip directories without valid modules
+    }
+  }
+
+  cachedActions = actions;
+  return actions;
+}
+
+export async function resolve(name: string): Promise<Meta | null> {
+  const actions = await discoverActions();
+
+  // check explicit namespace
+  if (name.startsWith("action/")) {
+    const actionName = name.slice(7);
+    return actions.find((a) => a.name === actionName) || null;
+  }
+
+  // check actions
+  const action = actions.find((a) => a.name === name);
+  if (action) return action;
+
+  return null;
+}
+
+export async function search(query: string): Promise<Meta[]> {
+  const actions = await discoverActions();
+  const q = query.toLowerCase();
+
+  return actions.filter(
+    (a) =>
+      a.name.toLowerCase().includes(q) ||
+      a.description.toLowerCase().includes(q) ||
+      a.inputType.toLowerCase().includes(q) ||
+      a.outputType.toLowerCase().includes(q),
+  );
+}
+
+export async function list(): Promise<Meta[]> {
+  return discoverActions();
+}

package/cli/index.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+/**
+ * varg cli
+ * ai video infrastructure from your terminal
+ */
+
+import { defineCommand, runMain } from "citty";
+import { findCmd } from "./commands/find";
+import { helpCmd } from "./commands/help";
+import { listCmd } from "./commands/list";
+import { runCmd } from "./commands/run";
+import { whichCmd } from "./commands/which";
+
+const main = defineCommand({
+  meta: {
+    name: "varg",
+    version: "0.1.0",
+    description: "ai video infrastructure from your terminal",
+  },
+  subCommands: {
+    run: runCmd,
+    list: listCmd,
+    ls: listCmd,
+    find: findCmd,
+    search: findCmd,
+    which: whichCmd,
+    inspect: whichCmd,
+    help: helpCmd,
+  },
+});
+
+runMain(main);

package/cli/runner.ts

@@ -0,0 +1,65 @@
+/**
+ * shared cli runner for actions
+ * parses args and calls meta.run()
+ */
+
+import type { Meta } from "./types";
+
+export async function runCli(meta: Meta) {
+  const args = process.argv.slice(2);
+
+  if (args[0] === "help" || args[0] === "--help" || args.length === 0) {
+    console.log(`
+${meta.name} - ${meta.description}
+
+usage:
+  bun run action/${meta.name} [options]
+
+options:`);
+
+    for (const [key, prop] of Object.entries(meta.schema.input.properties)) {
+      const req = meta.schema.input.required.includes(key) ? " (required)" : "";
+      const def =
+        prop.default !== undefined ? ` [default: ${prop.default}]` : "";
+      console.log(`  --${key.padEnd(14)} ${prop.description}${req}${def}`);
+    }
+
+    console.log(`
+examples:
+  bun run action/${meta.name} --${meta.schema.input.required[0]} "value"
+`);
+    return;
+  }
+
+  // parse args
+  const options: Record<string, unknown> = {};
+  const firstRequired = meta.schema.input.required[0];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg?.startsWith("--")) {
+      const key = arg.slice(2);
+      const value = args[++i];
+      options[key] = value;
+    } else if (arg && firstRequired && !options[firstRequired]) {
+      // first positional arg goes to first required field
+      options[firstRequired] = arg;
+    }
+  }
+
+  // validate required
+  for (const req of meta.schema.input.required) {
+    if (!options[req]) {
+      console.error(`error: --${req} is required`);
+      process.exit(1);
+    }
+  }
+
+  try {
+    const result = await meta.run(options);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    console.error(`error: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+}

package/cli/types.ts

@@ -0,0 +1,49 @@
+/**
+ * shared types for varg cli
+ * actions and models export meta objects conforming to these types
+ */
+
+export interface SchemaProperty {
+  type: string;
+  description: string;
+  enum?: (string | number)[];
+  default?: unknown;
+  format?: string;
+}
+
+export interface Schema {
+  input: {
+    type: "object";
+    required: string[];
+    properties: Record<string, SchemaProperty>;
+  };
+  output: {
+    type: string;
+    format?: string;
+    description: string;
+  };
+}
+
+export interface ActionMeta {
+  name: string;
+  type: "action";
+  description: string;
+  inputType: string;
+  outputType: string;
+  schema: Schema;
+  run: (options: Record<string, unknown>) => Promise<unknown>;
+}
+
+export interface ModelMeta {
+  name: string;
+  type: "model";
+  description: string;
+  inputType: string;
+  outputType: string;
+  providers: string[];
+  defaultProvider: string;
+  schema: Schema;
+  run: (options: Record<string, unknown>) => Promise<unknown>;
+}
+
+export type Meta = ActionMeta | ModelMeta;