api-spec-cli 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +129 -73
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -17,47 +17,67 @@ npx api-spec-cli <command>
17
17
 
18
18
  ## How It Works
19
19
 
20
- The CLI follows a progressive discovery pattern. You never dump an entire API spec at once — instead you narrow down to what you need.
20
+ Every command is stateless — you specify the spec source on each call. Two paths:
21
21
 
22
- ### Step 1: Load the spec
22
+ | Path | When to use |
23
+ |---|---|
24
+ | `--spec <name>` | Registered spec — auto-fetches and caches on first use |
25
+ | Inline flags | Ad-hoc — no registration, fetched each call |
26
+
27
+ ### Register once, use everywhere
23
28
 
24
29
  ```bash
25
- # OpenAPI
26
- spec load https://petstore3.swagger.io/api/v3/openapi.json
27
- spec load ./openapi.yaml
30
+ spec add petstore --openapi https://petstore3.swagger.io/api/v3/openapi.json \
31
+ --base-url https://petstore3.swagger.io/api/v3 \
32
+ --description "Petstore example"
33
+
34
+ spec add hashnode --graphql https://gql.hashnode.com --auth YOUR_TOKEN
28
35
 
29
- # GraphQL (auto-introspects)
30
- spec load https://gql.hashnode.com
36
+ spec add agno --mcp-http https://docs.agno.com/mcp --description "Agno docs"
37
+
38
+ spec add fs --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
39
+ ```
31
40
 
32
- # MCP — stdio transport (spawn a local server)
33
- spec load --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
41
+ Registration is instant — does not connect. Connection happens on first `list`/`show`/`call` and the result is cached at `~/spec-cli-config/cache/<name>.json`.
34
42
 
35
- # MCP — SSE transport
36
- spec load --mcp-sse http://localhost:3000/sse
43
+ ### Or use inline (no registration)
37
44
 
38
- # MCP — Streamable HTTP transport
39
- spec load --mcp-http https://docs.agno.com/mcp
45
+ ```bash
46
+ spec list --openapi https://petstore3.swagger.io/api/v3/openapi.json
47
+ spec list --graphql https://gql.hashnode.com
48
+ spec list --mcp-http https://docs.agno.com/mcp
49
+ spec list --mcp-sse http://localhost:3000/sse
50
+ spec list --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
40
51
  ```
41
52
 
42
- Output tells you what was loaded:
43
- ```json
44
- { "ok": true, "type": "mcp", "transport": "streamable-http", "toolCount": 1 }
53
+ Inline fetches every call, nothing cached.
54
+
55
+ ---
56
+
57
+ ## Discovery
58
+
59
+ ### List all specs in the registry
60
+
61
+ ```bash
62
+ spec specs # Compact: name, type, enabled
63
+ spec specs --compact false # Full: includes source, config
45
64
  ```
46
65
 
47
- ### Step 2: Find what you need
66
+ ### List operations / tools
48
67
 
49
68
  `list` is compact by default — just IDs, no schemas. Use `--filter`, `--tag`, `--limit` to narrow down.
50
69
 
51
70
  ```bash
52
- spec list # All operations/tools (compact IDs only)
53
- spec list --filter publish # Search by keyword
54
- spec list --tag pets # OpenAPI: filter by tag
55
- spec list --tag mutation # GraphQL: filter by kind (query/mutation/subscription)
56
- spec list --limit 10 # First 10 only
57
- spec list --limit 10 --offset 10 # Next 10
71
+ spec list --spec agno # Registered spec (uses cache)
72
+ spec list --spec petstore --filter pet # Search by keyword
73
+ spec list --spec petstore --tag pets # OpenAPI: filter by tag
74
+ spec list --spec hashnode --tag mutation # GraphQL: filter by kind
75
+ spec list --spec petstore --limit 10 # First 10 only
76
+ spec list --spec petstore --limit 10 --offset 10 # Next 10
77
+ spec list --mcp-http https://docs.agno.com/mcp # Inline: no registration needed
58
78
  ```
59
79
 
60
- Compact output (token-efficient):
80
+ Compact output:
61
81
  ```json
62
82
  {
63
83
  "type": "mcp",
@@ -69,99 +89,135 @@ Compact output (token-efficient):
69
89
  }
70
90
  ```
71
91
 
72
- Use `--compact false` for full details (including `inputSchema` for MCP tools).
92
+ Use `--compact false` for full details including `inputSchema` for MCP tools.
73
93
 
74
- ### Step 3: Inspect one operation or tool
94
+ ### Inspect one operation or tool
75
95
 
76
- `show` gives you everything you need to make a call — params, body schema, response, and related types — in one call.
96
+ `show` gives you everything to make a call — params, body schema, response schemas, related types — in one call.
77
97
 
78
98
  ```bash
79
- spec show publishPost # GraphQL: by operation name
80
- spec show getPetById # OpenAPI: by operationId
81
- spec show /pet/{petId} # OpenAPI: by path
82
- spec show "GET /pet/{petId}" # OpenAPI: by method + path
83
- spec show search_agno # MCP: by tool name
99
+ spec show --spec petstore getPetById # OpenAPI: by operationId
100
+ spec show --spec petstore /pet/{petId} # OpenAPI: by path
101
+ spec show --spec petstore "GET /pet/{petId}" # OpenAPI: by method + path
102
+ spec show --spec hashnode publishPost # GraphQL: by operation name
103
+ spec show --spec agno search_agno # MCP: by tool name
84
104
  ```
85
105
 
86
106
  MCP output includes the full `inputSchema` so you know exactly what arguments to pass.
87
107
 
88
- ### Step 4: Drill into types (OpenAPI/GraphQL only)
108
+ ### Drill into types (OpenAPI/GraphQL only)
89
109
 
90
110
  ```bash
91
- spec types # List all schema/type names
92
- spec types Pet # Inspect one schema
93
- spec types PublishPostInput # Inspect a GraphQL input type
111
+ spec types --spec petstore # List all schema names
112
+ spec types --spec petstore Pet # Inspect one schema
113
+ spec types --spec hashnode PublishPostInput # GraphQL input type
94
114
  ```
95
115
 
96
- ### Step 5: Call the API
116
+ ---
117
+
118
+ ## Calling APIs
97
119
 
98
120
  ```bash
99
- # Set base URL and auth first (persisted across calls — OpenAPI/GraphQL)
100
- spec config set baseUrl https://petstore3.swagger.io/api/v3
101
- spec config set auth YOUR_TOKEN
121
+ # OpenAPI
122
+ spec call --spec petstore getPetById --var petId=1
123
+ spec call --spec petstore findPetsByStatus --query status=available
124
+ spec call --spec petstore addPet --data '{"name":"Rex","photoUrls":[]}'
102
125
 
103
- # OpenAPI calls
104
- spec call getPetById --var petId=1
105
- spec call findPetsByStatus --query status=available
106
- spec call addPet --data '{"name":"Rex","photoUrls":[]}'
126
+ # GraphQL (auto-generates query from schema)
127
+ spec call --spec hashnode me
128
+ spec call --spec hashnode publication --var host=blog.hashnode.dev
107
129
 
108
- # GraphQL calls (auto-generates query from schema)
109
- spec call me
110
- spec call publication --var host=blog.hashnode.dev
130
+ # MCP
131
+ spec call --spec agno search_agno --var query="how to create an agent"
132
+ spec call --spec agno search_agno --data '{"query":"agents"}'
111
133
 
112
- # MCP calls — use --var for individual args or --data for the full JSON object
113
- spec call search_agno --var query="how to create an agent"
114
- spec call read_file --data '{"path":"/tmp/hello.txt"}'
134
+ # Inline (no registration)
135
+ spec call --openapi https://petstore3.swagger.io/api/v3/openapi.json \
136
+ getPetById --var petId=1 --base-url https://petstore3.swagger.io/api/v3
115
137
  ```
116
138
 
139
+ ### Per-call overrides
140
+
141
+ Flags passed at call time win over registry entry config, which wins over `.spec-cli/config.json`.
142
+
143
+ ```bash
144
+ spec call --spec agno search_agno --var query="foo" --header X-Tenant=acme
145
+ spec call --spec petstore getPetById --var petId=1 --auth staging-token
146
+ spec list --spec petstore --base-url https://staging.api.example.com
147
+ ```
148
+
149
+ ---
150
+
151
+ ## Registry Management
152
+
153
+ ```bash
154
+ spec remove <name> # Delete entry and remove cache
155
+ spec enable <name> # Re-enable a disabled spec
156
+ spec disable <name> # Disable without removing
157
+ spec refresh <name> # Force re-fetch and update cache
158
+ ```
159
+
160
+ ---
161
+
162
+ ## spec add options
163
+
164
+ ```bash
165
+ spec add <name> --openapi <url-or-file> [--base-url <url>] [--auth <token>] [--header k=v]
166
+ spec add <name> --graphql <url> [--auth <token>] [--header k=v]
167
+ spec add <name> --mcp-http <url> [--header k=v]
168
+ spec add <name> --mcp-sse <url> [--header k=v]
169
+ spec add <name> --mcp-stdio "<cmd args>" [--env KEY=VAL]
170
+ [--description <text>] (all types)
171
+ ```
172
+
173
+ Headers are sent on every request. For stdio MCP, use `--env` to pass environment variables to the subprocess.
174
+
175
+ ---
176
+
117
177
  ## Config
118
178
 
119
- Persistent config stored in `.spec-cli/config.json`. Set once, used for all calls.
179
+ Persistent config stored in `.spec-cli/config.json` (lowest priority — overridden by registry entry config and call-time flags).
120
180
 
121
181
  ```bash
122
182
  spec config set baseUrl https://api.example.com
123
183
  spec config set auth my-token # Auto-adds "Bearer " prefix
124
- spec config set auth "Basic dXNlcjpwYXNz" # Or explicit auth header
125
- spec config set headers.X-API-Key abc123 # Custom headers (dot notation)
126
- spec config get # Show all config
127
- spec config unset auth # Remove a key
184
+ spec config set auth "Basic dXNlcjpwYXNz" # Or explicit scheme
185
+ spec config set headers.X-API-Key abc123 # Custom header (dot notation)
186
+ spec config get
187
+ spec config unset auth
128
188
  ```
129
189
 
130
190
  ## Validate
131
191
 
132
- Check an OpenAPI spec for errors before using it:
133
-
134
192
  ```bash
135
193
  spec validate https://api.example.com/openapi.json
194
+ spec validate ./openapi.yaml
136
195
  ```
137
196
 
138
197
  Reports broken `$ref` references, missing required fields, duplicate operationIds, invalid schema types, and more.
139
198
 
140
199
  ## Output Format
141
200
 
142
- JSON by default. Use `--format text` or `--format yaml` for alternatives:
201
+ JSON by default. Errors go to stderr as `{"error": "message"}` with a non-zero exit code.
143
202
 
144
203
  ```bash
145
- spec list --format text
146
- spec show getPetById --format yaml
204
+ spec list --spec petstore --format text
205
+ spec show --spec petstore getPetById --format yaml
206
+ spec list --spec petstore --format=json # equals syntax also works
147
207
  ```
148
208
 
149
- Errors always go to stderr as JSON: `{"error": "message"}` with non-zero exit code.
150
-
151
209
  ## Token Efficiency
152
210
 
153
- The CLI is designed to minimize context window usage for AI agents:
154
-
155
- - `list` returns only IDs by default (not full schemas)
156
- - `show` resolves schemas compactly — nested refs show as names, not deep explosions
157
- - `types` lets you inspect one type at a time instead of loading all schemas
158
- - `--limit` and `--offset` paginate large APIs
211
+ - `list` returns only IDs by default — no schemas
212
+ - `show` resolves `$ref` compactly — nested refs show as names, not explosions
213
+ - `types` lets you inspect one schema at a time
214
+ - `--limit` / `--offset` paginate large APIs
159
215
  - `--filter` and `--tag` narrow results before output
160
216
 
161
217
  ## Storage
162
218
 
163
- All state lives in `.spec-cli/` in the working directory:
164
- - `spec.json` — loaded spec cache
165
- - `config.json` — base URL, auth, headers
166
-
167
- Add `.spec-cli/` to your `.gitignore`.
219
+ | Path | Purpose |
220
+ |---|---|
221
+ | `~/spec-cli-config/registry.json` | Global named registry |
222
+ | `~/spec-cli-config/cache/<name>.json` | Cached spec per registered entry |
223
+ | `.spec-cli/config.json` | Project-local config (baseUrl, auth, headers) |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "api-spec-cli",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "description": "Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs",
5
5
  "type": "module",
6
6
  "bin": {