@aigne/cli 1.49.2-beta → 1.50.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [1.50.0-beta.1](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.49.2-beta.1...cli-v1.50.0-beta.1) (2025-09-30)
+
+
+### Features
+
+* **cli:** support define nested commands for sub apps ([#568](https://github.com/AIGNE-io/aigne-framework/issues/568)) ([0693b80](https://github.com/AIGNE-io/aigne-framework/commit/0693b807e0f8d335010e6ad00763b07cf095e65b))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/agent-library bumped to 1.21.47-beta.1
+    * @aigne/agentic-memory bumped to 1.0.47-beta.1
+    * @aigne/aigne-hub bumped to 0.10.1-beta.1
+    * @aigne/core bumped to 1.62.0-beta
+    * @aigne/default-memory bumped to 1.2.10-beta.1
+    * @aigne/openai bumped to 0.16.1-beta.1
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.54-beta.1
+
+## [1.49.2-beta.1](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.49.2-beta...cli-v1.49.2-beta.1) (2025-09-29)
+
+
+### Bug Fixes
+
+* **cli:** improve app loading reliability with force upgrade on error ([#566](https://github.com/AIGNE-io/aigne-framework/issues/566)) ([d7c49cf](https://github.com/AIGNE-io/aigne-framework/commit/d7c49cfdfdc72c0d1a98c3033babe1392cb707c1))
+
 ## [1.49.2-beta](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.49.1...cli-v1.49.2-beta) (2025-09-29)
 
 

package/dist/cli.js

@@ -16,7 +16,8 @@ function getAIGNEFilePath() {
     }
 }
 const aigneFilePath = getAIGNEFilePath();
-export default createAIGNECommand({ aigneFilePath })
+const argv = process.argv.slice(aigneFilePath ? 3 : 2);
+export default createAIGNECommand({ argv, aigneFilePath })
     .fail((message, error, yargs) => {
     // We catch all errors below, here just print the help message non-error case like demandCommand
     if (!error) {
@@ -25,7 +26,7 @@ export default createAIGNECommand({ aigneFilePath })
         process.exit(1);
     }
 })
-    .parseAsync(process.argv.slice(aigneFilePath ? 3 : 2))
+    .parseAsync(argv)
     .catch((error) => {
     console.log(""); // Add an empty line for better readability
     console.error(`${chalk.red("Error:")} ${highlightUrl(error.message)}`);

package/dist/commands/aigne.d.ts

@@ -1,4 +1,5 @@
 import yargs from "yargs";
 export declare function createAIGNECommand(options?: {
+    argv?: string[];
     aigneFilePath?: string;
 }): yargs.Argv<{}>;

package/dist/commands/aigne.js

@@ -21,7 +21,7 @@ export function createAIGNECommand(options) {
         .command(createCreateCommand())
         .command(createServeMCPCommand(options))
         .command(createObservabilityCommand())
-        .command(createAppCommands())
+        .command(createAppCommands(options))
         .command(createHubCommand())
         .command(createDeployCommands())
         .demandCommand()

package/dist/commands/app.d.ts

@@ -1,11 +1,18 @@
 import type { CommandModule } from "yargs";
-import { type AgentInChildProcess, type LoadAIGNEInChildProcessResult } from "../utils/workers/run-aigne-in-child-process.js";
+import { type AgentInChildProcess, type CLIAgentInChildProcess, type LoadAIGNEInChildProcessResult } from "../utils/workers/run-aigne-in-child-process.js";
 import { type AgentRunCommonOptions } from "../utils/yargs.js";
-export declare function createAppCommands(): CommandModule[];
+export declare function createAppCommands({ argv }?: {
+    argv?: string[];
+}): CommandModule[];
 export declare const agentCommandModule: ({ dir, agent, }: {
     dir: string;
     agent: AgentInChildProcess;
 }) => CommandModule<unknown, AgentRunCommonOptions>;
+export declare const cliAgentCommandModule: ({ dir, parent, cliAgent, }: {
+    dir: string;
+    parent?: string[];
+    cliAgent: CLIAgentInChildProcess;
+}) => CommandModule<unknown, AgentRunCommonOptions>;
 interface LoadApplicationOptions {
     packageName: string;
     dir: string;

package/dist/commands/app.js

@@ -1,3 +1,4 @@
+import assert from "node:assert";
 import { spawn } from "node:child_process";
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -7,6 +8,7 @@ import { jsonSchemaToZod } from "@aigne/json-schema-to-zod";
 import { Listr, PRESET_TIMER } from "@aigne/listr2";
 import { joinURL } from "ufo";
 import { downloadAndExtract } from "../utils/download.js";
+import { withSpinner } from "../utils/spinner.js";
 import { runAIGNEInChildProcess, } from "../utils/workers/run-aigne-in-child-process.js";
 import { withAgentInputSchema } from "../utils/yargs.js";
 import { serveMCPServerFromDir } from "./serve-mcp.js";
@@ -32,36 +34,36 @@ const builtinApps = [
         aliases: ["websmith", "web"],
     },
 ];
-export function createAppCommands() {
+export function createAppCommands({ argv } = {}) {
     return builtinApps.map((app) => ({
         command: app.name,
         describe: app.describe,
         aliases: app.aliases,
-        builder: async (yargs) => {
+        builder: async (y) => {
             const dir = join(homedir(), ".aigne", "registry.npmjs.org", app.packageName);
-            const { aigne, version } = await loadApplication({
-                dir,
-                packageName: app.packageName,
-                install: true,
-            });
-            if (aigne.cli?.chat) {
-                yargs.command({
-                    ...agentCommandModule({ dir, agent: aigne.cli.chat }),
-                    command: "$0",
+            y.command(upgradeCommandModule({ packageName: app.packageName, dir }));
+            if (!argv || !isUpgradeCommand(argv)) {
+                const { aigne, version } = await loadApplication({
+                    dir,
+                    packageName: app.packageName,
+                    install: true,
                 });
+                if (aigne.cli?.chat) {
+                    y.command({
+                        ...agentCommandModule({ dir, agent: aigne.cli.chat }),
+                        command: "$0",
+                    });
+                }
+                for (const cliAgent of aigne.cli?.agents ?? []) {
+                    y.command(cliAgentCommandModule({ dir, cliAgent }));
+                }
+                y.option("model", {
+                    type: "string",
+                    description: "Model to use for the application, example: openai:gpt-4.1 or google:gemini-2.5-flash",
+                }).command(serveMcpCommandModule({ name: app.name, dir }));
+                y.version(`${app.name} v${version}`).alias("version", "v");
             }
-            for (const agent of aigne.cli?.agents ?? []) {
-                yargs.command(agentCommandModule({ dir, agent }));
-            }
-            yargs
-                .option("model", {
-                type: "string",
-                description: "Model to use for the application, example: openai:gpt-4.1 or google:gemini-2.5-flash",
-            })
-                .command(serveMcpCommandModule({ name: app.name, dir }))
-                .command(upgradeCommandModule({ packageName: app.packageName, dir }));
-            yargs.version(`${app.name} v${version}`).alias("version", "v");
-            return yargs.demandCommand();
+            return y.demandCommand();
         },
         handler: () => { },
     }));
@@ -90,11 +92,15 @@ const serveMcpCommandModule = ({ name, dir, }) => ({
         await serveMCPServerFromDir({ ...options, dir });
     },
 });
+function isUpgradeCommand(argv) {
+    const skipGlobalOptions = ["-v", "--version"];
+    return argv[1] === "upgrade" && !argv.some((arg) => skipGlobalOptions.includes(arg));
+}
 const upgradeCommandModule = ({ packageName, dir, }) => ({
     command: "upgrade",
     describe: `Upgrade ${packageName} to the latest version`,
-    builder: (argv) => {
-        return argv
+    builder: (yargs) => {
+        return yargs
             .option("beta", {
             type: "boolean",
             describe: "Use beta versions if available",
@@ -112,11 +118,13 @@ const upgradeCommandModule = ({ packageName, dir, }) => ({
     },
     handler: async ({ beta, targetVersion, force }) => {
         beta ??= shouldUseBetaApps();
-        let app = await loadApplication({ packageName, dir });
-        const npm = await getNpmTgzInfo(packageName, { beta, version: targetVersion });
-        if (!app || force || npm.version !== app.version) {
+        const npm = await withSpinner("", async () => {
             if (force)
                 await rm(dir, { force: true, recursive: true });
+            return await getNpmTgzInfo(packageName, { beta, version: targetVersion });
+        });
+        let app = await loadApplication({ packageName, dir });
+        if (!app || force || npm.version !== app.version) {
             await installApp({ packageName, dir, beta, version: targetVersion });
             app = await loadApplication({ dir, packageName, install: true });
             console.log(`\n✅ Upgraded ${packageName} to version ${app.version}`);
@@ -145,12 +153,52 @@ export const agentCommandModule = ({ dir, agent, }) => {
         },
     };
 };
+export const cliAgentCommandModule = ({ dir, parent, cliAgent, }) => {
+    const { agent, agents } = cliAgent;
+    const name = cliAgent.name || agent?.name;
+    assert(name, "CLI agent must have a name");
+    return {
+        command: name,
+        aliases: cliAgent.alias || agent?.alias || [],
+        describe: cliAgent.description || agent?.description || "",
+        builder: async (yargs) => {
+            if (agent) {
+                withAgentInputSchema(yargs, { inputSchema: jsonSchemaToZod(agent.inputSchema) });
+            }
+            if (agents?.length) {
+                for (const cmd of agents) {
+                    yargs.command(cliAgentCommandModule({ dir, parent: (parent ?? []).concat(name), cliAgent: cmd }));
+                }
+            }
+            if (!agent)
+                yargs.demandCommand();
+            return yargs;
+        },
+        handler: async (options) => {
+            if (!agent)
+                throw new Error("CLI agent is not defined");
+            if (options.logLevel)
+                logger.level = options.logLevel;
+            await runAIGNEInChildProcess("invokeCLIAgentFromDir", {
+                dir,
+                parent,
+                agent: name,
+                input: options,
+            });
+            process.exit(0);
+        },
+    };
+};
 export async function loadApplication(options) {
     const { dir, packageName } = options;
     const check = await checkInstallation(dir);
     if (check && !check.expired) {
-        const aigne = await runAIGNEInChildProcess("loadAIGNE", dir).catch((error) => {
-            console.warn(`⚠️ Failed to load ${packageName}, trying to reinstall:`, error.message);
+        const aigne = await runAIGNEInChildProcess("loadAIGNE", dir).catch(async (error) => {
+            logger.error(`⚠️ Failed to load ${packageName}, trying to reinstall:`, error.message);
+            await withSpinner("", async () => {
+                await rm(options.dir, { recursive: true, force: true });
+                await mkdir(options.dir, { recursive: true });
+            });
         });
         if (aigne) {
             return { aigne, version: check.version, isCache: true };

package/dist/commands/eval.js

@@ -1,5 +1,6 @@
 import { isAbsolute, resolve } from "node:path";
 import { exists } from "@aigne/agent-library/utils/fs.js";
+import { findCliAgent } from "@aigne/core/utils/agent-utils.js";
 import { z } from "zod";
 import { runEvaluationPipeline } from "../utils/evaluation/core.js";
 import { FileDataset } from "../utils/evaluation/dataset.js";
@@ -70,7 +71,7 @@ export function createEvalCommand({ aigneFilePath, } = {}) {
             const { chat } = aigne.cli;
             const agent = chat && chat.name === entryAgent
                 ? chat
-                : aigne.cli.agents[entryAgent] ||
+                : findCliAgent(aigne.cli, "*", entryAgent) ||
                     aigne.agents[entryAgent] ||
                     aigne.skills[entryAgent] ||
                     aigne.mcpServer.agents[entryAgent];
@@ -80,7 +81,7 @@ export function createEvalCommand({ aigneFilePath, } = {}) {
             let evaluatorAgent;
             if (evaluatorName) {
                 evaluatorAgent =
-                    aigne.cli.agents[evaluatorName] ||
+                    findCliAgent(aigne.cli, "*", evaluatorName) ||
                         aigne.agents[evaluatorName] ||
                         aigne.skills[evaluatorName] ||
                         aigne.mcpServer.agents[evaluatorName];

package/dist/commands/run.js

@@ -2,6 +2,7 @@ import { cp, mkdir, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { exists } from "@aigne/agent-library/utils/fs.js";
+import { mapCliAgent } from "@aigne/core/utils/agent-utils.js";
 import { flat, isNonNullable } from "@aigne/core/utils/type-utils.js";
 import { Listr, PRESET_TIMER } from "@aigne/listr2";
 import { config } from "dotenv-flow";
@@ -11,7 +12,7 @@ import { downloadAndExtract } from "../utils/download.js";
 import { loadAIGNE } from "../utils/load-aigne.js";
 import { isUrl } from "../utils/url.js";
 import { serializeAgent } from "../utils/workers/run-aigne-in-child-process.js";
-import { agentCommandModule } from "./app.js";
+import { agentCommandModule, cliAgentCommandModule } from "./app.js";
 export function createRunCommand({ aigneFilePath, } = {}) {
     return {
         command: "run [path] [entry-agent]",
@@ -47,10 +48,16 @@ export function createRunCommand({ aigneFilePath, } = {}) {
                 });
             }
             // Allow user to run all of agents in the AIGNE instances
-            const allAgents = flat(aigne.cli.agents, aigne.agents, aigne.skills, aigne.cli.chat, aigne.mcpServer.agents);
+            const allAgents = flat(aigne.agents, aigne.skills, aigne.cli.chat, aigne.mcpServer.agents);
             for (const agent of allAgents) {
                 subYargs.command(agentCommandModule({ dir: path, agent: serializeAgent(agent) }));
             }
+            for (const cliAgent of aigne.cli.agents ?? []) {
+                subYargs.command(cliAgentCommandModule({
+                    dir: path,
+                    cliAgent: mapCliAgent(cliAgent, (a) => (a ? serializeAgent(a) : undefined)),
+                }));
+            }
             const argv = process.argv.slice(aigneFilePath ? 3 : 2);
             if (argv[0] === "run")
                 argv.shift(); // remove 'run' command
@@ -62,8 +69,9 @@ export function createRunCommand({ aigneFilePath, } = {}) {
             if (argv[0] === "--entry-agent")
                 argv.shift();
             const firstAgent = aigne.agents[0]?.name;
-            if (!options.entryAgent && firstAgent)
+            if (!options.entryAgent && firstAgent && !argv.some((i) => ["-h", "--help"].includes(i))) {
                 argv.unshift(firstAgent);
+            }
             await subYargs
                 .strict()
                 .demandCommand()

package/dist/utils/spinner.d.ts

@@ -0,0 +1 @@
+export declare function withSpinner<T>(message: string, fn: () => Promise<T>): Promise<T>;

package/dist/utils/spinner.js

@@ -0,0 +1,14 @@
+import { Spinner } from "@aigne/listr2";
+export async function withSpinner(message, fn) {
+    const spinner = new Spinner();
+    spinner.start(() => {
+        process.stdout.write(`\r\x1b[K${spinner.fetch()} ${message}`);
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        spinner.stop();
+        process.stdout.write("\r\x1b[K"); // Clear the spinner line
+    }
+}

package/dist/utils/workers/run-aigne-in-child-process-worker.d.ts

@@ -1,11 +1,11 @@
 import { AIGNE, type Message } from "@aigne/core";
 import { type AgentRunCommonOptions } from "../yargs.js";
-import { type AgentInChildProcess } from "./run-aigne-in-child-process.js";
+import { type AgentInChildProcess, type CLIAgentInChildProcess } from "./run-aigne-in-child-process.js";
 export declare function loadAIGNEInChildProcess(...args: Parameters<typeof AIGNE.load>): Promise<{
     agents?: AgentInChildProcess[];
     cli?: {
         chat?: AgentInChildProcess;
-        agents?: AgentInChildProcess[];
+        agents?: CLIAgentInChildProcess[];
     };
     mcpServer?: {
         agents?: AgentInChildProcess[];
@@ -13,6 +13,7 @@ export declare function loadAIGNEInChildProcess(...args: Parameters<typeof AIGNE
 }>;
 export declare function invokeCLIAgentFromDirInChildProcess(options: {
     dir: string;
+    parent?: string[];
     agent: string;
     input: Message & AgentRunCommonOptions;
 }): Promise<void>;

package/dist/utils/workers/run-aigne-in-child-process-worker.js

@@ -1,9 +1,10 @@
 import assert from "node:assert";
 import { AIGNE } from "@aigne/core";
+import { findCliAgent, mapCliAgent } from "@aigne/core/utils/agent-utils.js";
 import { loadAIGNE } from "../load-aigne.js";
 import { runAgentWithAIGNE } from "../run-with-aigne.js";
 import { parseAgentInput } from "../yargs.js";
-import { serializeAgent } from "./run-aigne-in-child-process.js";
+import { serializeAgent, } from "./run-aigne-in-child-process.js";
 const METHODS = {
     loadAIGNE: loadAIGNEInChildProcess,
     invokeCLIAgentFromDir: invokeCLIAgentFromDirInChildProcess,
@@ -38,7 +39,7 @@ export async function loadAIGNEInChildProcess(...args) {
         agents: aigne.agents.map(serializeAgent),
         cli: {
             chat: aigne.cli.chat ? serializeAgent(aigne.cli.chat) : undefined,
-            agents: aigne.cli.agents.map(serializeAgent),
+            agents: aigne.cli.agents?.map((item) => mapCliAgent(item, serializeAgent)),
         },
         mcpServer: {
             agents: aigne.mcpServer.agents.map(serializeAgent),
@@ -52,12 +53,20 @@ export async function invokeCLIAgentFromDirInChildProcess(options) {
     });
     try {
         const { chat } = aigne.cli;
-        const agent = chat && chat.name === options.agent
-            ? chat
-            : aigne.cli.agents[options.agent] ||
-                aigne.agents[options.agent] ||
-                aigne.skills[options.agent] ||
-                aigne.mcpServer.agents[options.agent];
+        let agent;
+        if (chat && chat.name === options.agent) {
+            agent = chat;
+        }
+        else if (options.parent) {
+            agent = findCliAgent(aigne.cli, options.parent, options.agent);
+        }
+        else {
+            agent =
+                findCliAgent(aigne.cli, [], options.agent) ||
+                    aigne.agents[options.agent] ||
+                    aigne.skills[options.agent] ||
+                    aigne.mcpServer.agents[options.agent];
+        }
         assert(agent, `Agent ${options.agent} not found in ${options.dir}`);
         const input = await parseAgentInput(options.input, agent);
         await runAgentWithAIGNE(aigne, agent, {

package/dist/utils/workers/run-aigne-in-child-process.d.ts

@@ -1,4 +1,5 @@
 import type { Agent } from "@aigne/core";
+import type { AIGNECLIAgent } from "@aigne/core/aigne/type.js";
 import type { JsonSchema } from "@aigne/json-schema-to-zod";
 import type { invokeCLIAgentFromDirInChildProcess, loadAIGNEInChildProcess } from "./run-aigne-in-child-process-worker.js";
 export type LoadAIGNEInChildProcessResult = Awaited<ReturnType<typeof loadAIGNEInChildProcess>>;
@@ -6,6 +7,10 @@ export interface AgentInChildProcess extends Pick<Agent, "name" | "description"
     inputSchema: JsonSchema;
     outputSchema: JsonSchema;
 }
+export interface CLIAgentInChildProcess extends Omit<AIGNECLIAgent, "agent" | "agents"> {
+    agent?: AgentInChildProcess;
+    agents?: CLIAgentInChildProcess[];
+}
 export declare function serializeAgent(agent: Agent): AgentInChildProcess;
 export interface ChildProcessAIGNEMethods {
     loadAIGNE: typeof loadAIGNEInChildProcess;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/cli",
-  "version": "1.49.2-beta",
+  "version": "1.50.0-beta.1",
   "description": "Your command center for agent development",
   "publishConfig": {
     "access": "public"
@@ -84,13 +84,13 @@
     "yoctocolors-cjs": "^2.1.3",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/agent-library": "^1.21.47-beta",
-    "@aigne/aigne-hub": "^0.10.1-beta",
-    "@aigne/core": "^1.61.1-beta",
-    "@aigne/default-memory": "^1.2.10-beta",
-    "@aigne/agentic-memory": "^1.0.47-beta",
-    "@aigne/observability-api": "^0.11.1-beta",
-    "@aigne/openai": "^0.16.1-beta"
+    "@aigne/agent-library": "^1.21.47-beta.1",
+    "@aigne/aigne-hub": "^0.10.1-beta.1",
+    "@aigne/agentic-memory": "^1.0.47-beta.1",
+    "@aigne/core": "^1.62.0-beta",
+    "@aigne/default-memory": "^1.2.10-beta.1",
+    "@aigne/openai": "^0.16.1-beta.1",
+    "@aigne/observability-api": "^0.11.1-beta"
   },
   "devDependencies": {
     "@inquirer/testing": "^2.1.50",
@@ -107,7 +107,7 @@
     "rimraf": "^6.0.1",
     "typescript": "^5.9.2",
     "ufo": "^1.6.1",
-    "@aigne/test-utils": "^0.5.54-beta"
+    "@aigne/test-utils": "^0.5.54-beta.1"
   },
   "scripts": {
     "lint": "tsc --noEmit",