api-spec-cli 0.2.4 → 0.2.5

package/README.md

@@ -174,6 +174,49 @@ spec disable <name>   # Disable without removing
 spec refresh <name>   # Force re-fetch and update cache
 ```
 
+`spec add` is an upsert — re-adding an existing name overwrites the entry (and clears its stale cache), since there's no separate `update` command. The response includes `"overwritten": true` when an existing entry was replaced.
+
+## Usage Ranking
+
+`spec` records which operations/tools you call so agents can surface the ones that matter:
+
+```bash
+spec list --spec petstore --top 5   # the 5 most-called operations first
+spec usage                          # recorded usage across all specs
+spec usage petstore                 # ranked operations for one spec
+```
+
+Counts are stored locally in `~/spec-cli-config/usage.json`. `--top` applies after `--filter`/`--tag` and overrides `--limit`. Set `SPEC_NO_USAGE=1` to disable tracking.
+
+## Secrets & Environment Overrides
+
+Stored values can reference environment variables instead of holding raw secrets. Use `${VAR}` in `--auth` or header values — it's expanded from the environment at call time, never stored expanded:
+
+```bash
+spec add gh --mcp-http https://api.example.com/mcp --header "Authorization=Bearer ${GH_TOKEN}"
+spec config set auth '${API_TOKEN}'
+```
+
+A `.env` file in the working directory is auto-loaded on startup (real environment variables take precedence; set `SPEC_NO_DOTENV=1` to disable).
+
+Two environment variables override a registered spec's connection per call — useful in CI:
+
+```bash
+SPEC_URL=https://staging.example.com/mcp spec call --spec gh some_tool   # override MCP/GraphQL endpoint
+SPEC_HEADER_X_TENANT=acme spec list --spec gh                            # add/override a header
+```
+
+`SPEC_HEADER_<NAME>` maps underscores to dashes (`SPEC_HEADER_X_TENANT` → `X-Tenant`). Precedence: call-time flags > env override > registry entry > project config.
+
+## Agent Skill
+
+Install a ready-made skill that teaches an agent the explore-then-call workflow:
+
+```bash
+spec skill install   # copy SKILL.md into ~/.claude/skills/api-spec-cli/
+spec skill path      # print the bundled SKILL.md location
+```
+
 ---
 
 ## spec add options
@@ -259,7 +302,7 @@ spec auth myserver           # Re-run the OAuth flow
 spec auth myserver --revoke  # Clear stored token only
 ```
 
-Tokens are stored in `~/spec-cli-config/tokens/<name>.json` — separate from the cache, not touched by `spec refresh`.
+Tokens are stored in `~/spec-cli-config/tokens/<name>.json` — separate from the cache, not touched by `spec refresh`. Access tokens are refreshed automatically: when a stored token expires, the refresh token is used and the rotated tokens are persisted, so the next command picks them up without re-authenticating.
 
 ### OAuth flags
 
@@ -301,9 +344,12 @@ JSON by default. Errors go to stderr as `{"error": "message"}` with a non-zero e
 ```bash
 spec list --spec petstore --format text
 spec show --spec petstore getPetById --format yaml
+spec list --spec petstore --format toon    # Token-Oriented Object Notation (densest)
 spec list --spec petstore --format=json    # equals syntax also works
 ```
 
+`toon` ([Token-Oriented Object Notation](https://github.com/toon-format/spec)) is the most token-efficient format for tabular/list output — the best choice when feeding results back into a model. Errors are always JSON regardless of format.
+
 ## Token Efficiency
 
 - `list` returns only IDs by default — no schemas
@@ -336,6 +382,7 @@ spec add fs --mcp-stdio "npx -y server /tmp" --env "TOKEN=${MY_SECRET}"
 | `~/spec-cli-config/registry.json` | Global named registry |
 | `~/spec-cli-config/cache/<name>.json` | Cached spec per registered entry |
 | `~/spec-cli-config/tokens/<name>.json` | OAuth tokens per MCP entry |
+| `~/spec-cli-config/usage.json` | Operation/tool call counts for `--top` and `spec usage` |
 | `.spec-cli/config.json` | Project-local config (baseUrl, auth, headers) |
 
 ## Planned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-spec-cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs",
   "type": "module",
   "bin": {
@@ -44,8 +44,10 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.28.0",
-    "yaml": "^2.7.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@toon-format/toon": "^2.3.0",
+    "yaml": "^2.9.0",
+    "yargs": "^18.0.0"
   },
   "devDependencies": {
     "prettier": "^3.8.1"

package/src/cli.js

@@ -1,3 +1,4 @@
+import yargs from "yargs";
 import { listOperations } from "./commands/list.js";
 import { showOperation } from "./commands/show.js";
 import { callOperation } from "./commands/call.js";
@@ -8,6 +9,9 @@ import { addCmd } from "./commands/add.js";
 import { specsCmd, registryMutate } from "./commands/specs.js";
 import { grepCmd } from "./commands/grep.js";
 import { authCmd } from "./commands/auth.js";
+import { usageCmd } from "./commands/usage.js";
+import { skillCmd } from "./commands/skill.js";
+import { loadDotenv } from "./dotenv.js";
 import { out, err, setFormat } from "./output.js";
 
 const HELP = `spec-cli — Explore and call APIs from the command line.
@@ -51,9 +55,12 @@ DISCOVER:
   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 --spec <name> --top 10            Rank by call count (most-used first)
   spec list --mcp-http <url>           Inline: no registration needed
   spec grep <pattern>                  Search across all registered specs
   spec grep <pattern> --spec <name>    Search within one spec
+  spec usage                           Show recorded usage for all specs
+  spec usage <name>                    Ranked operations for one spec
 
 INSPECT:
   spec show --spec <name> <op>         Operation details (params, body, responses)
@@ -86,12 +93,22 @@ OTHER:
   spec auth <name>                     Re-authenticate an OAuth-protected MCP spec
   spec auth <name> --revoke            Clear stored OAuth token
   spec validate <file-or-url>          Check OpenAPI spec for errors
-  --format json|text|yaml              Output format (default: json)
+  spec skill install                   Install the agent skill into ~/.claude/skills/
+  spec skill path                      Print the bundled SKILL.md location
+  --format json|text|yaml|toon         Output format (default: json; toon is densest)
 
-ENV VARS (MCP):
+SECRETS & OVERRIDES:
+  Stored values (auth, headers) may use \${VAR} — expanded from the environment at call time.
+  A .env file in the working directory is auto-loaded (real env vars take precedence).
+  SPEC_URL=<url>                  Override a registered MCP/GraphQL spec's endpoint for this call
+  SPEC_HEADER_<NAME>=<value>      Add/override a header (SPEC_HEADER_X_TENANT -> X-Tenant)
+
+ENV VARS:
   MCP_MAX_RETRIES=3               Retry attempts on connection failure (default: 3)
   MCP_RETRY_DELAY=1000            Base retry delay in ms, doubles each attempt (default: 1000)
   SPEC_OAUTH_CALLBACK_PORT=3141   Default fixed port for browser OAuth callback
+  SPEC_NO_USAGE=1                 Disable usage tracking
+  SPEC_NO_DOTENV=1                Disable .env auto-loading
 
 EXAMPLES:
   spec add agno --mcp-http https://docs.agno.com/mcp --description "Agno docs"
@@ -104,78 +121,216 @@ EXAMPLES:
   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 (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 specSourceOptions = {
+  spec: { type: "string", describe: "Use a registered spec" },
+  openapi: { type: "string", describe: "Inline OpenAPI URL or file" },
+  graphql: { type: "string", describe: "Inline GraphQL URL" },
+  "mcp-http": { type: "string", describe: "Inline MCP streamable-HTTP URL" },
+  "mcp-sse": { type: "string", describe: "Inline MCP SSE URL" },
+  "mcp-stdio": { type: "string", describe: "Inline MCP stdio command" },
+};
+
+const overrideOptions = {
+  auth: { type: "string", describe: "Override auth token" },
+  "base-url": { type: "string", describe: "Override base URL" },
+  header: { type: "string", array: true, describe: "Header k=v (repeatable)" },
+  "allow-tool": { type: "string", array: true, describe: "Allow tool glob (repeatable)" },
+  "disable-tool": { type: "string", array: true, describe: "Disable tool glob (repeatable)" },
+  env: { type: "string", array: true, describe: "Env KEY=VAL (repeatable, stdio only)" },
+  cwd: { type: "string", describe: "Working directory (stdio only)" },
+};
 
-  const cmd = args[0];
+const sourceOptions = { ...specSourceOptions, ...overrideOptions };
+
+const commands = (rest) => [
+  {
+    command: ["list", "ls"],
+    describe: "List operations or tools for a spec",
+    builder: (y) =>
+      y.options({
+        ...sourceOptions,
+        filter: { type: "string", describe: "Substring search across fields" },
+        compact: { type: "string", describe: "Set false to show full details" },
+        limit: { type: "string", describe: "Max results" },
+        offset: { type: "string", describe: "Skip the first N results" },
+        tag: { type: "string", describe: "OpenAPI tag or GraphQL kind" },
+        top: { type: "string", describe: "Rank by call count (most-used first)" },
+      }),
+    handler: () => listOperations(rest),
+  },
+  {
+    command: "show <operation>",
+    describe: "Show operation or tool details",
+    builder: (y) =>
+      y
+        .positional("operation", { type: "string", describe: "Operation id, path, or tool name" })
+        .options(sourceOptions),
+    handler: () => showOperation(rest),
+  },
+  {
+    command: "call <operation>",
+    describe: "Call an operation or MCP tool",
+    builder: (y) =>
+      y
+        .positional("operation", { type: "string", describe: "Operation id, path, or tool name" })
+        .options({
+          ...sourceOptions,
+          data: { type: "string", describe: "JSON body / MCP args, or - for stdin" },
+          "data-file": { type: "string", describe: "Read JSON body from a file" },
+          var: { type: "string", array: true, describe: "Path/GraphQL var k=v (repeatable)" },
+          query: { type: "string", array: true, describe: "Query param k=v (repeatable)" },
+          method: { type: "string", describe: "Override HTTP method" },
+        }),
+    handler: () => callOperation(rest),
+  },
+  {
+    command: ["types [type]", "type [type]"],
+    describe: "List schema/type names or inspect one type",
+    builder: (y) =>
+      y
+        .positional("type", { type: "string", describe: "Type or schema name to inspect" })
+        .options(sourceOptions),
+    handler: () => typesCmd(rest),
+  },
+  {
+    command: "grep <pattern>",
+    describe: "Search operations across registered specs",
+    builder: (y) =>
+      y
+        .positional("pattern", { type: "string", describe: "Glob or substring pattern" })
+        .option("spec", specSourceOptions.spec),
+    handler: () => grepCmd(rest),
+  },
+  {
+    command: "usage [name]",
+    describe: "Show recorded usage",
+    builder: (y) =>
+      y.positional("name", { type: "string", describe: "Spec name for ranked operations" }),
+    handler: () => usageCmd(rest),
+  },
+  {
+    command: "add <name>",
+    describe: "Register a spec in the registry",
+    builder: (y) =>
+      y.positional("name", { type: "string", describe: "Registry name" }).options({
+        ...specSourceOptions,
+        ...overrideOptions,
+        description: { type: "string", describe: "Human-readable description" },
+        "oauth-flow": { type: "string", choices: ["browser", "device"], describe: "OAuth flow" },
+        "oauth-client-id": { type: "string", describe: "Pre-registered OAuth client ID" },
+        "oauth-client-secret": {
+          type: "string",
+          describe: "OAuth client secret (stored securely)",
+        },
+        "oauth-callback-port": { type: "number", describe: "Fixed local OAuth callback port" },
+      }),
+    handler: () => addCmd(rest),
+  },
+  {
+    command: ["specs", "registry"],
+    describe: "List all registered specs",
+    builder: (y) =>
+      y.option("compact", { type: "string", describe: "Set false to show full entry config" }),
+    handler: () => specsCmd(rest),
+  },
+  {
+    command: "remove <name>",
+    describe: "Delete a spec from the registry",
+    builder: (y) => y.positional("name", { type: "string", describe: "Registry name" }),
+    handler: () => registryMutate("remove", rest),
+  },
+  {
+    command: "enable <name>",
+    describe: "Enable a disabled spec",
+    builder: (y) => y.positional("name", { type: "string", describe: "Registry name" }),
+    handler: () => registryMutate("enable", rest),
+  },
+  {
+    command: "disable <name>",
+    describe: "Disable a spec without removing it",
+    builder: (y) => y.positional("name", { type: "string", describe: "Registry name" }),
+    handler: () => registryMutate("disable", rest),
+  },
+  {
+    command: "refresh <name>",
+    describe: "Force re-fetch and update the cache",
+    builder: (y) => y.positional("name", { type: "string", describe: "Registry name" }),
+    handler: () => registryMutate("refresh", rest),
+  },
+  {
+    command: "auth <name>",
+    describe: "Re-authenticate or revoke an OAuth MCP spec",
+    builder: (y) =>
+      y
+        .positional("name", { type: "string", describe: "Registry name" })
+        .option("revoke", { type: "boolean", describe: "Clear the stored OAuth token" }),
+    handler: () => authCmd(rest),
+  },
+  {
+    command: ["config [action] [key] [value]", "cfg [action] [key] [value]"],
+    describe: "Get, set, or unset persisted config",
+    builder: (y) =>
+      y
+        .positional("action", { type: "string", choices: ["get", "show", "set", "unset"] })
+        .positional("key", { type: "string" })
+        .positional("value", { type: "string" }),
+    handler: () => configCmd(rest),
+  },
+  {
+    command: "validate <source>",
+    describe: "Check an OpenAPI spec for errors",
+    builder: (y) => y.positional("source", { type: "string", describe: "OpenAPI file or URL" }),
+    handler: () => validateSpec(rest),
+  },
+  {
+    command: "skill [sub]",
+    describe: "Manage the bundled agent skill",
+    builder: (y) =>
+      y
+        .positional("sub", { type: "string", choices: ["install", "path"] })
+        .option("install", { type: "boolean" })
+        .option("path", { type: "boolean" }),
+    handler: () => skillCmd(rest),
+  },
+];
+
+function isHelpRequest(args) {
+  return !args[0] || args[0] === "help" || args.includes("--help") || args.includes("-h");
+}
 
-  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+export async function run(argv) {
+  loadDotenv();
+
+  const args = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--format" && i + 1 < argv.length) setFormat(argv[++i]);
+    else if (argv[i].startsWith("--format=")) setFormat(argv[i].slice(9));
+    else args.push(argv[i]);
+  }
+
+  if (isHelpRequest(args)) {
     out({ help: HELP });
     return;
   }
 
+  const rest = args.slice(1);
+  const validationArgs = args.filter((arg) => arg !== "-");
+  const cli = yargs(validationArgs)
+    .scriptName("spec")
+    .help(false)
+    .version(false)
+    .strict()
+    .demandCommand(1, "No command given. Run 'spec help' for usage.")
+    .fail((msg, error) => {
+      err(error?.message || msg);
+      process.exit(1);
+    })
+    .exitProcess(false);
+
+  for (const command of commands(rest)) cli.command(command);
+
   try {
-    switch (cmd) {
-      case "list":
-      case "ls":
-        await listOperations(args.slice(1));
-        break;
-      case "show":
-        await showOperation(args.slice(1));
-        break;
-      case "call":
-        await callOperation(args.slice(1));
-        break;
-      case "validate":
-        await validateSpec(args.slice(1));
-        break;
-      case "types":
-      case "type":
-        await typesCmd(args.slice(1));
-        break;
-      case "config":
-      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;
-      case "grep":
-        await grepCmd(args.slice(1));
-        break;
-      case "auth":
-        await authCmd(args.slice(1));
-        break;
-      default:
-        err(`Unknown command: ${cmd}. Run 'spec help' for usage.`);
-    }
+    await cli.parseAsync();
   } catch (e) {
     err(e.message);
     process.exit(1);

package/src/commands/add.js

@@ -1,5 +1,5 @@
 import { parseArgs, parseKV } from "../args.js";
-import { getRegistry, saveRegistry } from "../registry.js";
+import { getRegistry, saveRegistry, removeCachedSpec } from "../registry.js";
 import { out } from "../output.js";
 import { saveTokenFile } from "../oauth/tokens.js";
 import { runOAuthFlow } from "../oauth/auth-flow.js";
@@ -17,10 +17,11 @@ export async function addCmd(args) {
 
   const registry = getRegistry();
 
-  // Check for name collision across all sections
-  for (const section of ["mcp", "openapi", "graphql"]) {
-    if (registry[section]?.[name]) {
-      throw new Error(`Spec '${name}' already exists. Run 'spec remove ${name}' first.`);
+  let overwritten = false;
+  for (const existingSection of ["mcp", "openapi", "graphql"]) {
+    if (registry[existingSection]?.[name]) {
+      delete registry[existingSection][name];
+      overwritten = true;
     }
   }
 
@@ -127,6 +128,7 @@ export async function addCmd(args) {
 
   registry[section][name] = entry;
   saveRegistry(registry);
+  if (overwritten) removeCachedSpec(name);
 
   // Store client secret in token file (not registry) — it's sensitive
   if (oauthClientSecret) {
@@ -142,7 +144,7 @@ export async function addCmd(args) {
     await probeAndAuth({ ...entry, name, _section: "mcp" });
   }
 
-  out({ ok: true, name, section, type: entry.type });
+  out({ ok: true, name, section, type: entry.type, ...(overwritten ? { overwritten: true } : {}) });
 }
 
 async function probeAndAuth(entry) {

package/src/commands/auth.js

@@ -1,32 +1,32 @@
-import { parseArgs } from "../args.js";
-import { getEntry } from "../registry.js";
-import { clearTokenFile } from "../oauth/tokens.js";
-import { runOAuthFlow } from "../oauth/auth-flow.js";
-import { out } from "../output.js";
-
-export async function authCmd(args) {
-  const { positional, flags } = parseArgs(args);
-  const name = positional[0];
-  if (!name) throw new Error("Usage: spec auth <name> [--revoke]");
-
-  const entry = getEntry(name);
-
-  if (entry._section !== "mcp" || (entry.type !== "http" && entry.type !== "sse")) {
-    throw new Error(
-      `'${name}' is not an HTTP/SSE MCP spec — OAuth only applies to mcp http and sse entries`
-    );
-  }
-
-  if ("revoke" in flags) {
-    // revokeAll wipes everything including clientSecret
-    clearTokenFile(name, { revokeAll: true });
-    out({ ok: true, name, revoked: true });
-    return;
-  }
-
-  // Clear session tokens but preserve clientSecret so client credentials flow still works
-  clearTokenFile(name);
-
-  const { flow } = await runOAuthFlow(name, entry);
-  out({ ok: true, name, flow });
-}
+import { parseArgs } from "../args.js";
+import { getEntry } from "../registry.js";
+import { clearTokenFile } from "../oauth/tokens.js";
+import { runOAuthFlow } from "../oauth/auth-flow.js";
+import { out } from "../output.js";
+
+export async function authCmd(args) {
+  const { positional, flags } = parseArgs(args);
+  const name = positional[0];
+  if (!name) throw new Error("Usage: spec auth <name> [--revoke]");
+
+  const entry = getEntry(name);
+
+  if (entry._section !== "mcp" || (entry.type !== "http" && entry.type !== "sse")) {
+    throw new Error(
+      `'${name}' is not an HTTP/SSE MCP spec — OAuth only applies to mcp http and sse entries`
+    );
+  }
+
+  if ("revoke" in flags) {
+    // revokeAll wipes everything including clientSecret
+    clearTokenFile(name, { revokeAll: true });
+    out({ ok: true, name, revoked: true });
+    return;
+  }
+
+  // Clear session tokens but preserve clientSecret so client credentials flow still works
+  clearTokenFile(name);
+
+  const { flow } = await runOAuthFlow(name, entry);
+  out({ ok: true, name, flow });
+}

package/src/commands/call.js

@@ -3,6 +3,7 @@ import { out } from "../output.js";
 import { parseArgs, parseKV } from "../args.js";
 import { createMcpClient } from "../mcp-client.js";
 import { resolveSpec, resolveConfig } from "../resolve.js";
+import { recordUsage } from "../usage.js";
 
 const HTTP_TIMEOUT = parseInt(process.env.SPEC_HTTP_TIMEOUT ?? "30000");
 
@@ -60,6 +61,7 @@ async function callMCP(spec, entry, target, flags) {
     // Normalize MCP result: expose isError and content at the top level
     const isError = result.isError === true;
     out({ tool: tool.name, arguments: toolArgs, isError, content: result.content, result });
+    recordUsage(flags.spec, tool.name);
     if (isError) process.exit(1);
   } finally {
     await client.close();
@@ -122,6 +124,7 @@ async function callOpenAPI(spec, config, target, flags) {
     headers: Object.fromEntries(res.headers.entries()),
     body: responseBody,
   });
+  recordUsage(flags.spec, op.id);
 }
 
 async function callGraphQL(spec, config, target, flags) {
@@ -177,6 +180,7 @@ async function callGraphQL(spec, config, target, flags) {
     data: responseBody?.data || null,
     errors: responseBody?.errors || null,
   });
+  recordUsage(flags.spec, op.name);
 }
 
 function buildGraphQLQuery(op, types) {