# Cómo usar Cursor CLI: guía paso a paso

URL: https://agentvera.dev/es/blog/how-to-use-cursor-cli/ · Publicado: 2026-10-29

Cómo usar Cursor CLI: instala el comando agent, inicia sesión, cambia entre los modos Agent, Plan y Ask, automatiza con print mode y configura modelos, reglas y MCP.

**En resumen:**

- Instala Cursor CLI con un comando curl (en Windows, con una línea de PowerShell), inicia sesión con agent login y ejecuta agent en tu proyecto. El nombre antiguo, cursor-agent, sigue funcionando como alias.
- agent abre una sesión interactiva con los modos Agent, Plan y Ask. agent -p ejecuta una sola tarea para scripts y CI; añade --force para que aplique los cambios y --output-format json para salida legible por máquina.
- La CLI usa el cupo de uso de tu plan de Cursor, las mismas reglas que el editor (.cursor/rules, AGENTS.md, CLAUDE.md) y el mismo mcp.json, así que tu configuración de Cursor viene contigo.

Para usar Cursor CLI, instálala con `curl https://cursor.com/install -fsS | bash`, inicia sesión con `agent login`, entra en la carpeta de un proyecto y ejecuta `agent`. Describes una tarea y el agente de Cursor lee tu código, edita archivos y ejecuta comandos después de que los apruebes. Para scripts y CI, `agent -p "tu tarea"` ejecuta un solo prompt sin la interfaz interactiva.

Ese es el ciclo básico. Esta guía cubre el resto: los tres modos, el print mode, los modelos, los archivos de reglas, los servidores MCP, los permisos, cómo consume la CLI el uso de tu plan de Cursor, sus límites y cómo usarla junto a otras CLI de programación. Todo lo que hay aquí se basa en la documentación oficial de Cursor a octubre de 2026.

## Qué es Cursor CLI

Cursor CLI lleva el agente del editor de Cursor a tu terminal. Usa la misma cuenta, los mismos modelos, las mismas reglas y la misma configuración MCP que el editor, así que si tu equipo ya usa Cursor, la CLI se comporta como todos esperan. Funciona en cualquier sitio donde haya un terminal: un servidor al que entras por SSH, un runner de CI o un panel junto a otro agente.

Una nota sobre el nombre: el comando se llamaba `cursor-agent`. En enero de 2026 Cursor convirtió `agent` en el comando principal, y `cursor-agent` sigue funcionando como alias. Las guías y herramientas antiguas que llaman a `cursor-agent` no se rompen; esta guía usa `agent`.

Si aún dudas entre Cursor y un agente pensado para el terminal, [Claude Code vs Cursor](/es/blog/claude-code-vs-cursor/ "Claude Code vs Cursor") compara los dos. Este artículo da por hecho que elegiste Cursor y quieres usarlo desde el terminal.

## Paso 1: instala Cursor CLI

| Plataforma | Comando |
| --- | --- |
| macOS, Linux, WSL | `curl https://cursor.com/install -fsS \| bash` |
| Windows (PowerShell) | `irm 'https://cursor.com/install?win32=true' \| iex` |

Comprueba la instalación:

```bash
agent --version
```

Si tu shell no encuentra `agent`, añade `~/.local/bin` a tu `PATH` y abre un terminal nuevo. La CLI se actualiza sola por defecto; para hacerlo a mano basta con `agent update`.

## Paso 2: inicia sesión

```bash
agent login     # abre el navegador
agent status    # muestra con qué cuenta has iniciado sesión
agent logout
```

En una máquina sin navegador, define `NO_OPEN_BROWSER=1` y `agent login` mostrará la URL en lugar de abrirla. Para CI y scripts, crea una clave de API en el panel de Cursor, en API Keys, y pásala con la variable de entorno `CURSOR_API_KEY` o con `--api-key`.

## Paso 3: la sesión interactiva

Arranca el agente en un proyecto, con o sin un primer prompt:

```bash
cd my-project
agent
agent "add input validation to the signup form"
```

La CLI tiene tres modos y Shift+Tab alterna entre ellos:

| Modo | Qué hace | Cómo cambiar |
| --- | --- | --- |
| Agent | El predeterminado. Edita archivos y ejecuta comandos. | Predeterminado |
| Plan | Define contigo el enfoque antes de tocar el código. | Shift+Tab, `/plan`, `--plan` o `--mode=plan` |
| Ask | Solo lectura. Explora el código y responde preguntas. | `/ask` o `--mode=ask` |

Un buen hábito para cualquier cosa no trivial: empieza en Plan, acordad el enfoque y luego pasa a Agent para que lo implemente. Algunas cosas más que usarás a diario:

- **`@`** elige archivos para adjuntar a tu mensaje.
- **Ctrl+R** te deja revisar los cambios que hizo el agente.
- **Shift+Enter** (o Ctrl+J) añade un salto de línea; **flecha arriba** recorre tus mensajes anteriores.
- **Los comandos de shell** esperan un y/n antes de ejecutarse.
- **`/model`** cambia de modelo; **`/clear`** empieza un chat nuevo; **`/summarize`** resume un chat largo.
- **Ctrl+D dos veces** sale.

Los chats se guardan. `agent ls` los lista, `agent resume` (o `--continue`) vuelve al último y `--resume="chat-id"` abre uno concreto. Dentro de la sesión, `/resume`, `/fork` y `/rewind` hacen lo que su nombre indica.

Hay dos extras que vale la pena conocer. Si empiezas un mensaje con `&`, la conversación pasa a un Cursor Cloud Agent que sigue trabajando mientras no estás, y la retomas en cursor.com/agents. Y `-w` (o `--worktree nombre`) ejecuta el agente en un nuevo worktree de Git dentro de `~/.cursor/worktrees/`, así que tu copia de trabajo actual no se toca.

## Paso 4: print mode para scripts y CI

El print mode ejecuta un solo prompt y termina. Eso te permite usar la CLI desde scripts, hooks de Git y pipelines de CI:

```bash
# Una pregunta de solo lectura, respuesta en texto plano
agent -p "summarize what changed in src/billing since the last release"

# Aplicar cambios (sin --force solo se proponen)
agent -p --force "add JSDoc comments to every exported function in src/utils"

# Salida legible por máquina para otra herramienta
agent -p --output-format json "list the TODO comments in this repo"
```

Los flags que importan aquí:

- **`--force`** (alias `--yolo`) deja que el agente escriba archivos y ejecute comandos sin preguntar, salvo que una regla de denegación lo bloquee. Es el interruptor que hace que el print mode cambie algo de verdad.
- **`--output-format`** acepta `text` (predeterminado), `json` o `stream-json`. Combina `stream-json` con `--stream-partial-output` para recibir el texto a medida que se genera.
- **`--trust`** confía en el espacio de trabajo sin preguntar; **`--approve-mcps`** aprueba los servidores MCP configurados.
- **`--model`** y **`--workspace`** fijan el modelo y la carpeta.

Cursor también documenta cómo ejecutar la CLI en GitHub Actions. Si usas `--force` en CI, trátalo como cualquier agente desatendido: una clave de API con alcance limitado, un runner desechable y cambios que llegan a una rama para revisarlos.

## Paso 5: elige un modelo

```bash
agent models                   # modelos que tu cuenta puede usar
agent --model <model-id>       # empezar con un modelo concreto
```

Dentro de la sesión, `/model` abre el selector y `/model grok` filtra la lista. Si no indicas un modelo, la CLI usa el configurado en tu cuenta. Los modelos que ves dependen de tu plan (mira la sección de precios más abajo): todos los planes de pago incluyen los modelos propios de Cursor, mientras que los de terceros requieren Premium o superior.

## Paso 6: reglas, AGENTS.md y CLAUDE.md

Cursor CLI usa el mismo sistema de reglas que el editor. Las reglas viven en `.cursor/rules`, y la CLI también lee `AGENTS.md` y `CLAUDE.md` en la raíz del proyecto y los aplica como reglas. Desde la versión de octubre de 2026, los `AGENTS.md` de subcarpetas se aplican cuando el agente edita archivos dentro de esas carpetas.

```markdown
# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- Never edit files in src/generated/.
```

Si varios agentes trabajan en el mismo repo, `AGENTS.md` es el archivo que todos leen, así que es el sitio adecuado para las reglas compartidas. `agent generate-rule` crea una regla nueva de Cursor de forma interactiva. Qué conviene poner en estos archivos lo explica [Cómo escribir CLAUDE.md y AGENTS.md](/es/blog/claude-md-agents-md/ "Cómo escribir CLAUDE.md y AGENTS.md").

## Paso 7: servidores MCP

Los [servidores MCP](/es/blog/what-is-mcp-server/ "Qué es un servidor MCP") dan nuevas herramientas al agente: un navegador, un gestor de incidencias, una base de datos. Cursor CLI lee el mismo `mcp.json` que el editor: `.cursor/mcp.json` para el proyecto y `~/.cursor/mcp.json` para todos. Lo que configuraste en el editor ya está disponible en la CLI.

```bash
agent mcp list                 # servidores configurados y su estado
agent mcp list-tools <id>      # herramientas que ofrece un servidor
agent mcp login <id>           # iniciar sesión en un servidor con OAuth
agent mcp disable <id>         # desactivarlo sin quitarlo
```

Dentro de la sesión, `/mcp list` muestra lo mismo. Cada servidor añade sus herramientas al contexto del agente, así que deja activados solo los que necesites.

## Paso 8: permisos y configuración

La configuración global está en `~/.cursor/cli-config.json` (en Windows, `%USERPROFILE%\.cursor\cli-config.json`). Un proyecto puede añadir un `.cursor/cli.json` que solo contiene permisos. Ambos son JSON puro, sin comentarios.

```json
{
  "permissions": {
    "allow": ["Shell(git)", "Shell(ls)", "Read(src/**/*.ts)", "Write(package.json)", "Mcp(datadog:*)"],
    "deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)"]
  }
}
```

Cada entrada indica una herramienta y un patrón: `Shell(...)`, `Read(...)`, `Write(...)`, `WebFetch(dominio)` y `Mcp(servidor:herramienta)`. La denegación gana a la autorización. El archivo global también define el modo de aprobación (`allowlist`, `auto-review` o `unrestricted`), los ajustes de sandbox y si los commits llevan una línea “Made with Cursor”.

## Cómo se relaciona Cursor CLI con tu plan de Cursor

No hay una suscripción aparte para la CLI. Usa tu cuenta de Cursor y, a octubre de 2026, Cursor se vende como parte de The X Subscription, junto con Grok y X. Cada plan de pago tiene un único cupo de uso para los modelos propios de Cursor (Grok 4.7, Grok 4.6, Grok 4.5 y Composer 2.5). El editor, la CLI, los Cloud Agents y las apps de Grok consumen de él, y se renueva cada semana.

| Plan | Precio al mes | Uso incluido | Modelos de terceros |
| --- | --- | --- | --- |
| Free | 0 $ | Limitado | No |
| Plus | 8 $ | Base | No |
| Premium | 30 $ | 4 veces Plus | Precio de lista de la API desde crédito prepago |
| Super | 100 $ | 15 veces Plus | Precio de lista de la API desde crédito prepago |
| Ultra | 200 $ | 50 veces Plus | Precio de lista de la API desde crédito prepago |
| Teams | 30, 100 o 200 $ por puesto | Según el nivel del puesto | Precio de lista de la API más la tarifa por token de Cursor |

Lo que esto significa al usar la CLI:

- **Cada modelo consume el cupo a un ritmo distinto.** El uso restante y la próxima renovación aparecen en los ajustes del editor y en el panel de uso.
- **Claude, GPT y Gemini no están en el cupo.** En Premium y superiores los pagas desde la primera petición a precio de lista de la API con crédito prepago. Plus y Free no pueden usarlos.
- **Plus no incluye Cloud Agents ni Auto.** Pasar la conversación a un Cloud Agent con `&` requiere Premium o superior.
- **Los planes antiguos siguen funcionando.** Pro, Pro+, Ultra, Start y los puestos Teams Standard o Premium cuentan como planes heredados y conservan sus dos cupos mensuales y el uso bajo demanda.

## Límites que conviene conocer

- **Shell Mode tiene un tiempo límite de 30 segundos.** `/shell` ejecuta comandos directamente, pero no puede mantener servidores en marcha ni responder a prompts interactivos, y `cd` no se conserva entre comandos.
- **El print mode es prudente por defecto.** Sin `--force` propone los cambios en lugar de escribirlos, algo que sorprende a casi todo el mundo la primera vez.
- **Los archivos de configuración son JSON estricto.** Un comentario o una coma de más en `cli-config.json` lo rompen.
- **Un chat por terminal.** La CLI tiene worktrees y Cloud Agents, pero ninguna vista integrada que muestre varios agentes locales a la vez.

## Errores frecuentes

- **`command not found: agent`.** `~/.local/bin` no está en tu `PATH`.
- **Una herramienta sigue llamando a `cursor-agent`.** No pasa nada, el alias se mantiene. Solo la documentación ha pasado a `agent`.
- **El modelo que quieres no aparece en la lista.** Es un modelo de terceros y tu plan es Free o Plus.
- **Las reglas se ignoran.** Comprueba que `AGENTS.md` o `CLAUDE.md` estén en la raíz del proyecto, o que la regla de `.cursor/rules` se aplique a los archivos que se editan.
- **CI se queda esperando una aprobación.** Añade `--trust`, usa `CURSOR_API_KEY` y pasa `--approve-mcps` si hay servidores MCP configurados.

## Usar Cursor CLI junto a otras CLI

Si tu equipo ya vive en Cursor, Cursor CLI es una buena elección: los mismos modelos, reglas y servidores MCP en el editor y en el terminal. Si buscas puntos de extensión profundos en el terminal, como hooks, skills y plugins, Claude Code es más fuerte en eso. Y si piensas dejar Cursor del todo, [Mejores alternativas a Cursor](/es/blog/best-cursor-alternatives/ "Mejores alternativas a Cursor") repasa las opciones con honestidad.

Mucha gente acaba usando Cursor CLI junto a Claude Code, Codex o Gemini CLI, cada uno en su propia tarea. En terminales sueltos eso significa una pestaña por agente y worktrees con `-w` para mantenerlos separados. AgentVera es una app de escritorio que ejecuta estas CLI lado a lado en terminales reales, con tus propias instalaciones y sesiones. El [soporte de Cursor](/es/agents/cursor-agent/ "Cursor en AgentVera") funciona así:

- **Cada agente tiene su propio chat.** Para cada agente de Cursor nuevo se crea un chat vacío (`cursor-agent create-chat`) y el agente siempre vuelve a él, así que varios agentes de Cursor trabajan en el mismo proyecto sin pisarse. No hace falta tener abierto el editor de Cursor.
- **Tu sesión, tus modelos.** Usa el inicio de sesión propio de Cursor CLI; si dejas el modelo vacío, se usa el de los ajustes de Cursor.
- **Reglas, no prompt de rol.** Cursor CLI no tiene un flag de instrucciones extra, así que el campo Rol del agente no llega a Cursor. Pon las instrucciones permanentes en `AGENTS.md` o en archivos de reglas.
- **MCP desde un solo sitio.** Los servidores MCP que añades en AgentVera y el navegador de AgentVera se añaden como un plugin local y se aprueban para esa ejecución.
- **Cuadrícula, cuentas y servidores.** Ejecuta Cursor en la cuadrícula del [Workspace](/es/features/workspace/ "Workspace") junto a otros agentes, con revisión de código automática al terminar cada turno. En Ajustes → Cuentas puedes poner [varias cuentas de Cursor](/es/features/account-switching/ "Cambio de cuenta") en orden de respaldo, y un agente de Cursor también puede ejecutarse en un servidor SSH guardado.

Para probarlo, [descarga AgentVera](/es/download/ "Descargar AgentVera").

## En resumen

Para usar Cursor CLI, instálala, ejecuta `agent login` y lanza `agent` en un proyecto. Pasa a Plan con Shift+Tab antes de cambios grandes, usa `agent -p --force` en scripts y guarda tus reglas en `AGENTS.md` o `.cursor/rules` y tus herramientas en `mcp.json`. Cuánto uso tienes lo decide tu plan de Cursor, así que elige los modelos pensando en el cupo semanal.

## Preguntas frecuentes

**¿El comando de Cursor CLI es agent o cursor-agent?** Los dos funcionan. A octubre de 2026, agent es el comando principal y cursor-agent se mantiene como alias para scripts y herramientas antiguos. Puedes comprobar la instalación con agent --version.

**¿Cursor CLI es gratis?** Instalar la CLI es gratis y funciona en el plan Free de Cursor con uso limitado. Los planes de pago incluyen un cupo semanal para los modelos propios de Cursor que comparten el editor, la CLI y los Cloud Agents. Los modelos de terceros como Claude, GPT y Gemini requieren Premium o superior y se cobran a precio de lista de la API desde crédito prepago.

**¿Cursor CLI lee AGENTS.md y CLAUDE.md?** Sí. Además de las reglas de .cursor/rules, la CLI lee AGENTS.md y CLAUDE.md en la raíz del proyecto y los aplica como reglas. Los AGENTS.md de subcarpetas se aplican cuando el agente edita archivos dentro de esas carpetas.

**¿Por qué agent -p no cambia mis archivos?** Sin --force (o su alias --yolo), el print mode solo propone los cambios en archivos en lugar de aplicarlos. Usa agent -p --force en scripts que deban escribir archivos, y solo en repos y máquinas donde te parezca bien permitirlo.

**¿Necesito tener el editor de Cursor instalado o abierto?** No. Cursor CLI se instala por separado y funciona por sí sola en cualquier terminal de macOS, Linux, WSL o Windows. Comparte tu cuenta, tus reglas y tu configuración MCP con el editor, pero no necesita que esté abierto.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/