Merge pull request #3 from EvilFreelancer/feat/commands

Use commands instead of search

Author: EvilFreelancer

README.md

@@ -90,19 +90,19 @@ ocli messages --limit 10
 
 ### Command search
 
-When the API surface is too large for `--help`, use the built-in search:
+When the API surface is too large for `--help`, use command filtering with `commands`:
 
 ```bash
 # BM25 natural language search
-ocli search --query "upload files"
-ocli search -q "list messages" --limit 5
+ocli commands --query "upload files"
+ocli commands -q "list messages" --limit 5
 
 # Regex pattern matching
-ocli search --regex "admin.*get"
-ocli search -r "messages" -n 3
+ocli commands --regex "admin.*get"
+ocli commands -r "messages" -n 3
 ```
 
-The BM25 engine (ported from [picoclaw](https://github.com/sipeed/picoclaw)) ranks commands by relevance across name, method, path, description, and parameter names. This enables agents to discover the right endpoint without loading all command schemas into context.
+The BM25 engine (ported from [picoclaw](https://github.com/sipeed/picoclaw)) ranks commands by relevance across name, method, path, description, and parameter names. This enables agents to discover the right endpoint without loading all command schemas into context. The legacy `ocli search` command is kept as a deprecated alias and internally forwards to `ocli commands` with the same flags.
 
 ### Installation and usage via npm and npx
 
@@ -236,9 +236,8 @@ The `ocli` binary provides the following core commands:
 - `ocli profiles show <profile>` - show profile details;
 - `ocli profiles remove <profile>` - remove a profile;
 - `ocli use <profile>` - set the profile to use when `--profile` is not passed (writes profile name to `.ocli/current`).
-- `ocli commands` - list available commands generated from the current profile and its OpenAPI spec.
-- `ocli search --query <text>` - BM25-ranked search across commands by name, path, description.
-- `ocli search --regex <pattern>` - regex pattern search across commands.
+- `ocli commands` - list available commands generated from the current profile and its OpenAPI spec, optionally filter them with `--query` (BM25) or `--regex`.
+- `ocli search` - deprecated alias for `ocli commands` with `--query/--regex`, kept for backward compatibility.
 - `ocli --version` - print the CLI version baked at build time (derived from the latest git tag when available).
 
 Help:
@@ -275,6 +274,7 @@ The project mirrors parts of the `openapi-to-mcp` architecture but implements a
 ### Similar projects
 
 - [openapi-cli-generator](https://github.com/danielgtaylor/openapi-cli-generator) - generates a CLI from an OpenAPI 3 specification using code generation.
+- [anything-llm-cli](https://github.com/Mintplex-Labs/anything-llm/tree/master/clients/anything-cli) - CLI for interacting with AnythingLLM, can consume HTTP APIs and tools.
 - [openapi-commander](https://github.com/bcoughlan/openapi-commander) - Node.js command-line tool generator based on OpenAPI definitions.
 - [OpenAPI Generator](https://openapi-generator.tech/docs/usage) - general-purpose OpenAPI code generator that can also generate CLI clients.
 - [openapi2cli](https://pypi.org/project/openapi2cli/) - Python tool that builds CLI interfaces for OpenAPI 3 APIs.

src/cli.ts

@@ -376,9 +376,27 @@ export async function run(argv: string[], options?: RunOptions): Promise<void> {
     )
     .command(
       "commands",
-      "List available commands for the current profile",
-      (y) => y.version(false),
-      async () => {
+      "List available commands for the current profile (supports --query/--regex search filters)",
+      (y) =>
+        y
+          .version(false)
+          .option("query", {
+            alias: "q",
+            type: "string",
+            description: "Natural language search query to filter commands",
+          })
+          .option("regex", {
+            alias: "r",
+            type: "string",
+            description: "Regex pattern to filter commands by name, path, or description",
+          })
+          .option("limit", {
+            alias: "n",
+            type: "number",
+            default: 10,
+            description: "Maximum number of results when using query or regex filters",
+          }),
+      async (args) => {
         const profile = profileStore.getCurrentProfile(cwd);
         if (!profile) {
           throw new Error("No current profile configured");
@@ -390,33 +408,62 @@ export async function run(argv: string[], options?: RunOptions): Promise<void> {
           return;
         }
 
+        const hasFilters = Boolean(args.query || args.regex);
+
+        if (!hasFilters) {
+          stdout(`Available commands for profile ${profile.name}:\n\n`);
+
+          const maxNameLength = commands.reduce((max, cmd) => (cmd.name.length > max ? cmd.name.length : max), 0);
+          const padding = maxNameLength + 2;
+
+          commands.forEach((cmd) => {
+            const description = cmd.description ?? "";
+            const namePadded = cmd.name.padEnd(padding, " ");
+            stdout(`  ${namePadded}${description}\n`);
+          });
+          return;
+        }
+
+        const searcher = new CommandSearch();
+        searcher.load(commands);
+
+        const limit = (args.limit as number) ?? 10;
+        const results = args.query
+          ? searcher.search(args.query as string, limit)
+          : searcher.searchRegex(args.regex as string, limit);
+
+        if (results.length === 0) {
+          stdout("No commands found.\n");
+          return;
+        }
+
         stdout(`Available commands for profile ${profile.name}:\n\n`);
 
-        const maxNameLength = commands.reduce((max, cmd) => (cmd.name.length > max ? cmd.name.length : max), 0);
+        const maxNameLength = results.reduce((max, r) => (r.name.length > max ? r.name.length : max), 0);
         const padding = maxNameLength + 2;
 
-        commands.forEach((cmd) => {
-          const description = cmd.description ?? "";
-          const namePadded = cmd.name.padEnd(padding, " ");
+        results.forEach((r) => {
+          const description = r.description ?? "";
+          const namePadded = r.name.padEnd(padding, " ");
           stdout(`  ${namePadded}${description}\n`);
         });
       }
     )
     .command(
       "search",
-      "Search commands by query (BM25) or regex pattern",
+      "Deprecated: use 'commands --query/--regex' instead",
       (y) =>
         y
           .version(false)
           .option("query", {
             alias: "q",
             type: "string",
-            description: "Natural language search query",
+            description: "Natural language search query (deprecated, use commands --query instead)",
           })
           .option("regex", {
             alias: "r",
             type: "string",
-            description: "Regex pattern to match command name, path, or description",
+            description: "Regex pattern to match command name, path, or description (deprecated, use commands --regex instead)",
           })
           .option("limit", {
             alias: "n",
@@ -431,38 +478,26 @@ export async function run(argv: string[], options?: RunOptions): Promise<void> {
             return true;
           }),
       async (args) => {
-        const profile = profileStore.getCurrentProfile(cwd);
-        if (!profile) {
-          throw new Error("No current profile configured");
-        }
-
-        const spec = await openapiLoader.loadSpec(profile);
-        const commands = openapiToCommands.buildCommands(spec, profile);
-
-        const searcher = new CommandSearch();
-        searcher.load(commands);
+        stdout("Warning: 'search' is deprecated, use 'commands --query/--regex' instead.\n\n");
 
         const limit = (args.limit as number) ?? 10;
-        const results = args.query
-          ? searcher.search(args.query as string, limit)
-          : searcher.searchRegex(args.regex as string, limit);
-
-        if (results.length === 0) {
-          stdout("No commands found.\n");
-          return;
+        const forwardedArgs: string[] = [];
+        if (args.query) {
+          forwardedArgs.push("--query", String(args.query));
         }
-
-        const maxName = results.reduce((m, r) => (r.name.length > m ? r.name.length : m), 0);
-        const maxMethod = results.reduce((m, r) => (r.method.length > m ? r.method.length : m), 0);
-
-        stdout(`Found ${results.length} command(s):\n\n`);
-        for (const r of results) {
-          const name = r.name.padEnd(maxName + 2);
-          const method = r.method.padEnd(maxMethod + 1);
-          const desc = r.description ?? "";
-          const scorePart = r.score < 1 ? ` [score: ${r.score}]` : "";
-          stdout(`  ${name}${method} ${r.path}  ${desc}${scorePart}\n`);
+        if (args.regex) {
+          forwardedArgs.push("--regex", String(args.regex));
         }
+        forwardedArgs.push("--limit", String(limit));
+
+        await run(["commands", ...forwardedArgs], {
+          cwd,
+          configLocator,
+          profileStore,
+          openapiLoader,
+          stdout,
+          httpClient,
+        });
       }
     )
     .demandCommand(1, "")

tests/cli.test.ts

@@ -329,6 +329,112 @@ describe("cli", () => {
     expect(out).toContain("api_v1_search  Search in content index");
   });
 
+  it("commands supports regex filtering of commands", async () => {
+    const localDir = `${cwd}/.ocli`;
+    const profilesPath = `${localDir}/profiles.ini`;
+    const specPath = "/project/spec.json";
+    const cachePath = `${localDir}/specs/messages-api.json`;
+
+    const spec = {
+      openapi: "3.0.0",
+      paths: {
+        "/messages": {
+          get: {
+            summary: "List messages",
+          },
+        },
+        "/status": {
+          get: {
+            summary: "Get status",
+          },
+        },
+      },
+    };
+
+    const iniContent = [
+      "[messages-api]",
+      "api_base_url = https://api.example.com",
+      "api_basic_auth = ",
+      "api_bearer_token = ",
+      `openapi_spec_source = ${specPath}`,
+      `openapi_spec_cache = ${cachePath}`,
+      "include_endpoints = get:/messages,get:/status",
+      "exclude_endpoints = ",
+      "",
+    ].join("\n");
+
+    const log: string[] = [];
+    const { profileStore, openapiLoader } = createCliDeps(cwd, homeDir, {
+      [profilesPath]: iniContent,
+      [`${localDir}/current`]: "messages-api",
+      [specPath]: JSON.stringify(spec),
+    });
+
+    await run(["commands", "--regex", "messages"], {
+      cwd,
+      profileStore,
+      openapiLoader,
+      stdout: (msg: string) => log.push(msg),
+    });
+
+    const out = log.join("");
+    expect(out).toContain("messages  List messages");
+    expect(out).not.toContain("status");
+  });
+
+  it("commands supports BM25 query filtering of commands", async () => {
+    const localDir = `${cwd}/.ocli`;
+    const profilesPath = `${localDir}/profiles.ini`;
+    const specPath = "/project/spec.json";
+    const cachePath = `${localDir}/specs/messages-api.json`;
+
+    const spec = {
+      openapi: "3.0.0",
+      paths: {
+        "/messages": {
+          get: {
+            summary: "List messages",
+          },
+        },
+        "/status": {
+          get: {
+            summary: "Get status",
+          },
+        },
+      },
+    };
+
+    const iniContent = [
+      "[messages-api]",
+      "api_base_url = https://api.example.com",
+      "api_basic_auth = ",
+      "api_bearer_token = ",
+      `openapi_spec_source = ${specPath}`,
+      `openapi_spec_cache = ${cachePath}`,
+      "include_endpoints = get:/messages,get:/status",
+      "exclude_endpoints = ",
+      "",
+    ].join("\n");
+
+    const log: string[] = [];
+    const { profileStore, openapiLoader } = createCliDeps(cwd, homeDir, {
+      [profilesPath]: iniContent,
+      [`${localDir}/current`]: "messages-api",
+      [specPath]: JSON.stringify(spec),
+    });
+
+    await run(["commands", "--query", "list messages"], {
+      cwd,
+      profileStore,
+      openapiLoader,
+      stdout: (msg: string) => log.push(msg),
+    });
+
+    const out = log.join("");
+    expect(out).toContain("messages  List messages");
+    expect(out).not.toContain("status");
+  });
+
   it("commands add method suffix when spec path has multiple methods even if only one is included", async () => {
     const localDir = `${cwd}/.ocli`;
     const profilesPath = `${localDir}/profiles.ini`;