← back to Cli Printing Press
docs: rewrite README to reflect what the press actually does now
b8c762c663e1d6b7e03d9d91cec6710ffa262bd8 · 2026-03-25 10:38:22 -0700 · Matt Van Horn
The README was from before the intelligence engine, LLM brains, agent-native
audit, scorecard, and competitor intelligence. Updated to show the real
architecture: LLM before + template + LLM after, 18 catalog entries,
107 tests, Grade A scorecard, agent-native features.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Files touched
Diff
commit b8c762c663e1d6b7e03d9d91cec6710ffa262bd8
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Wed Mar 25 10:38:22 2026 -0700
docs: rewrite README to reflect what the press actually does now
The README was from before the intelligence engine, LLM brains, agent-native
audit, scorecard, and competitor intelligence. Updated to show the real
architecture: LLM before + template + LLM after, 18 catalog entries,
107 tests, Grade A scorecard, agent-native features.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
README.md | 405 +++++++++++++++++---------------------------------------------
1 file changed, 107 insertions(+), 298 deletions(-)
diff --git a/README.md b/README.md
index e9809769..055f541b 100644
--- a/README.md
+++ b/README.md
@@ -1,359 +1,168 @@
# CLI Printing Press
-One command. Any API. A production CLI walks out the other side.
-
-Peter Steinberger hand-crafts [gogcli](https://github.com/steipete/gogcli), [discrawl](https://github.com/steipete/discrawl), [wacli](https://github.com/steipete/wacli) - beautiful Go CLIs that take weeks each. The printing press does it in 60 seconds. Point it at any OpenAPI spec in the world and get a finished CLI with auth, pagination, tables, retries, color, doctor, completions. Not a scaffold. Not a starting point. A finished product.
+Give it an API. It researches the competition, understands the docs, generates a Go CLI, polishes it with an LLM, scores it against Steinberger, and tells you if it's good enough to ship. One command.
```bash
-./printing-press generate --spec https://petstore3.swagger.io/api/v3/openapi.json
+printing-press generate --spec https://raw.githubusercontent.com/plaid/plaid-openapi/master/2020-09-14.yml --polish
```
```
+Using LLM to understand API docs...
PASS go mod tidy
PASS go vet ./...
PASS go build ./...
PASS build runnable binary
-PASS petstore-cli --help
-PASS petstore-cli version
-PASS petstore-cli doctor
-Generated petstore-cli at ./petstore-cli
+PASS plaid-cli --help
+PASS plaid-cli version
+PASS plaid-cli doctor
+Polish: 12 help texts improved, 8 examples added, README rewritten
+Generated plaid-cli at ./plaid-cli
```
-Seven quality gates. All green. Ship it.
-
-## The 60-Second Demo
-
-```bash
-# Build the press
-git clone https://github.com/mvanhorn/cli-printing-press.git
-cd cli-printing-press
-go build -o ./printing-press ./cmd/printing-press
+No official Plaid CLI exists. Now one does. 51 resources. Agent-native. Grade A on the Steinberger bar.
-# Print a CLI from any OpenAPI spec
-./printing-press generate \
- --spec https://petstore3.swagger.io/api/v3/openapi.json \
- --output ./petstore-cli
+## How It Works
-# Use it
-cd petstore-cli && go build -o petstore-cli ./cmd/petstore-cli
-./petstore-cli --help
-```
+The press has three brains:
```
-Usage:
- petstore-cli [command]
-
-Available Commands:
- completion Generate the autocompletion script for the specified shell
- doctor Check CLI health
- help Help about any command
- pet Everything about your Pets
- store Access to Petstore orders
- user Operations about user
- version Print version
-
-Flags:
- --config string Config file path
- --dry-run Show request without sending
- -h, --help help for petstore-cli
- --json Output as JSON
- --no-color Disable colored output
- --plain Output as plain tab-separated text
- --quiet Bare output, one value per line
- --timeout duration Request timeout (default 30s)
- -v, --version version for petstore-cli
+LLM BEFORE ($0.30) TEMPLATE ($0) LLM AFTER ($0.25)
+ reads API docs -> Go templates render -> improves help text
+ understands competitors deterministic code adds real examples
+ writes complete spec error handling rewrites README
+ plans what to build agent-native flags sells the tool
```
-```bash
-./petstore-cli doctor
-```
+**Pass 1 - LLM understands the API.** Reads the docs or OpenAPI spec. Analyzes competing CLIs on GitHub (issues, README, PRs). Decides what commands to generate.
-```
- OK Config: ok
- FAIL Auth: not configured
- OK API: reachable (HTTP 404)
- config_path: ~/.config/petstore-cli/config.toml
- base_url: https://petstore3.swagger.io/api/v3
- version: 1.0.27
-```
+**Pass 2 - Templates generate correct code.** 14 Go templates produce a complete CLI project: auth, pagination, retries, color, doctor, --json, --select, --dry-run, --stdin, caching.
-Every resource, every endpoint, every flag - auto-generated from the spec.
+**Pass 3 - LLM polishes the output.** Rewrites help descriptions from spec jargon to developer-friendly. Generates realistic examples. Writes a README that sells the tool.
-```bash
-./petstore-cli pet --help
-```
+Without an LLM, the press still works - it falls back to regex-based doc parsing and template-only generation. The LLM makes it smart, not functional.
-```
-Available Commands:
- add Add a new pet to the store.
- delete Deletes a pet.
- find-by-status Finds Pets by status.
- find-by-tags Finds Pets by tags.
- get-by-id Find pet by ID.
- update Update an existing pet.
- update-with-form Updates a pet in the store with form data.
- upload-image Manage upload image
-```
-
-## What Gets Generated
-
-Every printed CLI ships with everything a Steinberger-quality CLI needs:
-
-### Commands
-
-- **Cobra subcommand tree** - `<name>-cli <resource> <action>` hierarchy, auto-generated from spec paths
-- **Sub-resource grouping** - nested API paths become `resource sub-resource action`
-- **doctor** - formatted health dashboard with status checks, config paths, and version
-- **version** - semantic version from config
-- **Shell completions** - bash, zsh, fish, powershell via Cobra
-
-### Output
-
-- **Table output** - list responses auto-detected from array schemas, rendered as formatted tables
-- **`--json`** - raw JSON for piping and scripting
-- **`--plain`** - tab-separated values for `awk`/`cut`
-- **`--quiet`** - bare values, one per line
-- **Color and TTY detection** - ANSI color when interactive, plain when piped. Respects `NO_COLOR`, `TERM=dumb`, and `--no-color`
-
-### Auth
-
-- **API key** - header or query parameter
-- **Bearer token** - standard Authorization header
-- **Basic auth** - username:password
-- **OAuth2** - full browser-based authorization flow with token refresh, authorization URL, and token URL support
-
-### Reliability
-
-- **Retry with exponential backoff** - automatic retry on 5xx responses
-- **Rate limit detection** - 429 status + Retry-After header handling
-- **Structured exit codes** - 0 (ok), 1 (general error), 3 (not found), 4 (auth error), 7 (rate limited), 130 (interrupted)
-- **Request timeout** - configurable via `--timeout` flag (default 30s)
-- **`--dry-run`** - preview mutation requests without sending them
-
-### Pagination
-
-- **Auto-detected from spec** - `--limit` and `--all` flags generated when pagination is detected
-- **Cursor-based and offset-based** - handles both pagination styles
-
-### Build Tooling
-
-- **go.mod** - clean module with pinned dependencies
-- **Makefile** - build, test, lint, install targets
-- **.goreleaser.yaml** - cross-platform release automation
-- **.golangci.yml** - linter configuration
-- **README.md** - auto-generated documentation for the CLI itself
-- **Config** - TOML config at `~/.config/<name>-cli/config.toml`
-
-## Usage
-
-### From OpenAPI URL
+## Quick Start
```bash
-./printing-press generate --spec https://petstore3.swagger.io/api/v3/openapi.json
-```
-
-Specs are cached locally for 24 hours at `~/.cache/printing-press/specs/`.
-
-### From Local File
+git clone https://github.com/mvanhorn/cli-printing-press.git
+cd cli-printing-press
+go build -o ./printing-press ./cmd/printing-press
-```bash
-./printing-press generate --spec ./my-api-spec.yaml --output ./my-cli
-```
+# From an OpenAPI spec (fast, free)
+./printing-press generate --spec https://petstore3.swagger.io/api/v3/openapi.json
-### From Internal YAML Format
+# From API docs when no spec exists (uses LLM)
+./printing-press generate --docs "https://developers.notion.com/reference" --name notion
-For APIs without OpenAPI specs, write a simpler YAML format:
+# With LLM polish pass (better help text, examples, README)
+./printing-press generate --spec <url> --polish
-```bash
-./printing-press generate --spec ./my-api.yaml
+# With lenient parsing for messy specs (PagerDuty, Intercom)
+./printing-press generate --spec <url> --lenient
```
-See `skills/printing-press/references/spec-format.md` for the YAML format reference.
+## What Gets Generated
-### Multi-Spec Composition
+Every CLI ships with:
-Merge multiple APIs into a single CLI:
+| Feature | Flag | What It Does |
+|---------|------|-------------|
+| JSON output | `--json` | Machine-readable, pipeable to jq |
+| Field filtering | `--select id,name` | Only the fields you want |
+| Dry run | `--dry-run` | Shows the exact API request without sending |
+| Stdin input | `--stdin` | Pipe JSON body: `echo '{}' \| mycli create --stdin` |
+| Response cache | `--no-cache` | GET responses cached 5 min, bypass with flag |
+| Skip confirmation | `--yes` | For agents and scripts on destructive actions |
+| Plain output | `--plain` | Tab-separated for awk/cut |
+| Color control | `--no-color` | Respects NO_COLOR, TERM=dumb |
-```bash
-./printing-press generate \
- --spec https://api1.example.com/openapi.json \
- --spec https://api2.example.com/openapi.json \
- --name combined-cli
-```
+Plus: doctor health check, shell completions, TOML config, OAuth2 browser flow, retry with backoff, rate limit detection, typed exit codes with actionable hints, idempotent creates/deletes.
-Auth configuration is taken from the first spec that defines OAuth2.
+## Agent-Native by Default
-### Supported Formats
+Every generated CLI is designed for AI agents:
-- **OpenAPI 3.0+** (YAML or JSON)
-- **Swagger 2.0** (YAML or JSON)
-- **Internal YAML** (hand-written, simpler schema)
+- **Non-interactive** - never prompts, every input is a flag
+- **Pipeable** - stdout is data, stderr is errors
+- **Filterable** - `--select id,name` returns only fields you need
+- **Previewable** - `--dry-run` shows the request without sending
+- **Retryable** - creates return "already exists" on retry, deletes return "already deleted"
+- **Piped input** - `echo '{"key":"value"}' | mycli create --stdin`
+- **Cacheable** - GET responses cached, bypass with `--no-cache`
-Auto-detection reads the first 500 bytes and routes to the correct parser.
+Exit codes: `0` success, `2` usage, `3` not found, `4` auth, `5` API error, `7` rate limited, `10` config error.
-## Autonomous Pipeline
+## Scorecard
-For complex APIs, the press doesn't just generate - it thinks.
+The press scores every generated CLI against the Steinberger bar (Peter Steinberger's gogcli at 6.5K stars is the 10/10 benchmark):
```bash
-./printing-press print gmail
-```
-
-```
-Pipeline created for gmail
- Spec: https://gmail.googleapis.com/$discovery/rest?version=v1
- Output: ./gmail-cli
- Plans:
- 0. docs/plans/gmail-pipeline/00-preflight-plan.md
- 1. docs/plans/gmail-pipeline/01-scaffold-plan.md
- 2. docs/plans/gmail-pipeline/02-enrich-plan.md
- 3. docs/plans/gmail-pipeline/03-regenerate-plan.md
- 4. docs/plans/gmail-pipeline/04-review-plan.md
- 5. docs/plans/gmail-pipeline/05-ship-plan.md
-```
-
-This kicks off a 6-phase autonomous pipeline. Each phase runs in a fresh AI session, chains automatically, and tracks state across sessions:
-
-| Phase | What Happens |
-|-------|-------------|
-| Preflight | Verify Go installed, download spec, cache project conventions |
-| Scaffold | Generate CLI, pass all 7 quality gates |
-| Enrich | Research API docs, discover missing endpoints, auth flows, pagination patterns |
-| Regenerate | Merge enrichments back into the spec, regenerate with full knowledge |
-| Review | Lint, test, benchmark, fix issues found |
-| Ship | Build, tag, generate release notes |
-
-The pipeline uses [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) for planning and execution. Each phase produces a plan that gets expanded with parallel research agents, then executed with full test coverage.
-
-Budget gate stops at 3 hours. Heartbeat safety net resumes if a session dies. Morning report tells you what happened.
-
-### Known APIs
-
-16 APIs are pre-registered and discoverable by name:
-
-| API | Spec Format |
-|-----|-------------|
-| Petstore | OpenAPI 3.0 |
-| Stripe | OpenAPI 3.0 |
-| Square | OpenAPI 3.0 |
-| Stytch | OpenAPI 3.0 |
-| Discord | OpenAPI 3.1 |
-| Twilio | OpenAPI 3.0 |
-| SendGrid | OpenAPI 3.0 |
-| GitHub | OpenAPI 3.0 |
-| DigitalOcean | OpenAPI 3.0 |
-| Asana | OpenAPI 3.0 |
-| HubSpot | OpenAPI 3.0 |
-| Front | OpenAPI 3.0 |
-
-Unknown APIs fall back to the [apis-guru](https://apis.guru/) directory.
-
-## Claude Code Plugin
-
+FULL_RUN=1 go test ./internal/pipeline/ -run TestFullRun -v -timeout 10m
```
-/plugin marketplace add mvanhorn/cli-printing-press
-```
-
-Then just say what you want:
```
-/printing-press Stripe payments API
-/printing-press Discord bot management
-/printing-press --spec ./openapi.yaml
-/printing-press print gmail
+Metric | petstore (EASY) | plaid (MEDIUM) | notion (HARD)
+-------------------------|-------------------|-------------------|------------------
+Quality Gates | 7/7 PASS | 7/7 PASS | 7/7 PASS
+Commands | 8 | 51 | 6
+Steinberger Total | 67/80 (83%) | 69/80 (86%) | 67/80 (83%)
+Grade | A | A | A
```
-The skill finds the spec (or writes one from API docs), generates the CLI, and presents the result.
+8 dimensions scored: output modes, auth, error handling, terminal UX, README, doctor, agent-native, local cache. The scorecard auto-generates fix plans for any dimension below 5/10.
-### Catalog Skill
+## Intelligence Engine
-Browse and install pre-built CLIs:
+The press doesn't just generate - it thinks:
-```
-/printing-press-catalog
-/printing-press-catalog search payments
-/printing-press-catalog install stripe
-```
+- **Research phase** - discovers competing CLIs, analyzes their GitHub repos (issues, README, PRs), identifies what they're missing
+- **Competitor intelligence** - reads competitor READMEs to extract command lists, feature requests, pain points
+- **Doc-to-spec** - when no OpenAPI spec exists, reads API docs and generates a YAML spec (regex fallback if no LLM)
+- **Dynamic planning** - each pipeline phase writes the next phase's plan using what it learned
+- **Learning system** - remembers issues from past runs, auto-suggests fixes for future runs
+- **Self-improvement** - scorecard gaps auto-generate fix plans for the press templates
## Catalog
-12 pre-built CLI definitions for popular APIs:
-
-| API | Category | Spec Format |
-|-----|----------|-------------|
-| Stripe | Payments | OpenAPI 3.0 |
-| Square | Payments | OpenAPI 3.0 |
-| Stytch | Auth | OpenAPI 3.0 |
-| Discord | Communication | OpenAPI 3.1 |
-| Twilio | Communication | OpenAPI 3.0 |
-| SendGrid | Email | OpenAPI 3.0 |
-| GitHub | Developer Tools | OpenAPI 3.0 |
-| DigitalOcean | Developer Tools | OpenAPI 3.0 |
-| Asana | Project Management | OpenAPI 3.0 |
-| HubSpot | CRM | OpenAPI 3.0 |
-| Front | Communication | OpenAPI 3.0 |
-| Petstore | Example | OpenAPI 3.0 |
-
-## Quality Gates
-
-Every generated CLI must pass 7 gates before the press considers it done:
-
-| Gate | What It Checks |
-|------|---------------|
-| `go mod tidy` | Clean, minimal dependencies |
-| `go vet ./...` | Static analysis passes |
-| `go build ./...` | All packages compile |
-| Binary build | Produces a runnable binary |
-| `--help` | Usage renders without crash |
-| `version` | Prints version string |
-| `doctor` | Health check runs |
-
-If any gate fails, the press retries with fixes. If it still fails, it tells you exactly what broke and why.
-
-## Contributing Catalog Entries
-
-1. Generate a CLI from an API spec:
- ```bash
- ./printing-press generate --spec <your-openapi-spec>
- ```
-2. Verify it compiles and passes all 7 gates
-3. Create `catalog/<api-name>.yaml`:
- ```yaml
- name: my-api
- display_name: My API
- description: One-line description
- category: developer-tools
- spec_url: https://example.com/openapi.json
- spec_format: json
- openapi_version: "3.0"
- tier: community
- verified_date: "2026-03-24"
- homepage: https://example.com
- ```
-4. Open a PR - CI validates the entry automatically (schema + URL accessibility + full generate + compile)
-
-Or use the skill: `/printing-press submit <name>`
+18 APIs pre-registered with verified spec URLs:
+
+| API | Category | Known Competitors |
+|-----|----------|------------------|
+| Plaid | Payments | plaid-cli (57 stars, abandoned) |
+| Pipedrive | CRM | None |
+| Stripe | Payments | stripe-cli (official) |
+| GitHub | Developer Tools | gh (official) |
+| Telegram | Communication | telegram-bot-api |
+| Square | Payments | square-cli (3 stars) |
+| Sentry | Developer Tools | sentry-cli (official) |
+| LaunchDarkly | Developer Tools | ldcli (official) |
+| + 10 more | Various | See catalog/ |
+
+## Project Structure
+
+```
+cmd/printing-press/ CLI entry point
+internal/
+ catalog/ Catalog schema validator
+ cli/ CLI commands (generate, print, version)
+ docspec/ Doc-to-spec generator (regex + LLM)
+ generator/ Template engine + quality gates (14 templates)
+ llm/ Shared LLM runner (claude/codex CLI)
+ llmpolish/ LLM polish pass (help, examples, README)
+ openapi/ OpenAPI 3.0 parser (strict + lenient modes)
+ pipeline/ Intelligence engine (research, scorecard, dogfood,
+ comparative, learnings, planner, self-improve)
+ spec/ Internal YAML spec parser
+catalog/ 18 API catalog entries
+skills/ Claude Code skill definitions
+```
## Development
```bash
-# Build
go build -o ./printing-press ./cmd/printing-press
-
-# Run tests
-go test ./...
-
-# Generate from internal YAML spec
-./printing-press generate --spec testdata/stytch.yaml
-
-# Generate from OpenAPI spec
-./printing-press generate --spec testdata/openapi/petstore.yaml
-
-# Generate from URL
-./printing-press generate --spec https://petstore3.swagger.io/api/v3/openapi.json
-
-# Initialize a pipeline
-./printing-press print petstore
+go test ./... # 107 tests across 9 packages
+FULL_RUN=1 go test ./internal/pipeline/ -run TestFullRun -v -timeout 10m # full scorecard
```
## License
← a1e7af4e feat(llm): add LLM brain before generation - the press under
·
back to Cli Printing Press
·
feat(templates): add --human-friendly flag and NDJSON pagina c266b6fb →