api-spec-cli 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,191 @@
+# spec-cli
+
+Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs. Designed for AI coding agents — all output is structured JSON by default, with optional text and YAML formats.
+
+## Install
+
+```bash
+bun install
+bun link
+```
+
+Or run directly:
+
+```bash
+bun bin/spec.js <command>
+```
+
+## Quick Start
+
+```bash
+# Load an OpenAPI spec
+spec load https://petstore3.swagger.io/api/v3/openapi.json
+
+# Load a GraphQL endpoint (introspection)
+spec load https://gql.hashnode.com
+
+# List operations
+spec list
+spec list --filter pets
+
+# Show operation details
+spec show getPetById
+spec show publishPost
+
+# Call an endpoint
+spec config set baseUrl https://petstore3.swagger.io/api/v3
+spec call findPetsByStatus --query status=available
+
+# GraphQL with auth
+spec config set auth YOUR_TOKEN
+spec call me
+```
+
+## Commands
+
+### `spec load <file-or-url>`
+
+Load an API spec from a local file (JSON/YAML) or URL.
+
+- **OpenAPI/Swagger**: Detects JSON or YAML, supports v2 and v3
+- **GraphQL**: Runs introspection query on the endpoint
+
+```bash
+spec load ./openapi.yaml
+spec load https://api.example.com/openapi.json
+spec load https://gql.example.com/graphql
+```
+
+### `spec list [--filter <text>]`
+
+List all operations in the loaded spec.
+
+```bash
+spec list                    # all operations
+spec list --filter user      # filter by keyword
+```
+
+**OpenAPI output**: `id`, `method`, `path`, `summary`, `tags`, `deprecated`
+**GraphQL output**: `id`, `kind` (query/mutation/subscription), `description`, `args`, `returnType`
+
+### `spec show <operation>`
+
+Show full details of an operation.
+
+```bash
+spec show getPetById          # by operationId
+spec show /pet/{petId}        # by path
+spec show "GET /pet/{petId}"  # by method + path
+spec show publishPost         # GraphQL operation name
+```
+
+For OpenAPI: resolves `$ref` references in parameters, request body, and responses.
+For GraphQL: includes related types with field definitions.
+
+### `spec call <operation> [options]`
+
+Execute an API request.
+
+```bash
+# OpenAPI
+spec call addPet --data '{"name":"Rex","photoUrls":[]}'
+spec call getPetById --var petId=1
+spec call findPetsByStatus --query status=available
+spec call updatePet --method PUT --data '{"id":1,"name":"Rex"}'
+
+# GraphQL
+spec call me
+spec call publication --var host=blog.example.com
+spec call publishPost --data '{"query":"mutation { ... }"}'
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--data '{"key":"val"}'` | Request body (JSON) |
+| `--query key=val` | Query parameter (repeatable) |
+| `--header key=val` | Per-request header (repeatable) |
+| `--var key=val` | Path variable or GraphQL variable (repeatable) |
+| `--method GET\|POST\|...` | Override HTTP method |
+
+For GraphQL calls without `--data`, the CLI auto-generates a query from the operation's schema, selecting scalar fields from the return type.
+
+### `spec validate <file-or-url>`
+
+Validate an OpenAPI spec and report errors and warnings.
+
+```bash
+spec validate ./openapi.yaml
+spec validate https://api.example.com/openapi.json
+```
+
+Checks:
+- Required fields (`info`, `info.title`, `info.version`, `paths`)
+- Valid HTTP methods and schema types
+- Unique `operationId` values
+- Broken `$ref` references
+- Array schemas have `items`
+- Path parameters are declared
+- Server/host definitions
+- Unusual patterns (request body on GET)
+
+### `spec config`
+
+Manage persistent configuration stored in `.spec-cli/config.json`.
+
+```bash
+spec config get                              # show all config
+spec config get baseUrl                      # show single key
+spec config set baseUrl https://api.example.com
+spec config set auth my-api-token            # adds Bearer prefix
+spec config set auth "Bearer my-token"       # explicit Bearer
+spec config set auth "Basic dXNlcjpwYXNz"   # Basic auth
+spec config set headers.X-API-Key abc123     # custom header (dot notation)
+spec config unset headers.X-API-Key          # remove a key
+```
+
+## Output Formats
+
+All commands support `--format`:
+
+```bash
+spec list --format json     # JSON (default)
+spec list --format text     # human-readable
+spec list --format yaml     # YAML
+```
+
+Errors always output as JSON to stderr for reliable agent parsing.
+
+## GraphQL Coverage
+
+Full GraphQL schema support via introspection:
+- **Queries** — all root query fields
+- **Mutations** — all root mutation fields
+- **Subscriptions** — all root subscription fields
+- **Types** — input objects, enums, scalars, object types with fields
+- **Args** — full argument definitions with types and defaults
+
+## For AI Agents
+
+This CLI is designed to be used by AI coding agents (Claude, GPT, etc.) as an MCP tool or shell command:
+
+1. **Structured output** — JSON by default, every field is predictable
+2. **Error format** — `{"error": "message"}` on stderr, non-zero exit code
+3. **Discoverable** — `list` and `show` let agents explore APIs without docs
+4. **Auto-query building** — GraphQL calls auto-generate queries from the schema
+5. **Persistent config** — set auth once, use across calls
+6. **No interactive prompts** — everything is flags and args
+
+## Storage
+
+All state is stored in `.spec-cli/` in the current directory:
+- `spec.json` — cached loaded spec
+- `config.json` — base URL, headers, auth
+
+Add `.spec-cli/` to your `.gitignore`.
+
+## Dependencies
+
+- [yaml](https://www.npmjs.com/package/yaml) — YAML parsing (for OpenAPI YAML specs and YAML output)
+
+No other runtime dependencies. Uses Bun's built-in `fetch` for HTTP.

package/bin/spec.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2));

package/package.json

@@ -1,13 +1,37 @@
 {
   "name": "api-spec-cli",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
+  "version": "0.0.2",
+  "description": "Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs",
+  "type": "module",
+  "bin": {
+    "spec": "./bin/spec.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "bun test"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "openapi",
+    "graphql",
+    "cli",
+    "agent",
+    "api",
+    "swagger",
+    "ai-agent",
+    "mcp",
+    "introspection"
+  ],
+  "author": "niradler55",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niradler/api-spec-cli.git"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "dependencies": {
+    "yaml": "^2.7.0"
+  }
 }

package/src/args.js

@@ -0,0 +1,46 @@
+// Simple arg parser — no deps needed.
+// Supports: --flag value, --flag=value, and positional args
+// Repeatable flags (--query, --header, --var) are collected into arrays.
+
+const REPEATABLE = new Set(["query", "header", "var"]);
+
+export function parseArgs(args) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      let key, value;
+      if (arg.includes("=")) {
+        [key, ...value] = arg.slice(2).split("=");
+        value = value.join("=");
+      } else {
+        key = arg.slice(2);
+        value = args[++i];
+      }
+
+      if (REPEATABLE.has(key)) {
+        if (!flags[key]) flags[key] = [];
+        flags[key].push(value);
+      } else {
+        flags[key] = value;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { flags, positional };
+}
+
+// Parse key=value pairs from an array of strings
+export function parseKV(pairs) {
+  const result = {};
+  for (const pair of pairs || []) {
+    const idx = pair.indexOf("=");
+    if (idx === -1) throw new Error(`Invalid key=value: ${pair}`);
+    result[pair.slice(0, idx)] = pair.slice(idx + 1);
+  }
+  return result;
+}

package/src/cli.js

@@ -0,0 +1,79 @@
+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 { out, err, setFormat } from "./output.js";
+
+const HELP = `spec-cli — Agent-friendly API spec explorer
+
+Commands:
+  spec load <file-or-url>              Load an OpenAPI (JSON/YAML) or GraphQL endpoint
+  spec list [--filter <text>]          List all operations
+  spec show <operation>                Show operation details (params, body, response)
+  spec call <operation> [options]      Execute a request
+  spec validate <file-or-url>          Validate an OpenAPI spec (errors + warnings)
+  spec config set <key> <value>        Set config (baseUrl, headers.X-Key, auth)
+  spec config get [key]                Show config
+  spec config unset <key>              Remove config key
+
+Call options:
+  --data '{"key":"val"}'               Request body (JSON)
+  --query key=val                      Query parameters (repeatable)
+  --header key=val                     Per-request headers (repeatable)
+  --var key=val                        Path variables (repeatable)
+  --method GET|POST|...                Override HTTP method
+
+Output format (all commands):
+  --format json                        JSON (default, best for agents)
+  --format text                        Human-readable text
+  --format yaml                        YAML output
+
+All output defaults to JSON for agent consumption.`;
+
+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)];
+  }
+
+  const cmd = args[0];
+
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    out({ help: HELP });
+    return;
+  }
+
+  try {
+    switch (cmd) {
+      case "load":
+        await loadSpec(args.slice(1));
+        break;
+      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 "config":
+      case "cfg":
+        await configCmd(args.slice(1));
+        break;
+      default:
+        err(`Unknown command: ${cmd}. Run 'spec help' for usage.`);
+    }
+  } catch (e) {
+    err(e.message);
+    process.exit(1);
+  }
+}

package/src/commands/call.js

@@ -0,0 +1,198 @@
+import { getSpec, getConfig } from "../store.js";
+import { out } from "../output.js";
+import { parseArgs, parseKV } from "../args.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 '{}'] [--query k=v] [--header k=v] [--var k=v] [--method GET]");
+
+  const spec = getSpec();
+  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
+
+  const config = getConfig();
+
+  if (spec.type === "openapi") {
+    await callOpenAPI(spec, config, target, flags);
+  } else {
+    await callGraphQL(spec, config, 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
+    );
+  });
+
+  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();
+
+  // 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";
+    }
+  }
+
+  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();
+  }
+
+  out({
+    status: res.status,
+    statusText: res.statusText,
+    headers: Object.fromEntries(res.headers.entries()),
+    body: responseBody,
+  });
+}
+
+async function callGraphQL(spec, config, target, flags) {
+  const lower = target.toLowerCase();
+
+  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");
+
+  // Build query from operation
+  let query;
+  if (flags.data) {
+    // If --data is provided, treat as raw GraphQL query
+    try {
+      const parsed = JSON.parse(flags.data);
+      query = parsed.query || flags.data;
+    } catch {
+      query = flags.data;
+    }
+  } else {
+    // Auto-build a simple query/mutation
+    query = buildGraphQLQuery(op, spec.types);
+  }
+
+  // Variables from --var flags
+  const variables = parseKV(flags.var);
+
+  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 responseBody = await res.json();
+
+  out({
+    status: res.status,
+    query,
+    variables: Object.keys(variables).length > 0 ? variables : undefined,
+    data: responseBody.data || null,
+    errors: responseBody.errors || null,
+  });
+}
+
+function buildGraphQLQuery(op, types) {
+  const args = op.args || [];
+  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, "");
+        const t = types?.find((tt) => tt.name === typeName);
+        return !t || t.kind === "SCALAR" || t.kind === "ENUM";
+      })
+      .map((f) => f.name);
+
+    if (scalarFields.length > 0) {
+      fields = ` { ${scalarFields.join(" ")} }`;
+    }
+  }
+
+  const keyword = op.kind === "mutation" ? "mutation" : "query";
+  return `${keyword}${argsStr} { ${op.name}${passArgs}${fields} }`;
+}
+
+function flattenType(t) {
+  if (!t) return null;
+  if (typeof t === "string") return t;
+  if (t.name) return t.kind === "NON_NULL" ? `${t.name}!` : t.name;
+  if (t.ofType) {
+    const inner = flattenType(t.ofType);
+    if (t.kind === "LIST") return `[${inner}]`;
+    if (t.kind === "NON_NULL") return `${inner}!`;
+    return inner;
+  }
+  return t.kind;
+}

package/src/commands/config.js

@@ -0,0 +1,75 @@
+import { getConfig, setConfig } from "../store.js";
+import { out } from "../output.js";
+
+export async function configCmd(args) {
+  const sub = args[0];
+
+  if (!sub || sub === "get" || sub === "show") {
+    const key = args[1];
+    const config = getConfig();
+    if (key) {
+      out({ [key]: getNestedValue(config, key) });
+    } else {
+      out(config);
+    }
+    return;
+  }
+
+  if (sub === "set") {
+    const key = args[1];
+    const value = args[2];
+    if (!key || value === undefined) throw new Error("Usage: spec config set <key> <value>");
+
+    const config = getConfig();
+    setNestedValue(config, key, value);
+    setConfig(config);
+    out({ ok: true, [key]: value });
+    return;
+  }
+
+  if (sub === "unset") {
+    const key = args[1];
+    if (!key) throw new Error("Usage: spec config unset <key>");
+
+    const config = getConfig();
+    deleteNestedValue(config, key);
+    setConfig(config);
+    out({ ok: true, deleted: key });
+    return;
+  }
+
+  throw new Error(`Unknown config subcommand: ${sub}. Use: get, set, unset`);
+}
+
+// Support dotted keys: "headers.Authorization", "headers.X-API-Key"
+function setNestedValue(obj, key, value) {
+  const parts = key.split(".");
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!(parts[i] in current) || typeof current[parts[i]] !== "object") {
+      current[parts[i]] = {};
+    }
+    current = current[parts[i]];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+function getNestedValue(obj, key) {
+  const parts = key.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function deleteNestedValue(obj, key) {
+  const parts = key.split(".");
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (current == null) return;
+    current = current[parts[i]];
+  }
+  if (current != null) delete current[parts[parts.length - 1]];
+}

package/src/commands/list.js

@@ -0,0 +1,47 @@
+import { getSpec } from "../store.js";
+import { out } from "../output.js";
+import { parseArgs } from "../args.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();
+
+  let operations;
+
+  if (spec.type === "openapi") {
+    operations = spec.operations.map((op) => ({
+      id: op.id,
+      method: op.method,
+      path: op.path,
+      summary: op.summary,
+      tags: op.tags,
+      deprecated: op.deprecated,
+    }));
+  } else {
+    // graphql
+    operations = spec.operations.map((op) => ({
+      id: op.name,
+      kind: op.kind,
+      description: op.description,
+      args: op.args.map((a) => a.name),
+      returnType: op.returnType,
+      isDeprecated: op.isDeprecated,
+    }));
+  }
+
+  if (filter) {
+    operations = operations.filter((op) => {
+      const text = JSON.stringify(op).toLowerCase();
+      return text.includes(filter);
+    });
+  }
+
+  out({
+    type: spec.type,
+    count: operations.length,
+    operations,
+  });
+}