docs(cli): add Cursor guide for printed CLIs (#833)

f34645a80456a6353ba83d22f49c603bc899632f · 2026-05-09 15:12:46 -0500 · Giuliano Pezzolo Giacaglia

* Add Cursor + Linear setup doc

Link from README. Covers Security & access API keys, env vs
auth set-token, and the library CURSOR guide.

* Use auth set-api-key for Linear personal keys

* Generalize Cursor doc for any printed CLI

Replace Linear-specific cursor-linear.md with docs/cursor.md: install,
skills, auth, agent usage, CLI vs MCP, and per-CLI README/CURSOR notes.
Point README at the new guide.

* docs(cli): clarify downstream AGENTS.md vs Press commits

Cursor guide now tells agents to follow the workspace repo AGENTS.md for
commits and points readers at this repo's Conventional Commit rules when
contributing to the generator.

* chore(ci): retrigger checks after semantic PR title

* docs(cli): name Cursor guide docs/CURSOR.md

Match ALL_CAPS convention under docs/. List CURSOR.md in DOCS.md; fix README link.

---------

Co-authored-by: Giuliano Pezzolo Giacaglia <giuliano@MacBook-Pro.local>

Files touched

M README.md
A docs/CURSOR.md
M docs/DOCS.md

Diff

commit f34645a80456a6353ba83d22f49c603bc899632f
Author: Giuliano Pezzolo Giacaglia <raulzito234@gmail.com>
Date:   Sat May 9 15:12:46 2026 -0500

    docs(cli): add Cursor guide for printed CLIs (#833)
    
    * Add Cursor + Linear setup doc
    
    Link from README. Covers Security & access API keys, env vs
    auth set-token, and the library CURSOR guide.
    
    * Use auth set-api-key for Linear personal keys
    
    * Generalize Cursor doc for any printed CLI
    
    Replace Linear-specific cursor-linear.md with docs/cursor.md: install,
    skills, auth, agent usage, CLI vs MCP, and per-CLI README/CURSOR notes.
    Point README at the new guide.
    
    * docs(cli): clarify downstream AGENTS.md vs Press commits
    
    Cursor guide now tells agents to follow the workspace repo AGENTS.md for
    commits and points readers at this repo's Conventional Commit rules when
    contributing to the generator.
    
    * chore(ci): retrigger checks after semantic PR title
    
    * docs(cli): name Cursor guide docs/CURSOR.md
    
    Match ALL_CAPS convention under docs/. List CURSOR.md in DOCS.md; fix README link.
    
    ---------
    
    Co-authored-by: Giuliano Pezzolo Giacaglia <giuliano@MacBook-Pro.local>
---
 README.md      |  2 ++
 docs/CURSOR.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/DOCS.md   |  1 +
 3 files changed, 62 insertions(+)

diff --git a/README.md b/README.md
index 1d5f1f53..dfe47273 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ Three CLIs printed by the press, installable today:
 
 Browse the full catalog of printed CLIs at [printingpress.dev](https://printingpress.dev) or in the [Printing Press Library](https://github.com/mvanhorn/printing-press-library), organized by category, most with full MCP servers.
 
+**Cursor users:** see [docs/CURSOR.md](docs/CURSOR.md) for how to install a printed CLI, attach the matching skill, handle auth, and choose CLI vs MCP when your repo does not already document a workflow.
+
 ## Install
 
 You need both the **binary** and the **Claude Code skills**. The skills (`/printing-press <app>`) are the primary interface; they drive the binary behind the scenes.
diff --git a/docs/CURSOR.md b/docs/CURSOR.md
new file mode 100644
index 00000000..f6d86258
--- /dev/null
+++ b/docs/CURSOR.md
@@ -0,0 +1,59 @@
+# Using Printing Press CLIs in Cursor
+
+This repo ships **skills** (Markdown playbooks) and generated **`<api>-pp-cli`** binaries. Cursor agents invoke the CLI from the terminal (or you can wire the matching **`<api>-pp-mcp`** server in MCP settings). Use this page when your project does not already document a Cursor-specific flow.
+
+## 1. Install the CLI
+
+Pick one:
+
+- **Installer (skills + binary):** `npx -y @mvanhorn/printing-press install pp-<slug>`  
+  Replace `<slug>` with the catalog slug (for example the skill name without the `pp-` prefix when it matches the published package).
+
+- **Go toolchain:** from the [Printing Press Library](https://github.com/mvanhorn/printing-press-library), each CLI documents `go install …` on its README.
+
+Confirm the binary is on `PATH` (`which <cli>` or `<cli> --version`). Many CLIs also support `<cli> doctor` for a quick health check.
+
+## 2. Add the skill to Cursor
+
+Published mirrors live under [`cli-skills/`](https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills) in the library repo (`pp-<slug>/SKILL.md`). Copy the `SKILL.md` you need into your workspace where Cursor loads skills (for example `.cursor/skills/<skill-name>/SKILL.md`), or install skills globally the way your team already does for other plugins.
+
+The skill describes **when** to use the CLI, **which flags** matter (`--agent`, `--json`, `--data-source`, etc.), and **auth** expectations.
+
+## 3. Authentication
+
+Auth is **per API**. Open the matching library README:
+
+`https://github.com/mvanhorn/printing-press-library/tree/main/library/<category>/<slug>/README.md`
+
+Typical patterns:
+
+- Environment variables (for example `*_API_KEY`)
+- `auth` subcommands on the CLI, if generated
+- Optional **MCP** wiring with the same secrets documented on the README
+
+Never commit secrets; use env vars or your OS secret store.
+
+## 4. Running commands from the agent
+
+- Prefer following the **skill** step-by-step.
+- For ad-hoc use, run the CLI in Cursor’s terminal. Agent-friendly defaults are usually behind `--agent` (often implies `--json --no-input --no-color --yes`).
+- Rely on **typed exit codes** (`4` = auth, `5` = API, `7` = rate limit) so the agent can retry or fix configuration.
+
+## 5. CLI vs MCP in Cursor
+
+The press generates **both** a Cobra CLI and an MCP server from the same spec. Shell-based flows (skills + terminal) usually spend **fewer context tokens** than loading a large MCP tool surface; MCP is convenient when you want IDE-native tool discovery. See [Why CLIs plus MCP](../README.md#why-clis-plus-mcp) in the main README.
+
+## 6. Per-CLI extras
+
+Some library packages add a **`CURSOR.md`** or extra notes next to `README.md`. If present, it lives beside the CLI under `library/<category>/<slug>/` in the Printing Press Library.
+
+## 7. Commit and PR style in *your* repo (not the Press)
+
+Skills and CLIs from this ecosystem do **not** define how you commit in **your** application monorepo. Always follow the **`AGENTS.md`**, **`CONTRIBUTING.md`**, and Cursor rules **in the repository where you are committing**.
+
+Examples:
+
+- Some organizations use imperative subjects **without** Conventional Commits (`feat:`, `fix:` prefixes are disallowed). Their root **`AGENTS.md`** states that explicitly.
+- **This** repository (`mvanhorn/cli-printing-press`) uses **required** Conventional Commits with a fixed scope list; see [AGENTS.md](../AGENTS.md#commit-style) here before contributing to the generator.
+
+If your workspace has no `AGENTS.md` yet, add one that matches your team’s policy so agents and humans do not assume the wrong commit format.
diff --git a/docs/DOCS.md b/docs/DOCS.md
index f8c6259a..23590462 100644
--- a/docs/DOCS.md
+++ b/docs/DOCS.md
@@ -24,4 +24,5 @@ The extracted developer docs are:
 - `docs/RELEASE.md` — release-please / goreleaser flow
 - `docs/CATALOG.md` — catalog validator rationale and wrapper-only shape
 - `docs/ARTIFACTS.md` — local library, manuscripts, and public-library flow
+- `docs/CURSOR.md` — using printed CLIs and skills in Cursor
 - `docs/DOCS.md` — this doc-authoring guidance

← 2d9a304a fix(cli): preserve manifest fields during dogfood sync (#844 · back to Cli Printing Press · fix(cli): default Surf browser transport to h2 (#850) 9f2a4efe →