Skip to content

Commit 08c2bbe

Browse files
ericzakariassonericzakariasson
authored
Merge pull request #42 from cursor/add-cli-for-agent-plugin
Add cli-for-agent plugin
2 parents 3b0296e + 26a1497 commit 08c2bbe

File tree

6 files changed

+155
-0
lines changed

6 files changed

+155
-0
lines changed

‎.cursor-plugin/marketplace.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,11 @@
3737
"name": "agent-compatibility",
3838
"source": "agent-compatibility",
3939
"description": "CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality."
40+
},
41+
{
42+
"name": "cli-for-agent",
43+
"source": "cli-for-agent",
44+
"description": "Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run."
4045
}
4146
]
4247
}

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc
1010
| `cursor-team-kit` | [Cursor Team Kit](cursor-team-kit/) | Cursor | Developer Tools | Internal team workflows used by Cursor developers for CI, code review, and shipping. |
1111
| `create-plugin` | [Create Plugin](create-plugin/) | Cursor | Developer Tools | Scaffold and validate new Cursor plugins. |
1212
| `agent-compatibility` | [Agent Compatibility](agent-compatibility/) | Cursor | Developer Tools | CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality. |
13+
| `cli-for-agent` | [CLI for Agents](cli-for-agent/) | Cursor | Developer Tools | Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run. |
1314

1415
Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest).
1516

‎cli-for-agent/.cursor-plugin/plugin.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "cli-for-agent",
3+
"displayName": "CLI for Agents",
4+
"version": "1.0.0",
5+
"description": "Patterns for designing CLIs that coding agents can run reliably: non-interactive flags, layered help with examples, pipelines, actionable errors, idempotency, and dry-run.",
6+
"author": {
7+
"name": "Cursor",
8+
"email": "plugins@cursor.com"
9+
},
10+
"homepage": "https://github.com/cursor/plugins/tree/main/cli-for-agent",
11+
"repository": "https://github.com/cursor/plugins",
12+
"license": "MIT",
13+
"keywords": [
14+
"cli",
15+
"command-line",
16+
"agents",
17+
"automation",
18+
"terminal",
19+
"flags",
20+
"help"
21+
],
22+
"category": "developer-tools",
23+
"tags": [
24+
"cli",
25+
"agents",
26+
"automation",
27+
"developer-tools"
28+
],
29+
"skills": "./skills/"
30+
}

‎cli-for-agent/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 Cursor
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.

‎cli-for-agent/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# CLI for Agents
2+
3+
Cursor plugin with a single skill that encodes patterns for **CLIs meant to be driven by coding agents**: non-interactive flags first, layered `--help` with examples, stdin and pipelines, fast actionable errors, idempotency, `--dry-run`, and predictable command structure.
4+
5+
## What it includes
6+
7+
- `cli-for-agents`: design and review guidance for agent-friendly command-line tools
8+
9+
## When to use it
10+
11+
Use when you are building or refactoring a CLI, writing subcommand help, or reviewing whether an existing tool will block agents (interactive prompts, missing examples, ambiguous errors).

‎cli-for-agent/skills/cli-for-agents/SKILL.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
name: cli-for-agents
3+
description: >-
4+
Designs or reviews CLIs so coding agents can run them reliably: non-interactive
5+
flags, layered --help with examples, stdin/pipelines, fast actionable errors,
6+
idempotency, dry-run, and predictable structure. Use when building a CLI,
7+
adding commands, writing --help, or when the user mentions agents, terminals,
8+
or automation-friendly CLIs.
9+
---
10+
11+
# CLI for agents
12+
13+
Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, and help text without copy-pasteable examples. Prefer patterns that work headlessly and compose in pipelines.
14+
15+
## Non-interactive first
16+
17+
- Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts.
18+
- If flags are missing, **then** fall back to interactive mode—not the other way around.
19+
20+
**Bad:** `mycli deploy` → `? Which environment? (use arrow keys)`
21+
**Good:** `mycli deploy --env staging`
22+
23+
## Discoverability without dumping context
24+
25+
- Agents discover subcommands incrementally: `mycli`, then `mycli deploy --help`. Do not print the entire manual on every run.
26+
- Let each subcommand own its documentation so unused commands stay out of context.
27+
28+
## `--help` that works
29+
30+
- Every subcommand has `--help`.
31+
- Every `--help` includes **Examples** with real invocations. Examples do more than prose for pattern-matching.
32+
33+
```text
34+
Options:
35+
--env Target environment (staging, production)
36+
--tag Image tag (default: latest)
37+
--force Skip confirmation
38+
39+
Examples:
40+
mycli deploy --env staging
41+
mycli deploy --env production --tag v1.2.3
42+
mycli deploy --env staging --force
43+
```
44+
45+
## stdin, flags, and pipelines
46+
47+
- Accept stdin where it makes sense (e.g. `cat config.json | mycli config import --stdin`).
48+
- Avoid odd positional ordering and avoid falling back to interactive prompts for missing values.
49+
- Support chaining: `mycli deploy --env staging --tag $(mycli build --output tag-only)`.
50+
51+
## Fail fast with actionable errors
52+
53+
- On missing required flags: exit immediately with a clear message and a **correct example invocation**, not a hang.
54+
55+
```text
56+
Error: No image tag specified.
57+
mycli deploy --env staging --tag <image-tag>
58+
Available tags: mycli build list --output tags
59+
```
60+
61+
## Idempotency
62+
63+
- Agents retry often. The same successful command run twice should be safe (no-op or explicit "already done"), not duplicate side effects.
64+
65+
## Destructive actions
66+
67+
- Add `--dry-run` (or equivalent) so agents can preview plans before committing.
68+
- Offer `--yes` / `--force` to skip confirmations while keeping the safe default for humans.
69+
70+
## Predictable structure
71+
72+
- Use a consistent pattern everywhere, e.g. `resource` + `verb`: if `mycli service list` exists, `mycli deploy list` and `mycli config list` should follow the same shape.
73+
74+
## Success output
75+
76+
- On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; avoid relying on decorative output alone.
77+
78+
```text
79+
deployed v1.2.3 to staging
80+
url: https://staging.myapp.com
81+
deploy_id: dep_abc123
82+
duration: 34s
83+
```
84+
85+
## When reviewing an existing CLI
86+
87+
- Check: non-interactive path, layered help, examples on `--help`, stdin/pipeline story, error messages with invocations, idempotency, dry-run, confirmation bypass flags, consistent command structure, structured success output.

0 commit comments

Comments
 (0)