Skip to content

Commit ff936e3

Browse files
derrickkoderrickko
committed
Initial commit — clify v0.1.0
Claude Code plugin that turns any API documentation URL into a self-updating, zero-dependency CLI repo.
0 parents  commit ff936e3

11 files changed

Lines changed: 1755 additions & 0 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"name": "derrickko-clify",
3+
"owner": {
4+
"name": "derrickko",
5+
"url": "https://github.com/derrickko"
6+
},
7+
"plugins": [
8+
{
9+
"name": "clify",
10+
"description": "Generate self-updating CLI repos from API documentation URLs.",
11+
"version": "0.1.0",
12+
"source": "./"
13+
}
14+
]
15+
}

‎.claude-plugin/plugin.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "clify",
3+
"version": "0.1.0",
4+
"description": "Generate self-updating CLI repos from API documentation URLs. Produces Node.js CLIs with agent framework wrappers, smoke tests, and a self-learning knowledge system.",
5+
"author": {
6+
"name": "Derrick",
7+
"url": "https://github.com/derrickko"
8+
},
9+
"homepage": "https://github.com/derrickko/clify",
10+
"repository": "https://github.com/derrickko/clify",
11+
"license": "MIT",
12+
"keywords": ["cli-generator", "api", "openapi", "codegen", "agent"]
13+
}

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
.env
3+
.docs-snapshot/
4+
.DS_Store

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
<h1 align="center">clify</h1>
2+
3+
<p align="center">
4+
<strong>Paste a URL. Get a CLI.</strong>
5+
</p>
6+
7+
<p align="center">
8+
A Claude Code plugin that turns any API documentation into a self-updating CLI repo.
9+
</p>
10+
11+
<p align="center">
12+
<a href="https://github.com/derrickko/clify/blob/main/LICENSE"><img src="https://img.shields.io/github/license/derrickko/clify?style=flat" alt="License"></a>
13+
<a href="#install"><img src="https://img.shields.io/badge/Claude_Code-plugin-blueviolet?style=flat" alt="Claude Code plugin"></a>
14+
<img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat" alt="Node 20+">
15+
</p>
16+
17+
---
18+
19+
```
20+
You: /clify https://developer.calendly.com/api-docs
21+
22+
Claude: Fetching docs... detected REST API.
23+
Crawling 8 doc pages...
24+
25+
Detected API: Calendly
26+
Base URL: https://api.calendly.com
27+
Auth: Bearer token via CALENDLY_API_KEY
28+
29+
Resources (15 endpoints):
30+
events: list, get, cancel
31+
scheduling-links: list, create
32+
users: get, list
33+
invitees: list, get, no-show
34+
webhooks: list, get, create, delete
35+
organizations: get, invite
36+
37+
CLI name: calendly-cli
38+
39+
Recommendations:
40+
1. Include all 6 resources — small enough to ship as one CLI.
41+
2. Map DELETE /scheduled_events/{uuid} → events cancel (not
42+
events delete) — Calendly treats this as a cancellation.
43+
44+
Before generating, one question:
45+
Docs show both OAuth and Personal Access Token auth.
46+
Recommendation: Personal Access Token only — simpler for
47+
CLI/agent use. OK?
48+
49+
You: yes, ship it
50+
51+
Claude: Generated ./calendly-cli/ with:
52+
- 6 resources, 15 actions
53+
- CLI: bin/calendly-cli.mjs
54+
- Skills: skills/calendly/SKILL.md, skills/sync/SKILL.md
55+
- Tests: 15 passing
56+
57+
Install as Claude Code plugin:
58+
claude plugin add ./calendly-cli
59+
```
60+
61+
## Install
62+
63+
```
64+
/plugin marketplace add derrickko/clify
65+
/plugin install clify@derrickko-clify
66+
```
67+
68+
Or from a local clone:
69+
70+
```bash
71+
git clone https://github.com/derrickko/clify.git
72+
```
73+
```
74+
/plugin add ./clify
75+
```
76+
77+
## What You Get
78+
79+
One command produces a complete, installable repo:
80+
81+
```
82+
calendly-cli/
83+
├── bin/calendly-cli.mjs ← zero-dep CLI (Node.js built-ins only)
84+
├── skills/calendly/SKILL.md ← Claude Code skill with guided setup
85+
├── skills/sync/SKILL.md ← detects doc changes, regenerates
86+
├── knowledge/ ← patterns learned from usage
87+
├── test/smoke.test.mjs ← structural tests (pass without API key)
88+
├── .claude-plugin/ ← plugin registration
89+
├── AGENTS.md ← Codex / OpenAI agent instructions
90+
├── .clify.json ← metadata + content hash for sync
91+
├── .env.example ← annotated credential template
92+
├── package.json
93+
└── LICENSE (MIT)
94+
```
95+
96+
The generated CLI works three ways:
97+
98+
| Mode | How | Example |
99+
|------|-----|---------|
100+
| **Standalone** | Run directly from terminal | `calendly-cli events list --status active` |
101+
| **Claude Code plugin** | Install and use conversationally | `"cancel all my Calendly events for next Friday"` |
102+
| **Codex / agent** | Reads AGENTS.md for autonomous use | Agent runs CLI commands with structured JSON output |
103+
104+
## Features
105+
106+
| | Feature | Details |
107+
|-|---------|---------|
108+
| **Zero deps** | Generated CLIs use only Node.js built-ins | No `node_modules`, no supply chain risk |
109+
| **Any format** | OpenAPI specs parsed directly; HTML/Markdown crawled and extracted | Structured specs preferred for accuracy |
110+
| **Self-update** | `/sync` re-crawls docs, diffs content hashes, regenerates on change | Knowledge files preserved across syncs |
111+
| **Guided setup** | Generated skill walks through auth + defaults on first use | Auto-detects pervasive parameters (e.g., `workspace_id`) |
112+
| **Knowledge system** | Learns gotchas, patterns, and shortcuts as you use the CLI | Agents consult knowledge before every command |
113+
| **Smoke tests** | Every generated repo ships with structural tests | Tests pass with no API key — validates CLI shape, not API responses |
114+
| **Agent-native** | Structured JSON output, error taxonomy, three-level `--help` | Agents discover flags at runtime via `--help` |
115+
| **Consulted generation** | Shows parsed endpoints and recommendations before writing code | You approve, override, or refine before anything is generated |
116+
117+
## Usage
118+
119+
```
120+
/clify <api-docs-url>
121+
```
122+
123+
That's it. clify fetches, parses, asks you to confirm, generates, and tests.
124+
125+
### Examples
126+
127+
```bash
128+
# From OpenAPI specs (highest accuracy)
129+
/clify https://api.example.com/openapi.json
130+
131+
# From HTML documentation
132+
/clify https://developer.calendly.com/api-docs
133+
134+
# From Markdown docs
135+
/clify https://raw.githubusercontent.com/org/repo/main/docs/api.md
136+
```
137+
138+
### Generated CLI in Action
139+
140+
Every generated CLI follows the same resource-action pattern:
141+
142+
```bash
143+
# CRUD operations map naturally
144+
calendly-cli events list --status active --json
145+
calendly-cli webhooks create --url https://hook.example.com --events invitee.created
146+
calendly-cli scheduling-links create --owner-uri <user-uri> --max-event-count 1
147+
148+
# Global flags work on every command
149+
calendly-cli invitees list --event <uri> --all # auto-paginate
150+
calendly-cli events get --uuid <uuid> --verbose # show request/response details
151+
152+
# Three-level help for runtime discovery
153+
calendly-cli --help # list all resources
154+
calendly-cli events --help # list actions for events
155+
calendly-cli events cancel --help # show flags with descriptions
156+
157+
# Structured errors for agents
158+
calendly-cli events cancel --uuid bad
159+
# → { "type": "error", "code": "not_found", "message": "...", "retryable": false }
160+
```
161+
162+
### Self-Update
163+
164+
When the API changes, the generated `/sync` skill keeps your CLI current:
165+
166+
```
167+
/sync
168+
→ "3 new endpoints, 1 removed, 2 modified"
169+
→ Regenerates CLI + skills
170+
→ Runs smoke tests
171+
→ Reviews knowledge/ for stale entries
172+
```
173+
174+
Content hashes in `.clify.json` track exactly what changed. Knowledge files survive regeneration, so your learned patterns carry forward.
175+
176+
### Knowledge System
177+
178+
As agents use the generated CLI, they write down what they learn:
179+
180+
```yaml
181+
# knowledge/upload-content-type.md
182+
---
183+
type: gotcha
184+
command: "files upload"
185+
learned: 2026-04-06
186+
confidence: high
187+
---
188+
Upload endpoint returns 422 if Content-Type header is missing.
189+
Always include --content-type application/octet-stream for binary uploads.
190+
```
191+
192+
Four knowledge types: **gotcha** (error → recovery), **pattern** (common flag combos), **shortcut** (multi-step workflows), **quirk** (API contradicts docs). The generated skill reads all knowledge files before every command, so accumulated patterns carry forward without touching code.
193+
194+
## How It Works
195+
196+
clify is a pure Claude Code skill with no runtime dependencies. The generation pipeline:
197+
198+
1. **Fetch** — pulls the docs URL
199+
2. **Detect** — checks for OpenAPI/Swagger (parsed directly) vs HTML/Markdown (crawled up to depth 2)
200+
3. **Parse** — extracts endpoints, auth scheme, resource structure, pervasive parameters
201+
4. **Consult** — presents findings with opinionated recommendations; you confirm before generating
202+
5. **Generate** — writes all files following rigid conventions ([`conventions.md`](skills/clify/references/conventions.md))
203+
6. **Validate** — runs smoke tests, scans for leaked secrets, self-reviews generated skills
204+
7. **Report** — summary + install command
205+
206+
OpenAPI specs skip crawling entirely — structured data means higher accuracy and fewer questions.
207+
208+
<details>
209+
<summary>Error taxonomy in generated CLIs</summary>
210+
211+
Every generated CLI maps HTTP errors to a standard taxonomy that agents can act on programmatically:
212+
213+
| Code | Retryable | When |
214+
|------|-----------|------|
215+
| `auth_missing` | No | No API key in `.env` |
216+
| `auth_invalid` | No | Key rejected (401) |
217+
| `validation_error` | No | Bad request (400, 422) |
218+
| `not_found` | No | Resource doesn't exist (404) |
219+
| `forbidden` | No | Insufficient permissions (403) |
220+
| `conflict` | No | State conflict (409) |
221+
| `rate_limited` | Yes | Too many requests (429) |
222+
| `server_error` | Yes | API server error (5xx) |
223+
| `network_error` | Yes | Connection failed |
224+
| `timeout` | Yes | Request exceeded timeout |
225+
226+
Retry logic lives in the skill wrapper, not the CLI — the agent decides when and how to retry.
227+
228+
</details>
229+
230+
<details>
231+
<summary>Generated CLI conventions</summary>
232+
233+
All generated CLIs follow the same contracts:
234+
235+
- **Resource-action pattern:** `<cli> <resource> <action> [flags]`
236+
- **Standard CRUD mapping:** `list`, `get`, `create`, `update`, `delete`
237+
- **Non-CRUD verbs:** use the API's own terminology (`send`, `verify`, `cancel`)
238+
- **Nesting cap:** 2 levels max; deeper paths flatten to flags
239+
- **Global flags:** `--json`, `--dry-run`, `--help`, `--version`, `--verbose`, `--all`
240+
- **Per-action flags:** declared via `_flags` metadata — single source of truth for both parsing and help text
241+
- **`.env` loading:** reads from repo root only, never overrides shell env vars
242+
- **Pagination:** one page by default, `--all` auto-paginates
243+
- **`--body <json>`:** escape hatch on every mutating endpoint
244+
245+
See [`conventions.md`](skills/clify/references/conventions.md) for the full specification.
246+
247+
</details>
248+
249+
## Contributing
250+
251+
Contributions welcome.
252+
253+
- [Report a bug](https://github.com/derrickko/clify/issues/new?labels=bug)
254+
- [Request a feature](https://github.com/derrickko/clify/issues/new?labels=enhancement)
255+
256+
## License
257+
258+
[MIT](LICENSE)

‎package.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "clify",
3+
"version": "0.1.0",
4+
"description": "Generate self-updating CLI repos from API documentation URLs.",
5+
"type": "module",
6+
"engines": {
7+
"node": ">=20"
8+
},
9+
"license": "MIT",
10+
"repository": {
11+
"type": "git",
12+
"url": "git+https://github.com/derrickko/clify.git"
13+
},
14+
"homepage": "https://github.com/derrickko/clify",
15+
"bugs": {
16+
"url": "https://github.com/derrickko/clify/issues"
17+
}
18+
}

0 commit comments

Comments
 (0)