api-spec-cli 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-spec-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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 });
+}

package/src/commands/call.js

@@ -1,38 +1,36 @@
 import { readFileSync } from "fs";
-import { getSpec, getConfig } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs, parseKV } from "../args.js";
 import { createMcpClient } from "../mcp-client.js";
+import { resolveActiveSpec, resolveConfig } from "../resolve.js";
 
 export async function callOperation(args) {
   const { flags, positional } = parseArgs(args);
   const target = positional[0];
-  if (!target) throw new Error("Usage: spec call <operationId-or-path> [--data '{}'] [--data-file path.json] [--query k=v] [--header k=v] [--var k=v] [--method GET]");
+  if (!target) throw new Error(
+    "Usage: spec call <operation> [--spec <name> | --openapi <url> | ...] [--data '{}'] [--var k=v] [--header k=v]"
+  );
 
-  // Support --data-file to avoid shell escaping issues
   if (flags["data-file"] && !flags.data) {
     flags.data = readFileSync(flags["data-file"], "utf-8").trim();
   }
 
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
-
-  const config = getConfig();
+  const { spec, entry } = await resolveActiveSpec(flags);
+  const config = resolveConfig(flags, entry);
 
   if (spec.type === "openapi") {
     await callOpenAPI(spec, config, target, flags);
   } else if (spec.type === "mcp") {
-    await callMCP(spec, target, flags);
+    await callMCP(spec, entry, target, flags);
   } else {
     await callGraphQL(spec, config, target, flags);
   }
 }
 
-async function callMCP(spec, target, flags) {
+async function callMCP(spec, entry, target, flags) {
   const tool = spec.tools.find((t) => t.name.toLowerCase() === target.toLowerCase());
   if (!tool) throw new Error(`Tool not found: ${target}. Run 'spec list' to see available tools.`);
 
-  // Build arguments: --data for full JSON object, --var for individual keys
   let toolArgs = {};
   if (flags.data) {
     try {
@@ -41,11 +39,11 @@ async function callMCP(spec, target, flags) {
       throw new Error("--data must be valid JSON when calling an MCP tool");
     }
   }
-  // --var key=value overrides / extends --data args
   const varOverrides = parseKV(flags.var);
   toolArgs = { ...toolArgs, ...varOverrides };
 
-  const client = await createMcpClient(spec);
+  // Re-connect using the original entry (which holds transport config + headers/env)
+  const client = await createMcpClient(entry);
   try {
     const result = await client.callTool({ name: tool.name, arguments: toolArgs });
     out({ tool: tool.name, arguments: toolArgs, result });
@@ -57,67 +55,38 @@ async function callMCP(spec, target, flags) {
 async function callOpenAPI(spec, config, target, flags) {
   const lower = target.toLowerCase();
 
-  const op = spec.operations.find((o) => {
-    return (
-      o.id.toLowerCase() === lower ||
-      o.path.toLowerCase() === lower ||
-      `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
-    );
-  });
+  const op = spec.operations.find((o) =>
+    o.id.toLowerCase() === lower ||
+    o.path.toLowerCase() === lower ||
+    `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
+  );
 
   if (!op) throw new Error(`Operation not found: ${target}`);
 
-  // Build URL
   const baseUrl = config.baseUrl || spec.servers?.[0]?.url || "";
   let path = op.path;
 
-  // Substitute path variables
   const vars = parseKV(flags.var);
   for (const [key, val] of Object.entries(vars)) {
     path = path.replace(`{${key}}`, encodeURIComponent(val));
   }
 
-  // Query params
   const queryParams = parseKV(flags.query);
   const qs = new URLSearchParams(queryParams).toString();
   const url = `${baseUrl}${path}${qs ? "?" + qs : ""}`;
 
-  // Method
   const method = (flags.method || op.method).toUpperCase();
+  const headers = { ...config.headers };
 
-  // Headers
-  const headers = {
-    ...config.headers,
-    ...parseKV(flags.header),
-  };
-
-  // Auth
-  if (config.auth) {
-    if (config.auth.startsWith("Bearer ") || config.auth.startsWith("Basic ")) {
-      headers["Authorization"] = config.auth;
-    } else {
-      headers["Authorization"] = `Bearer ${config.auth}`;
-    }
-  }
-
-  // Body
   let body = undefined;
   if (flags.data) {
     body = flags.data;
-    if (!headers["Content-Type"]) {
-      headers["Content-Type"] = "application/json";
-    }
+    if (!headers["Content-Type"]) headers["Content-Type"] = "application/json";
   }
 
   const res = await fetch(url, { method, headers, body });
   const contentType = res.headers.get("content-type") || "";
-  let responseBody;
-
-  if (contentType.includes("json")) {
-    responseBody = await res.json();
-  } else {
-    responseBody = await res.text();
-  }
+  const responseBody = contentType.includes("json") ? await res.json() : await res.text();
 
   out({
     status: res.status,
@@ -133,14 +102,12 @@ async function callGraphQL(spec, config, target, flags) {
   const op = spec.operations.find((o) => o.name.toLowerCase() === lower);
   if (!op) throw new Error(`Operation not found: ${target}`);
 
-  const endpoint = spec.endpoint;
-  if (!endpoint) throw new Error("No GraphQL endpoint set");
+  const endpoint = config.baseUrl || spec.endpoint;
+  if (!endpoint) throw new Error("No GraphQL endpoint. Set --base-url or register with --graphql <url>.");
 
-  // Build query from operation
   let query;
   let dataVariables;
   if (flags.data) {
-    // If --data is provided, treat as raw GraphQL query
     try {
       const parsed = JSON.parse(flags.data);
       query = parsed.query || flags.data;
@@ -149,34 +116,23 @@ async function callGraphQL(spec, config, target, flags) {
       query = flags.data;
     }
   } else {
-    // Auto-build a simple query/mutation
     query = buildGraphQLQuery(op, spec.types);
   }
 
-  // Variables: --data variables merged with --var overrides
   const varOverrides = parseKV(flags.var);
   const variables = { ...dataVariables, ...varOverrides };
 
   const headers = {
     "Content-Type": "application/json",
     ...config.headers,
-    ...parseKV(flags.header),
   };
 
-  if (config.auth) {
-    if (config.auth.startsWith("Bearer ") || config.auth.startsWith("Basic ")) {
-      headers["Authorization"] = config.auth;
-    } else {
-      headers["Authorization"] = `Bearer ${config.auth}`;
-    }
-  }
-
   const body = JSON.stringify({
     query,
     variables: Object.keys(variables).length > 0 ? variables : undefined,
   });
 
-  const res = await fetch(config.baseUrl || endpoint, { method: "POST", headers, body });
+  const res = await fetch(endpoint, { method: "POST", headers, body });
   const responseBody = await res.json();
 
   out({
@@ -193,18 +149,15 @@ function buildGraphQLQuery(op, types) {
   const argsStr = args.length > 0
     ? `(${args.map((a) => `$${a.name}: ${flattenType(a.type)}`).join(", ")})`
     : "";
-
   const passArgs = args.length > 0
     ? `(${args.map((a) => `${a.name}: $${a.name}`).join(", ")})`
     : "";
 
-  // Try to build a field selection from the return type
   const returnTypeName = op.returnType?.replace(/[[\]!]/g, "");
   const returnType = types?.find((t) => t.name === returnTypeName);
   let fields = "";
 
   if (returnType?.fields) {
-    // Select scalar fields only (1 level deep)
     const scalarFields = returnType.fields
       .filter((f) => {
         const typeName = flattenType(f.type)?.replace(/[[\]!]/g, "");
@@ -213,9 +166,7 @@ function buildGraphQLQuery(op, types) {
       })
       .map((f) => f.name);
 
-    if (scalarFields.length > 0) {
-      fields = ` { ${scalarFields.join(" ")} }`;
-    }
+    if (scalarFields.length > 0) fields = ` { ${scalarFields.join(" ")} }`;
   }
 
   const keyword = op.kind === "mutation" ? "mutation" : "query";

package/src/commands/list.js

@@ -1,22 +1,27 @@
-import { getSpec } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
+import { resolveActiveSpec } from "../resolve.js";
 
 export async function listOperations(args) {
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
-
   const opts = parseArgs(args);
-  const filter = opts.flags.filter?.toLowerCase();
-  const compact = opts.flags.compact !== "false"; // compact by default
-  const limit = parseInt(opts.flags.limit) || 0;
-  const offset = parseInt(opts.flags.offset) || 0;
-  const tag = opts.flags.tag?.toLowerCase();
+  const { flags } = opts;
+
+  const { spec } = await resolveActiveSpec(flags);
+
+  const filter = flags.filter?.toLowerCase();
+  const compact = flags.compact !== "false";
+  const limit = parseInt(flags.limit) || 0;
+  const offset = parseInt(flags.offset) || 0;
+  const tag = flags.tag?.toLowerCase();
 
   let operations;
 
   if (spec.type === "openapi") {
-    operations = spec.operations.map((op) =>
+    let source = spec.operations;
+    if (tag) {
+      source = source.filter((op) => op.tags?.some((t) => t.toLowerCase().includes(tag)));
+    }
+    operations = source.map((op) =>
       compact
         ? { id: op.id, method: op.method, path: op.path }
         : {
@@ -28,14 +33,6 @@ export async function listOperations(args) {
             deprecated: op.deprecated,
           }
     );
-
-    // Filter by tag
-    if (tag) {
-      const fullOps = spec.operations;
-      operations = operations.filter((_, i) =>
-        fullOps[i].tags?.some((t) => t.toLowerCase().includes(tag))
-      );
-    }
   } else if (spec.type === "mcp") {
     operations = spec.tools.map((t) =>
       compact
@@ -57,28 +54,21 @@ export async function listOperations(args) {
           }
     );
 
-    // Filter by kind (query/mutation/subscription)
     if (tag) {
       operations = operations.filter((op) => op.kind === tag);
     }
   }
 
   if (filter) {
-    operations = operations.filter((op) => {
-      const text = JSON.stringify(op).toLowerCase();
-      return text.includes(filter);
-    });
+    operations = operations.filter((op) =>
+      JSON.stringify(op).toLowerCase().includes(filter)
+    );
   }
 
   const total = operations.length;
 
-  // Pagination
-  if (offset > 0) {
-    operations = operations.slice(offset);
-  }
-  if (limit > 0) {
-    operations = operations.slice(0, limit);
-  }
+  if (offset > 0) operations = operations.slice(offset);
+  if (limit > 0)  operations = operations.slice(0, limit);
 
   out({
     type: spec.type,

package/src/commands/load.js

@@ -1,9 +1,7 @@
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import YAML from "yaml";
-import { saveSpec } from "../store.js";
-import { out, err } from "../output.js";
-import { parseArgs } from "../args.js";
+import { parseKV } from "../args.js";
 import { createMcpClient } from "../mcp-client.js";
 
 const INTROSPECTION_QUERY = `{
@@ -61,78 +59,77 @@ fragment TypeRef on __Type {
   }
 }`;
 
-export async function loadSpec(args) {
-  const { flags, positional } = parseArgs(args);
-
-  // MCP transport flags
-  if (flags["mcp-stdio"] || flags["mcp-sse"] || flags["mcp-http"]) {
-    const spec = await loadMCP(flags);
-    saveSpec(spec);
-    out({
-      ok: true,
-      type: "mcp",
-      title: spec.title,
-      transport: spec.transport,
-      toolCount: spec.tools.length,
-    });
-    return;
-  }
-
-  const source = positional[0];
-  if (!source) throw new Error("Usage: spec load <file-or-url>  |  spec load --mcp-stdio <cmd>  |  spec load --mcp-sse <url>  |  spec load --mcp-http <url>");
-
-  // Detect if it's a URL or file
-  const isUrl = source.startsWith("http://") || source.startsWith("https://");
-
-  let spec;
-
-  if (isUrl) {
-    spec = await loadFromUrl(source);
-  } else {
-    spec = loadFromFile(source);
-  }
-
-  saveSpec(spec);
-  out({
-    ok: true,
-    type: spec.type,
-    title: spec.title || null,
-    operationCount: countOperations(spec),
-    source: source,
-  });
+/**
+ * Resolve a spec from a registry entry or inline flags entry.
+ * Entry shape:
+ *   { type: "openapi", source: "<url-or-file>", config: { headers, auth } }
+ *   { type: "graphql", source: "<url>", config: { headers, auth } }
+ *   { type: "mcp", transport: "stdio|sse|streamable-http", url?, command?, args?, config: { headers, env } }
+ */
+export async function resolveSpec(entry) {
+  if (entry.type === "mcp") return await loadMCPFromEntry(entry);
+  if (entry.type === "graphql") return await loadGraphQL(entry.source, entry.config?.headers);
+  // openapi — url or file; skip GraphQL probe since type is explicitly declared
+  const isUrl = entry.source?.startsWith("http://") || entry.source?.startsWith("https://");
+  return isUrl ? await loadFromUrl(entry.source, true) : loadFromFile(entry.source);
 }
 
-async function loadMCP(flags) {
-  let transportConfig;
-
+/**
+ * Build an inline entry from flags (for ad-hoc commands like --mcp-http <url>).
+ * Returns null if no inline source flags present.
+ */
+export function inlineEntryFromFlags(flags) {
   if (flags["mcp-stdio"]) {
     const raw = flags["mcp-stdio"];
-    // Split on whitespace, respecting that the value is already a single flag string
-    const parts = raw.match(/(?:[^\s"]+|"[^"]*")+/g).map((p) => p.replace(/^"|"$/g, ""));
-    transportConfig = {
+    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");
+    return {
+      type: "mcp",
       transport: "stdio",
       command: parts[0],
       args: parts.slice(1),
+      config: { env: parseKV(flags.env) },
     };
-  } else if (flags["mcp-sse"]) {
-    transportConfig = {
+  }
+  if (flags["mcp-sse"]) {
+    return {
+      type: "mcp",
       transport: "sse",
       url: flags["mcp-sse"],
+      config: { headers: parseKV(flags.header) },
     };
-  } else {
-    transportConfig = {
+  }
+  if (flags["mcp-http"]) {
+    return {
+      type: "mcp",
       transport: "streamable-http",
       url: flags["mcp-http"],
+      config: { headers: parseKV(flags.header) },
     };
   }
+  if (flags.graphql) {
+    return { type: "graphql", source: flags.graphql, config: { headers: parseKV(flags.header) } };
+  }
+  if (flags.openapi) {
+    return { type: "openapi", source: flags.openapi, config: { headers: parseKV(flags.header), baseUrl: flags["base-url"] || null } };
+  }
+  return null;
+}
+
+// --- Internal loaders ---
 
-  const client = await createMcpClient(transportConfig);
+async function loadMCPFromEntry(entry) {
+  const client = await createMcpClient(entry);
   try {
     const { tools } = await client.listTools();
     return {
       type: "mcp",
-      title: "MCP Server",
-      ...transportConfig,
+      title: entry.name || "MCP Server",
+      transport: entry.transport,
+      url: entry.url,
+      command: entry.command,
+      args: entry.args,
+      config: entry.config,
       tools: tools.map((t) => ({
         name: t.name,
         description: t.description || null,
@@ -144,24 +141,21 @@ async function loadMCP(flags) {
   }
 }
 
-async function loadFromUrl(url) {
-  // Try GraphQL introspection first if URL doesn't end with known extensions
+async function loadFromUrl(url, skipGraphQLProbe = false) {
   const lowerUrl = url.toLowerCase();
   const isLikelyFile =
     lowerUrl.endsWith(".json") ||
     lowerUrl.endsWith(".yaml") ||
     lowerUrl.endsWith(".yml");
 
-  if (!isLikelyFile) {
-    // Try GraphQL introspection
+  if (!isLikelyFile && !skipGraphQLProbe) {
     try {
       return await loadGraphQL(url);
-    } catch (e) {
+    } catch {
       // Fall through to OpenAPI
     }
   }
 
-  // Fetch as OpenAPI
   const res = await fetch(url);
   if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
   const text = await res.text();
@@ -175,10 +169,10 @@ function loadFromFile(path) {
   return parseOpenAPI(text, path);
 }
 
-async function loadGraphQL(url) {
+async function loadGraphQL(url, extraHeaders = {}) {
   const res = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...extraHeaders },
     body: JSON.stringify({ query: INTROSPECTION_QUERY }),
   });
 
@@ -190,8 +184,6 @@ async function loadGraphQL(url) {
   }
 
   const schema = json.data.__schema;
-
-  // Extract operations from query/mutation/subscription types
   const operations = [];
   const typeMap = {};
   for (const t of schema.types) {
@@ -237,7 +229,6 @@ function parseOpenAPI(text, source) {
     doc = YAML.parse(text);
   }
 
-  // Detect OpenAPI vs Swagger
   const version = doc.openapi || doc.swagger;
   if (!version) throw new Error("Not a valid OpenAPI/Swagger spec");
 
@@ -284,7 +275,3 @@ function flattenType(t) {
   }
   return t.kind;
 }
-
-function countOperations(spec) {
-  return spec.operations?.length || 0;
-}

package/src/commands/show.js

@@ -1,14 +1,13 @@
-import { getSpec } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
+import { resolveActiveSpec } from "../resolve.js";
 
 export async function showOperation(args) {
-  const { positional } = parseArgs(args);
+  const { flags, positional } = parseArgs(args);
   const target = positional[0];
-  if (!target) throw new Error("Usage: spec show <operationId-or-path>");
+  if (!target) throw new Error("Usage: spec show <operationId-or-path> [--spec <name> | --openapi <url> | ...]");
 
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
+  const { spec } = await resolveActiveSpec(flags);
 
   if (spec.type === "openapi") {
     showOpenAPI(spec, target);
@@ -22,13 +21,11 @@ export async function showOperation(args) {
 function showOpenAPI(spec, target) {
   const lower = target.toLowerCase();
 
-  const op = spec.operations.find((o) => {
-    return (
-      o.id.toLowerCase() === lower ||
-      o.path.toLowerCase() === lower ||
-      `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
-    );
-  });
+  const op = spec.operations.find((o) =>
+    o.id.toLowerCase() === lower ||
+    o.path.toLowerCase() === lower ||
+    `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
+  );
 
   if (!op) {
     throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
@@ -61,6 +58,18 @@ function showOpenAPI(spec, target) {
   });
 }
 
+function showMCP(spec, target) {
+  const tool = spec.tools.find((t) => t.name.toLowerCase() === target.toLowerCase());
+  if (!tool) {
+    throw new Error(`Tool not found: ${target}. Run 'spec list' to see available tools.`);
+  }
+  out({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  });
+}
+
 function showGraphQL(spec, target) {
   const lower = target.toLowerCase();
 
@@ -89,18 +98,6 @@ function showGraphQL(spec, target) {
   });
 }
 
-function showMCP(spec, target) {
-  const tool = spec.tools.find((t) => t.name.toLowerCase() === target.toLowerCase());
-  if (!tool) {
-    throw new Error(`Tool not found: ${target}. Run 'spec list' to see available tools.`);
-  }
-  out({
-    name: tool.name,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-  });
-}
-
 // --- Helpers ---
 
 function resolveRef(obj, root) {
@@ -108,9 +105,7 @@ function resolveRef(obj, root) {
   if (obj.$ref) {
     const path = obj.$ref.replace("#/", "").split("/");
     let resolved = root;
-    for (const p of path) {
-      resolved = resolved?.[p];
-    }
+    for (const p of path) resolved = resolved?.[p];
     return resolved || obj;
   }
   return obj;
@@ -120,7 +115,6 @@ function resolveRequestBody(body, root) {
   if (!body) return null;
   const resolved = resolveRef(body, root);
   if (resolved?.content) {
-    // Only show application/json if available (most useful for agents)
     const jsonContent = resolved.content["application/json"];
     if (jsonContent) {
       return {
@@ -129,7 +123,6 @@ function resolveRequestBody(body, root) {
         schema: resolveSchema(jsonContent.schema, root),
       };
     }
-    // Fallback: show first content type
     const [mediaType, value] = Object.entries(resolved.content)[0];
     return {
       description: resolved.description || undefined,
@@ -141,7 +134,6 @@ function resolveRequestBody(body, root) {
   return resolved;
 }
 
-// Only show success response schema — agent doesn't need error schemas to make a call
 function resolveResponsesCompact(responses, root) {
   if (!responses) return null;
   const result = {};
@@ -149,14 +141,9 @@ function resolveResponsesCompact(responses, root) {
     const resolved = resolveRef(resp, root);
     if (resolved?.content) {
       const jsonContent = resolved.content["application/json"];
-      if (jsonContent) {
-        result[code] = {
-          description: resolved.description,
-          schema: resolveSchema(jsonContent.schema, root),
-        };
-      } else {
-        result[code] = { description: resolved.description };
-      }
+      result[code] = jsonContent
+        ? { description: resolved.description, schema: resolveSchema(jsonContent.schema, root) }
+        : { description: resolved.description };
     } else {
       result[code] = { description: resolved.description };
     }
@@ -166,18 +153,12 @@ function resolveResponsesCompact(responses, root) {
 
 function resolveSchema(schema, root, depth = 0) {
   if (!schema || depth > 3) return schema;
-  if (schema.$ref) {
-    const resolved = resolveRef(schema, root);
-    // Resolve one more level for the top-level ref
-    return resolveSchema(resolved, root, depth + 1);
-  }
+  if (schema.$ref) return resolveSchema(resolveRef(schema, root), root, depth + 1);
   if (schema.properties) {
-    const result = { type: schema.type, required: schema.required };
-    result.properties = {};
+    const result = { type: schema.type, required: schema.required, properties: {} };
     for (const [key, val] of Object.entries(schema.properties)) {
       if (val.$ref) {
-        const refName = val.$ref.split("/").pop();
-        result.properties[key] = { $ref: refName };
+        result.properties[key] = { $ref: val.$ref.split("/").pop() };
       } else if (val.type === "array" && val.items?.$ref) {
         result.properties[key] = { type: "array", items: val.items.$ref.split("/").pop() };
       } else {
@@ -191,9 +172,7 @@ function resolveSchema(schema, root, depth = 0) {
     return result;
   }
   if (schema.items) {
-    if (schema.items.$ref) {
-      return { type: "array", items: schema.items.$ref.split("/").pop() };
-    }
+    if (schema.items.$ref) return { type: "array", items: schema.items.$ref.split("/").pop() };
     return { type: "array", items: resolveSchema(schema.items, root, depth + 1) };
   }
   return schema;
@@ -209,30 +188,16 @@ function findRelatedTypes(op, types) {
   }
 
   extractTypeNames(op.returnType);
-  for (const arg of op.args || []) {
-    extractTypeNames(flattenType(arg.type));
-  }
+  for (const arg of op.args || []) extractTypeNames(flattenType(arg.type));
 
   const scalars = new Set(["String", "Int", "Float", "Boolean", "ID"]);
   return types
     .filter((t) => names.has(t.name) && !scalars.has(t.name))
     .map((t) => {
       const result = { name: t.name, kind: t.kind };
-      if (t.fields) {
-        result.fields = t.fields.map((f) => ({
-          name: f.name,
-          type: flattenType(f.type),
-        }));
-      }
-      if (t.inputFields) {
-        result.inputFields = t.inputFields.map((f) => ({
-          name: f.name,
-          type: flattenType(f.type),
-        }));
-      }
-      if (t.enumValues) {
-        result.enumValues = t.enumValues.map((e) => e.name);
-      }
+      if (t.fields) result.fields = t.fields.map((f) => ({ name: f.name, type: flattenType(f.type) }));
+      if (t.inputFields) result.inputFields = t.inputFields.map((f) => ({ name: f.name, type: flattenType(f.type) }));
+      if (t.enumValues) result.enumValues = t.enumValues.map((e) => e.name);
       return result;
     });
 }

package/src/commands/specs.js

@@ -0,0 +1,69 @@
+import { parseArgs } from "../args.js";
+import { getRegistry, saveRegistry, getEntry, removeCachedSpec, saveCachedSpec } from "../registry.js";
+import { resolveSpec } from "./load.js";
+import { out } from "../output.js";
+
+export async function specsCmd(args) {
+  const { flags } = parseArgs(args);
+  const compact = flags.compact !== "false";
+  const registry = getRegistry();
+
+  const specs = registry.map((e) => {
+    if (compact) {
+      return {
+        name: e.name,
+        type: e.type,
+        transport: e.transport,
+        description: e.description || null,
+        enabled: e.enabled,
+      };
+    }
+    return e;
+  });
+
+  out({ specs });
+}
+
+export async function registryMutate(action, args) {
+  const { positional } = parseArgs(args);
+  const name = positional[0];
+  if (!name) throw new Error(`Usage: spec ${action} <name>`);
+
+  const registry = getRegistry();
+  const idx = registry.findIndex((e) => e.name === name);
+  if (idx === -1) throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
+
+  if (action === "remove") {
+    registry.splice(idx, 1);
+    saveRegistry(registry);
+    removeCachedSpec(name);
+    out({ ok: true, removed: name });
+    return;
+  }
+
+  if (action === "enable") {
+    registry[idx].enabled = true;
+    saveRegistry(registry);
+    out({ ok: true, enabled: name });
+    return;
+  }
+
+  if (action === "disable") {
+    registry[idx].enabled = false;
+    saveRegistry(registry);
+    out({ ok: true, disabled: name });
+    return;
+  }
+
+  if (action === "refresh") {
+    const entry = registry[idx];
+    if (!entry.enabled) throw new Error(`Spec '${name}' is disabled. Enable it first.`);
+    const spec = await resolveSpec(entry);
+    saveCachedSpec(name, spec);
+    const count = spec.tools?.length ?? spec.operations?.length ?? 0;
+    out({ ok: true, refreshed: name, type: spec.type, count });
+    return;
+  }
+
+  throw new Error(`Unknown registry action: ${action}`);
+}

package/src/commands/types.js

@@ -1,12 +1,10 @@
-import { getSpec } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
+import { resolveActiveSpec } from "../resolve.js";
 
 export async function typesCmd(args) {
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
-
   const { positional, flags } = parseArgs(args);
+  const { spec } = await resolveActiveSpec(flags);
   const target = positional[0];
 
   if (spec.type === "openapi") {

package/src/mcp-client.js

@@ -11,11 +11,18 @@ export async function createMcpClient(spec) {
     transport = new StdioClientTransport({
       command: spec.command,
       args: spec.args,
+      env: spec.config?.env ? { ...process.env, ...spec.config.env } : undefined,
     });
   } else if (spec.transport === "sse") {
-    transport = new SSEClientTransport(new URL(spec.url));
+    const h = spec.config?.headers;
+    transport = new SSEClientTransport(new URL(spec.url), {
+      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+    });
   } else if (spec.transport === "streamable-http") {
-    transport = new StreamableHTTPClientTransport(new URL(spec.url));
+    const h = spec.config?.headers;
+    transport = new StreamableHTTPClientTransport(new URL(spec.url), {
+      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+    });
   } else {
     throw new Error(`Unknown MCP transport: ${spec.transport}. Supported: stdio, sse, streamable-http`);
   }

package/src/registry.js

@@ -0,0 +1,53 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+
+const REGISTRY_DIR = join(homedir(), "spec-cli-config");
+const REGISTRY_FILE = join(REGISTRY_DIR, "registry.json");
+const CACHE_DIR = join(REGISTRY_DIR, "cache");
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function getRegistry() {
+  if (!existsSync(REGISTRY_FILE)) return [];
+  try {
+    return JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
+  } catch {
+    throw new Error(`Registry file is corrupt: ${REGISTRY_FILE}. Delete it to reset.`);
+  }
+}
+
+export function saveRegistry(entries) {
+  ensureDir(REGISTRY_DIR);
+  writeFileSync(REGISTRY_FILE, JSON.stringify(entries, null, 2));
+}
+
+export function getEntry(name) {
+  const registry = getRegistry();
+  const entry = registry.find((e) => e.name === name);
+  if (!entry) throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
+  if (!entry.enabled) throw new Error(`Spec '${name}' is disabled. Run 'spec enable ${name}' first.`);
+  return entry;
+}
+
+export function getCachedSpec(name) {
+  const file = join(CACHE_DIR, `${name}.json`);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return null; // Corrupt cache is treated as a miss — will re-fetch
+  }
+}
+
+export function saveCachedSpec(name, spec) {
+  ensureDir(CACHE_DIR);
+  writeFileSync(join(CACHE_DIR, `${name}.json`), JSON.stringify(spec, null, 2));
+}
+
+export function removeCachedSpec(name) {
+  const file = join(CACHE_DIR, `${name}.json`);
+  if (existsSync(file)) rmSync(file);
+}

package/src/resolve.js

@@ -0,0 +1,65 @@
+import { getEntry, getCachedSpec, saveCachedSpec } from "./registry.js";
+import { resolveSpec, inlineEntryFromFlags } from "./commands/load.js";
+import { getConfig } from "./store.js";
+import { parseKV } from "./args.js";
+
+/**
+ * Resolve the active spec from flags.
+ * Priority:
+ *   1. --spec <name>  → registry (auto-caches on first use)
+ *   2. Inline flags   → ad-hoc, no caching
+ *   3. Error          → no spec source given
+ */
+export async function resolveActiveSpec(flags) {
+  if (flags.spec) {
+    const entry = getEntry(flags.spec);     // throws if missing or disabled
+    let spec = getCachedSpec(flags.spec);
+    if (!spec) {
+      spec = await resolveSpec(entry);
+      saveCachedSpec(flags.spec, spec);
+    }
+    return { spec, entry };
+  }
+
+  const inlineEntry = inlineEntryFromFlags(flags);
+  if (inlineEntry) {
+    const spec = await resolveSpec(inlineEntry);
+    return { spec, entry: inlineEntry };
+  }
+
+  throw new Error(
+    "No spec source. Pass --spec <name> (registered) or an inline flag:\n" +
+    "  --openapi <url-or-file>\n" +
+    "  --graphql <url>\n" +
+    "  --mcp-http <url>\n" +
+    "  --mcp-sse <url>\n" +
+    '  --mcp-stdio "<cmd args>"'
+  );
+}
+
+/**
+ * Build the effective config for a command.
+ * Precedence (highest → lowest):
+ *   1. Call-time flags: --auth, --base-url, --header k=v
+ *   2. Registry entry config
+ *   3. .spec-cli/config.json
+ */
+export function resolveConfig(flags, entry) {
+  const global = getConfig();
+  const entryConfig = entry?.config || {};
+  const callHeaders = parseKV(flags.header);
+
+  const auth = flags.auth || entryConfig.auth || global.auth;
+  const baseUrl = flags["base-url"] || entryConfig.baseUrl || global.baseUrl;
+  const headers = { ...global.headers, ...(entryConfig.headers || {}), ...callHeaders };
+
+  // Apply auth as Authorization header if not already there (case-insensitive check)
+  const hasAuthHeader = Object.keys(headers).some((k) => k.toLowerCase() === "authorization");
+  if (auth && !hasAuthHeader) {
+    headers["Authorization"] = auth.startsWith("Bearer ") || auth.startsWith("Basic ")
+      ? auth
+      : `Bearer ${auth}`;
+  }
+
+  return { auth, baseUrl, headers };
+}