# Cursor Cli

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-ferueda-agent-skills-cursor-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ferueda](https://agentstack.voostack.com/s/ferueda)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ferueda](https://github.com/ferueda)
- **Source:** https://github.com/ferueda/agent-skills/tree/main/skills/cursor-cli

## Install

```sh
agentstack add skill-ferueda-agent-skills-cursor-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cursor CLI (Headless)

Delegate work to a Cursor agent from the shell without the IDE chat. Use when the user wants another agent to **call, ask, invoke, or run Cursor** on a task.

**Global script:** `~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs`  
**Optional launcher:** `cursor-agent`

Requires `agent` on PATH. Local dev: `agent login` once. CI/servers: `CURSOR_API_KEY`.

## When to use

| Situation | Use this |
|-----------|----------|
| User says "call cursor", "ask cursor", "invoke cursor", etc. | `cursor-agent "…"` |
| Already inside Cursor IDE chat | Task tool — not CLI |
| Long-lived typed service | `@cursor/sdk` |

## Quick start

```bash
# Check auth + CLI version
cursor-agent

# Invoke (read-only by default — no file edits)
cursor-agent "explain the backend routing"

# Allow edits
cursor-agent --force "add a regression test for auth"

# Typed JSON response
cursor-agent \
  --schema-json '{"type":"object","required":["verdict"],"properties":{"verdict":{"type":"string"}}}' \
  "Review auth.ts"

# Continue a session
cursor-agent --resume  "follow up"
```

**Caller flow:** parse stdout → check `status` → read `structuredOutput` or `result` → save `sessionId` for `--resume`.

If the launcher is not installed, call the script directly:

```bash
node ~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs "your task"
```

## Output

Default format is **TOON** on stdout (token-efficient). Use `--format json` when debugging.

Success example:

```
status: completed
sessionId: uuid
durationMs: 8783
usageSummary: 45271 in, 76 out
result: truncated answer preview…
help[1]: Run `cursor-agent --resume  "follow up"` to continue
```

With `--schema` / `--schema-json`:

```
status: completed
sessionId: uuid
structuredOutput:
  verdict: pass
  summary: …
```

Errors also go to stdout (not stderr):

```
status: failed
error: prompt is required
help[1]: Run `cursor-agent "your task"` or --prompt-file / --stdin
```

Exit codes: `0` success, `1` error, `2` usage.

### Envelope fields

| Field | When |
|-------|------|
| `status` | `completed`, `failed`, `timed_out` |
| `sessionId` | Resume with `--resume` |
| `result` | Answer text (~800 char preview; use `--full` for all) |
| `structuredOutput` | With `--schema` — validated JSON |
| `error` | Failure message |
| `help` | Suggested next commands |
| `usageSummary` | Token counts when available |

## Flags

| Flag | Purpose |
|------|---------|
| `--force` | Allow file/shell changes (off by default) |
| `--model ` | e.g. `composer-2.5` |
| `--mode plan\|ask` | Read-only modes |
| `--workspace ` | Repo root (default: cwd) |
| `--resume ` | Continue a session |
| `--schema ` | JSON Schema file |
| `--schema-json ''` | Inline schema (mutually exclusive with `--schema`) |
| `--format toon\|json` | Output format (default: toon) |
| `--full` | Untruncated `result` |
| `--verbose` | Include raw `usage` object |
| `--max-runtime-ms ` | Overall wall-clock limit (default: 30 minutes) |
| `--idle-timeout-ms ` | Optional no-output timeout; disabled by default because Cursor may be silent while tools run |
| `--quiet` | Suppress stdout |
| `--prompt-file`, `--stdin` | Prompt input |
| `--sandbox enabled\|disabled` | Sandbox override |

The wrapper always passes `--trust --approve-mcps` to Cursor CLI. Use `--force` only when the delegated agent should edit files or run mutating commands.

## Structured output

Cursor CLI has no native JSON-schema mode. The wrapper injects schema instructions into the prompt, parses JSON from the answer, and validates a basic subset (`type`, `required`, `properties`, `items`, `enum`).

- `--schema` — reusable schema file in the repo
- `--schema-json` — one-off inline schema

On success with a schema, prefer `structuredOutput` over `result`.

## Auth

| Context | What you need |
|---------|----------------|
| Your machine (after `agent login`) | Nothing extra |
| CI / headless server | `CURSOR_API_KEY` |

Verify: `agent status`

## Install globally

Install the skill folder at `~/.agents/skills/cursor-cli`. Node 18+, no npm dependencies.

Optional launcher:

```bash
mkdir -p ~/.local/bin
ln -sf ~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs ~/.local/bin/cursor-agent
chmod +x ~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs
```

Ensure `~/.local/bin` is on `PATH`.

## Raw CLI escape hatch

```bash
agent -p --trust --approve-mcps --workspace . "prompt"
agent -p --force "apply changes"
```

Docs: https://cursor.com/docs/cli

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ferueda](https://github.com/ferueda)
- **Source:** [ferueda/agent-skills](https://github.com/ferueda/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ferueda-agent-skills-cursor-cli
- Seller: https://agentstack.voostack.com/s/ferueda
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.