@aigne/cli 1.27.1-0 → 1.28.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.28.0](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.27.0...cli-v1.28.0) (2025-07-31)
+
+
+### Features
+
+* **cli:** support dynamic download and execution of doc-smith app ([#293](https://github.com/AIGNE-io/aigne-framework/issues/293)) ([4c40077](https://github.com/AIGNE-io/aigne-framework/commit/4c40077bacef076bc4b098879e948ef866218e39))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/agent-library bumped to 1.21.7
+    * @aigne/agentic-memory bumped to 1.0.7
+    * @aigne/aigne-hub bumped to 0.3.1
+    * @aigne/anthropic bumped to 0.10.3
+    * @aigne/bedrock bumped to 0.8.7
+    * @aigne/core bumped to 1.40.0
+    * @aigne/deepseek bumped to 0.7.7
+    * @aigne/default-memory bumped to 1.0.7
+    * @aigne/gemini bumped to 0.8.7
+    * @aigne/ollama bumped to 0.7.7
+    * @aigne/open-router bumped to 0.7.7
+    * @aigne/openai bumped to 0.10.7
+    * @aigne/xai bumped to 0.7.7
+
 ## [1.27.0](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.26.0...cli-v1.27.0) (2025-07-30)
 
 

package/dist/cli.d.ts

@@ -1,2 +1,7 @@
 #!/usr/bin/env node
-export {};
+declare const _default: Promise<{
+    [x: string]: unknown;
+    _: (string | number)[];
+    $0: string;
+}>;
+export default _default;

package/dist/cli.js

@@ -16,7 +16,7 @@ function getAIGNEFilePath() {
     }
 }
 const aigneFilePath = getAIGNEFilePath();
-createAIGNECommand({ aigneFilePath })
+export default createAIGNECommand({ aigneFilePath })
     .parseAsync(hideBin([...process.argv.slice(0, 2), ...process.argv.slice(aigneFilePath ? 3 : 2)]))
     .catch((error) => {
     console.log(""); // Add an empty line for better readability

package/dist/commands/app.d.ts

@@ -1,2 +1,19 @@
+import { AIGNE, type Message } from "@aigne/core";
 import type { CommandModule } from "yargs";
 export declare function createAppCommands(): CommandModule[];
+export declare function invokeCLIAgentFromDir(options: {
+    dir: string;
+    agent: string;
+    input: Message & {
+        input?: string[];
+        format?: "yaml" | "json";
+    };
+}): Promise<void>;
+export declare function loadApplication({ name, dir, }: {
+    name: string;
+    dir?: string;
+}): Promise<{
+    aigne: AIGNE;
+    dir: string;
+    version: string;
+}>;

package/dist/commands/app.js

@@ -1,88 +1,232 @@
 import assert from "node:assert";
 import { spawnSync } from "node:child_process";
-import { mkdir, readFile, stat } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { AIGNE } from "@aigne/core";
+import { extname, join } from "node:path";
+import { isatty } from "node:tty";
+import { AIAgent, AIGNE, readAllString } from "@aigne/core";
+import { pick } from "@aigne/core/utils/type-utils.js";
+import { Listr, PRESET_TIMER } from "@aigne/listr2";
 import { joinURL } from "ufo";
+import { parse } from "yaml";
 import { ZodObject, ZodString } from "zod";
 import { availableModels } from "../constants.js";
 import { downloadAndExtract } from "../utils/download.js";
-import { runAgentWithAIGNE } from "../utils/run-with-aigne.js";
+import { loadAIGNE } from "../utils/load-aigne.js";
+import { runAgentWithAIGNE, stdinHasData } from "../utils/run-with-aigne.js";
+import { serveMCPServerFromDir } from "./serve-mcp.js";
 const NPM_PACKAGE_CACHE_TIME_MS = 1000 * 60 * 60 * 24; // 1 day
+const builtinApps = [
+    {
+        name: "doc-smith",
+        describe: "Generate professional documents by doc-smith",
+        aliases: ["docsmith", "doc"],
+    },
+];
 export function createAppCommands() {
-    return [
-        {
-            command: "doc-smith",
-            describe: "Generate professional documents by doc-smith",
-            aliases: ["docsmith", "doc"],
-            builder: async (yargs) => {
-                const aigne = await loadApplication({ name: "doc-smith" });
-                for (const agent of aigne.agents) {
-                    yargs.command(agent.name, agent.description || "", (yargs) => {
-                        const options = Object.entries(agent.inputSchema instanceof ZodObject ? agent.inputSchema.shape : {});
-                        for (const [option, config] of options) {
-                            yargs.option(option, {
-                                // TODO: support more types
-                                type: config instanceof ZodString ? "string" : "string",
-                                description: config.description,
-                            });
-                            if (!(config.isNullable() || config.isOptional())) {
-                                yargs.demandOption(option);
-                            }
-                        }
-                    }, async (argv) => {
-                        try {
-                            await runAgentWithAIGNE(aigne, agent, { input: argv });
-                        }
-                        finally {
-                            await aigne.shutdown();
-                        }
-                    });
-                }
-                yargs.version('hello world');
-                return yargs.demandCommand();
-            },
-            handler: () => { },
+    return builtinApps.map((app) => ({
+        command: app.name,
+        describe: app.describe,
+        aliases: app.aliases,
+        builder: async (yargs) => {
+            const { aigne, dir, version } = await loadApplication({ name: app.name });
+            yargs.command(serveMcpCommandModule({ name: app.name, dir }));
+            for (const agent of aigne.cli?.agents ?? []) {
+                yargs.command(agentCommandModule({ dir, agent }));
+            }
+            yargs.version(`${app.name} v${version}`);
+            return yargs.demandCommand();
         },
-    ];
+        handler: () => { },
+    }));
 }
-async function loadApplication({ name }) {
-    const info = await shouldDownloadNewVersion(name);
-    if (info.shouldDownload) {
-        assert(info.url, "Package URL should be defined when downloading");
-        // TODO: clean up old versions
-        await mkdir(info.dir, { recursive: true });
-        await downloadAndExtract(info.url.toString(), info.dir, { strip: 1 });
-        spawnSync("npm", ["install", "--omit", "dev"], { cwd: info.dir, stdio: "inherit" });
+const serveMcpCommandModule = ({ name, dir, }) => ({
+    command: "serve-mcp",
+    describe: `Serve ${name} a MCP server (streamable http)`,
+    builder: (yargs) => {
+        return yargs
+            .option("host", {
+            describe: "Host to run the MCP server on, use 0.0.0.0 to publicly expose the server",
+            type: "string",
+            default: "localhost",
+        })
+            .option("port", {
+            describe: "Port to run the MCP server on",
+            type: "number",
+        })
+            .option("pathname", {
+            describe: "Pathname to the service",
+            type: "string",
+            default: "/mcp",
+        });
+    },
+    handler: async (options) => {
+        await serveMCPServerFromDir({ ...options, dir });
+    },
+});
+const agentCommandModule = ({ dir, agent, }) => {
+    const inputSchema = agent.inputSchema instanceof ZodObject ? agent.inputSchema.shape : {};
+    return {
+        command: agent.name,
+        describe: agent.description || "",
+        builder: (yargs) => {
+            for (const [option, config] of Object.entries(inputSchema)) {
+                yargs.option(option, {
+                    // TODO: support more types
+                    type: "string",
+                    description: config.description,
+                });
+                if (!(config.isNullable() || config.isOptional())) {
+                    yargs.demandOption(option);
+                }
+            }
+            return yargs
+                .option("input", {
+                type: "array",
+                description: "Input to the agent, use @<file> to read from a file",
+                alias: ["i"],
+            })
+                .option("format", {
+                type: "string",
+                description: 'Input format, can be "json" or "yaml"',
+                choices: ["json", "yaml"],
+            });
+        },
+        handler: async (input) => {
+            await invokeCLIAgentFromDir({ dir, agent: agent.name, input });
+        },
+    };
+};
+export async function invokeCLIAgentFromDir(options) {
+    const aigne = await loadAIGNE(options.dir);
+    try {
+        const agent = aigne.cli.agents[options.agent];
+        assert(agent, `Agent ${options.agent} not found in ${options.dir}`);
+        const inputSchema = agent.inputSchema instanceof ZodObject ? agent.inputSchema.shape : {};
+        const input = Object.fromEntries(await Promise.all(Object.entries(pick(options.input, Object.keys(inputSchema))).map(async ([key, val]) => {
+            if (typeof val === "string" && val.startsWith("@")) {
+                const schema = inputSchema[key];
+                val = await readFileAsInput(val, {
+                    format: schema instanceof ZodString ? "raw" : undefined,
+                });
+            }
+            return [key, val];
+        })));
+        const rawInput = options.input.input ||
+            (isatty(process.stdin.fd) || !(await stdinHasData())
+                ? null
+                : [await readAllString(process.stdin)].filter(Boolean));
+        if (rawInput) {
+            for (const raw of rawInput) {
+                const parsed = raw.startsWith("@")
+                    ? await readFileAsInput(raw, { format: options.input.format })
+                    : raw;
+                if (typeof parsed !== "string") {
+                    Object.assign(input, parsed);
+                }
+                else {
+                    const inputKey = agent instanceof AIAgent ? agent.inputKey : undefined;
+                    if (inputKey) {
+                        Object.assign(input, { [inputKey]: parsed });
+                    }
+                }
+            }
+        }
+        await runAgentWithAIGNE(aigne, agent, { input });
+    }
+    finally {
+        await aigne.shutdown();
     }
-    return AIGNE.load(info.dir, { models: availableModels() });
 }
-async function shouldDownloadNewVersion(name, { cacheTimeMs = NPM_PACKAGE_CACHE_TIME_MS } = {}) {
-    const nameWithOrg = `@aigne/${name}`;
-    const dir = join(homedir(), ".aigne", "registry.npmjs.org", nameWithOrg);
-    const s = await stat(join(dir, "package.json")).catch((error) => {
-        if (error.code === "ENOENT") {
-            return null;
+async function readFileAsInput(value, { format } = {}) {
+    if (value.startsWith("@")) {
+        const ext = extname(value);
+        value = await readFile(value.slice(1), "utf8");
+        if (!format) {
+            if (ext === ".json")
+                format = "json";
+            else if (ext === ".yaml" || ext === ".yml")
+                format = "yaml";
         }
-        throw error;
-    });
-    if (!s)
+    }
+    if (format === "json") {
+        return JSON.parse(value);
+    }
+    else if (format === "yaml") {
+        return parse(value);
+    }
+    return value;
+}
+export async function loadApplication({ name, dir, }) {
+    name = `@aigne/${name}`;
+    dir ??= join(homedir(), ".aigne", "registry.npmjs.org", name);
+    const check = await isInstallationAvailable(dir);
+    if (check?.available) {
         return {
-            shouldDownload: true,
+            aigne: await AIGNE.load(dir, { models: availableModels() }),
             dir,
-            url: await getNpmTgzInfo(nameWithOrg).then((info) => info.tarballUrl),
+            version: check.version,
         };
-    const lastModified = s.mtimeMs;
+    }
+    const result = await new Listr([
+        {
+            title: "Fetching application metadata",
+            task: async (ctx) => {
+                const info = await getNpmTgzInfo(name);
+                Object.assign(ctx, info);
+            },
+        },
+        {
+            title: "Downloading application",
+            skip: (ctx) => ctx.version === check?.version,
+            task: async (ctx) => {
+                await downloadAndExtract(ctx.url, dir, { strip: 1 });
+            },
+        },
+        {
+            title: "Installing dependencies",
+            skip: (ctx) => ctx.version === check?.version,
+            task: async () => {
+                await installDependencies(dir);
+            },
+        },
+    ], {
+        rendererOptions: {
+            collapseSubtasks: false,
+            showErrorMessage: false,
+            timer: PRESET_TIMER,
+        },
+    }).run();
+    return {
+        aigne: await AIGNE.load(dir, { models: availableModels() }),
+        dir,
+        version: result.version,
+    };
+}
+async function isInstallationAvailable(dir, { cacheTimeMs = NPM_PACKAGE_CACHE_TIME_MS } = {}) {
+    const s = await stat(join(dir, "package.json")).catch(() => null);
+    if (!s)
+        return null;
+    const version = safeParseJSON(await readFile(join(dir, "package.json"), "utf-8"))?.version;
+    if (!version)
+        return null;
+    const installedAt = safeParseJSON(await readFile(join(dir, ".aigne-cli.json"), "utf-8").catch(() => "{}"))?.installedAt;
+    if (!installedAt)
+        return null;
     const now = Date.now();
-    if (now - lastModified > cacheTimeMs) {
-        const version = JSON.parse(await readFile(join(dir, "package.json"), "utf-8")).version;
-        const latest = await getNpmTgzInfo(`@aigne/${name}`);
-        if (version !== latest.version) {
-            return { shouldDownload: true, url: latest.tarballUrl, dir };
-        }
+    const available = installedAt ? now - installedAt < cacheTimeMs : false;
+    return { version, available };
+}
+async function installDependencies(dir) {
+    const { stderr, status } = spawnSync("npm", ["install", "--omit", "dev"], {
+        cwd: dir,
+        stdio: "pipe",
+    });
+    if (status !== 0) {
+        console.error(stderr.toString());
+        throw new Error(`Failed to install dependencies in ${dir}`);
     }
-    return { shouldDownload: false, dir };
+    await writeFile(join(dir, ".aigne-cli.json"), JSON.stringify({ installedAt: Date.now() }, null, 2));
 }
 async function getNpmTgzInfo(name) {
     const res = await fetch(joinURL("https://registry.npmjs.org", name));
@@ -90,9 +234,15 @@ async function getNpmTgzInfo(name) {
         throw new Error(`Failed to fetch package info for ${name}: ${res.statusText}`);
     const data = await res.json();
     const latestVersion = data["dist-tags"].latest;
-    const tarballUrl = data.versions[latestVersion].dist.tarball;
+    const url = data.versions[latestVersion].dist.tarball;
     return {
         version: latestVersion,
-        tarballUrl,
+        url,
     };
 }
+function safeParseJSON(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch { }
+}

package/dist/commands/connect.d.ts

@@ -2,5 +2,5 @@ import type { CommandModule } from "yargs";
 interface ConnectOptions {
     url?: string;
 }
-export declare function createConnectCommand(): CommandModule<{}, ConnectOptions>;
+export declare function createConnectCommand(): CommandModule<unknown, ConnectOptions>;
 export {};

package/dist/commands/create.d.ts

@@ -2,5 +2,5 @@ import type { CommandModule } from "yargs";
 interface CreateOptions {
     path: string;
 }
-export declare function createCreateCommand(): CommandModule<{}, CreateOptions>;
+export declare function createCreateCommand(): CommandModule<unknown, CreateOptions>;
 export {};

package/dist/commands/observe.d.ts

@@ -3,5 +3,5 @@ interface ServeMCPOptions {
     host: string;
     port?: number;
 }
-export declare function createObservabilityCommand(): CommandModule<{}, ServeMCPOptions>;
+export declare function createObservabilityCommand(): CommandModule<unknown, ServeMCPOptions>;
 export {};

package/dist/commands/run.js

@@ -31,7 +31,8 @@ export function createRunCommand({ aigneFilePath, } = {}) {
                 .option("cache-dir", {
                 describe: "Directory to download the package to (defaults to the ~/.aigne/xxx)",
                 type: "string",
-            });
+            })
+                .strict(false);
         },
         handler: async (argv) => {
             const options = argv;

package/dist/commands/serve-mcp.d.ts

@@ -5,7 +5,14 @@ interface ServeMCPOptions {
     port?: number;
     pathname: string;
 }
+export declare const DEFAULT_PORT: () => number;
 export declare function createServeMCPCommand({ aigneFilePath, }?: {
     aigneFilePath?: string;
-}): CommandModule<{}, ServeMCPOptions>;
+}): CommandModule<unknown, ServeMCPOptions>;
+export declare function serveMCPServerFromDir(options: {
+    dir: string;
+    host: string;
+    port?: number;
+    pathname: string;
+}): Promise<void>;
 export {};

package/dist/commands/serve-mcp.js

@@ -2,7 +2,7 @@ import { isAbsolute, resolve } from "node:path";
 import { tryOrThrow } from "@aigne/core/utils/type-utils.js";
 import { loadAIGNE } from "../utils/load-aigne.js";
 import { serveMCPServer } from "../utils/serve-mcp.js";
-const DEFAULT_PORT = () => tryOrThrow(() => {
+export const DEFAULT_PORT = () => tryOrThrow(() => {
     const { PORT } = process.env;
     if (!PORT)
         return 3000;
@@ -41,15 +41,18 @@ export function createServeMCPCommand({ aigneFilePath, } = {}) {
         handler: async (options) => {
             const path = aigneFilePath || options.path;
             const absolutePath = isAbsolute(path) ? path : resolve(process.cwd(), path);
-            const port = options.port || DEFAULT_PORT();
-            const aigne = await loadAIGNE(absolutePath);
-            await serveMCPServer({
-                aigne,
-                host: options.host,
-                port,
-                pathname: options.pathname,
-            });
-            console.log(`MCP server is running on http://${options.host}:${port}${options.pathname}`);
+            await serveMCPServerFromDir({ ...options, dir: absolutePath });
         },
     };
 }
+export async function serveMCPServerFromDir(options) {
+    const port = options.port || DEFAULT_PORT();
+    const aigne = await loadAIGNE(options.dir);
+    await serveMCPServer({
+        aigne,
+        host: options.host,
+        port,
+        pathname: options.pathname,
+    });
+    console.log(`MCP server is running on http://${options.host}:${port}${options.pathname}`);
+}

package/dist/commands/test.d.ts

@@ -4,5 +4,5 @@ interface TestOptions {
 }
 export declare function createTestCommand({ aigneFilePath, }?: {
     aigneFilePath?: string;
-}): CommandModule<{}, TestOptions>;
+}): CommandModule<unknown, TestOptions>;
 export {};

package/dist/utils/download.js

@@ -1,3 +1,4 @@
+import { mkdir } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { finished } from "node:stream/promises";
 import { x } from "tar";
@@ -12,6 +13,7 @@ export async function downloadAndExtract(url, dir, options = {}) {
         throw new Error(`Failed to download package from ${url}: Unexpected to get empty response`);
     }
     try {
+        await mkdir(dir, { recursive: true });
         await finished(Readable.fromWeb(response.body).pipe(x({ C: dir, ...options })));
     }
     catch (error) {

package/dist/utils/run-with-aigne.d.ts

@@ -65,3 +65,4 @@ export declare function runAgentWithAIGNE(aigne: AIGNE, agent: Agent, { outputKe
 } & Omit<RunAIGNECommandOptions, "input">): Promise<{
     result: Message;
 } | undefined>;
+export declare function stdinHasData(): Promise<boolean>;

package/dist/utils/run-with-aigne.js

@@ -7,10 +7,11 @@ import { exists } from "@aigne/agent-library/utils/fs.js";
 import { AIAgent, AIGNE, DEFAULT_OUTPUT_KEY, readAllString, UserAgent, } from "@aigne/core";
 import { loadModel } from "@aigne/core/loader/index.js";
 import { getLevelFromEnv, LogLevel, logger } from "@aigne/core/utils/logger.js";
-import { flat, isEmpty, tryOrThrow, } from "@aigne/core/utils/type-utils.js";
+import { flat, isEmpty, tryOrThrow } from "@aigne/core/utils/type-utils.js";
 import chalk from "chalk";
 import { parse } from "yaml";
 import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
 import { ZodError, ZodObject, z } from "zod";
 import { availableModels } from "../constants.js";
 import { TerminalTracer } from "../tracer/terminal.js";
@@ -157,7 +158,7 @@ export async function runWithAIGNE(agentCreator, { argv = process.argv, chatLoop
     })
         .alias("h", "help")
         .alias("v", "version")
-        .parseAsync(argv)
+        .parseAsync(hideBin(argv))
         .catch((error) => {
         console.error(`${chalk.red("Error:")} ${error.message}`);
         process.exit(1);
@@ -209,7 +210,7 @@ export async function runAgentWithAIGNE(aigne, agent, { outputKey, chatLoopOptio
     }
     return { result };
 }
-async function stdinHasData() {
+export async function stdinHasData() {
     const stats = await promisify(fstat)(0);
     return stats.isFIFO() || stats.isFile();
 }

package/dist/utils/serve-mcp.js

@@ -72,7 +72,7 @@ export function createMcpServer(aigne) {
         capabilities: { tools: {} },
         instructions: aigne.description,
     });
-    for (const agent of aigne.agents) {
+    for (const agent of aigne.mcpServer?.agents ?? []) {
         const schema = agent.inputSchema;
         if (!(schema instanceof ZodObject))
             throw new Error("Agent input schema must be a ZodObject");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/cli",
-  "version": "1.27.1-0",
+  "version": "1.28.0",
   "description": "cli for AIGNE framework",
   "publishConfig": {
     "access": "public"
@@ -70,20 +70,20 @@
     "yaml": "^2.8.0",
     "yargs": "^18.0.0",
     "zod": "^3.25.67",
-    "@aigne/agent-library": "^1.21.6",
-    "@aigne/agentic-memory": "^1.0.6",
-    "@aigne/aigne-hub": "^0.3.0",
-    "@aigne/anthropic": "^0.10.2",
-    "@aigne/bedrock": "^0.8.6",
-    "@aigne/core": "^1.39.0",
-    "@aigne/deepseek": "^0.7.6",
-    "@aigne/default-memory": "^1.0.6",
-    "@aigne/gemini": "^0.8.6",
-    "@aigne/ollama": "^0.7.6",
-    "@aigne/open-router": "^0.7.6",
-    "@aigne/openai": "^0.10.6",
-    "@aigne/xai": "^0.7.6",
-    "@aigne/observability-api": "^0.8.2"
+    "@aigne/agentic-memory": "^1.0.7",
+    "@aigne/agent-library": "^1.21.7",
+    "@aigne/aigne-hub": "^0.3.1",
+    "@aigne/anthropic": "^0.10.3",
+    "@aigne/bedrock": "^0.8.7",
+    "@aigne/core": "^1.40.0",
+    "@aigne/default-memory": "^1.0.7",
+    "@aigne/gemini": "^0.8.7",
+    "@aigne/deepseek": "^0.7.7",
+    "@aigne/observability-api": "^0.8.2",
+    "@aigne/ollama": "^0.7.7",
+    "@aigne/open-router": "^0.7.7",
+    "@aigne/openai": "^0.10.7",
+    "@aigne/xai": "^0.7.7"
   },
   "devDependencies": {
     "@types/archiver": "^6.0.3",

package/templates/default/aigne.yaml

@@ -4,6 +4,6 @@ chat_model:
   temperature: 0.8
 agents:
   - chat.yaml
-tools:
+skills:
   - sandbox.js
   - filesystem.yaml

package/templates/default/chat.yaml

@@ -5,5 +5,5 @@ instructions: |
   Your goal is to assist users in finding the information they need and to engage in friendly conversation.
 input_key: message
 memory: true
-tools:
+skills:
   - sandbox.js