api-spec-cli 0.0.3 → 0.1.0

package/README.md

@@ -1,191 +1,153 @@
-# spec-cli
+# api-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.
+CLI for AI agents to explore and call OpenAPI and GraphQL APIs. Output is JSON by default — compact, parseable, token-efficient.
 
 ## Install
 
 ```bash
-bun install
-bun link
+npm install -g api-spec-cli
 ```
 
-Or run directly:
+Works with Node.js 18+ or Bun. No other dependencies.
 
 ```bash
-bun bin/spec.js <command>
+# Or run without installing
+npx api-spec-cli <command>
 ```
 
-## Quick Start
+## How It Works
 
-```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
+The CLI follows a progressive discovery pattern. You never dump an entire API spec at once — instead you narrow down to what you need.
 
-# Show operation details
-spec show getPetById
-spec show publishPost
+### Step 1: Load the spec
 
-# 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
+```bash
+spec load https://petstore3.swagger.io/api/v3/openapi.json   # OpenAPI
+spec load ./openapi.yaml                                       # Local file
+spec load https://gql.hashnode.com                             # GraphQL (introspection)
 ```
 
-## Commands
-
-### `spec load <file-or-url>`
+Output tells you what was loaded:
+```json
+{ "ok": true, "type": "graphql", "operationCount": 114, "source": "https://gql.hashnode.com" }
+```
 
-Load an API spec from a local file (JSON/YAML) or URL.
+### Step 2: Find what you need
 
-- **OpenAPI/Swagger**: Detects JSON or YAML, supports v2 and v3
-- **GraphQL**: Runs introspection query on the endpoint
+`list` is compact by default — just operation IDs, no schemas. Use `--filter`, `--tag`, `--limit` to narrow down.
 
 ```bash
-spec load ./openapi.yaml
-spec load https://api.example.com/openapi.json
-spec load https://gql.example.com/graphql
+spec list                          # All operations (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
+```
+
+Compact output (token-efficient):
+```json
+{
+  "type": "graphql",
+  "total": 5,
+  "showing": 5,
+  "operations": [
+    { "id": "publishPost", "kind": "mutation" },
+    { "id": "publishDraft", "kind": "mutation" }
+  ]
+}
 ```
 
-### `spec list [--filter <text>]`
+Use `--compact false` for full details (summary, tags, args).
 
-List all operations in the loaded spec.
+### Step 3: Inspect one operation
+
+`show` gives you everything you need to call an operation — params, body schema, response, and related types — in one call.
 
 ```bash
-spec list                    # all operations
-spec list --filter user      # filter by keyword
+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
 ```
 
-**OpenAPI output**: `id`, `method`, `path`, `summary`, `tags`, `deprecated`
-**GraphQL output**: `id`, `kind` (query/mutation/subscription), `description`, `args`, `returnType`
-
-### `spec show <operation>`
+Schemas are compact. Nested `$ref` references show as type names (not exploded), so the output stays small. If you need details on a referenced type, use `spec types <name>`.
 
-Show full details of an operation.
+### Step 4: Drill into types (if needed)
 
 ```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
+spec types                         # List all schema/type names
+spec types Pet                     # Inspect one schema
+spec types PublishPostInput        # Inspect a GraphQL input type
 ```
 
-For OpenAPI: resolves `$ref` references in parameters, request body, and responses.
-For GraphQL: includes related types with field definitions.
+This is optional — `show` already includes related types inline. Use `types` only when you need a type that wasn't included in the `show` output.
 
-### `spec call <operation> [options]`
-
-Execute an API request.
+### Step 5: Call the API
 
 ```bash
-# OpenAPI
-spec call addPet --data '{"name":"Rex","photoUrls":[]}'
+# Set base URL and auth first (persisted across calls)
+spec config set baseUrl https://petstore3.swagger.io/api/v3
+spec config set auth YOUR_TOKEN
+
+# OpenAPI calls
 spec call getPetById --var petId=1
 spec call findPetsByStatus --query status=available
-spec call updatePet --method PUT --data '{"id":1,"name":"Rex"}'
+spec call addPet --data '{"name":"Rex","photoUrls":[]}'
 
-# GraphQL
+# GraphQL calls (auto-generates query from schema)
 spec call me
-spec call publication --var host=blog.example.com
-spec call publishPost --data '{"query":"mutation { ... }"}'
+spec call publication --var host=blog.hashnode.dev
 ```
 
-**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.
+## Config
 
-### `spec validate <file-or-url>`
-
-Validate an OpenAPI spec and report errors and warnings.
+Persistent config stored in `.spec-cli/config.json`. Set once, used for all calls.
 
 ```bash
-spec validate ./openapi.yaml
-spec validate https://api.example.com/openapi.json
+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
 ```
 
-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`
+## Validate
 
-Manage persistent configuration stored in `.spec-cli/config.json`.
+Check an OpenAPI spec for errors before using it:
 
 ```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
+spec validate https://api.example.com/openapi.json
 ```
 
-## Output Formats
+Reports broken `$ref` references, missing required fields, duplicate operationIds, invalid schema types, and more.
 
-All commands support `--format`:
+## Output Format
+
+JSON by default. Use `--format text` or `--format yaml` for alternatives:
 
 ```bash
-spec list --format json     # JSON (default)
-spec list --format text     # human-readable
-spec list --format yaml     # YAML
+spec list --format text
+spec show getPetById --format yaml
 ```
 
-Errors always output as JSON to stderr for reliable agent parsing.
-
-## GraphQL Coverage
+Errors always go to stderr as JSON: `{"error": "message"}` with non-zero exit code.
 
-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
+## Token Efficiency
 
-## For AI Agents
+The CLI is designed to minimize context window usage 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
+- `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
+- `--filter` and `--tag` narrow results before output
 
 ## Storage
 
-All state is stored in `.spec-cli/` in the current directory:
-- `spec.json` — cached loaded spec
-- `config.json` — base URL, headers, auth
+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`.
-
-## 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

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 
 import { run } from "../src/cli.js";
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "api-spec-cli",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs",
   "type": "module",
   "bin": {
-    "spec": "./bin/spec.js"
+    "spec": "bin/spec.js"
   },
   "scripts": {
     "test": "bun test"
@@ -31,6 +31,9 @@
     "type": "git",
     "url": "git+https://github.com/niradler/api-spec-cli.git"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
     "yaml": "^2.7.0"
   }

package/src/cli.js

@@ -4,33 +4,53 @@ 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 { out, err, setFormat } from "./output.js";
 
-const HELP = `spec-cli — Agent-friendly API spec explorer
+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.
 
-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
+WORKFLOW (follow this order):
+  1. spec load <file-or-url>           Load an OpenAPI or GraphQL spec
+  2. spec list                         Browse operations (compact IDs)
+  3. spec show <operation>             Get params, body, response for one op
+  4. spec call <operation> [options]   Execute the request
 
-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
+  Use spec types [name] to inspect a schema/type referenced by show.
+  Use spec config to set baseUrl, auth, and headers before calling.
 
-Output format (all commands):
-  --format json                        JSON (default, best for agents)
-  --format text                        Human-readable text
-  --format yaml                        YAML output
+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
 
-All output defaults to JSON for agent consumption.`;
+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 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
+  spec call <op> --data-file /tmp/query.json          JSON body from file (avoids shell escaping)
+  spec call <op> --header X-Custom=val                Extra headers
+  spec call <op> --method PUT                         Override HTTP method
+
+CONFIG (persisted in .spec-cli/config.json):
+  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
+
+OTHER:
+  spec validate <file-or-url>          Check OpenAPI spec for errors
+  --format json|text|yaml              Output format (default: json)`;
 
 export async function run(args) {
   // Extract --format before routing
@@ -65,6 +85,10 @@ export async function run(args) {
       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));

package/src/commands/call.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "fs";
 import { getSpec, getConfig } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs, parseKV } from "../args.js";
@@ -5,7 +6,12 @@ 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]");
+  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]");
+
+  // 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>");
@@ -103,11 +109,13 @@ async function callGraphQL(spec, config, target, flags) {
 
   // 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;
+      dataVariables = parsed.variables;
     } catch {
       query = flags.data;
     }
@@ -116,8 +124,9 @@ async function callGraphQL(spec, config, target, flags) {
     query = buildGraphQLQuery(op, spec.types);
   }
 
-  // Variables from --var flags
-  const variables = parseKV(flags.var);
+  // Variables: --data variables merged with --var overrides
+  const varOverrides = parseKV(flags.var);
+  const variables = { ...dataVariables, ...varOverrides };
 
   const headers = {
     "Content-Type": "application/json",

package/src/commands/list.js

@@ -8,28 +8,53 @@ export async function listOperations(args) {
 
   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();
 
   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,
-    }));
+    operations = spec.operations.map((op) =>
+      compact
+        ? { id: op.id, method: op.method, path: op.path }
+        : {
+            id: op.id,
+            method: op.method,
+            path: op.path,
+            summary: op.summary,
+            tags: op.tags,
+            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 {
     // 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,
-    }));
+    operations = spec.operations.map((op) =>
+      compact
+        ? { id: op.name, kind: op.kind }
+        : {
+            id: op.name,
+            kind: op.kind,
+            description: op.description,
+            args: op.args.map((a) => a.name),
+            returnType: op.returnType,
+            isDeprecated: op.isDeprecated,
+          }
+    );
+
+    // Filter by kind (query/mutation/subscription)
+    if (tag) {
+      operations = operations.filter((op) => op.kind === tag);
+    }
   }
 
   if (filter) {
@@ -39,9 +64,21 @@ export async function listOperations(args) {
     });
   }
 
+  const total = operations.length;
+
+  // Pagination
+  if (offset > 0) {
+    operations = operations.slice(offset);
+  }
+  if (limit > 0) {
+    operations = operations.slice(0, limit);
+  }
+
   out({
     type: spec.type,
-    count: operations.length,
+    total,
+    showing: operations.length,
+    offset: offset || 0,
     operations,
   });
 }

package/src/commands/show.js

@@ -1,8 +1,10 @@
 import { getSpec } from "../store.js";
 import { out } from "../output.js";
+import { parseArgs } from "../args.js";
 
 export async function showOperation(args) {
-  const target = args[0];
+  const { positional } = parseArgs(args);
+  const target = positional[0];
   if (!target) throw new Error("Usage: spec show <operationId-or-path>");
 
   const spec = getSpec();
@@ -18,7 +20,6 @@ export async function showOperation(args) {
 function showOpenAPI(spec, target) {
   const lower = target.toLowerCase();
 
-  // Match by operationId, path, or "METHOD path"
   const op = spec.operations.find((o) => {
     return (
       o.id.toLowerCase() === lower ||
@@ -33,15 +34,29 @@ function showOpenAPI(spec, target) {
 
   const root = spec.raw || spec.components;
 
-  // Resolve $ref in parameters, requestBody, and responses
-  const resolved = {
-    ...op,
-    parameters: op.parameters.map((p) => resolveRef(p, root)),
+  out({
+    id: op.id,
+    method: op.method,
+    path: op.path,
+    summary: op.summary,
+    description: op.description,
+    tags: op.tags,
+    deprecated: op.deprecated,
+    parameters: op.parameters.map((p) => {
+      const resolved = resolveRef(p, root);
+      return {
+        name: resolved.name,
+        in: resolved.in,
+        required: resolved.required || false,
+        type: resolved.schema?.type || null,
+        format: resolved.schema?.format || undefined,
+        description: resolved.description || undefined,
+        enum: resolved.schema?.enum || undefined,
+      };
+    }),
     requestBody: op.requestBody ? resolveRequestBody(op.requestBody, root) : null,
-    responses: resolveResponses(op.responses, root),
-  };
-
-  out(resolved);
+    responses: resolveResponsesCompact(op.responses, root),
+  });
 }
 
 function showGraphQL(spec, target) {
@@ -53,15 +68,27 @@ function showGraphQL(spec, target) {
     throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
   }
 
-  // Also find related types
   const relatedTypes = findRelatedTypes(op, spec.types);
 
   out({
-    ...op,
+    name: op.name,
+    kind: op.kind,
+    description: op.description,
+    returnType: op.returnType,
+    isDeprecated: op.isDeprecated,
+    args: op.args?.map((a) => ({
+      name: a.name,
+      type: flattenType(a.type),
+      required: a.type?.kind === "NON_NULL",
+      description: a.description || undefined,
+      defaultValue: a.defaultValue || undefined,
+    })),
     relatedTypes,
   });
 }
 
+// --- Helpers ---
+
 function resolveRef(obj, root) {
   if (!obj || typeof obj !== "object") return obj;
   if (obj.$ref) {
@@ -79,55 +106,81 @@ function resolveRequestBody(body, root) {
   if (!body) return null;
   const resolved = resolveRef(body, root);
   if (resolved?.content) {
-    const result = { ...resolved, content: {} };
-    for (const [mediaType, value] of Object.entries(resolved.content)) {
-      result.content[mediaType] = {
-        ...value,
-        schema: resolveSchema(value.schema, root),
+    // Only show application/json if available (most useful for agents)
+    const jsonContent = resolved.content["application/json"];
+    if (jsonContent) {
+      return {
+        description: resolved.description || undefined,
+        required: resolved.required || undefined,
+        schema: resolveSchema(jsonContent.schema, root),
       };
     }
-    return result;
+    // Fallback: show first content type
+    const [mediaType, value] = Object.entries(resolved.content)[0];
+    return {
+      description: resolved.description || undefined,
+      required: resolved.required || undefined,
+      mediaType,
+      schema: resolveSchema(value.schema, root),
+    };
   }
   return resolved;
 }
 
-function resolveResponses(responses, root) {
-  if (!responses) return responses;
+// 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 = {};
   for (const [code, resp] of Object.entries(responses)) {
     const resolved = resolveRef(resp, root);
     if (resolved?.content) {
-      result[code] = {
-        ...resolved,
-        content: {},
-      };
-      for (const [mediaType, value] of Object.entries(resolved.content)) {
-        result[code].content[mediaType] = {
-          ...value,
-          schema: resolveSchema(value.schema, root),
+      const jsonContent = resolved.content["application/json"];
+      if (jsonContent) {
+        result[code] = {
+          description: resolved.description,
+          schema: resolveSchema(jsonContent.schema, root),
         };
+      } else {
+        result[code] = { description: resolved.description };
       }
     } else {
-      result[code] = resolved;
+      result[code] = { description: resolved.description };
     }
   }
   return result;
 }
 
 function resolveSchema(schema, root, depth = 0) {
-  if (!schema || depth > 5) return schema;
+  if (!schema || depth > 3) return schema;
   if (schema.$ref) {
-    return resolveRef(schema, root);
+    const resolved = resolveRef(schema, root);
+    // Resolve one more level for the top-level ref
+    return resolveSchema(resolved, root, depth + 1);
   }
   if (schema.properties) {
-    const result = { ...schema, properties: {} };
+    const result = { type: schema.type, required: schema.required };
+    result.properties = {};
     for (const [key, val] of Object.entries(schema.properties)) {
-      result.properties[key] = resolveSchema(val, root, depth + 1);
+      if (val.$ref) {
+        const refName = val.$ref.split("/").pop();
+        result.properties[key] = { $ref: refName };
+      } else if (val.type === "array" && val.items?.$ref) {
+        result.properties[key] = { type: "array", items: val.items.$ref.split("/").pop() };
+      } else {
+        const prop = { type: val.type };
+        if (val.format) prop.format = val.format;
+        if (val.enum) prop.enum = val.enum;
+        if (val.description) prop.description = val.description;
+        result.properties[key] = prop;
+      }
     }
     return result;
   }
   if (schema.items) {
-    return { ...schema, items: resolveSchema(schema.items, root, depth + 1) };
+    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;
 }
@@ -135,7 +188,6 @@ function resolveSchema(schema, root, depth = 0) {
 function findRelatedTypes(op, types) {
   const names = new Set();
 
-  // Collect type names from args and return type
   function extractTypeNames(typeStr) {
     if (!typeStr) return;
     const cleaned = typeStr.replace(/[[\]!]/g, "");
@@ -147,20 +199,28 @@ function findRelatedTypes(op, types) {
     extractTypeNames(flattenType(arg.type));
   }
 
-  // Filter out built-in scalar types
   const scalars = new Set(["String", "Int", "Float", "Boolean", "ID"]);
   return types
     .filter((t) => names.has(t.name) && !scalars.has(t.name))
-    .map((t) => ({
-      name: t.name,
-      kind: t.kind,
-      fields: t.fields?.map((f) => ({
-        name: f.name,
-        type: flattenType(f.type),
-        description: f.description,
-      })),
-      enumValues: t.enumValues,
-    }));
+    .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);
+      }
+      return result;
+    });
 }
 
 function flattenType(t) {

package/src/commands/types.js

@@ -0,0 +1,165 @@
+import { getSpec } from "../store.js";
+import { out } from "../output.js";
+import { parseArgs } from "../args.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 target = positional[0];
+
+  if (spec.type === "openapi") {
+    showOpenAPISchema(spec, target, flags);
+  } else {
+    showGraphQLType(spec, target, flags);
+  }
+}
+
+function showOpenAPISchema(spec, target, flags) {
+  const schemas = spec.raw?.components?.schemas || spec.raw?.definitions || {};
+
+  if (!target) {
+    // List all schema names — just names, very compact
+    const names = Object.keys(schemas);
+    out({
+      type: "openapi",
+      count: names.length,
+      schemas: names,
+    });
+    return;
+  }
+
+  // Find schema (case-insensitive)
+  const lower = target.toLowerCase();
+  const key = Object.keys(schemas).find((k) => k.toLowerCase() === lower);
+
+  if (!key) {
+    throw new Error(`Schema not found: ${target}. Run 'spec types' to list available schemas.`);
+  }
+
+  const schema = schemas[key];
+  const root = spec.raw;
+
+  // Resolve one level deep — don't recursively explode nested schemas
+  const resolved = resolveSchemaCompact(schema, root);
+
+  out({
+    name: key,
+    ...resolved,
+  });
+}
+
+function showGraphQLType(spec, target, flags) {
+  const scalars = new Set(["String", "Int", "Float", "Boolean", "ID"]);
+  const userTypes = spec.types?.filter((t) => !t.name.startsWith("__") && !scalars.has(t.name)) || [];
+
+  if (!target) {
+    // List type names grouped by kind — compact
+    const grouped = {};
+    for (const t of userTypes) {
+      if (!grouped[t.kind]) grouped[t.kind] = [];
+      grouped[t.kind].push(t.name);
+    }
+    out({
+      type: "graphql",
+      count: userTypes.length,
+      types: grouped,
+    });
+    return;
+  }
+
+  // Find specific type
+  const lower = target.toLowerCase();
+  const type = userTypes.find((t) => t.name.toLowerCase() === lower);
+
+  if (!type) {
+    throw new Error(`Type not found: ${target}. Run 'spec types' to list available types.`);
+  }
+
+  const result = {
+    name: type.name,
+    kind: type.kind,
+    description: type.description || null,
+  };
+
+  if (type.fields) {
+    result.fields = type.fields.map((f) => ({
+      name: f.name,
+      type: flattenType(f.type),
+      args: f.args?.length > 0 ? f.args.map((a) => ({ name: a.name, type: flattenType(a.type) })) : undefined,
+    }));
+  }
+
+  if (type.inputFields) {
+    result.inputFields = type.inputFields.map((f) => ({
+      name: f.name,
+      type: flattenType(f.type),
+      defaultValue: f.defaultValue || undefined,
+    }));
+  }
+
+  if (type.enumValues) {
+    result.enumValues = type.enumValues.map((e) => e.name);
+  }
+
+  out(result);
+}
+
+function resolveSchemaCompact(schema, root) {
+  if (!schema) return schema;
+
+  if (schema.$ref) {
+    const path = schema.$ref.replace("#/", "").split("/");
+    let resolved = root;
+    for (const p of path) resolved = resolved?.[p];
+    return resolveSchemaCompact(resolved, root);
+  }
+
+  const result = {};
+  if (schema.type) result.type = schema.type;
+  if (schema.description) result.description = schema.description;
+  if (schema.required) result.required = schema.required;
+  if (schema.enum) result.enum = schema.enum;
+
+  if (schema.properties) {
+    result.properties = {};
+    for (const [key, val] of Object.entries(schema.properties)) {
+      if (val.$ref) {
+        // Just show the type name, don't resolve
+        const refName = val.$ref.split("/").pop();
+        result.properties[key] = { $ref: refName };
+      } else if (val.type === "array" && val.items?.$ref) {
+        const refName = val.items.$ref.split("/").pop();
+        result.properties[key] = { type: "array", items: refName };
+      } else {
+        result.properties[key] = { type: val.type || null };
+        if (val.enum) result.properties[key].enum = val.enum;
+        if (val.format) result.properties[key].format = val.format;
+        if (val.description) result.properties[key].description = val.description;
+      }
+    }
+  }
+
+  if (schema.items) {
+    if (schema.items.$ref) {
+      result.items = schema.items.$ref.split("/").pop();
+    } else {
+      result.items = { type: schema.items.type };
+    }
+  }
+
+  return result;
+}
+
+function flattenType(t) {
+  if (!t) return null;
+  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;
+}