api-spec-cli 0.1.2 → 0.2.0

package/README.md

@@ -17,47 +17,67 @@ npx api-spec-cli <command>
 
 ## How It Works
 
-The CLI follows a progressive discovery pattern. You never dump an entire API spec at once — instead you narrow down to what you need.
+Every command is stateless — you specify the spec source on each call. Two paths:
 
-### Step 1: Load the spec
+| Path | When to use |
+|---|---|
+| `--spec <name>` | Registered spec — auto-fetches and caches on first use |
+| Inline flags | Ad-hoc — no registration, fetched each call |
+
+### Register once, use everywhere
 
 ```bash
-# OpenAPI
-spec load https://petstore3.swagger.io/api/v3/openapi.json
-spec load ./openapi.yaml
+spec add petstore --openapi https://petstore3.swagger.io/api/v3/openapi.json \
+  --base-url https://petstore3.swagger.io/api/v3 \
+  --description "Petstore example"
+
+spec add hashnode --graphql https://gql.hashnode.com --auth YOUR_TOKEN
 
-# GraphQL (auto-introspects)
-spec load https://gql.hashnode.com
+spec add agno --mcp-http https://docs.agno.com/mcp --description "Agno docs"
+
+spec add fs --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
+```
 
-# MCP — stdio transport (spawn a local server)
-spec load --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
+Registration is instant — does not connect. Connection happens on first `list`/`show`/`call` and the result is cached at `~/spec-cli-config/cache/<name>.json`.
 
-# MCP — SSE transport
-spec load --mcp-sse http://localhost:3000/sse
+### Or use inline (no registration)
 
-# MCP — Streamable HTTP transport
-spec load --mcp-http https://docs.agno.com/mcp
+```bash
+spec list --openapi https://petstore3.swagger.io/api/v3/openapi.json
+spec list --graphql https://gql.hashnode.com
+spec list --mcp-http https://docs.agno.com/mcp
+spec list --mcp-sse http://localhost:3000/sse
+spec list --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
 ```
 
-Output tells you what was loaded:
-```json
-{ "ok": true, "type": "mcp", "transport": "streamable-http", "toolCount": 1 }
+Inline fetches every call, nothing cached.
+
+---
+
+## Discovery
+
+### List all specs in the registry
+
+```bash
+spec specs                    # Compact: name, type, enabled
+spec specs --compact false    # Full: includes source, config
 ```
 
-### Step 2: Find what you need
+### List operations / tools
 
 `list` is compact by default — just IDs, no schemas. Use `--filter`, `--tag`, `--limit` to narrow down.
 
 ```bash
-spec list                          # All operations/tools (compact IDs only)
-spec list --filter publish         # Search by keyword
-spec list --tag pets               # OpenAPI: filter by tag
-spec list --tag mutation           # GraphQL: filter by kind (query/mutation/subscription)
-spec list --limit 10               # First 10 only
-spec list --limit 10 --offset 10   # Next 10
+spec list --spec agno                          # Registered spec (uses cache)
+spec list --spec petstore --filter pet         # Search by keyword
+spec list --spec petstore --tag pets           # OpenAPI: filter by tag
+spec list --spec hashnode --tag mutation        # GraphQL: filter by kind
+spec list --spec petstore --limit 10           # First 10 only
+spec list --spec petstore --limit 10 --offset 10  # Next 10
+spec list --mcp-http https://docs.agno.com/mcp # Inline: no registration needed
 ```
 
-Compact output (token-efficient):
+Compact output:
 ```json
 {
   "type": "mcp",
@@ -69,99 +89,135 @@ Compact output (token-efficient):
 }
 ```
 
-Use `--compact false` for full details (including `inputSchema` for MCP tools).
+Use `--compact false` for full details including `inputSchema` for MCP tools.
 
-### Step 3: Inspect one operation or tool
+### Inspect one operation or tool
 
-`show` gives you everything you need to make a call — params, body schema, response, and related types — in one call.
+`show` gives you everything to make a call — params, body schema, response schemas, related types — in one call.
 
 ```bash
-spec show publishPost              # GraphQL: by operation name
-spec show getPetById               # OpenAPI: by operationId
-spec show /pet/{petId}             # OpenAPI: by path
-spec show "GET /pet/{petId}"       # OpenAPI: by method + path
-spec show search_agno              # MCP: by tool name
+spec show --spec petstore getPetById           # OpenAPI: by operationId
+spec show --spec petstore /pet/{petId}         # OpenAPI: by path
+spec show --spec petstore "GET /pet/{petId}"   # OpenAPI: by method + path
+spec show --spec hashnode publishPost          # GraphQL: by operation name
+spec show --spec agno search_agno             # MCP: by tool name
 ```
 
 MCP output includes the full `inputSchema` so you know exactly what arguments to pass.
 
-### Step 4: Drill into types (OpenAPI/GraphQL only)
+### Drill into types (OpenAPI/GraphQL only)
 
 ```bash
-spec types                         # List all schema/type names
-spec types Pet                     # Inspect one schema
-spec types PublishPostInput        # Inspect a GraphQL input type
+spec types --spec petstore                     # List all schema names
+spec types --spec petstore Pet                 # Inspect one schema
+spec types --spec hashnode PublishPostInput    # GraphQL input type
 ```
 
-### Step 5: Call the API
+---
+
+## Calling APIs
 
 ```bash
-# Set base URL and auth first (persisted across calls — OpenAPI/GraphQL)
-spec config set baseUrl https://petstore3.swagger.io/api/v3
-spec config set auth YOUR_TOKEN
+# OpenAPI
+spec call --spec petstore getPetById --var petId=1
+spec call --spec petstore findPetsByStatus --query status=available
+spec call --spec petstore addPet --data '{"name":"Rex","photoUrls":[]}'
 
-# OpenAPI calls
-spec call getPetById --var petId=1
-spec call findPetsByStatus --query status=available
-spec call addPet --data '{"name":"Rex","photoUrls":[]}'
+# GraphQL (auto-generates query from schema)
+spec call --spec hashnode me
+spec call --spec hashnode publication --var host=blog.hashnode.dev
 
-# GraphQL calls (auto-generates query from schema)
-spec call me
-spec call publication --var host=blog.hashnode.dev
+# MCP
+spec call --spec agno search_agno --var query="how to create an agent"
+spec call --spec agno search_agno --data '{"query":"agents"}'
 
-# MCP calls — use --var for individual args or --data for the full JSON object
-spec call search_agno --var query="how to create an agent"
-spec call read_file --data '{"path":"/tmp/hello.txt"}'
+# Inline (no registration)
+spec call --openapi https://petstore3.swagger.io/api/v3/openapi.json \
+  getPetById --var petId=1 --base-url https://petstore3.swagger.io/api/v3
 ```
 
+### Per-call overrides
+
+Flags passed at call time win over registry entry config, which wins over `.spec-cli/config.json`.
+
+```bash
+spec call --spec agno search_agno --var query="foo" --header X-Tenant=acme
+spec call --spec petstore getPetById --var petId=1 --auth staging-token
+spec list --spec petstore --base-url https://staging.api.example.com
+```
+
+---
+
+## Registry Management
+
+```bash
+spec remove <name>    # Delete entry and remove cache
+spec enable <name>    # Re-enable a disabled spec
+spec disable <name>   # Disable without removing
+spec refresh <name>   # Force re-fetch and update cache
+```
+
+---
+
+## spec add options
+
+```bash
+spec add <name> --openapi <url-or-file>   [--base-url <url>] [--auth <token>] [--header k=v]
+spec add <name> --graphql <url>            [--auth <token>] [--header k=v]
+spec add <name> --mcp-http <url>           [--header k=v]
+spec add <name> --mcp-sse <url>            [--header k=v]
+spec add <name> --mcp-stdio "<cmd args>"   [--env KEY=VAL]
+                                           [--description <text>]  (all types)
+```
+
+Headers are sent on every request. For stdio MCP, use `--env` to pass environment variables to the subprocess.
+
+---
+
 ## Config
 
-Persistent config stored in `.spec-cli/config.json`. Set once, used for all calls.
+Persistent config stored in `.spec-cli/config.json` (lowest priority — overridden by registry entry config and call-time flags).
 
 ```bash
 spec config set baseUrl https://api.example.com
 spec config set auth my-token                        # Auto-adds "Bearer " prefix
-spec config set auth "Basic dXNlcjpwYXNz"            # Or explicit auth header
-spec config set headers.X-API-Key abc123              # Custom headers (dot notation)
-spec config get                                       # Show all config
-spec config unset auth                                # Remove a key
+spec config set auth "Basic dXNlcjpwYXNz"            # Or explicit scheme
+spec config set headers.X-API-Key abc123              # Custom header (dot notation)
+spec config get
+spec config unset auth
 ```
 
 ## Validate
 
-Check an OpenAPI spec for errors before using it:
-
 ```bash
 spec validate https://api.example.com/openapi.json
+spec validate ./openapi.yaml
 ```
 
 Reports broken `$ref` references, missing required fields, duplicate operationIds, invalid schema types, and more.
 
 ## Output Format
 
-JSON by default. Use `--format text` or `--format yaml` for alternatives:
+JSON by default. Errors go to stderr as `{"error": "message"}` with a non-zero exit code.
 
 ```bash
-spec list --format text
-spec show getPetById --format yaml
+spec list --spec petstore --format text
+spec show --spec petstore getPetById --format yaml
+spec list --spec petstore --format=json    # equals syntax also works
 ```
 
-Errors always go to stderr as JSON: `{"error": "message"}` with non-zero exit code.
-
 ## Token Efficiency
 
-The CLI is designed to minimize context window usage for AI agents:
-
-- `list` returns only IDs by default (not full schemas)
-- `show` resolves schemas compactly — nested refs show as names, not deep explosions
-- `types` lets you inspect one type at a time instead of loading all schemas
-- `--limit` and `--offset` paginate large APIs
+- `list` returns only IDs by default — no schemas
+- `show` resolves `$ref` compactly — nested refs show as names, not explosions
+- `types` lets you inspect one schema at a time
+- `--limit` / `--offset` paginate large APIs
 - `--filter` and `--tag` narrow results before output
 
 ## Storage
 
-All state lives in `.spec-cli/` in the working directory:
-- `spec.json` — loaded spec cache
-- `config.json` — base URL, auth, headers
-
-Add `.spec-cli/` to your `.gitignore`.
+| Path | Purpose |
+|---|---|
+| `~/spec-cli-config/registry.json` | Global named registry |
+| `~/spec-cli-config/cache/<name>.json` | Cached spec per registered entry |
+| `.spec-cli/config.json` | Project-local config (baseUrl, auth, headers) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-spec-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs",
   "type": "module",
   "bin": {

package/src/args.js

@@ -2,7 +2,7 @@
 // Supports: --flag value, --flag=value, and positional args
 // Repeatable flags (--query, --header, --var) are collected into arrays.
 
-const REPEATABLE = new Set(["query", "header", "var"]);
+const REPEATABLE = new Set(["query", "header", "var", "env"]);
 
 export function parseArgs(args) {
   const flags = {};

package/src/cli.js

@@ -1,77 +1,103 @@
-import { loadSpec } from "./commands/load.js";
 import { listOperations } from "./commands/list.js";
 import { showOperation } from "./commands/show.js";
 import { callOperation } from "./commands/call.js";
 import { configCmd } from "./commands/config.js";
 import { validateSpec } from "./commands/validate.js";
 import { typesCmd } from "./commands/types.js";
+import { addCmd } from "./commands/add.js";
+import { specsCmd, registryMutate } from "./commands/specs.js";
 import { out, err, setFormat } from "./output.js";
 
 const HELP = `spec-cli — Explore and call APIs from the command line.
 All output is JSON. Designed for AI agents but works for humans too.
 
-WORKFLOW (follow this order):
-  1. spec load <file-or-url>           Load an OpenAPI or GraphQL spec
-     spec load --mcp-stdio <cmd>       Load an MCP server via stdio
-     spec load --mcp-sse <url>         Load an MCP server via SSE
-     spec load --mcp-http <url>        Load an MCP server via streamable HTTP
-  2. spec list                         Browse operations/tools (compact IDs)
-  3. spec show <operation>             Get params, body, response for one op
-  4. spec call <operation> [options]   Execute the request
+Every command is stateless — specify the spec source on each call.
 
-  Use spec types [name] to inspect a schema/type referenced by show.
-  Use spec config to set baseUrl, auth, and headers before calling.
+SPEC SOURCE (required on every list/show/call):
+  --spec <name>                        Use a registered spec (auto-fetches + caches)
+  --openapi <url-or-file>              OpenAPI inline (no registration needed)
+  --graphql <url>                      GraphQL inline
+  --mcp-http <url>                     MCP streamable-HTTP inline
+  --mcp-sse <url>                      MCP SSE inline
+  --mcp-stdio "<cmd args>"             MCP stdio inline
 
-DISCOVERY (narrowing down):
-  spec list                            All operations (just IDs)
-  spec list --filter user              Search across all fields
-  spec list --tag pets                 OpenAPI tag or GraphQL kind (query/mutation)
-  spec list --limit 10 --offset 20     Paginate large APIs
+REGISTRY (register once, use anywhere):
+  spec add <name> --openapi <url>      Register an OpenAPI spec
+  spec add <name> --graphql <url>      Register a GraphQL endpoint
+  spec add <name> --mcp-http <url>     Register an MCP server (streamable-HTTP)
+  spec add <name> --mcp-sse <url>      Register an MCP server (SSE)
+  spec add <name> --mcp-stdio "<cmd>"  Register an MCP server (stdio)
+    Options: --description <text>  --base-url <url>  --auth <token>
+             --header k=v (repeatable)  --env KEY=VAL (repeatable, stdio only)
+
+  spec specs                           List all registered specs
+  spec specs --compact false           Show full entry config
+  spec remove <name>                   Delete from registry
+  spec enable <name>                   Enable a disabled spec
+  spec disable <name>                  Disable without removing
+  spec refresh <name>                  Force re-fetch and update cache
+
+DISCOVER:
+  spec list --spec <name>              All operations/tools (compact IDs)
+  spec list --spec <name> --filter user       Search by keyword
+  spec list --spec <name> --tag pets          OpenAPI tag or GraphQL kind
+  spec list --spec <name> --limit 10          Paginate
+  spec list --mcp-http <url>           Inline: no registration needed
 
 INSPECT:
-  spec show getPetById                 Match by operationId
-  spec show /pet/{petId}               Match by path
-  spec show "GET /pet/{petId}"         Match by method + path
-  spec show publishPost                GraphQL operation name
-  spec show read_file                  MCP tool name
-  spec types                           List all schema/type names
-  spec types Pet                       Inspect one schema (compact, no $ref explosion)
-
-EXECUTE:
-  spec call <op> --var petId=1                       Path or GraphQL variables
-  spec call <op> --query status=available             Query string params
-  spec call <op> --data '{"name":"Rex"}'              JSON body / MCP tool arguments
-  spec call <op> --data-file /tmp/query.json          JSON body from file (avoids shell escaping)
-  spec call <op> --header X-Custom=val                Extra headers (OpenAPI/GraphQL)
-  spec call <op> --method PUT                         Override HTTP method (OpenAPI)
-
-MCP EXAMPLES:
-  spec load --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
-  spec load --mcp-sse http://localhost:3000/sse
-  spec load --mcp-http https://example.com/mcp
-  spec list
-  spec show read_file
-  spec call read_file --var path=/tmp/hello.txt
-  spec call read_file --data '{"path":"/tmp/hello.txt"}'
-
-CONFIG (persisted in .spec-cli/config.json):
+  spec show --spec <name> <op>         Operation details (params, body, responses)
+  spec show --spec <name> <tool>       MCP tool input schema
+  spec types --spec <name>             List all schema/type names (OpenAPI/GraphQL)
+  spec types --spec <name> <TypeName>  Inspect one type
+
+CALL:
+  spec call --spec <name> <op> --var petId=1            Path/GraphQL vars
+  spec call --spec <name> <op> --query status=available  Query params
+  spec call --spec <name> <op> --data '{"name":"Rex"}'   JSON body / MCP args
+  spec call --spec <name> <op> --data-file args.json     Body from file
+  spec call --spec <name> <op> --header X-Custom=val     Extra headers
+  spec call --spec <name> <op> --method PUT              Override HTTP method
+
+PER-CALL OVERRIDES (win over registry entry config):
+  --auth <token>        Override auth for this call
+  --base-url <url>      Override base URL for this call
+  --header k=v          Merge/override headers for this call
+
+CONFIG (persisted in .spec-cli/config.json — lowest priority):
   spec config set baseUrl https://api.example.com
-  spec config set auth <token>                        Auto-adds Bearer prefix
-  spec config set headers.X-API-Key <key>             Dot notation for nested keys
-  spec config get                                     Show current config
-  spec config unset auth                              Remove a key
+  spec config set auth <token>
+  spec config set headers.X-API-Key <key>
+  spec config get
+  spec config unset auth
 
 OTHER:
   spec validate <file-or-url>          Check OpenAPI spec for errors
-  --format json|text|yaml              Output format (default: json)`;
+  --format json|text|yaml              Output format (default: json)
+
+EXAMPLES:
+  spec add agno --mcp-http https://docs.agno.com/mcp --description "Agno docs"
+  spec add petstore --openapi https://petstore3.swagger.io/api/v3/openapi.json \\
+    --base-url https://petstore3.swagger.io/api/v3
+  spec specs
+  spec list  --spec agno
+  spec show  --spec agno search_agno
+  spec call  --spec agno search_agno --var query="agents"
+  spec call  --spec agno search_agno --var query="foo" --header X-Tenant=acme
+  spec list  --mcp-http https://docs.agno.com/mcp    (inline, no registration)`;
 
 export async function run(args) {
-  // Extract --format before routing
-  const formatIdx = args.indexOf("--format");
-  if (formatIdx !== -1) {
-    setFormat(args[formatIdx + 1]);
-    args = [...args.slice(0, formatIdx), ...args.slice(formatIdx + 2)];
+  // Extract --format before routing (supports both --format json and --format=json)
+  const newArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--format" && i + 1 < args.length) {
+      setFormat(args[++i]);
+    } else if (args[i].startsWith("--format=")) {
+      setFormat(args[i].slice(9));
+    } else {
+      newArgs.push(args[i]);
+    }
   }
+  args = newArgs;
 
   const cmd = args[0];
 
@@ -82,9 +108,6 @@ export async function run(args) {
 
   try {
     switch (cmd) {
-      case "load":
-        await loadSpec(args.slice(1));
-        break;
       case "list":
       case "ls":
         await listOperations(args.slice(1));
@@ -106,6 +129,25 @@ export async function run(args) {
       case "cfg":
         await configCmd(args.slice(1));
         break;
+      case "add":
+        await addCmd(args.slice(1));
+        break;
+      case "specs":
+      case "registry":
+        await specsCmd(args.slice(1));
+        break;
+      case "remove":
+        await registryMutate("remove", args.slice(1));
+        break;
+      case "enable":
+        await registryMutate("enable", args.slice(1));
+        break;
+      case "disable":
+        await registryMutate("disable", args.slice(1));
+        break;
+      case "refresh":
+        await registryMutate("refresh", args.slice(1));
+        break;
       default:
         err(`Unknown command: ${cmd}. Run 'spec help' for usage.`);
     }

package/src/commands/add.js

@@ -0,0 +1,67 @@
+import { parseArgs, parseKV } from "../args.js";
+import { getRegistry, saveRegistry } from "../registry.js";
+import { out } from "../output.js";
+
+export async function addCmd(args) {
+  const { flags, positional } = parseArgs(args);
+  const name = positional[0];
+  if (!name) throw new Error(
+    "Usage: spec add <name> --openapi <url> | --graphql <url> | --mcp-http <url> | --mcp-sse <url> | --mcp-stdio \"<cmd>\""
+  );
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new Error("Spec name must contain only letters, numbers, hyphens, and underscores.");
+  }
+
+  const registry = getRegistry();
+  if (registry.find((e) => e.name === name)) {
+    throw new Error(`Spec '${name}' already exists. Run 'spec remove ${name}' first.`);
+  }
+
+  const entry = { name, enabled: true };
+
+  if (flags.description) entry.description = flags.description;
+
+  if (flags.openapi) {
+    entry.type = "openapi";
+    entry.source = flags.openapi;
+    entry.config = {
+      baseUrl: flags["base-url"] || null,
+      auth: flags.auth || null,
+      headers: parseKV(flags.header),
+    };
+  } else if (flags.graphql) {
+    entry.type = "graphql";
+    entry.source = flags.graphql;
+    entry.config = {
+      auth: flags.auth || null,
+      headers: parseKV(flags.header),
+    };
+  } else if (flags["mcp-stdio"]) {
+    const raw = flags["mcp-stdio"];
+    const parts = (raw.trim() ? raw.match(/(?:[^\s"]+|"[^"]*")+/g) : null)?.map((p) => p.replace(/^"|"$/g, ""));
+    if (!parts?.length) throw new Error("--mcp-stdio requires a non-empty command string");
+    entry.type = "mcp";
+    entry.transport = "stdio";
+    entry.command = parts[0];
+    entry.args = parts.slice(1);
+    entry.config = { env: parseKV(flags.env) };
+  } else if (flags["mcp-sse"]) {
+    entry.type = "mcp";
+    entry.transport = "sse";
+    entry.url = flags["mcp-sse"];
+    entry.config = { headers: parseKV(flags.header) };
+  } else if (flags["mcp-http"]) {
+    entry.type = "mcp";
+    entry.transport = "streamable-http";
+    entry.url = flags["mcp-http"];
+    entry.config = { headers: parseKV(flags.header) };
+  } else {
+    throw new Error(
+      "Specify a source: --openapi <url>, --graphql <url>, --mcp-http <url>, --mcp-sse <url>, or --mcp-stdio \"<cmd>\""
+    );
+  }
+
+  registry.push(entry);
+  saveRegistry(registry);
+  out({ ok: true, name, type: entry.type, transport: entry.transport });
+}