Как работать с Cursor через терминал: полный гайд по CLI

Cursor CLI позволяет управлять редактором, вызывать AI-агентов и выполнять рефакторинг кода напрямую из командной строки, не открывая графический интерфейс. Для установки используйте команду npm install -g @cursor/cli (или скачайте бинарный файл с официального сайта), а для проверки работоспособности введите cursor --version. Это экономит время при настройке CI/CD пайплайнов и автоматизации рутинных задач разработки.

Установка и настройка окружения

Cursor CLI интегрируется с существующей экосистемой Node.js или распространяется как самостоятельный бинарный файл. Выбор способа установки зависит от вашей операционной системы и предпочтений в управлении пакетами.

Системные требования

• ОС: Windows 10/11 (рекомендуется PowerShell или WSL2), macOS 12+, Linux (Ubuntu 20.04+).
• Зависимости: Node.js версии 18 или выше (если установка через npm).
• Доступ: Активная учетная запись Cursor для авторизации API-запросов.

Способы установки

1. Через npm (универсальный способ) Если у вас уже установлен Node.js, это самый быстрый метод:

npm install -g @cursor/cli

2. Через Homebrew (для macOS и Linux) Удобно для автоматического обновления вместе с остальным софтом:

brew install cursor-cli

3. Бинарная установка (Windows/Linux) Скачайте архив с релизами из официального репозитория, распакуйте его и добавьте путь к исполняемому файлу в системную переменную PATH.

Авторизация

Для работы с AI-функциями необходимо связать CLI с вашим аккаунтом:

cursor login

Эта команда откроет браузер для подтверждения доступа. После успешного входа токен сохранится в локальной конфигурации.

Обновление инструмента

Регулярное обновление важно, так как Cursor часто добавляет новые модели и улучшает логику агентов.

• Для npm:

    npm update -g @cursor/cli
    ```
*   **Для Homebrew:**
    
```bash
    brew upgrade cursor-cli
    ```
*   **Проверка версии:**
    
```bash
    cursor --version
    ```

Если после обновления возникают ошибки зависимостей, рекомендуется очистить кэш npm (`npm cache clean --force`) и переустановить пакет.

## Базовые команды и синтаксис

CLI построен вокруг глаголов действия. Основная структура команды: `cursor [действие] [аргументы] [флаги]`.

### Управление проектом и файлами

<div class="table-container"><table style="border-collapse: collapse; width: 100%; margin: 16px 0;"><thead><tr><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Команда</th><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Описание</th><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Пример использования</th></tr></thead><tbody><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor init</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Инициализация конфигурации <code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">.cursorrules</code> в текущей папке.</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor init</code></td></tr><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor open</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Открытие текущей директории или файла в редакторе Cursor.</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor open ./src/app.ts</code></td></tr><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor status</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Проверка состояния индексации проекта и токенов.</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor status</code></td></tr></tbody></table></div>


### Работа с AI-агентами (Composer)

Главная сила CLI — возможность запускать генерацию и рефакторинг кода без открытия GUI.

*   **Запуск агента с промптом:**
    
```bash
    cursor compose "Добавь обработку ошибок во все API роуты в папке src/api"
    ```
*   **Режим чата (без изменения файлов):**
    
```bash
    cursor chat "Объясни, как работает функция main.go"
    ```
*   **Применение диффов (патчей):**
    Если агент предложил изменения, их можно принять или отклонить через флаги или интерактивное меню.

### Конфигурация

Настройки хранятся в файле `~/.cursor/config.json` или локально в проекте.

*   **Просмотр настроек:**
    
```bash
    cursor config get model
    ```
*   **Изменение модели по умолчанию:**
    
```bash
    cursor config set model claude-3.5-sonnet
    ```
*   **Управление правилами (.cursorrules):**
    Вы можете динамически добавлять правила для конкретного сеанса:
    
```bash
    cursor rules add "Всегда пиши комментарии на русском языке"
    ```

## Частые ошибки при работе с Cursor CLI

1.  **Ошибка авторизации (401 Unauthorized)**
    *   *Причина:* Истек срок действия токена или он был отозван.
    *   *Решение:* Выполните `cursor logout`, а затем снова `cursor login`.

2.  **Команда не найдена (command not found)**
    *   *Причина:* Путь к глобальным пакетам npm не добавлен в PATH.
    *   *Решение:* Добавьте `$(npm bin -g)` в переменную PATH вашего shell (.zshrc или .bashrc).

3.  **Агент игнорирует контекст**
    *   *Причина:* Файлы не проиндексированы или исключены через `.gitignore` / `.cursorignore`.
    *   *Решение:* Проверьте файл `.cursorignore` и убедитесь, что нужные директории не заблокированы. Используйте флаг `--include` для принудительного добавления файлов.

4.  **Конфликты версий Node.js**
    *   *Причина:* Использование устаревшей версии Node (ниже 18).
    *   *Решение:* Обновите Node.js через nvm или официальный установщик.

## FAQ

**Можно ли использовать Cursor CLI в CI/CD пайплайнах?**
Да, но с ограничениями. Вы можете использовать CLI для линтинга, генерации документации или статического анализа. Однако интерактивные функции (Composer) требуют стабильного соединения с API и могут быть затратны по токенам в автоматическом режиме. Используйте сервисные ключи API для аутентификации в headless-режиме.

**Как задать контекст для конкретной задачи?**
Используйте флаг `--file` или указывайте пути к файлам прямо в промпте. Например: `cursor compose "Рефакторинг" --file ./src/utils.js --file ./src/helpers.js`.

**Где хранится история чатов из терминала?**
История команд сохраняется в локальной базе данных Cursor. Вы можете получить к ней доступ через GUI в разделе Settings > Chat History, но прямой экспорт из CLI пока ограничен функцией логирования в файл (флаг `--log`).

**Безопасно ли хранить API-ключи в конфиге?**
Нет. Никогда не храните секретные ключи в `config.json` в открытом виде. Используйте переменные окружения (например, `CURSOR_API_KEY`) или менеджеры секретов (Vault, AWS Secrets Manager), передавая их в среду выполнения.