Instalar Cursor CLI: guía básica

Objetivo

Al terminar vas a tener Cursor CLI instalado, autenticado con tu cuenta de Cursor, y una primera sesión de agente corriendo sobre un proyecto real, tanto en modo interactivo como headless.

Cursor CLI lleva el agente de Cursor a la terminal. Es el mismo acceso a modelos y el mismo comportamiento de agente que en el editor, invocable desde una shell: sesiones interactivas, ejecuciones headless para scripts y CI, modos plan/ask/agent y un sandbox configurable. El binario instalado se llama cursor-agent (la documentación también lo menciona como agent).

Prerrequisitos

macOS, Linux, WSL o Windows (PowerShell).
Una terminal con permisos para instalar binarios en tu PATH.
Una cuenta de Cursor (la CLI comparte tu plan y tu pricing de Cursor).
Un proyecto local sobre el que trabajar.

Esta guía cubre Cursor CLI al estado de septiembre de 2026.

Pasos

1. Instalar el binario

macOS / Linux / WSL:

curl https://cursor.com/install -fsS | bash

Windows (PowerShell):

irm 'https://cursor.com/install?win32=true' | iex

El instalador deja cursor-agent en tu PATH. Si no se encuentra después, abrí una terminal nueva.

2. Verificar la instalación

cursor-agent --version

Verificación esperada: imprime la versión instalada. Si la terminal responde "command not found", abrí una sesión nueva para que tome el PATH actualizado.

3. Iniciar sesión

cursor-agent login

Esto abre tu navegador para autenticarte con tu cuenta de Cursor. Si el navegador no se abre (por ejemplo por SSH), definí NO_OPEN_BROWSER=1 y abrí a mano la URL que se imprime.

Verificá el resultado:

cursor-agent status

Verificación esperada: muestra tu cuenta y el endpoint. Usá cursor-agent logout para cerrar sesión.

Para CI o automatización, salteá el navegador y usá una API key del dashboard de Cursor:

export CURSOR_API_KEY=tu_api_key
cursor-agent "corré la suite de tests y arreglá lo que falle"

4. Arrancar una sesión interactiva

cd ruta/a/tu/proyecto
cursor-agent

O arrancá directamente con un prompt:

cursor-agent "explicá el flujo de autenticación de este proyecto"

Cambiá de modo dentro de la sesión: Agent (acceso completo), Plan (diseña primero, sin editar), Ask (solo lectura). Controlá el acceso al sistema de archivos y a comandos con /sandbox o el flag --sandbox <modo>. Elegí modelo con --model (por ejemplo --model "gpt-5").

La CLI lee .cursor/rules, además de AGENTS.md y CLAUDE.md en la raíz del repo, y autodetecta mcp.json.

5. Correrlo en modo headless

Para scripts y pipelines:

cursor-agent -p "resumí los cambios del último commit" --output-format text

Usá --output-format json para una salida estructurada que puedas parsear.

6. Retomar y actualizar

cursor-agent ls          # listar chats anteriores
cursor-agent resume      # retomar el más reciente
cursor-agent update      # actualizar a la última versión

Resultado esperado

cursor-agent --version imprime una versión.
cursor-agent status muestra que tenés sesión iniciada.
cursor-agent abre una sesión interactiva sobre tu proyecto.
cursor-agent -p "..." --output-format text devuelve una respuesta sin prompt interactivo.

Troubleshooting

Problemas comunes

cursor-agent: command not found después de instalar: el instalador actualizó tu PATH pero la shell actual no lo recargó. Abrí una terminal nueva o hacé source de tu perfil de shell.
El navegador no se abre en login: definí NO_OPEN_BROWSER=1, volvé a correr cursor-agent login y abrí la URL que imprime.
Errores de autenticación en CI: confirmá que CURSOR_API_KEY esté exportada en el entorno del job, o pasá --api-key explícitamente.
El agente edita cuando solo querías un plan: cambiá a modo Plan o Ask, o restringí --sandbox.
Prompts de sudo dentro de una ejecución: la CLI enmascara la contraseña para que el modelo nunca la vea; escribila en el prompt.

Siguiente paso

Agregá reglas de proyecto en .cursor/rules para que cada sesión arranque con el contexto correcto, e integrá Cursor CLI a GitHub Actions para flujos automatizados de revisión y corrección.