@ai-agent-forge/agent-forge 0.85.0

package/dist/cli/args.js

@@ -0,0 +1,712 @@
+/**
+ * CLI argument parsing and help display
+ */
+import chalk from "chalk";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, ENV_SESSION_DIR } from "../config.js";
+// TRACE_KINDS_V1 is a value import, but observability-types.ts has no runtime
+// edges (its two imports are type-only), so no import cycle can form here.
+import { TRACE_KINDS_V1 } from "../plugins/observability-types.js";
+const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+const VALID_LOG_LEVELS = ["debug", "info", "warn", "error"];
+export function isValidHostLogLevel(level) {
+    return VALID_LOG_LEVELS.includes(level);
+}
+/** Single source of valid `--trace-kind` values: the TRACE_KINDS_V1 runtime mirror. */
+export function isValidTraceKind(kind) {
+    return TRACE_KINDS_V1.includes(kind);
+}
+/** Keep CLI plugin selection bounded before it reaches profile resolution. */
+export const MAX_PLUGIN_CLI_ID_CHARS = 128;
+export const MAX_PLUGIN_CLI_IDS = 128;
+export function isValidThinkingLevel(level) {
+    return VALID_THINKING_LEVELS.includes(level);
+}
+export function normalizeSessionName(value) {
+    const name = value.trim();
+    return name.length > 0 ? name : undefined;
+}
+function parseBoundedPluginId(args, index, result, option, values) {
+    const raw = args[index + 1];
+    if (raw === undefined || raw.startsWith("-")) {
+        result.diagnostics.push({ type: "error", message: `${option} requires a plugin id` });
+        return index;
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        result.diagnostics.push({ type: "error", message: `${option} requires a non-empty plugin id` });
+        return index + 1;
+    }
+    if (value.length > MAX_PLUGIN_CLI_ID_CHARS) {
+        result.diagnostics.push({
+            type: "error",
+            message: `${option} plugin id must be at most ${MAX_PLUGIN_CLI_ID_CHARS} characters`,
+        });
+        return index + 1;
+    }
+    if (values.length >= MAX_PLUGIN_CLI_IDS) {
+        result.diagnostics.push({
+            type: "error",
+            message: `${option} accepts at most ${MAX_PLUGIN_CLI_IDS} plugin ids`,
+        });
+        return index + 1;
+    }
+    values.push(value);
+    return index + 1;
+}
+function parsePluginProfileValue(args, index, result, rawValue) {
+    const raw = rawValue ?? args[index + 1];
+    if (raw === undefined || raw.startsWith("-")) {
+        result.diagnostics.push({ type: "error", message: "--plugin-profile requires a profile id" });
+        return rawValue === undefined ? index : index;
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        result.diagnostics.push({ type: "error", message: "--plugin-profile requires a non-empty profile id" });
+        return rawValue === undefined ? index + 1 : index;
+    }
+    if (value.length > MAX_PLUGIN_CLI_ID_CHARS) {
+        result.diagnostics.push({
+            type: "error",
+            message: `--plugin-profile id must be at most ${MAX_PLUGIN_CLI_ID_CHARS} characters`,
+        });
+        return rawValue === undefined ? index + 1 : index;
+    }
+    result.pluginProfile = value;
+    return rawValue === undefined ? index + 1 : index;
+}
+export function parseArgs(args) {
+    const result = {
+        messages: [],
+        fileArgs: [],
+        diagnostics: [],
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--") {
+            for (const positionalArg of args.slice(i + 1)) {
+                if (positionalArg.startsWith("@")) {
+                    result.fileArgs.push(positionalArg.slice(1));
+                }
+                else {
+                    result.messages.push(positionalArg);
+                }
+            }
+            break;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            result.help = true;
+        }
+        else if (arg === "--version" || arg === "-v") {
+            result.version = true;
+        }
+        else if (arg === "--mode" && i + 1 < args.length) {
+            const mode = args[++i];
+            if (mode === "text" || mode === "json" || mode === "rpc") {
+                result.mode = mode;
+            }
+        }
+        else if (arg === "--continue" || arg === "-c") {
+            result.continue = true;
+        }
+        else if (arg === "--resume" || arg === "-r") {
+            result.resume = true;
+        }
+        else if (arg === "--provider" && i + 1 < args.length) {
+            result.provider = args[++i];
+        }
+        else if ((arg === "--model" || arg === "-m") && i + 1 < args.length) {
+            result.model = args[++i];
+        }
+        else if (arg === "--api-key" && i + 1 < args.length) {
+            result.apiKey = args[++i];
+        }
+        else if (arg === "--system-prompt" && i + 1 < args.length) {
+            result.systemPrompt = args[++i];
+        }
+        else if (arg === "--append-system-prompt" && i + 1 < args.length) {
+            result.appendSystemPrompt = result.appendSystemPrompt ?? [];
+            result.appendSystemPrompt.push(args[++i]);
+        }
+        else if (arg === "--name" || arg === "-n") {
+            if (i + 1 < args.length) {
+                result.name = args[++i];
+            }
+            else {
+                result.diagnostics.push({ type: "error", message: "--name requires a value" });
+            }
+        }
+        else if (arg === "--no-session") {
+            result.noSession = true;
+        }
+        else if (arg === "--session" && i + 1 < args.length) {
+            result.session = args[++i];
+        }
+        else if (arg === "--session-id" && i + 1 < args.length) {
+            result.sessionId = args[++i];
+        }
+        else if (arg === "--fork" && i + 1 < args.length) {
+            result.fork = args[++i];
+        }
+        else if (arg === "--session-dir" && i + 1 < args.length) {
+            result.sessionDir = args[++i];
+        }
+        else if (arg === "--suite") {
+            const id = args[i + 1];
+            if (id !== undefined && !id.startsWith("-")) {
+                result.suite = id;
+                i++;
+            }
+            else {
+                result.diagnostics.push({ type: "error", message: "--suite requires a suite id" });
+            }
+        }
+        else if (arg === "--suite-create") {
+            const id = args[i + 1];
+            if (id !== undefined && !id.startsWith("-")) {
+                result.suiteCreate = id;
+                i++;
+            }
+            else {
+                result.diagnostics.push({ type: "error", message: "--suite-create requires a suite id" });
+            }
+        }
+        else if (arg === "--clone-from") {
+            const id = args[i + 1];
+            if (id !== undefined && !id.startsWith("-")) {
+                result.cloneFrom = id;
+                i++;
+            }
+            else {
+                result.diagnostics.push({ type: "error", message: "--clone-from requires a suite id" });
+            }
+        }
+        else if (arg === "--suite-delete") {
+            const id = args[i + 1];
+            if (id !== undefined && !id.startsWith("-")) {
+                result.suiteDelete = id;
+                i++;
+            }
+            else {
+                result.diagnostics.push({ type: "error", message: "--suite-delete requires a suite id" });
+            }
+        }
+        else if (arg === "--suite-reset") {
+            const id = args[i + 1];
+            if (id !== undefined && !id.startsWith("-")) {
+                result.suiteReset = id;
+                i++;
+            }
+            else {
+                result.diagnostics.push({ type: "error", message: "--suite-reset requires a suite id" });
+            }
+        }
+        else if (arg === "--serve") {
+            const raw = args[i + 1];
+            const port = raw !== undefined && /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+            if (Number.isInteger(port) && port <= 65535) {
+                result.serve = port;
+                i++;
+            }
+            else {
+                result.diagnostics.push({ type: "error", message: "--serve requires a valid TCP port (0-65535)" });
+                if (raw !== undefined)
+                    i++;
+            }
+        }
+        else if (arg === "--subagent-runner") {
+            result.subagentRunner = true;
+        }
+        else if (arg === "--serve-workspace-root") {
+            const dir = args[i + 1];
+            if (dir === undefined || dir.startsWith("-")) {
+                result.diagnostics.push({ type: "error", message: "--serve-workspace-root requires a directory" });
+            }
+            else {
+                result.serveWorkspaceRoots = result.serveWorkspaceRoots ?? [];
+                result.serveWorkspaceRoots.push(dir);
+                i++;
+            }
+        }
+        else if (arg === "--models" && i + 1 < args.length) {
+            result.models = args[++i].split(",").map((s) => s.trim());
+        }
+        else if (arg === "--no-tools" || arg === "-nt") {
+            result.noTools = true;
+        }
+        else if (arg === "--no-builtin-tools" || arg === "-nbt") {
+            result.noBuiltinTools = true;
+        }
+        else if ((arg === "--tools" || arg === "-t") && i + 1 < args.length) {
+            result.tools = args[++i]
+                .split(",")
+                .map((s) => s.trim())
+                .filter((name) => name.length > 0);
+        }
+        else if ((arg === "--exclude-tools" || arg === "-xt") && i + 1 < args.length) {
+            result.excludeTools = args[++i]
+                .split(",")
+                .map((s) => s.trim())
+                .filter((name) => name.length > 0);
+        }
+        else if (arg === "--thinking" && i + 1 < args.length) {
+            const level = args[++i];
+            if (isValidThinkingLevel(level)) {
+                result.thinking = level;
+            }
+            else {
+                result.diagnostics.push({
+                    type: "warning",
+                    message: `Invalid thinking level "${level}". Valid values: ${VALID_THINKING_LEVELS.join(", ")}`,
+                });
+            }
+        }
+        else if (arg === "--print" || arg === "-p") {
+            result.print = true;
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("@") && (!next.startsWith("-") || next.startsWith("---"))) {
+                result.messages.push(next);
+                i++;
+            }
+        }
+        else if (arg === "--export" && i + 1 < args.length) {
+            result.export = args[++i];
+        }
+        else if (arg === "--trace") {
+            // View command: bare --trace targets the most recent session; a
+            // following non-option token is the session id or trace/session path.
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                result.trace = next;
+                i++;
+            }
+            else {
+                result.trace = "";
+            }
+        }
+        else if (arg === "--trace-json") {
+            result.traceJson = true;
+        }
+        else if (arg === "--trace-kind") {
+            const raw = args[i + 1];
+            if (raw === undefined || raw.startsWith("-")) {
+                result.diagnostics.push({ type: "error", message: "--trace-kind requires a comma-separated kind list" });
+            }
+            else {
+                i++;
+                const kinds = raw
+                    .split(",")
+                    .map((kind) => kind.trim())
+                    .filter((kind) => kind.length > 0);
+                const invalid = kinds.filter((kind) => !isValidTraceKind(kind));
+                if (kinds.length === 0) {
+                    result.diagnostics.push({ type: "error", message: "--trace-kind requires at least one trace kind" });
+                }
+                else if (invalid.length > 0) {
+                    result.diagnostics.push({
+                        type: "error",
+                        message: `Invalid trace kind(s) "${invalid.join(", ")}". Valid values: ${TRACE_KINDS_V1.join(", ")}`,
+                    });
+                }
+                else {
+                    result.traceKind = kinds;
+                }
+            }
+        }
+        else if (arg === "--trace-limit") {
+            const raw = args[i + 1];
+            if (raw === undefined || raw.startsWith("-")) {
+                result.diagnostics.push({ type: "error", message: "--trace-limit requires a positive integer" });
+            }
+            else {
+                i++;
+                const limit = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+                if (Number.isInteger(limit) && limit > 0) {
+                    result.traceLimit = limit;
+                }
+                else {
+                    result.diagnostics.push({
+                        type: "error",
+                        message: `Invalid trace limit "${raw}". Expected a positive integer`,
+                    });
+                }
+            }
+        }
+        else if (arg === "--no-plugins" || arg === "-np") {
+            result.noPlugins = true;
+        }
+        else if (arg === "--no-trace") {
+            result.noTrace = true;
+        }
+        else if (arg === "--log-level") {
+            const level = args[i + 1];
+            if (level === undefined || level.startsWith("-")) {
+                result.diagnostics.push({ type: "error", message: "--log-level requires a level" });
+            }
+            else if (!isValidHostLogLevel(level)) {
+                i++;
+                result.diagnostics.push({
+                    type: "error",
+                    message: `Invalid log level "${level}". Valid values: ${VALID_LOG_LEVELS.join(", ")}`,
+                });
+            }
+            else {
+                result.logLevel = level;
+                i++;
+            }
+        }
+        else if (arg === "--plugin-profile") {
+            i = parsePluginProfileValue(args, i, result);
+        }
+        else if (arg.startsWith("--plugin-profile=")) {
+            parsePluginProfileValue(args, i, result, arg.slice("--plugin-profile=".length));
+        }
+        else if (arg === "--plugin-scope" || arg.startsWith("--plugin-scope=")) {
+            const raw = arg === "--plugin-scope" ? args[i + 1] : arg.slice("--plugin-scope=".length);
+            if (arg === "--plugin-scope")
+                i++;
+            if (raw !== "global" && raw !== "project") {
+                result.diagnostics.push({ type: "error", message: "--plugin-scope must be global or project" });
+            }
+            else if (result.pluginSelectionScope !== undefined) {
+                result.diagnostics.push({ type: "error", message: "--plugin-scope may be specified only once" });
+            }
+            else {
+                result.pluginSelectionScope = raw;
+            }
+        }
+        else if (arg === "--plugin") {
+            result.plugins = result.plugins ?? [];
+            i = parseBoundedPluginId(args, i, result, "--plugin", result.plugins);
+        }
+        else if (arg.startsWith("--plugin=")) {
+            result.plugins = result.plugins ?? [];
+            const value = arg.slice("--plugin=".length).trim();
+            if (value.length === 0) {
+                result.diagnostics.push({ type: "error", message: "--plugin requires a non-empty plugin id" });
+            }
+            else if (value.length > MAX_PLUGIN_CLI_ID_CHARS) {
+                result.diagnostics.push({
+                    type: "error",
+                    message: `--plugin plugin id must be at most ${MAX_PLUGIN_CLI_ID_CHARS} characters`,
+                });
+            }
+            else if (result.plugins.length >= MAX_PLUGIN_CLI_IDS) {
+                result.diagnostics.push({
+                    type: "error",
+                    message: `--plugin accepts at most ${MAX_PLUGIN_CLI_IDS} plugin ids`,
+                });
+            }
+            else {
+                result.plugins.push(value);
+            }
+        }
+        else if (arg === "--disable-plugin") {
+            result.disabledPlugins = result.disabledPlugins ?? [];
+            i = parseBoundedPluginId(args, i, result, "--disable-plugin", result.disabledPlugins);
+        }
+        else if (arg.startsWith("--disable-plugin=")) {
+            result.disabledPlugins = result.disabledPlugins ?? [];
+            const value = arg.slice("--disable-plugin=".length).trim();
+            if (value.length === 0) {
+                result.diagnostics.push({ type: "error", message: "--disable-plugin requires a non-empty plugin id" });
+            }
+            else if (value.length > MAX_PLUGIN_CLI_ID_CHARS) {
+                result.diagnostics.push({
+                    type: "error",
+                    message: `--disable-plugin plugin id must be at most ${MAX_PLUGIN_CLI_ID_CHARS} characters`,
+                });
+            }
+            else if (result.disabledPlugins.length >= MAX_PLUGIN_CLI_IDS) {
+                result.diagnostics.push({
+                    type: "error",
+                    message: `--disable-plugin accepts at most ${MAX_PLUGIN_CLI_IDS} plugin ids`,
+                });
+            }
+            else {
+                result.disabledPlugins.push(value);
+            }
+        }
+        else if (arg === "--skill" && i + 1 < args.length) {
+            result.skills = result.skills ?? [];
+            result.skills.push(args[++i]);
+        }
+        else if (arg === "--prompt-template" && i + 1 < args.length) {
+            result.promptTemplates = result.promptTemplates ?? [];
+            result.promptTemplates.push(args[++i]);
+        }
+        else if (arg === "--theme" && i + 1 < args.length) {
+            result.themes = result.themes ?? [];
+            result.themes.push(args[++i]);
+        }
+        else if (arg === "--use-theme") {
+            const themeName = args[i + 1];
+            if (themeName === undefined || themeName.startsWith("-")) {
+                result.diagnostics.push({ type: "error", message: "--use-theme requires a theme name" });
+            }
+            else {
+                result.useTheme = themeName;
+                i++;
+            }
+        }
+        else if (arg === "--no-skills" || arg === "-ns") {
+            result.noSkills = true;
+        }
+        else if (arg === "--no-prompt-templates" || arg === "-np") {
+            result.noPromptTemplates = true;
+        }
+        else if (arg === "--no-themes") {
+            result.noThemes = true;
+        }
+        else if (arg === "--no-context-files" || arg === "-nc") {
+            result.noContextFiles = true;
+        }
+        else if (arg === "--list-models") {
+            // Check if next arg is a search pattern (not a flag or file arg)
+            if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {
+                result.listModels = args[++i];
+            }
+            else {
+                result.listModels = true;
+            }
+        }
+        else if (arg === "--tui-mode") {
+            const mode = args[i + 1];
+            if (mode === "regular" || mode === "fullscreen") {
+                result.tuiMode = mode;
+                i++;
+            }
+            else if (mode === undefined || mode.startsWith("-")) {
+                result.diagnostics.push({ type: "error", message: "--tui-mode requires regular or fullscreen" });
+            }
+            else {
+                i++;
+                result.diagnostics.push({
+                    type: "error",
+                    message: `Invalid TUI mode "${mode}". Valid values: regular, fullscreen`,
+                });
+            }
+        }
+        else if (arg === "--verbose") {
+            result.verbose = true;
+        }
+        else if (arg === "--offline") {
+            result.offline = true;
+        }
+        else if (arg.startsWith("@")) {
+            result.fileArgs.push(arg.slice(1)); // Remove @ prefix
+        }
+        else if (arg.startsWith("--")) {
+            // Unknown long options are errors: extension-registered CLI flags no
+            // longer exist, so there is nothing left that could claim them.
+            result.diagnostics.push({ type: "error", message: `Unknown option: ${arg.split("=")[0]}` });
+            i++;
+        }
+        else if (arg.startsWith("-") && !arg.startsWith("--")) {
+            result.diagnostics.push({ type: "error", message: `Unknown option: ${arg}` });
+        }
+        else if (!arg.startsWith("-")) {
+            result.messages.push(arg);
+        }
+    }
+    return result;
+}
+export function printHelp() {
+    console.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} [options] [--] [@files...] [messages...]
+
+${chalk.bold("Commands:")}
+  ${APP_NAME} install <source> [-l]     Install extension source and add to settings
+  ${APP_NAME} remove <source> [-l]      Remove extension source from settings
+  ${APP_NAME} uninstall <source> [-l]   Alias for remove
+  ${APP_NAME} update [source|self|agent-forge]   Update Agent Forge, extensions, or model catalogs
+  ${APP_NAME} list                      List installed extensions from settings
+  ${APP_NAME} config [-l]               Open TUI to enable/disable package resources (Tab switches scope)
+  ${APP_NAME} auth <command>            Print credentials or check provider readiness
+  ${APP_NAME} <command> --help          Show help for install/remove/uninstall/update/list/config/auth
+
+${chalk.bold("Options:")}
+  --provider <name>              Provider name (default: google)
+  --model <pattern>              Model pattern or ID (supports "provider/id" and optional ":<thinking>")
+  --api-key <key>                API key (defaults to env vars)
+  --system-prompt <text>         System prompt (default: coding assistant prompt)
+  --append-system-prompt <text>  Append text or file contents to the system prompt (can be used multiple times)
+  --mode <mode>                  Output mode: text (default), json, or rpc
+  --print, -p                    Non-interactive mode: process prompt and exit
+  --continue, -c                 Continue previous session
+  --resume, -r                   Select a session to resume
+  --session <path|id>            Use specific session file or partial UUID
+  --session-id <id>              Use exact project session ID, creating it if missing
+  --fork <path|id>               Fork specific session file or partial UUID into a new session
+  --session-dir <dir>            Directory for session storage and lookup
+  --suite <id>                   Suite (方案) for this run: assistant (default) or coding; new sessions only
+  --suite-create <id>            Create a user suite workspace and exit; add --clone-from <id> to copy one
+  --suite-delete <id>            Delete a user suite workspace (active session references refuse) and exit
+  --suite-reset <id>             Reset a builtin suite to factory contents (shows a diff) and exit
+  --serve <port>                 (Experimental, local trust only) Serve the coding-agent session runtime over the WebSocket gateway (default: 127.0.0.1; HTTP surface: /healthz plus token-protected artifact reads) and exit on SIGINT/SIGTERM
+                                 Durable journal: <agentDir>/remote-server-journal.jsonl (never the process cwd)
+  --serve-workspace-root <dir>   Opt-in --serve boundary: remote creates must run inside one of these roots (repeatable); without it any local directory is allowed
+  --subagent-runner              (Experimental) Run as a headless subagent runner: serve the subagent-task protocol on stdio for a parent session's runner pool (D-045)
+  --no-session                   Don't save session (ephemeral)
+  --name, -n <name>              Set session display name
+  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling
+                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching
+  --no-tools, -nt                Disable all tools by default (built-in and plugin)
+  --no-builtin-tools, -nbt       Disable built-in tools by default but keep plugin/custom tools enabled
+  --tools, -t <tools>            Comma-separated allowlist of tool names to enable
+                                 Applies to built-in, plugin, and custom tools
+  --exclude-tools, -xt <tools>   Comma-separated denylist of tool names to disable
+                                 Applies to built-in, plugin, and custom tools
+  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh, max
+  --no-plugins, -np               Disable capability plugin discovery (D-028 escape hatch)
+  --no-trace                      Disable session trace collection (no .trace.jsonl file is written)
+  --log-level <level>             Host log level: debug, info (default), warn, error
+  --plugin-profile <id>            Select a builtin capability plugin profile for this run
+  --plugin <id>                    Select a plugin within the profile (repeatable)
+  --disable-plugin <id>            Disable a plugin within the profile (repeatable)
+  --plugin-scope <scope>           Read the explicit selection from global or project storage
+  plugin catalog list             List installed/available ecosystem plugins (independent namespace)
+  --skill <path>                 Load a skill file or directory (can be used multiple times)
+  --no-skills, -ns               Disable skills discovery and loading
+  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)
+  --no-prompt-templates, -np     Disable prompt template discovery and loading
+  --theme <path>                 Load a theme file or directory (can be used multiple times)
+  --use-theme <name[/name]>      Set the initial interactive theme for this run
+  --no-themes                    Disable theme discovery and loading
+  --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md discovery and loading
+  --export <file>                Export session file to HTML and exit
+  --trace <session>              View a session trace file as a text timeline and exit; <session> is a session id/prefix or trace/session file path, omit it for the most recent session
+  --trace-json                   With --trace, output the structured trace records as JSON instead of the text timeline
+  --trace-kind <k1,k2>           With --trace, show only records of these kinds (comma-separated); valid kinds: ${TRACE_KINDS_V1.join(", ")}
+  --trace-limit <n>              With --trace, show only the last N records (positive integer)
+  --list-models [search]         List available models (with optional fuzzy search)
+  --verbose                      Force verbose startup (overrides quietStartup setting)
+  --tui-mode <mode>              TUI mode: regular (default) or fullscreen
+  --offline                      Disable startup network operations (same as AGENT_FORGE_OFFLINE=1)
+  --                             End option parsing; treat remaining arguments as messages/files
+  --help, -h                     Show this help
+  --version, -v                  Show version number
+
+${chalk.bold("Examples:")}
+  # Print a provider API key for an external client
+  ${APP_NAME} auth print-api-key --provider openai
+
+  # Print an OAuth bearer token for an external client (refreshes if expired)
+  ${APP_NAME} auth print-bearer-token --provider openai-codex
+
+  # Interactive mode
+  ${APP_NAME}
+
+  # Interactive mode with initial prompt
+  ${APP_NAME} "List all .ts files in src/"
+
+  # Include files in initial message
+  ${APP_NAME} @prompt.md @image.png "What color is the sky?"
+
+  # Non-interactive mode (process and exit)
+  ${APP_NAME} -p "List all .ts files in src/"
+
+  # Prompt beginning with a dash
+  ${APP_NAME} -p -- "- Summarize these points"
+
+  # Multiple messages (interactive)
+  ${APP_NAME} "Read package.json" "What dependencies do we have?"
+
+  # Continue previous session
+  ${APP_NAME} --continue "What did we discuss?"
+
+  # Start a named session
+  ${APP_NAME} --name "Refactor auth module"
+
+  # Use different model
+  ${APP_NAME} --provider openai --model gpt-4o-mini "Help me refactor this code"
+
+  # Use model with provider prefix (no --provider needed)
+  ${APP_NAME} --model openai/gpt-4o "Help me refactor this code"
+
+  # Use model with thinking level shorthand
+  ${APP_NAME} --model sonnet:high "Solve this complex problem"
+
+  # Limit model cycling to specific models
+  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o
+
+  # Limit to a specific provider with glob pattern
+  ${APP_NAME} --models "github-copilot/*"
+
+  # Cycle models with fixed thinking levels
+  ${APP_NAME} --models sonnet:high,haiku:low
+
+  # Start with a specific thinking level
+  ${APP_NAME} --thinking high "Solve this complex problem"
+
+  # Read-only mode (no file modifications possible)
+  ${APP_NAME} --tools read,grep,find,ls -p "Review the code in src/"
+
+  # Disable one tool while keeping the rest available
+  ${APP_NAME} --exclude-tools ask_question
+
+  # Export a session file to HTML
+  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl
+  ${APP_NAME} --export session.jsonl output.html
+
+${chalk.bold("Environment Variables:")}
+  ANTHROPIC_AUTH_TOKEN             - Anthropic bearer auth token
+  ANTHROPIC_API_KEY                - Anthropic Claude API key
+  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)
+  ANT_LING_API_KEY                 - Ant Ling API key
+  OPENAI_API_KEY                   - OpenAI GPT API key
+  AZURE_OPENAI_API_KEY             - Azure OpenAI API key
+  AZURE_OPENAI_BASE_URL            - Azure OpenAI/Cognitive Services base URL (e.g. https://{resource}.openai.azure.com)
+  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)
+  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)
+  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)
+  DEEPSEEK_API_KEY                 - DeepSeek API key
+  NVIDIA_API_KEY                   - NVIDIA NIM API key
+  GEMINI_API_KEY                   - Google Gemini API key
+  GROQ_API_KEY                     - Groq API key
+  CEREBRAS_API_KEY                 - Cerebras API key
+  XAI_API_KEY                      - xAI Grok API key
+  FIREWORKS_API_KEY                - Fireworks API key
+  TOGETHER_API_KEY                 - Together AI API key
+  BASETEN_API_KEY                  - Baseten API key
+  OPENROUTER_API_KEY               - OpenRouter API key
+  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key
+  ZAI_API_KEY                      - ZAI Coding Plan API key (Global)
+  ZAI_CODING_CN_API_KEY            - ZAI Coding Plan API key (China)
+  MISTRAL_API_KEY                  - Mistral API key
+  MINIMAX_API_KEY                  - MiniMax API key
+  MOONSHOT_API_KEY                 - Moonshot AI API key
+  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key
+  KIMI_API_KEY                     - Kimi For Coding API key
+  CLOUDFLARE_API_KEY               - Cloudflare API token (Workers AI and AI Gateway)
+  CLOUDFLARE_ACCOUNT_ID            - Cloudflare account id (required for both)
+  CLOUDFLARE_GATEWAY_ID            - Cloudflare AI Gateway slug (required for AI Gateway)
+  QWEN_TOKEN_PLAN_API_KEY          - Qwen Token Plan API key (international region)
+  QWEN_TOKEN_PLAN_CN_API_KEY       - Qwen Token Plan API key (China region)
+  XIAOMI_API_KEY                   - Xiaomi MiMo API key (api.xiaomimimo.com billing)
+  XIAOMI_TOKEN_PLAN_CN_API_KEY     - Xiaomi MiMo Token Plan API key (China region)
+  XIAOMI_TOKEN_PLAN_AMS_API_KEY    - Xiaomi MiMo Token Plan API key (Amsterdam region)
+  XIAOMI_TOKEN_PLAN_SGP_API_KEY    - Xiaomi MiMo Token Plan API key (Singapore region)
+  AWS_PROFILE                      - AWS profile for Amazon Bedrock
+  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock
+  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock
+  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)
+  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)
+  ${ENV_AGENT_DIR.padEnd(32)} - Config directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  ${ENV_SESSION_DIR.padEnd(32)} - Session storage directory (overridden by --session-dir)
+  AGENT_FORGE_PACKAGE_DIR                   - Override package directory (for Nix/Guix store paths)
+  AGENT_FORGE_OFFLINE                       - Disable startup network operations when set to 1/true/yes
+
+${chalk.bold("Built-in Tool Names:")}
+  read       - Read file contents
+  bash       - Execute bash commands
+  powershell - Execute PowerShell commands on Windows
+  edit       - Edit files with find/replace
+  write      - Write files (creates/overwrites)
+  grep       - Search file contents (read-only, off by default)
+  find       - Find files by glob pattern (read-only, off by default)
+  ls         - List directory contents (read-only, off by default)
+`);
+}
+//# sourceMappingURL=args.js.map