ok
This commit is contained in:
ray zhou
@@ -0,0 +1,30 @@
|
||||
{
|
||||
"name": "cli-for-agent",
|
||||
"displayName": "CLI for Agents",
|
||||
"version": "1.0.0",
|
||||
"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.",
|
||||
"author": {
|
||||
"name": "Cursor",
|
||||
"email": "plugins@cursor.com"
|
||||
},
|
||||
"homepage": "https://github.com/cursor/plugins/tree/main/cli-for-agent",
|
||||
"repository": "https://github.com/cursor/plugins",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"cli",
|
||||
"command-line",
|
||||
"agents",
|
||||
"automation",
|
||||
"terminal",
|
||||
"flags",
|
||||
"help"
|
||||
],
|
||||
"category": "developer-tools",
|
||||
"tags": [
|
||||
"cli",
|
||||
"agents",
|
||||
"automation",
|
||||
"developer-tools"
|
||||
],
|
||||
"skills": "./skills/"
|
||||
}
|
||||
21
plugins/cache/cursor-public/cli-for-agent/e46364b8be46000b7df0f260550cd712afbb8d36/LICENSE
vendored
Normal file
21
plugins/cache/cursor-public/cli-for-agent/e46364b8be46000b7df0f260550cd712afbb8d36/LICENSE
vendored
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Cursor
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
11
plugins/cache/cursor-public/cli-for-agent/e46364b8be46000b7df0f260550cd712afbb8d36/README.md
vendored
Normal file
11
plugins/cache/cursor-public/cli-for-agent/e46364b8be46000b7df0f260550cd712afbb8d36/README.md
vendored
Normal file
@@ -0,0 +1,11 @@
|
||||
# CLI for Agents
|
||||
|
||||
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.
|
||||
|
||||
## What it includes
|
||||
|
||||
- `cli-for-agents`: design and review guidance for agent-friendly command-line tools
|
||||
|
||||
## When to use it
|
||||
|
||||
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).
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
name: cli-for-agents
|
||||
description: >-
|
||||
Designs or reviews CLIs so coding agents can run them reliably: non-interactive
|
||||
flags, layered --help with examples, stdin/pipelines, fast actionable errors,
|
||||
idempotency, dry-run, and predictable structure. Use when building a CLI,
|
||||
adding commands, writing --help, or when the user mentions agents, terminals,
|
||||
or automation-friendly CLIs.
|
||||
---
|
||||
|
||||
# CLI for agents
|
||||
|
||||
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.
|
||||
|
||||
## Non-interactive first
|
||||
|
||||
- Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts.
|
||||
- If flags are missing, **then** fall back to interactive mode—not the other way around.
|
||||
|
||||
**Bad:** `mycli deploy` → `? Which environment? (use arrow keys)`
|
||||
**Good:** `mycli deploy --env staging`
|
||||
|
||||
## Discoverability without dumping context
|
||||
|
||||
- Agents discover subcommands incrementally: `mycli`, then `mycli deploy --help`. Do not print the entire manual on every run.
|
||||
- Let each subcommand own its documentation so unused commands stay out of context.
|
||||
|
||||
## `--help` that works
|
||||
|
||||
- Every subcommand has `--help`.
|
||||
- Every `--help` includes **Examples** with real invocations. Examples do more than prose for pattern-matching.
|
||||
|
||||
```text
|
||||
Options:
|
||||
--env Target environment (staging, production)
|
||||
--tag Image tag (default: latest)
|
||||
--force Skip confirmation
|
||||
|
||||
Examples:
|
||||
mycli deploy --env staging
|
||||
mycli deploy --env production --tag v1.2.3
|
||||
mycli deploy --env staging --force
|
||||
```
|
||||
|
||||
## stdin, flags, and pipelines
|
||||
|
||||
- Accept stdin where it makes sense (e.g. `cat config.json | mycli config import --stdin`).
|
||||
- Avoid odd positional ordering and avoid falling back to interactive prompts for missing values.
|
||||
- Support chaining: `mycli deploy --env staging --tag $(mycli build --output tag-only)`.
|
||||
|
||||
## Fail fast with actionable errors
|
||||
|
||||
- On missing required flags: exit immediately with a clear message and a **correct example invocation**, not a hang.
|
||||
|
||||
```text
|
||||
Error: No image tag specified.
|
||||
mycli deploy --env staging --tag <image-tag>
|
||||
Available tags: mycli build list --output tags
|
||||
```
|
||||
|
||||
## Idempotency
|
||||
|
||||
- Agents retry often. The same successful command run twice should be safe (no-op or explicit "already done"), not duplicate side effects.
|
||||
|
||||
## Destructive actions
|
||||
|
||||
- Add `--dry-run` (or equivalent) so agents can preview plans before committing.
|
||||
- Offer `--yes` / `--force` to skip confirmations while keeping the safe default for humans.
|
||||
|
||||
## Predictable structure
|
||||
|
||||
- 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.
|
||||
|
||||
## Success output
|
||||
|
||||
- On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; avoid relying on decorative output alone.
|
||||
|
||||
```text
|
||||
deployed v1.2.3 to staging
|
||||
url: https://staging.myapp.com
|
||||
deploy_id: dep_abc123
|
||||
duration: 34s
|
||||
```
|
||||
|
||||
## When reviewing an existing CLI
|
||||
|
||||
- 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.
|
||||
Reference in New Issue
Block a user