agnes-ai-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jomeswang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# agnes-ai-cli
+
+CLI and JS API for Agnes text, image, and video workflows.
+
+## Install
+
+Current verified distribution path:
+
+```bash
+npm install -g github:jomeswang/agnes-ai-cli
+```
+
+Ad hoc execution without a global install:
+
+```bash
+npx -y github:jomeswang/agnes-ai-cli --help
+```
+
+Planned npm package name:
+
+```bash
+agnes-ai-cli
+```
+
+Once the npm publish path is cleared, the package will also be installable as:
+
+```bash
+npm install -g agnes-ai-cli
+```
+
+## CLI
+
+```bash
+agnes --help
+agnes auth check
+agnes media url ./input.png
+agnes text chat --prompt "say pong"
+agnes image text2img --prompt "a polished product photo of a perfume bottle"
+agnes image img2img --image ./input.png --prompt "turn this into a clean editorial poster"
+agnes video text2video --prompt "a cinematic drone shot of waves at dusk"
+agnes video img2video --image ./frame.png --prompt "animate subtle rain and drifting fog"
+agnes video multivideo --image ./frame-a.png --image ./frame-b.png --prompt "blend these references into one motion concept"
+agnes video keyframes --image ./frame-a.png --image ./frame-b.png --prompt "morph between the two scenes"
+agnes video poll <task-id>
+```
+
+## JS API
+
+```js
+import { createAgnesClient } from "agnes-ai-cli";
+
+const agnes = createAgnesClient({ apiKey: process.env.AGNES_API_KEY });
+
+const image = await agnes.image.generate({
+  mode: "text2img",
+  prompt: "A cinematic product shot of a silver watch on black stone."
+});
+
+console.log(image.url);
+```

package/bin/agnes.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from "../dist/cli.js";
+
+void runCli(process.argv);

package/dist/auth/check.d.ts

@@ -0,0 +1,7 @@
+export declare function checkAuth(config?: {
+    env?: NodeJS.ProcessEnv;
+}): {
+    readonly ok: boolean;
+    readonly configured: boolean;
+    readonly source: "env" | "missing";
+};

package/dist/auth/check.js

@@ -0,0 +1,10 @@
+import { resolveConfig } from "../config.js";
+export function checkAuth(config) {
+    const resolved = resolveConfig({ env: config?.env });
+    const configured = Boolean(resolved.apiKey);
+    return {
+        ok: configured,
+        configured,
+        source: configured ? "env" : "missing",
+    };
+}

package/dist/auth/saveKey.d.ts

@@ -0,0 +1,12 @@
+export interface SaveKeyOptions {
+    shell?: string;
+    homeDir?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface SaveKeyResult {
+    ok: true;
+    rcFile: string;
+    variable: "AGNES_API_KEY";
+}
+export declare function resolveRcFile(shellName: string | undefined, homeDir: string): string;
+export declare function saveKeyToShell(key: string, options?: SaveKeyOptions): Promise<SaveKeyResult>;

package/dist/auth/saveKey.js

@@ -0,0 +1,43 @@
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { AgnesCliError } from "../errors.js";
+export function resolveRcFile(shellName, homeDir) {
+    if (shellName === "zsh")
+        return join(homeDir, ".zshrc");
+    if (shellName === "bash")
+        return join(homeDir, ".bashrc");
+    return join(homeDir, ".profile");
+}
+export async function saveKeyToShell(key, options = {}) {
+    if (!key || !key.trim()) {
+        throw new AgnesCliError("INVALID_KEY", "Agnes API key is required.");
+    }
+    const env = options.env ?? process.env;
+    const shellName = options.shell ?? (env.SHELL ? env.SHELL.split("/").pop() : undefined);
+    const homeDir = options.homeDir ?? env.HOME;
+    if (!homeDir) {
+        throw new AgnesCliError("HOME_MISSING", "HOME is not available, so the shell rc file cannot be resolved.");
+    }
+    const rcFile = resolveRcFile(shellName, homeDir);
+    let existing = "";
+    try {
+        existing = await fs.readFile(rcFile, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const filtered = existing
+        .split("\n")
+        .filter((line) => !line.startsWith("export AGNES_API_KEY="))
+        .join("\n")
+        .replace(/\n*$/, "\n");
+    const escaped = shellEscape(key);
+    const next = `${filtered}\nexport AGNES_API_KEY=${escaped}\n`;
+    await fs.writeFile(rcFile, next, "utf8");
+    process.env.AGNES_API_KEY = key;
+    return { ok: true, rcFile, variable: "AGNES_API_KEY" };
+}
+function shellEscape(value) {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,431 @@
+import { Command } from "commander";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { saveKeyToShell } from "./auth/saveKey.js";
+import { createAgnesClient } from "./index.js";
+import { isAgnesCliError } from "./errors.js";
+import { printJson, printLines } from "./output.js";
+export async function runCli(argv = process.argv) {
+    const program = new Command();
+    program
+        .name("agnes")
+        .description("CLI for Agnes AI text, image, and video workflows, with auth and media URL bridging")
+        .version("0.1.0")
+        .addHelpText("after", `
+Examples:
+  agnes auth check
+  agnes media url ./input.png
+  agnes image img2img --image ./input.png --prompt "Turn this into an editorial campaign"
+  agnes video keyframes --image ./a.png --image ./b.png --prompt "Transition between these frames"
+
+Use this CLI when you want explicit Agnes request-shape handling, local-file URL bridging, or stable JSON output for agents.
+`);
+    const client = createAgnesClient();
+    const auth = program.command("auth").description("Inspect and configure Agnes auth");
+    auth.addHelpText("after", `
+Examples:
+  agnes auth check
+  agnes auth save-key --key sk-...
+
+Use this group to verify AGNES_API_KEY or persist it into the active shell rc file.
+`);
+    auth
+        .command("check")
+        .description("Check whether AGNES_API_KEY is configured")
+        .option("--json", "Output JSON")
+        .action((options) => {
+        const result = client.auth.check();
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        printLines([
+            result.configured ? "AGNES_API_KEY is configured." : "AGNES_API_KEY is missing.",
+            `source: ${result.source}`,
+        ]);
+    });
+    auth
+        .command("save-key")
+        .description("Persist AGNES_API_KEY into the current shell rc file")
+        .requiredOption("--key <value>", "Agnes API key to persist")
+        .option("--json", "Output JSON")
+        .action(async (options) => {
+        const result = await saveKeyToShell(options.key);
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        printLines([
+            "AGNES_API_KEY saved.",
+            `rc file: ${result.rcFile}`,
+        ]);
+    });
+    const media = program.command("media").description("Resolve Agnes media inputs");
+    media.addHelpText("after", `
+Examples:
+  agnes media url ./frame.png
+  agnes media url https://example.com/frame.png
+
+Use this group when Agnes requires a public image URL and your source asset is a local file path.
+`);
+    media
+        .command("url")
+        .description("Return a public URL for a local file or pass through an existing URL")
+        .argument("<file-or-url>", "Local file path or http(s) URL")
+        .option("--ttl <ttl>", "Litterbox TTL (1h, 12h, 24h, 72h)", "1h")
+        .option("--json", "Output JSON")
+        .action(async (input, options) => {
+        const result = await client.media.toPublicUrl(input, { ttl: ttlSchema.parse(options.ttl) });
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        console.log(result.url);
+    });
+    const text = program.command("text").description("Run Agnes text workflows");
+    text.addHelpText("after", `
+Examples:
+  agnes text chat --prompt "Reply with exactly pong."
+
+Use this group for Agnes chat/completions request shapes when you want a minimal one-shot text call through the CLI.
+`);
+    text
+        .command("chat")
+        .description("Run a one-shot Agnes chat completion")
+        .requiredOption("--prompt <text>", "Prompt text")
+        .option("--model <model>", "Agnes text model", "agnes-2.0-flash")
+        .option("--json", "Output JSON")
+        .addHelpText("after", `
+Example:
+  agnes text chat --prompt "Reply with exactly pong."
+
+Request shape:
+  Sends a single-user-message Agnes /chat/completions request with agnes-2.0-flash by default.
+`)
+        .action(async (options) => {
+        const result = await client.text.complete({
+            prompt: options.prompt,
+            model: options.model,
+        });
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        console.log(result.text);
+    });
+    const image = program.command("image").description("Generate Agnes images");
+    image.addHelpText("after", `
+Examples:
+  agnes image text2img --prompt "A luminous city at sunrise"
+  agnes image img2img --image ./input.png --prompt "Restyle this frame for a premium campaign"
+  agnes image compose --image ./a.png --image ./b.png --prompt "Blend these references"
+
+Use this group for /images/generations request shapes. text2img sends prompt-only payloads. img2img sends a single image URL. compose sends an image URL array.
+`);
+    image
+        .command("text2img")
+        .description("Generate an image from text")
+        .requiredOption("--prompt <text>", "Prompt text")
+        .option("--model <model>", "Agnes image model")
+        .option("--size <size>", "Image size, e.g. 1024x768")
+        .option("--seed <number>", "Seed", parseInteger)
+        .option("--json", "Output JSON")
+        .addHelpText("after", `
+Example:
+  agnes image text2img --prompt "A luminous city at sunrise" --size 1024x1024
+
+Request shape:
+  Sends prompt-only generation to Agnes /images/generations with agnes-image-2.1-flash by default.
+`)
+        .action(async (options) => {
+        const result = await client.image.generate({
+            mode: "text2img",
+            prompt: options.prompt,
+            model: options.model,
+            size: options.size,
+            seed: options.seed,
+        });
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        console.log(result.url);
+    });
+    image
+        .command("img2img")
+        .description("Generate an image from one input image")
+        .requiredOption("--image <path-or-url>", "Input image path or URL")
+        .requiredOption("--prompt <text>", "Prompt text")
+        .option("--model <model>", "Agnes image model")
+        .option("--size <size>", "Image size, e.g. 1024x768")
+        .option("--seed <number>", "Seed", parseInteger)
+        .option("--ttl <ttl>", "Temporary upload TTL", "1h")
+        .option("--json", "Output JSON")
+        .addHelpText("after", `
+Example:
+  agnes image img2img --image ./input.png --prompt "Turn this into an editorial travel poster"
+
+Request shape:
+  Resolves the local file to a public URL when needed, then sends a single Agnes image URL for image-to-image generation.
+`)
+        .action(async (options) => {
+        const result = await client.image.generate({
+            mode: "img2img",
+            image: options.image,
+            prompt: options.prompt,
+            model: options.model,
+            size: options.size,
+            seed: options.seed,
+            ttl: ttlSchema.parse(options.ttl),
+        });
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        console.log(result.url);
+    });
+    image
+        .command("compose")
+        .description("Generate an image from multiple input images")
+        .requiredOption("--image <path-or-url...>", "Repeatable image path or URL")
+        .requiredOption("--prompt <text>", "Prompt text")
+        .option("--model <model>", "Agnes image model")
+        .option("--size <size>", "Image size, e.g. 1024x768")
+        .option("--seed <number>", "Seed", parseInteger)
+        .option("--ttl <ttl>", "Temporary upload TTL", "1h")
+        .option("--json", "Output JSON")
+        .addHelpText("after", `
+Example:
+  agnes image compose --image ./a.png --image ./b.png --prompt "Blend these references into one campaign frame"
+
+Request shape:
+  Resolves each input to a public URL, preserves image order, and sends an Agnes image URL array for multi-image composition.
+`)
+        .action(async (options) => {
+        const images = toArray(options.image);
+        const result = await client.image.generate({
+            mode: "compose",
+            images,
+            prompt: options.prompt,
+            model: options.model,
+            size: options.size,
+            seed: options.seed,
+            ttl: ttlSchema.parse(options.ttl),
+        });
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        console.log(result.url);
+    });
+    const video = program.command("video").description("Generate Agnes videos");
+    video.addHelpText("after", `
+Examples:
+  agnes video text2video --prompt "A cinematic beach scene at sunset"
+  agnes video img2video --image ./frame.png --prompt "Add gentle wind and a soft push-in"
+  agnes video keyframes --image ./a.png --image ./b.png --prompt "Transition between the frames"
+  agnes video poll task_123
+
+Use this group for Agnes video task creation and polling. Video creation is asynchronous; poll returns the final result.
+`);
+    buildVideoGenerateCommand(video, "text2video", "Generate a video from text", async (client, options) => client.video.generate({
+        mode: "text2video",
+        prompt: options.prompt,
+        width: options.width,
+        height: options.height,
+        numFrames: options.numFrames,
+        frameRate: options.frameRate,
+        seed: options.seed,
+        negativePrompt: options.negativePrompt,
+    }));
+    buildVideoGenerateCommand(video, "img2video", "Generate a video from one input image", async (client, options) => client.video.generate({
+        mode: "img2video",
+        image: Array.isArray(options.image) ? options.image[0] : options.image,
+        prompt: options.prompt,
+        width: options.width,
+        height: options.height,
+        numFrames: options.numFrames,
+        frameRate: options.frameRate,
+        seed: options.seed,
+        negativePrompt: options.negativePrompt,
+        ttl: ttlSchema.parse(options.ttl),
+    }), "single");
+    buildVideoGenerateCommand(video, "multivideo", "Generate a video from multiple input images", async (client, options) => client.video.generate({
+        mode: "multivideo",
+        images: toArray(options.image),
+        prompt: options.prompt,
+        width: options.width,
+        height: options.height,
+        numFrames: options.numFrames,
+        frameRate: options.frameRate,
+        seed: options.seed,
+        negativePrompt: options.negativePrompt,
+        ttl: ttlSchema.parse(options.ttl),
+    }), "multi");
+    buildVideoGenerateCommand(video, "keyframes", "Generate a keyframe video from multiple images", async (client, options) => client.video.generate({
+        mode: "keyframes",
+        images: toArray(options.image),
+        prompt: options.prompt,
+        width: options.width,
+        height: options.height,
+        numFrames: options.numFrames,
+        frameRate: options.frameRate,
+        seed: options.seed,
+        negativePrompt: options.negativePrompt,
+        ttl: ttlSchema.parse(options.ttl),
+    }), "multi");
+    video
+        .command("poll")
+        .description("Poll an Agnes video task until it finishes")
+        .argument("<task-id>", "Task id returned by Agnes video creation")
+        .option("--interval <seconds>", "Polling interval seconds", parseInteger, 3)
+        .option("--timeout <seconds>", "Polling timeout seconds", parseInteger, 600)
+        .option("--json", "Output JSON")
+        .addHelpText("after", `
+Example:
+  agnes video poll task_123 --interval 3 --timeout 600
+
+Request shape:
+  Polls Agnes /videos/{task_id} until the task completes, fails, or times out. Use this after any asynchronous video creation command.
+`)
+        .action(async (taskId, options) => {
+        const result = await client.video.poll(taskId, {
+            intervalSeconds: options.interval,
+            timeoutSeconds: options.timeout,
+        });
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        printLines([
+            result.videoUrl,
+            `status: ${result.status}`,
+            result.seconds !== undefined ? `seconds: ${result.seconds}` : undefined,
+            result.size ? `size: ${result.size}` : undefined,
+        ]);
+    });
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (error) {
+        handleCliError(error, argv);
+    }
+}
+function buildVideoGenerateCommand(video, name, description, fn, imageMode = false) {
+    let command = video
+        .command(name)
+        .description(description)
+        .requiredOption("--prompt <text>", "Prompt text")
+        .option("--width <number>", "Video width", parseInteger)
+        .option("--height <number>", "Video height", parseInteger)
+        .option("--num-frames <number>", "Video frame count, must satisfy 8n + 1", parseInteger)
+        .option("--frame-rate <number>", "Frame rate (1-60)", parseInteger)
+        .option("--seed <number>", "Seed", parseInteger)
+        .option("--negative-prompt <text>", "Negative prompt")
+        .option("--json", "Output JSON");
+    if (imageMode === "single") {
+        command = command
+            .requiredOption("--image <path-or-url>", "Input image path or URL")
+            .option("--ttl <ttl>", "Temporary upload TTL", "1h");
+    }
+    else if (imageMode === "multi") {
+        command = command
+            .requiredOption("--image <path-or-url...>", "Repeatable image path or URL")
+            .option("--ttl <ttl>", "Temporary upload TTL", "1h");
+    }
+    command.addHelpText("after", buildVideoHelp(name, imageMode));
+    command.action(async (options) => {
+        const client = createAgnesClient();
+        const result = await fn(client, options);
+        if (options.json) {
+            printJson(result);
+            return;
+        }
+        const task = result;
+        printLines([
+            `taskId: ${task.taskId}`,
+            `status: ${task.status}`,
+        ]);
+    });
+}
+function handleCliError(error, argv) {
+    const wantsJson = argv.includes("--json");
+    if (isAgnesCliError(error)) {
+        if (wantsJson) {
+            printJson({
+                ok: false,
+                code: error.code,
+                message: error.message,
+                ...toJsonDetails(error.details),
+            });
+            process.exit(error.exitCode);
+        }
+        console.error(error.message);
+        process.exit(error.exitCode);
+    }
+    if (error instanceof z.ZodError) {
+        if (wantsJson) {
+            printJson({
+                ok: false,
+                code: "INVALID_ARGUMENTS",
+                message: error.issues.map((issue) => issue.message).join("\n"),
+            });
+            process.exit(1);
+        }
+        console.error(error.issues.map((issue) => issue.message).join("\n"));
+        process.exit(1);
+    }
+    if (wantsJson) {
+        printJson({
+            ok: false,
+            code: "UNEXPECTED_ERROR",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+}
+function parseInteger(value) {
+    return Number.parseInt(value, 10);
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+const ttlSchema = z.enum(["1h", "12h", "24h", "72h"]);
+function toJsonDetails(details) {
+    if (!details || typeof details !== "object" || Array.isArray(details)) {
+        return {};
+    }
+    return details;
+}
+function buildVideoHelp(name, imageMode) {
+    const examples = {
+        text2video: 'agnes video text2video --prompt "A cinematic beach scene at sunset"',
+        img2video: 'agnes video img2video --image ./frame.png --prompt "Add gentle wind and a soft push-in"',
+        multivideo: 'agnes video multivideo --image ./a.png --image ./b.png --prompt "Blend these references into one motion concept"',
+        keyframes: 'agnes video keyframes --image ./a.png --image ./b.png --prompt "Transition between these frames"',
+    };
+    const shapeNotes = {
+        text2video: "Sends a prompt-only Agnes video task payload.",
+        img2video: "Resolves the input file to a public URL when needed, then sends a single top-level image field.",
+        multivideo: "Resolves each input to a public URL and sends an ordered Agnes image URL array in extra_body.image.",
+        keyframes: "Uses Agnes keyframes mode. Pass --image at least twice; each image keeps its original order and is sent in extra_body.image with extra_body.mode=keyframes.",
+    };
+    const imageNote = imageMode === "multi"
+        ? "Required image input: repeat --image two or more times."
+        : imageMode === "single"
+            ? "Required image input: provide exactly one --image."
+            : "No image input is required for this mode.";
+    return `
+Example:
+  ${examples[name] ?? `agnes video ${name} --help`}
+
+Request shape:
+  ${shapeNotes[name] ?? "Creates an Agnes video task."}
+  ${imageNote}
+`;
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    void runCli(process.argv);
+}

package/dist/config.d.ts

@@ -0,0 +1,70 @@
+export type Ttl = "1h" | "12h" | "24h" | "72h";
+export type FetchLike = typeof fetch;
+export interface AgnesClientConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: FetchLike;
+    defaultMediaTtl?: Ttl;
+    mediaProvider?: MediaUrlProvider;
+    env?: NodeJS.ProcessEnv;
+}
+export interface MediaUrlProvider {
+    upload(localPath: string, options?: {
+        ttl?: Ttl;
+    }): Promise<string>;
+}
+export interface ResolvedConfig {
+    apiKey?: string;
+    baseUrl: string;
+    fetchImpl: FetchLike;
+    defaultMediaTtl: Ttl;
+    mediaProvider?: MediaUrlProvider;
+    env: NodeJS.ProcessEnv;
+}
+export declare const DEFAULT_BASE_URL = "https://apihub.agnes-ai.com/v1";
+export declare const DEFAULT_MEDIA_TTL: Ttl;
+export declare const DEFAULT_VIDEO_DIMENSIONS: {
+    width: number;
+    height: number;
+};
+export declare const DEFAULT_VIDEO_TEMPORAL: {
+    numFrames: number;
+    frameRate: number;
+};
+export declare function resolveConfig(config?: AgnesClientConfig): ResolvedConfig;
+export interface AuthCheckResult {
+    ok: boolean;
+    configured: boolean;
+    source: "env" | "missing";
+}
+export interface PublicUrlResult {
+    ok: true;
+    url: string;
+    source: "passthrough" | "litterbox" | "provider";
+}
+export type AgnesStatus = "queued" | "in_progress" | "completed" | "failed" | "timed_out";
+export interface NormalizedVideoTask {
+    ok: true;
+    taskId: string;
+    status: AgnesStatus;
+    rawStatus?: string;
+    model: string;
+    raw: unknown;
+}
+export interface NormalizedVideoResult {
+    ok: true;
+    taskId: string;
+    status: AgnesStatus;
+    rawStatus?: string;
+    model: string;
+    videoUrl: string;
+    seconds?: number;
+    size?: string;
+    raw: unknown;
+}
+export interface ImageGenerationResult {
+    ok: true;
+    model: string;
+    url: string;
+    raw: unknown;
+}