specli 0.0.30 → 0.0.32

package/dist/ai/tools.d.ts

@@ -25,7 +25,7 @@ import { type SpecliOptions } from "../client/index.js";
  * tool already has the spec loaded and ready to use.
  */
 export declare function specliTool(options: SpecliOptions): Promise<import("ai").Tool<{
-    command: "list" | "exec" | "help";
+    command: "list" | "help" | "exec";
     resource?: string | undefined;
     action?: string | undefined;
     args?: string[] | undefined;

package/dist/cli/main.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import { Command, Help } from "commander";
 import { getArgValue, hasAnyArg } from "./runtime/argv.js";
 import { collectRepeatable } from "./runtime/collect.js";
 /**
@@ -28,6 +28,7 @@ import { deleteToken, getToken, setToken } from "./runtime/profile/secrets.js";
 import { readProfiles, upsertProfile, writeProfiles, } from "./runtime/profile/store.js";
 export async function main(argv, options = {}) {
     const program = new Command();
+    const defaultHelp = new Help();
     // Get version - use embedded version if available, otherwise read from package.json
     const cliVersion = options.version ?? getPackageVersion();
     program
@@ -177,6 +178,10 @@ export async function main(argv, options = {}) {
                 process.stdout.write(`- ${program.name()} ${op.resource} ${op.action}${args}\n`);
             }
         }
+        process.stdout.write("\nTip: explore required flags with --help at each level:\n" +
+            `- ${program.name()} --help\n` +
+            `- ${program.name()} <resource> --help\n` +
+            `- ${program.name()} <resource> <action> --help\n`);
     });
     addGeneratedCommands(program, {
         servers: ctx.servers,
@@ -189,5 +194,128 @@ export async function main(argv, options = {}) {
             auth: options.auth,
         },
     });
+    program.configureHelp({
+        formatHelp: (cmd, _helper) => {
+            // Only customize the top-level help. Subcommands should keep
+            // their own default or explicitly configured help.
+            if (cmd !== program)
+                return defaultHelp.formatHelp(cmd, defaultHelp);
+            const lines = [];
+            const name = program.name();
+            const embedded = Boolean(options.embeddedSpecText);
+            lines.push(`Usage: ${name} [options] [command]`);
+            lines.push("");
+            lines.push(program.description());
+            lines.push("");
+            // OpenAPI-derived commands first (resources)
+            if (ctx.commands.resources.length > 0) {
+                lines.push("OpenAPI Commands:");
+                const resources = [...ctx.commands.resources]
+                    .map((r) => r.resource)
+                    .sort((a, b) => a.localeCompare(b));
+                for (const r of resources) {
+                    lines.push(`  ${r}`);
+                }
+                lines.push("");
+            }
+            // Non-OpenAPI commands (built-ins)
+            lines.push("Global Commands:");
+            const globalCommands = ["login", "logout", "whoami", "__schema", "help"];
+            const maxCmdLen = Math.max(...globalCommands.map((c) => c.length));
+            for (const cmdName of globalCommands) {
+                const c = program.commands.find((c) => c.name() === cmdName);
+                if (!c)
+                    continue;
+                const term = cmdName === "login"
+                    ? "login [token]"
+                    : cmdName === "help"
+                        ? "help [command]"
+                        : cmdName;
+                const desc = c.description();
+                const pad = " ".repeat(Math.max(1, maxCmdLen - cmdName.length + 2));
+                lines.push(`  ${term}${pad}${desc}`);
+            }
+            lines.push("");
+            // Global options last
+            lines.push("Global Options:");
+            const optionRows = [];
+            for (const opt of program.options) {
+                // In compiled binaries the spec is embedded; --spec is meaningless.
+                if (embedded && opt.long === "--spec")
+                    continue;
+                optionRows.push({ flags: opt.flags, desc: opt.description });
+            }
+            optionRows.push({
+                flags: "-h, --help",
+                desc: "display help for command",
+            });
+            const maxOptLen = Math.max(...optionRows.map((o) => o.flags.length));
+            for (const row of optionRows) {
+                const pad = " ".repeat(Math.max(1, maxOptLen - row.flags.length + 2));
+                lines.push(`  ${row.flags}${pad}${row.desc}`);
+            }
+            lines.push("");
+            lines.push("Agent workflow:");
+            lines.push(`  1) ${name} __schema --json --min`);
+            lines.push(`  2) ${name} <resource> --help`);
+            lines.push(`  3) ${name} <resource> <action> --help`);
+            lines.push("");
+            return lines.join("\n");
+        },
+    });
+    if (argv.length <= 2) {
+        program.outputHelp();
+        return;
+    }
+    const args = argv.slice(2);
+    const flagWithValue = new Set([
+        "--spec",
+        "--server",
+        "--server-var",
+        "--auth",
+        "--bearer-token",
+        "--oauth-token",
+        "--username",
+        "--password",
+        "--api-key",
+    ]);
+    const boolFlags = new Set(["--json"]);
+    const passthroughFlags = new Set(["-h", "--help", "-v", "--version"]);
+    let hasSubcommand = false;
+    let onlyKnownGlobals = true;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a)
+            continue;
+        if (passthroughFlags.has(a))
+            break;
+        if (boolFlags.has(a))
+            continue;
+        if (flagWithValue.has(a)) {
+            i++;
+            continue;
+        }
+        if (a.startsWith("--") && a.includes("=")) {
+            const key = a.slice(0, a.indexOf("="));
+            if (!flagWithValue.has(key) &&
+                !boolFlags.has(key) &&
+                !passthroughFlags.has(key)) {
+                onlyKnownGlobals = false;
+            }
+            continue;
+        }
+        if (a.startsWith("--") || a.startsWith("-")) {
+            onlyKnownGlobals = false;
+            continue;
+        }
+        hasSubcommand = true;
+        break;
+    }
+    if (!hasSubcommand &&
+        onlyKnownGlobals &&
+        !hasAnyArg(argv, ["-h", "--help", "-v", "--version"])) {
+        program.outputHelp();
+        return;
+    }
     await program.parseAsync(argv);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "specli",
-	"version": "0.0.30",
+	"version": "0.0.32",
 	"description": "Run any OpenAPI spec as a CLI. Built for Agents.",
 	"repository": {
 		"type": "git",