docstar-cli 1.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,16 @@
 # docstar-cli
 
-A CLI for calling published DocStar API endpoints directly from your terminal, without leaving the shell to read docs. Point it at a DocStar docs site, pick which modules (e.g. "Slack") you want, and it turns each published endpoint into a real command you can run.
+A CLI for calling published DocStar API endpoints directly from your terminal, without leaving the shell to read docs. Point it at a DocStar docs site, pick which modules (e.g. "Slack") you want, and it turns each published endpoint into a real command you can run. You can install from multiple docs sites/collections at once — each is kept separate under its own **CLI name**.
+
+## Concepts: collection → module → endpoint
+
+Every command follows a fixed three-level hierarchy:
+
+1. **Collection** — a docs site, identified by its **CLI name** (e.g. `msg91`). This is what `docstar-cli init` installs.
+2. **Module** — a top-level section within that collection (e.g. `slack`).
+3. **Endpoint** — one published API within a module, turned into a command (e.g. `send-message-1`).
+
+Put together: `docstar-cli <collection> <module> <endpoint> [--flags]`, e.g. `docstar-cli msg91 slack send-message-1 --message "hi"`.
 
 ## Install
 
@@ -26,48 +36,70 @@ For a local/non-custom-domain docs site, pass the collection id explicitly:
 docstar-cli init localhost:3000 --collectionId paM4R4A26Hvb
 ```
 
-This fetches the list of published modules for that site, shows an interactive checklist (all modules pre-checked — press `space` to toggle, `enter` to confirm), and for each selected module:
+This fetches the list of published modules for that collection and shows an interactive checklist (nothing checked by default — press `space` to toggle a module, or select the **"Select all modules"** entry at the bottom of the list to install everything, then `enter` to confirm). For each selected module it:
 
-- saves its full endpoint contract to `~/.docstar/modules/<module>.json`
-- registers a real CLI command for every endpoint in that module
-- registers a `<module> list` command
+- saves its full endpoint contract to `~/.docstar/modules/<cli-name>/<module>.json`
+- registers a real CLI command for every endpoint: `docstar-cli <cli-name> <module> <command>`
 
-Overall settings (domain, collection, installed modules) are saved to `~/.docstar/config.json`.
+The **CLI name** comes from the collection's settings (set it under the collection's Domain settings in the docs editor — lowercase letters, numbers, `-` and `_` only; auto-generated from the collection name if not set yet). Running `init` against a different domain/collection adds it alongside any others already installed — nothing gets overwritten.
 
-### 2. See what's available in a module
+Everything is saved to `~/.docstar/config.json`, grouped by collection.
+
+### 2. See what's installed
 
 ```sh
-docstar-cli slack list
+docstar-cli list                    # every installed collection
+docstar-cli list msg91              # modules installed for the "msg91" collection
+docstar-cli list msg91 slack        # Slack's installed endpoints in "msg91"
 ```
 
 ```
 send-message-1
   send message
   POST
-  required: MY_SECRET_KEY
+  required: message
 ```
 
 ### 3. Call an endpoint
 
-Pass required parameters as flags:
-
 ```sh
-docstar-cli slack send-message-1 --MY_SECRET_KEY "hello from the CLI"
+docstar-cli msg91 slack send-message-1 --message "hello from the CLI"
 ```
 
-Or omit them and answer the prompts instead:
+Or omit required parameters and answer the prompts instead:
 
 ```sh
-docstar-cli slack send-message-1
-? Enter value for MY_SECRET_KEY
+docstar-cli msg91 slack send-message-1
+? Enter value for message
 ```
 
 The command prints the response status and body from the actual API call.
 
+### 4. Shell tab-completion
+
+This is a purpose-built completion, not a generic "complete every command" plugin: it **only**
+completes a module name (once you've typed a collection) and an endpoint name (once you've typed
+a collection and module). It never completes the collection name itself, and never completes
+top-level commands like `list`/`init`/`mcp` — you always type the collection by hand.
+
+Set it up once (bash, or zsh with `bashcompinit` loaded):
+
+```sh
+echo 'eval "$(docstar-cli completion-script)"' >> ~/.bashrc   # or ~/.zshrc
+```
+
+Then, after typing a known collection name, `Tab` completes modules and endpoints:
+
+```sh
+docstar-cli msg91 sla<Tab>            # -> slack
+docstar-cli msg91 slack send<Tab>     # -> send-message-1
+```
+
 ## Use from an AI client (MCP)
 
 `docstar-cli` can run as an [MCP](https://modelcontextprotocol.io) server, turning every installed
-endpoint into a proper tool an AI client can call directly — no shell access required.
+endpoint (across all installed collections) into a proper tool an AI client can call directly — no
+shell access required.
 
 ```sh
 docstar-cli mcp
@@ -86,17 +118,19 @@ Register it with Claude Code (`.mcp.json`) or Claude Desktop (`claude_desktop_co
 }
 ```
 
-Each installed endpoint becomes one tool named `<module>__<command>` (e.g. `slack__send-message-1`),
-with required/optional parameters exposed in its schema. A prompt like "call the slack api and
-send a message saying hi" resolves directly to that tool call — the AI client asks you for any
+Each installed endpoint becomes one tool named `<collection>__<module>__<endpoint>` (e.g.
+`msg91__slack__send-message-1`) — the same collection → module → endpoint hierarchy described
+above, just joined with `__` instead of spaces because MCP tool names can't contain spaces.
+Required/optional parameters are exposed in the tool's schema. A prompt like "call the slack api
+and send a message saying hi" resolves directly to that tool call — the AI client asks you for any
 required value it can't infer, exactly like any other MCP tool. Run `docstar-cli init` first so
 there's at least one installed module for `mcp` to expose.
 
 ## How it works
 
-- `docstar-cli init` talks to `GET /p/module.json?collectionId=...` (list of modules) and `GET /p/<module>/module.json?collectionId=...` (a module's endpoint contract) on the docs site.
+- `docstar-cli init` talks to `GET /p/module.json?collectionId=...` (the collection's name, CLI name, and list of modules) and `GET /p/<module>/module.json?collectionId=...` (a module's endpoint contract) on the docs site.
 - Each endpoint's contract (method, url, base url, headers, body, and CLI parameter names) is saved locally and used to build the real HTTP request when you run its command — no network round-trip to the docs site is needed to run a command once a module is installed.
-- Commands are generated as real files on disk under this repo's `dist/commands/<module>/`, which is why `npm run build` (it wipes `dist/`) requires re-running `docstar-cli init` afterwards to reinstall your modules.
+- Commands are generated as real files on disk under this repo's `dist/commands/<cli-name>/<module>/`, which is why `npm run build` (it wipes `dist/`) requires re-running `docstar-cli init` for each installed collection afterwards to reinstall your modules.
 
 ## Development
 

package/dist/commands/complete.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class Complete extends Command {
+    static args: {
+        collection: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        module: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static hidden: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/complete.js

@@ -0,0 +1,20 @@
+import { Args, Command } from '@oclif/core';
+import { completeEndpoints, completeModules } from '../lib/complete.js';
+// Hidden helper invoked by the shell completion function (see `completion-script`), not meant to
+// be run directly. Prints one suggestion per line: module names for `docstar-cli complete
+// <collection>`, endpoint command names/aliases for `docstar-cli complete <collection> <module>`.
+// Never suggests a collection name or a top-level command — completion only starts once the
+// collection has already been typed.
+export default class Complete extends Command {
+    static args = {
+        collection: Args.string({ required: true }),
+        module: Args.string({ required: false }),
+    };
+    static hidden = true;
+    async run() {
+        const { args } = await this.parse(Complete);
+        const suggestions = args.module ? await completeEndpoints(args.collection, args.module) : await completeModules(args.collection);
+        for (const suggestion of suggestions)
+            this.log(suggestion);
+    }
+}

package/dist/commands/{hello/world.d.ts → completion-script.d.ts}

@@ -1,8 +1,6 @@
 import { Command } from '@oclif/core';
-export default class World extends Command {
-    static args: {};
+export default class CompletionScript extends Command {
     static description: string;
     static examples: string[];
-    static flags: {};
     run(): Promise<void>;
 }

package/dist/commands/completion-script.js

@@ -0,0 +1,39 @@
+import { Command } from '@oclif/core';
+const scriptFor = (bin) => {
+    const fnName = `_${bin.replaceAll(/[^a-zA-Z0-9]/g, '_')}_complete`;
+    return `# zsh doesn't support the bash-style \`complete\` builtin used below until compinit (for
+# compdef) and bashcompinit (for complete/compgen) are both loaded, in that order.
+if [ -n "$ZSH_VERSION" ]; then
+  autoload -Uz compinit && compinit -u
+  autoload -U +X bashcompinit && bashcompinit
+fi
+
+${fnName}() {
+  local cur collection module
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  collection="\${COMP_WORDS[1]}"
+  module="\${COMP_WORDS[2]}"
+
+  COMPREPLY=()
+
+  if [ "$COMP_CWORD" -eq 2 ] && [ -n "$collection" ]; then
+    COMPREPLY=( $(compgen -W "$(${bin} complete "$collection" 2>/dev/null)" -- "$cur") )
+  elif [ "$COMP_CWORD" -eq 3 ] && [ -n "$collection" ] && [ -n "$module" ]; then
+    COMPREPLY=( $(compgen -W "$(${bin} complete "$collection" "$module" 2>/dev/null)" -- "$cur") )
+  fi
+  # COMP_CWORD 0/1 (the binary name and the collection itself) intentionally get no
+  # suggestions — the collection is always typed out by hand.
+}
+complete -F ${fnName} ${bin}
+`;
+};
+export default class CompletionScript extends Command {
+    static description = [
+        'Print a shell completion function that completes ONLY module names (once a collection is typed) and endpoint names (once a collection and module are typed).',
+        'It never completes the collection name itself, and never completes top-level commands like `list`/`init`/`mcp` — those are typed out by hand.',
+    ].join('\n');
+    static examples = ['echo \'eval "$(<%= config.bin %> <%= command.id %>)"\' >> ~/.bashrc  # or ~/.zshrc'];
+    async run() {
+        this.log(scriptFor(this.config.bin));
+    }
+}

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import { checkbox } from '@inquirer/prompts';
 import { Args, Command, Flags } from '@oclif/core';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { generateCommandFile, generateListCommandFile } from '../lib/codegen.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { generateCommandFile } from '../lib/codegen.js';
 import { configDir, configPath, modulePath } from '../lib/paths.js';
 const buildBaseUrl = (domain) => {
     if (domain.startsWith('http://') || domain.startsWith('https://'))
@@ -15,11 +15,23 @@ const fetchJson = async (url) => {
         throw new Error(`Request to ${url} failed (${response.status} ${response.statusText})`);
     return (await response.json());
 };
+const readSavedConfig = async () => {
+    try {
+        return JSON.parse(await readFile(configPath(), 'utf8'));
+    }
+    catch {
+        return { collections: [] };
+    }
+};
 export default class Init extends Command {
     static args = {
         domain: Args.string({ description: 'DocStar docs domain, e.g. docs.msg91.com or localhost:3000', required: true }),
     };
-    static description = 'Discover published modules for a DocStar docs site, pick which ones to install, and register their CLI commands';
+    static description = [
+        'Discover published modules for a DocStar docs site, pick which ones to install, and register their CLI commands.',
+        'You can run this against multiple docs sites/collections — each is kept separate under its own CLI name (`docstar-cli <cli-name> <module> <command>`).',
+        'After installing, run `docstar-cli list` to see what got installed.',
+    ].join('\n');
     static examples = [
         '<%= config.bin %> <%= command.id %> docs.msg91.com',
         '<%= config.bin %> <%= command.id %> localhost:3000 --collectionId paM4R4A26Hvb',
@@ -35,21 +47,30 @@ export default class Init extends Command {
             listUrl.searchParams.set('collectionId', flags.collectionId);
         this.log(`Fetching modules from ${listUrl.toString()} ...`);
         const listResponse = await fetchJson(listUrl.toString());
+        if (!listResponse.collection?.cliName) {
+            this.error('The docs site did not return a CLI name for this collection. Please update hitman-api/hitman-ui, or set one in the collection settings.');
+        }
         if (!listResponse.modules || listResponse.modules.length === 0) {
             this.log('No published modules found.');
             return;
         }
-        const selectedPaths = await checkbox({
-            choices: listResponse.modules.map((module) => {
-                const count = module.endpointCount ?? module.endpoints?.length ?? 0;
-                return {
-                    checked: true,
-                    name: `${module.name} (${module.path}) — ${count} endpoint${count === 1 ? '' : 's'}`,
-                    value: module.path,
-                };
-            }),
-            message: 'Select modules to install (space to toggle, enter to confirm)',
+        const { cliName } = listResponse.collection;
+        const SELECT_ALL = '__select_all__';
+        const rawSelection = await checkbox({
+            choices: [
+                ...listResponse.modules.map((module) => {
+                    const count = module.endpointCount ?? module.endpoints?.length ?? 0;
+                    return {
+                        checked: false,
+                        name: `${module.name} (${module.path}) — ${count} endpoint${count === 1 ? '' : 's'}`,
+                        value: module.path,
+                    };
+                }),
+                { checked: false, name: '➤ Select all modules', value: SELECT_ALL },
+            ],
+            message: `Select modules to install for "${cliName}" (space to toggle, enter to confirm)`,
         });
+        const selectedPaths = rawSelection.includes(SELECT_ALL) ? listResponse.modules.map((module) => module.path) : rawSelection;
         if (selectedPaths.length === 0) {
             this.log('No modules selected, nothing installed.');
             return;
@@ -61,26 +82,32 @@ export default class Init extends Command {
             if (flags.collectionId)
                 moduleUrl.searchParams.set('collectionId', flags.collectionId);
             this.log(`Fetching ${path} ...`);
+            // eslint-disable-next-line no-await-in-loop
             const moduleJson = await fetchJson(moduleUrl.toString());
-            await mkdir(configDir() + '/modules', { recursive: true });
-            await writeFile(modulePath(path), JSON.stringify(moduleJson, null, 2));
+            // eslint-disable-next-line no-await-in-loop
+            await mkdir(configDir() + `/modules/${cliName}`, { recursive: true });
+            // eslint-disable-next-line no-await-in-loop
+            await writeFile(modulePath(cliName, path), JSON.stringify(moduleJson, null, 2));
             for (const endpoint of moduleJson.endpoints) {
-                const filePath = await generateCommandFile(this.config.root, path, endpoint);
-                this.log(`  registered command: ${this.config.bin} ${path} ${endpoint.cli.command.name} -> ${filePath}`);
+                // eslint-disable-next-line no-await-in-loop
+                await generateCommandFile(this.config.root, cliName, path, endpoint);
+                this.log(`  registered command: ${this.config.bin} ${cliName} ${path} ${endpoint.cli.command.name}`);
             }
-            await generateListCommandFile(this.config.root, path);
-            this.log(`  registered command: ${this.config.bin} ${path} list`);
             selectedModules.push({ name: moduleJson.module.name, path });
         }
-        const savedConfig = {
+        const collectionConfig = {
             baseUrl,
-            collection: listResponse.collection ?? null,
+            cliName,
             collectionId: flags.collectionId ?? null,
             domain: args.domain,
             modules: selectedModules,
+            name: listResponse.collection.name,
             updatedAt: new Date().toISOString(),
         };
+        const savedConfig = await readSavedConfig();
+        const otherCollections = savedConfig.collections.filter((collection) => collection.cliName !== cliName);
+        savedConfig.collections = [...otherCollections, collectionConfig];
         await writeFile(configPath(), JSON.stringify(savedConfig, null, 2));
-        this.log(`\nInstalled ${selectedModules.length} module(s). Config saved to ${configPath()}`);
+        this.log(`\nInstalled ${selectedModules.length} module(s) for "${cliName}". Config saved to ${configPath()}`);
     }
 }

package/dist/commands/list.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class List extends Command {
+    static args: {
+        collection: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+        module: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/list.js

@@ -0,0 +1,71 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { loadModule } from '../lib/http.js';
+import { configPath } from '../lib/paths.js';
+export default class List extends Command {
+    static args = {
+        collection: Args.string({ description: 'Show modules installed for this collection (CLI name), e.g. msg91', required: false }),
+        module: Args.string({ description: 'Show all endpoints for this module within the collection, e.g. slack', required: false }),
+    };
+    static description = 'List installed collections, the modules within one, or every endpoint of one module';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>              # list every installed collection',
+        '<%= config.bin %> <%= command.id %> --all        # same as above',
+        '<%= config.bin %> <%= command.id %> msg91         # list modules installed for the "msg91" collection',
+        '<%= config.bin %> <%= command.id %> msg91 slack   # list all of Slack\'s installed endpoints in "msg91"',
+    ];
+    static flags = {
+        all: Flags.boolean({ description: 'List every installed collection (default when no arguments are given)' }),
+    };
+    async run() {
+        const { args } = await this.parse(List);
+        let savedConfig;
+        try {
+            savedConfig = JSON.parse(await readFile(configPath(), 'utf8'));
+        }
+        catch {
+            this.error('No installed modules found. Run `docstar-cli init <domain>` first.');
+        }
+        if (savedConfig.collections.length === 0) {
+            this.log('No collections installed. Run `docstar-cli init <domain>` to install one.');
+            return;
+        }
+        if (!args.collection) {
+            for (const collection of savedConfig.collections) {
+                this.log(`${collection.name} (${collection.cliName}) — ${collection.domain} — ${collection.modules.length} module${collection.modules.length === 1 ? '' : 's'}`);
+            }
+            return;
+        }
+        const collection = savedConfig.collections.find((c) => c.cliName === args.collection);
+        if (!collection) {
+            this.error(`Collection "${args.collection}" isn't installed. Run \`docstar-cli list\` to see installed collections.`);
+        }
+        if (!args.module) {
+            for (const module of collection.modules) {
+                // eslint-disable-next-line no-await-in-loop
+                const moduleJson = await loadModule(collection.cliName, module.path);
+                const count = moduleJson.endpoints.length;
+                this.log(`${module.name} (${module.path}) — ${count} endpoint${count === 1 ? '' : 's'}`);
+            }
+            return;
+        }
+        const moduleJson = await loadModule(collection.cliName, args.module);
+        if (moduleJson.endpoints.length === 0) {
+            this.log(`No endpoints found for module "${args.module}".`);
+            return;
+        }
+        for (const endpoint of moduleJson.endpoints) {
+            const { cli } = endpoint;
+            const aliases = cli.command.aliases.filter((alias) => alias !== cli.command.name);
+            this.log(`${cli.command.name}${aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : ''}`);
+            if (cli.description)
+                this.log(`  ${cli.description}`);
+            this.log(`  ${endpoint.method}`);
+            if (cli.parameters.required.length > 0)
+                this.log(`  required: ${cli.parameters.required.join(', ')}`);
+            if (cli.parameters.optional.length > 0)
+                this.log(`  optional: ${cli.parameters.optional.join(', ')}`);
+            this.log('');
+        }
+    }
+}

package/dist/commands/mcp.js

@@ -15,8 +15,17 @@ const buildInputShape = (required, optional) => {
     return shape;
 };
 export default class Mcp extends Command {
-    static description = 'Start an MCP server exposing every installed endpoint as a tool for AI clients (Claude Desktop, Claude Code, etc.)';
-    static examples = ['<%= config.bin %> <%= command.id %>'];
+    static description = [
+        'Start an MCP (Model Context Protocol) server exposing every installed endpoint (across all installed collections) as a callable tool for AI clients (Claude Desktop, Claude Code, etc.).',
+        'Every tool follows the collection -> module -> endpoint hierarchy: e.g. collection "msg91" -> module "slack" -> endpoint "send-message-1" becomes the tool `msg91__slack__send-message-1`.',
+        'Run `docstar-cli init <domain>` first so there is at least one installed module to expose.',
+        'This command does not exit on its own — it stays running and communicates over stdio for as long as the connecting AI client keeps the connection open.',
+    ].join('\n');
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '# Then register it in an MCP client config, e.g. .mcp.json:',
+        '# { "mcpServers": { "docstar": { "command": "docstar-cli", "args": ["mcp"] } } }',
+    ];
     async run() {
         let savedConfig;
         try {
@@ -27,24 +36,26 @@ export default class Mcp extends Command {
         }
         const server = new McpServer({ name: 'docstar-cli', version: '1.0.0' });
         let toolCount = 0;
-        for (const module of savedConfig.modules) {
-            // eslint-disable-next-line no-await-in-loop
-            const moduleJson = await loadModule(module.path);
-            for (const endpoint of moduleJson.endpoints) {
-                const { cli } = endpoint;
-                const toolName = sanitize(`${module.path}__${cli.command.name}`);
-                const description = cli.description || `${cli.command.name} (${module.path})`;
-                const inputShape = buildInputShape(cli.parameters.required, cli.parameters.optional);
-                server.tool(toolName, description, inputShape, async (args) => {
-                    try {
-                        const result = await executeCliCommand(module.path, cli.command.name, args);
-                        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-                    }
-                    catch (error) {
-                        return { content: [{ type: 'text', text: error.message }], isError: true };
-                    }
-                });
-                toolCount++;
+        for (const collection of savedConfig.collections) {
+            for (const module of collection.modules) {
+                // eslint-disable-next-line no-await-in-loop
+                const moduleJson = await loadModule(collection.cliName, module.path);
+                for (const endpoint of moduleJson.endpoints) {
+                    const { cli } = endpoint;
+                    const toolName = sanitize(`${collection.cliName}__${module.path}__${cli.command.name}`);
+                    const description = `[collection: ${collection.cliName} / module: ${module.path}] ${cli.description || cli.command.name}`;
+                    const inputShape = buildInputShape(cli.parameters.required, cli.parameters.optional);
+                    server.tool(toolName, description, inputShape, async (args) => {
+                        try {
+                            const result = await executeCliCommand(collection.cliName, module.path, cli.command.name, args);
+                            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+                        }
+                        catch (error) {
+                            return { content: [{ type: 'text', text: error.message }], isError: true };
+                        }
+                    });
+                    toolCount++;
+                }
             }
         }
         if (toolCount === 0) {

package/dist/lib/codegen.d.ts

@@ -1,3 +1,2 @@
 import type { EndpointContract } from './types.js';
-export declare const generateCommandFile: (cliRoot: string, modulePathSegment: string, endpoint: EndpointContract) => Promise<string>;
-export declare const generateListCommandFile: (cliRoot: string, modulePathSegment: string) => Promise<string>;
+export declare const generateCommandFile: (cliRoot: string, cliName: string, modulePathSegment: string, endpoint: EndpointContract) => Promise<string>;

package/dist/lib/codegen.js

@@ -2,21 +2,25 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 const flagLine = (name, required) => 
 // Required params are collected interactively when missing, so the flag itself stays optional to oclif.
-`    '${name}': Flags.string({description: '${required ? 'Required' : 'Optional'} parameter'}),`;
-const commandFileContent = (modulePathSegment, endpoint) => {
+// Param names come from endpoint body/param keys authored in a rich-text editor and can contain
+// quotes or HTML markup (e.g. a stray `<span text-block='true'>...`) — JSON.stringify escapes
+// that safely for embedding in generated source; naive string interpolation does not and can
+// produce invalid JS.
+`    ${JSON.stringify(name)}: Flags.string({description: ${JSON.stringify(`${required ? 'Required' : 'Optional'} parameter`)}}),`;
+const commandFileContent = (cliName, modulePathSegment, endpoint) => {
     const { cli } = endpoint;
     const flagLines = [
         ...cli.parameters.required.map((name) => flagLine(name, true)),
         ...cli.parameters.optional.map((name) => flagLine(name, false)),
     ].join('\n');
     return `import {Command, Flags} from '@oclif/core'
-import {executeCliCommand} from '../../lib/http.js'
-import {promptForMissingParams} from '../../lib/prompt.js'
+import {executeCliCommand} from '../../../lib/http.js'
+import {promptForMissingParams} from '../../../lib/prompt.js'
 
 const REQUIRED_PARAMS = ${JSON.stringify(cli.parameters.required)}
 
 export default class Generated extends Command {
-  static description = ${JSON.stringify(cli.description || `${cli.name} (${modulePathSegment})`)}
+  static description = ${JSON.stringify(cli.description || `${cli.name} (${cliName} ${modulePathSegment})`)}
   static aliases = ${JSON.stringify(cli.command.aliases.filter((alias) => alias !== cli.name))}
   static flags = {
 ${flagLines}
@@ -32,7 +36,7 @@ ${flagLines}
     Object.assign(params, await promptForMissingParams(REQUIRED_PARAMS, params))
 
     try {
-      const result = await executeCliCommand('${modulePathSegment}', '${cli.command.name}', params)
+      const result = await executeCliCommand(${JSON.stringify(cliName)}, ${JSON.stringify(modulePathSegment)}, ${JSON.stringify(cli.command.name)}, params)
       this.log(JSON.stringify(result, null, 2))
     } catch (error) {
       this.error(error.message)
@@ -41,38 +45,10 @@ ${flagLines}
 }
 `;
 };
-const listCommandFileContent = (modulePathSegment) => `import {Command} from '@oclif/core'
-import {loadModule} from '../../lib/http.js'
-
-export default class GeneratedList extends Command {
-  static description = 'List installed APIs for the ${modulePathSegment} module'
-
-  async run() {
-    const moduleJson = await loadModule('${modulePathSegment}')
-
-    for (const endpoint of moduleJson.endpoints) {
-      const {cli} = endpoint
-      this.log(\`\${cli.command.name}\${cli.command.aliases.filter((alias) => alias !== cli.command.name).length > 0 ? \` (aliases: \${cli.command.aliases.filter((alias) => alias !== cli.command.name).join(', ')})\` : ''}\`)
-      if (cli.description) this.log(\`  \${cli.description}\`)
-      this.log(\`  \${endpoint.method}\`)
-      if (cli.parameters.required.length > 0) this.log(\`  required: \${cli.parameters.required.join(', ')}\`)
-      if (cli.parameters.optional.length > 0) this.log(\`  optional: \${cli.parameters.optional.join(', ')}\`)
-      this.log('')
-    }
-  }
-}
-`;
-export const generateCommandFile = async (cliRoot, modulePathSegment, endpoint) => {
-    const dir = join(cliRoot, 'dist', 'commands', modulePathSegment);
+export const generateCommandFile = async (cliRoot, cliName, modulePathSegment, endpoint) => {
+    const dir = join(cliRoot, 'dist', 'commands', cliName, modulePathSegment);
     await mkdir(dir, { recursive: true });
     const filePath = join(dir, `${endpoint.cli.command.name}.js`);
-    await writeFile(filePath, commandFileContent(modulePathSegment, endpoint));
-    return filePath;
-};
-export const generateListCommandFile = async (cliRoot, modulePathSegment) => {
-    const dir = join(cliRoot, 'dist', 'commands', modulePathSegment);
-    await mkdir(dir, { recursive: true });
-    const filePath = join(dir, 'list.js');
-    await writeFile(filePath, listCommandFileContent(modulePathSegment));
+    await writeFile(filePath, commandFileContent(cliName, modulePathSegment, endpoint));
     return filePath;
 };

package/dist/lib/complete.d.ts

@@ -0,0 +1,2 @@
+export declare const completeModules: (cliName: string) => Promise<string[]>;
+export declare const completeEndpoints: (cliName: string, modulePathSegment: string) => Promise<string[]>;

package/dist/lib/complete.js

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises';
+import { loadModule } from './http.js';
+import { configPath } from './paths.js';
+const readSavedConfig = async () => {
+    try {
+        return JSON.parse(await readFile(configPath(), 'utf8'));
+    }
+    catch {
+        return { collections: [] };
+    }
+};
+// Suggestions for shell completion — intentionally scoped to module names (given a collection)
+// and endpoint command names/aliases (given a collection + module). Never suggests collection
+// names or top-level commands (list/init/mcp/...); the user is expected to type the collection
+// themselves.
+export const completeModules = async (cliName) => {
+    const savedConfig = await readSavedConfig();
+    const collection = savedConfig.collections.find((c) => c.cliName === cliName);
+    return collection ? collection.modules.map((module) => module.path) : [];
+};
+export const completeEndpoints = async (cliName, modulePathSegment) => {
+    try {
+        const moduleJson = await loadModule(cliName, modulePathSegment);
+        const names = moduleJson.endpoints.flatMap((endpoint) => [endpoint.cli.command.name, ...endpoint.cli.command.aliases]);
+        return [...new Set(names)];
+    }
+    catch {
+        return [];
+    }
+};

package/dist/lib/http.d.ts

@@ -1,8 +1,8 @@
 import type { EndpointContract, ModuleJson } from './types.js';
 export declare const stripHtml: (value: string | null | undefined) => string;
-export declare const loadModule: (modulePathSegment: string) => Promise<ModuleJson>;
+export declare const loadModule: (cliName: string, modulePathSegment: string) => Promise<ModuleJson>;
 export declare const findEndpoint: (moduleJson: ModuleJson, commandName: string) => EndpointContract | undefined;
-export declare const executeCliCommand: (modulePathSegment: string, commandName: string, params: Record<string, string>) => Promise<{
+export declare const executeCliCommand: (cliName: string, modulePathSegment: string, commandName: string, params: Record<string, string>) => Promise<{
     status: number;
     body: unknown;
 }>;

package/dist/lib/http.js

@@ -4,8 +4,8 @@ import { modulePath } from './paths.js';
 // `<span text-block="true">...</span>`-style markup; unwrap to the raw value.
 export const stripHtml = (value) => (value ?? '').replaceAll(/<[^>]*>/g, '');
 const substitutePlaceholders = (template, params) => Object.entries(params).reduce((result, [key, value]) => result.replaceAll(`:${key}`, value).replaceAll(`{${key}}`, value).replaceAll(`{{${key}}}`, value), template);
-export const loadModule = async (modulePathSegment) => {
-    const raw = await readFile(modulePath(modulePathSegment), 'utf8');
+export const loadModule = async (cliName, modulePathSegment) => {
+    const raw = await readFile(modulePath(cliName, modulePathSegment), 'utf8');
     return JSON.parse(raw);
 };
 export const findEndpoint = (moduleJson, commandName) => moduleJson.endpoints.find((endpoint) => endpoint.cli.command.name === commandName || endpoint.cli.command.aliases.includes(commandName));
@@ -17,14 +17,47 @@ const buildUrl = (endpoint, params) => {
     return `${baseUrl}${path}`;
 };
 const buildHeaders = (endpoint, params) => {
+    // Header names are case-insensitive; the docs editor can end up storing two entries that only
+    // differ by case (e.g. "Content-Type" and "content-type"). Sending both as separate header
+    // lines has been observed to break body parsing on the receiving server, so dedupe by
+    // lowercased name — first entry wins, using its original casing for readability.
+    const seenLowerNames = new Set();
     const headers = {};
     for (const [rawKey, rawValue] of Object.entries(endpoint.headers || {})) {
         const key = stripHtml(rawKey);
+        const lowerKey = key.toLowerCase();
+        if (seenLowerNames.has(lowerKey))
+            continue;
+        seenLowerNames.add(lowerKey);
         const value = stripHtml(rawValue?.value ?? rawValue);
         headers[key] = params[key] ?? value;
     }
     return headers;
 };
+// CLI flag values always arrive as strings, but the JSON body template's existing value for a
+// key tells us its real type (boolean/number/array) — coerce back to that shape instead of
+// clobbering e.g. `getUrl: true` with the literal string "true", or `collectionIds: []` with a
+// plain string.
+const coerceToTemplateType = (existingValue, rawValue) => {
+    if (typeof existingValue === 'boolean')
+        return rawValue === 'true';
+    if (typeof existingValue === 'number') {
+        const parsedNumber = Number(rawValue);
+        return Number.isNaN(parsedNumber) ? rawValue : parsedNumber;
+    }
+    if (Array.isArray(existingValue)) {
+        try {
+            const parsed = JSON.parse(rawValue);
+            if (Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // not a JSON array literal — fall through to comma-splitting
+        }
+        return rawValue.split(',').map((item) => item.trim());
+    }
+    return rawValue;
+};
 const buildBody = (endpoint, params) => {
     const rawValue = endpoint.body?.raw?.value;
     if (endpoint.body?.type !== 'JSON' || !rawValue)
@@ -38,15 +71,15 @@ const buildBody = (endpoint, params) => {
     }
     for (const [key, value] of Object.entries(params)) {
         if (key in parsed)
-            parsed[key] = value;
+            parsed[key] = coerceToTemplateType(parsed[key], value);
     }
     return JSON.stringify(parsed);
 };
-export const executeCliCommand = async (modulePathSegment, commandName, params) => {
-    const moduleJson = await loadModule(modulePathSegment);
+export const executeCliCommand = async (cliName, modulePathSegment, commandName, params) => {
+    const moduleJson = await loadModule(cliName, modulePathSegment);
     const endpoint = findEndpoint(moduleJson, commandName);
     if (!endpoint) {
-        throw new Error(`No endpoint found for command "${commandName}" in module "${modulePathSegment}"`);
+        throw new Error(`No endpoint found for command "${commandName}" in module "${cliName} ${modulePathSegment}"`);
     }
     const url = buildUrl(endpoint, params);
     const headers = buildHeaders(endpoint, params);

package/dist/lib/paths.d.ts

@@ -1,4 +1,5 @@
 export declare const configDir: () => string;
 export declare const configPath: () => string;
 export declare const modulesDir: () => string;
-export declare const modulePath: (modulePathSegment: string) => string;
+export declare const collectionModulesDir: (cliName: string) => string;
+export declare const modulePath: (cliName: string, modulePathSegment: string) => string;

package/dist/lib/paths.js

@@ -3,4 +3,5 @@ import { join } from 'node:path';
 export const configDir = () => join(homedir(), '.docstar');
 export const configPath = () => join(configDir(), 'config.json');
 export const modulesDir = () => join(configDir(), 'modules');
-export const modulePath = (modulePathSegment) => join(modulesDir(), `${modulePathSegment}.json`);
+export const collectionModulesDir = (cliName) => join(modulesDir(), cliName);
+export const modulePath = (cliName, modulePathSegment) => join(collectionModulesDir(cliName), `${modulePathSegment}.json`);

package/dist/lib/types.d.ts

@@ -41,14 +41,20 @@ export type ModuleSummary = {
         path: string;
     }[];
 };
-export type SavedConfig = {
-    baseUrl: string;
+export type CollectionSummary = {
+    id: string;
+    name: string;
+    cliName: string;
+};
+export type CollectionConfig = {
+    cliName: string;
+    name: string;
     domain: string;
+    baseUrl: string;
     collectionId: string | null;
-    collection: {
-        id: string;
-        name: string;
-    } | null;
     modules: ModuleSummary[];
     updatedAt: string;
 };
+export type SavedConfig = {
+    collections: CollectionConfig[];
+};

package/oclif.manifest.json

@@ -1,31 +1,22 @@
 {
   "commands": {
-    "init": {
+    "complete": {
       "aliases": [],
       "args": {
-        "domain": {
-          "description": "DocStar docs domain, e.g. docs.msg91.com or localhost:3000",
-          "name": "domain",
+        "collection": {
+          "name": "collection",
           "required": true
+        },
+        "module": {
+          "name": "module",
+          "required": false
         }
       },
-      "description": "Discover published modules for a DocStar docs site, pick which ones to install, and register their CLI commands",
-      "examples": [
-        "<%= config.bin %> <%= command.id %> docs.msg91.com",
-        "<%= config.bin %> <%= command.id %> localhost:3000 --collectionId paM4R4A26Hvb"
-      ],
-      "flags": {
-        "collectionId": {
-          "description": "Collection id (required when the domain is not a custom domain, e.g. localhost)",
-          "name": "collectionId",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
+      "flags": {},
       "hasDynamicHelp": false,
+      "hidden": true,
       "hiddenAliases": [],
-      "id": "init",
+      "id": "complete",
       "pluginAlias": "docstar-cli",
       "pluginName": "docstar-cli",
       "pluginType": "core",
@@ -35,20 +26,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "init.js"
+        "complete.js"
       ]
     },
-    "mcp": {
+    "completion-script": {
       "aliases": [],
       "args": {},
-      "description": "Start an MCP server exposing every installed endpoint as a tool for AI clients (Claude Desktop, Claude Code, etc.)",
+      "description": "Print a shell completion function that completes ONLY module names (once a collection is typed) and endpoint names (once a collection and module are typed).\nIt never completes the collection name itself, and never completes top-level commands like `list`/`init`/`mcp` — those are typed out by hand.",
       "examples": [
-        "<%= config.bin %> <%= command.id %>"
+        "echo 'eval \"$(<%= config.bin %> <%= command.id %>)\"' >> ~/.bashrc  # or ~/.zshrc"
       ],
       "flags": {},
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "mcp",
+      "id": "completion-script",
       "pluginAlias": "docstar-cli",
       "pluginName": "docstar-cli",
       "pluginType": "core",
@@ -58,28 +49,27 @@
       "relativePath": [
         "dist",
         "commands",
-        "mcp.js"
+        "completion-script.js"
       ]
     },
-    "hello": {
+    "init": {
       "aliases": [],
       "args": {
-        "person": {
-          "description": "Person to say hello to",
-          "name": "person",
+        "domain": {
+          "description": "DocStar docs domain, e.g. docs.msg91.com or localhost:3000",
+          "name": "domain",
           "required": true
         }
       },
-      "description": "Say hello",
+      "description": "Discover published modules for a DocStar docs site, pick which ones to install, and register their CLI commands.\nYou can run this against multiple docs sites/collections — each is kept separate under its own CLI name (`docstar-cli <cli-name> <module> <command>`).\nAfter installing, run `docstar-cli list` to see what got installed.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> friend --from oclif\nhello friend from oclif! (./src/commands/hello/index.ts)\n"
+        "<%= config.bin %> <%= command.id %> docs.msg91.com",
+        "<%= config.bin %> <%= command.id %> localhost:3000 --collectionId paM4R4A26Hvb"
       ],
       "flags": {
-        "from": {
-          "char": "f",
-          "description": "Who is saying hello",
-          "name": "from",
-          "required": true,
+        "collectionId": {
+          "description": "Collection id (required when the domain is not a custom domain, e.g. localhost)",
+          "name": "collectionId",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -87,7 +77,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "hello",
+      "id": "init",
       "pluginAlias": "docstar-cli",
       "pluginName": "docstar-cli",
       "pluginType": "core",
@@ -97,21 +87,66 @@
       "relativePath": [
         "dist",
         "commands",
-        "hello",
-        "index.js"
+        "init.js"
       ]
     },
-    "hello:world": {
+    "list": {
+      "aliases": [],
+      "args": {
+        "collection": {
+          "description": "Show modules installed for this collection (CLI name), e.g. msg91",
+          "name": "collection",
+          "required": false
+        },
+        "module": {
+          "description": "Show all endpoints for this module within the collection, e.g. slack",
+          "name": "module",
+          "required": false
+        }
+      },
+      "description": "List installed collections, the modules within one, or every endpoint of one module",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>              # list every installed collection",
+        "<%= config.bin %> <%= command.id %> --all        # same as above",
+        "<%= config.bin %> <%= command.id %> msg91         # list modules installed for the \"msg91\" collection",
+        "<%= config.bin %> <%= command.id %> msg91 slack   # list all of Slack's installed endpoints in \"msg91\""
+      ],
+      "flags": {
+        "all": {
+          "description": "List every installed collection (default when no arguments are given)",
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "list",
+      "pluginAlias": "docstar-cli",
+      "pluginName": "docstar-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "list.js"
+      ]
+    },
+    "mcp": {
       "aliases": [],
       "args": {},
-      "description": "Say hello world",
+      "description": "Start an MCP (Model Context Protocol) server exposing every installed endpoint (across all installed collections) as a callable tool for AI clients (Claude Desktop, Claude Code, etc.).\nEvery tool follows the collection -> module -> endpoint hierarchy: e.g. collection \"msg91\" -> module \"slack\" -> endpoint \"send-message-1\" becomes the tool `msg91__slack__send-message-1`.\nRun `docstar-cli init <domain>` first so there is at least one installed module to expose.\nThis command does not exit on its own — it stays running and communicates over stdio for as long as the connecting AI client keeps the connection open.",
       "examples": [
-        "<%= config.bin %> <%= command.id %>\nhello world! (./src/commands/hello/world.ts)\n"
+        "<%= config.bin %> <%= command.id %>",
+        "# Then register it in an MCP client config, e.g. .mcp.json:",
+        "# { \"mcpServers\": { \"docstar\": { \"command\": \"docstar-cli\", \"args\": [\"mcp\"] } } }"
       ],
       "flags": {},
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "hello:world",
+      "id": "mcp",
       "pluginAlias": "docstar-cli",
       "pluginName": "docstar-cli",
       "pluginType": "core",
@@ -121,10 +156,9 @@
       "relativePath": [
         "dist",
         "commands",
-        "hello",
-        "world.js"
+        "mcp.js"
       ]
     }
   },
-  "version": "1.0.1"
+  "version": "1.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docstar-cli",
-  "description": "A new CLI generated with oclif",
-  "version": "1.0.1",
+  "description": "Call published DocStar API endpoints directly from your terminal, or expose them as MCP tools for AI clients.",
+  "version": "1.1.0",
   "author": "Swayam Maheshwari",
   "bin": {
     "docstar-cli": "./bin/run.js"
@@ -56,11 +56,9 @@
       "@oclif/plugin-plugins"
     ],
     "topicSeparator": " ",
-    "topics": {
-      "hello": {
-        "description": "Say hello to the world and others"
-      }
-    }
+    "additionalVersionFlags": [
+      "-v"
+    ]
   },
   "repository": "swayammaheshwari/docstar-cli",
   "scripts": {

package/dist/commands/hello/index.d.ts

@@ -1,12 +0,0 @@
-import { Command } from '@oclif/core';
-export default class Hello extends Command {
-    static args: {
-        person: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    static description: string;
-    static examples: string[];
-    static flags: {
-        from: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-    };
-    run(): Promise<void>;
-}

package/dist/commands/hello/index.js

@@ -1,19 +0,0 @@
-import { Args, Command, Flags } from '@oclif/core';
-export default class Hello extends Command {
-    static args = {
-        person: Args.string({ description: 'Person to say hello to', required: true }),
-    };
-    static description = 'Say hello';
-    static examples = [
-        `<%= config.bin %> <%= command.id %> friend --from oclif
-hello friend from oclif! (./src/commands/hello/index.ts)
-`,
-    ];
-    static flags = {
-        from: Flags.string({ char: 'f', description: 'Who is saying hello', required: true }),
-    };
-    async run() {
-        const { args, flags } = await this.parse(Hello);
-        this.log(`hello ${args.person} from ${flags.from}! (./src/commands/hello/index.ts)`);
-    }
-}

package/dist/commands/hello/world.js

@@ -1,14 +0,0 @@
-import { Command } from '@oclif/core';
-export default class World extends Command {
-    static args = {};
-    static description = 'Say hello world';
-    static examples = [
-        `<%= config.bin %> <%= command.id %>
-hello world! (./src/commands/hello/world.ts)
-`,
-    ];
-    static flags = {};
-    async run() {
-        this.log('hello world! (./src/commands/hello/world.ts)');
-    }
-}