Команда gemini в терминале выдаёт ошибку «command not found» или зависает на этапе авторизации — чаще всего причина в несоответствии версии Node.js требованиям пакета или в незавершённой настройке учётных данных. Gemini CLI — это официальный консольный агент от Google с открытым исходным кодом, который подключает модели семейства Gemini прямо к командной строке и распространяется через npm.
Прежде чем искать сложные причины сбоев, стоит проверить базовую цепочку: версию Node.js, корректность установки пакета и способ авторизации. Ниже разберём установку, первичную настройку, основные команды и типичные ошибки с осторожными, проверяемыми решениями.
Что такое Gemini CLI и чем он отличается от веб-версии
Gemini CLI — это инструмент командной строки, который работает как автономный агент: он умеет читать файлы проекта, выполнять команды оболочки с вашего разрешения и редактировать код. В отличие от чата в браузере, агент видит контекст текущей директории и может работать с репозиторием целиком.
Исходный код проекта опубликован Google в открытом репозитории, поэтому поведение инструмента прозрачно, а сообщество может предлагать исправления. По сути, это аналог консольных агентов вроде Claude Code или GitHub Copilot CLI, но с интеграцией в экосистему Google и бесплатным уровнем использования для личных аккаунтов.
- 🖥️ Работает в терминале на Windows, macOS и Linux.
- 📂 Анализирует файлы проекта и выполняет многошаговые задачи.
- 🔓 Открытый исходный код — можно изучить и доработать.
- 🔑 Поддерживает вход через личный аккаунт Google или API-ключ.
Системные требования и подготовка
Для работы пакета требуется Node.js версии 20 или выше — это ключевая зависимость, из-за которой чаще всего ломается установка. Проверить установленную версию можно одной командой:
node --versionЕсли версия ниже требуемой, обновите Node.js с официального сайта проекта или через менеджер версий вроде nvm. На Windows удобно использовать установщик LTS-версии, на macOS — пакетный менеджер Homebrew.
⚠️ Внимание: установка Gemini CLI на устаревшую версию Node.js может пройти с предупреждениями, но при запуске агент будет падать с малопонятными ошибками. Сначала обновите окружение, потом ставьте пакет.
Установка Gemini CLI через npm
Установка выполняется стандартной командой npm глобально, чтобы команда gemini была доступна из любой директории:
npm install -g @google/gemini-cliПосле завершения установки запустите агент командой gemini в папке проекта. Если система сообщает, что команда не найдена, проверьте, входит ли глобальный каталог npm в переменную окружения PATH. Узнать путь к глобальным пакетам можно командой npm config get prefix.
☑️ Проверка перед первым запуском
Альтернативный вариант — запуск без глобальной установки через npx @google/gemini-cli. Это удобно для разовой проверки, но каждый запуск будет подтягивать пакет заново, что медленнее.
Авторизация: аккаунт Google или API-ключ
При первом запуске агент предложит выбрать способ входа. Самый простой путь — авторизация через личный аккаунт Google: откроется окно браузера, где нужно подтвердить доступ. Для личного использования предусмотрен бесплатный уровень с лимитами запросов, которых обычно хватает для повседневных задач.
Второй вариант — API-ключ из Google AI Studio. Он задаётся через переменную окружения GEMINI_API_KEY и подходит тем, кто хочет явно контролировать расходы и квоты. Ключ создаётся в консоли AI Studio, а переменную окружения нужно прописать в профиле оболочки или задать перед запуском.
export GEMINI_API_KEY="ваш_ключ"⚠️ Внимание: не публикуйте API-ключ в репозитории и не вставляйте его в команды, которые попадают в историю общего доступа. Скомпрометированный ключ следует сразу отозвать в консоли и создать новый.
Основные команды и контекст проекта
Внутри интерактивной сессии доступны служебные команды, начинающиеся со слэша. Их полный список выводится командой /help — именно её стоит использовать как источник актуальных возможностей, поскольку набор команд меняется от версии к версии.
| Команда | Назначение |
|---|---|
/help | Список доступных команд и справка |
/clear | Очистка контекста текущей сессии |
/memory | Работа с долговременным контекстом проекта |
/stats | Статистика использования токенов за сессию |
Отдельный механизм — файл GEMINI.md в корне проекта. В него записывают постоянные инструкции для агента: стиль кода, соглашения проекта, запреты на изменение отдельных файлов. Содержимое GEMINI.md подхватывается автоматически при каждом запуске, поэтому именно здесь задаётся «характер» работы агента в конкретном репозитории.
Как агент выполняет команды оболочки
Перед выполнением потенциально опасных действий Gemini CLI запрашивает подтверждение в терминале. Вы можете разрешить действие один раз или добавить его в список доверенных на время сессии. Не отключайте подтверждения глобально для незнакомых проектов — это защита от случайного удаления или изменения файлов.
Типичные ошибки и их устранение
Большинство проблем сводится к четырём сценариям: сбой авторизации, превышение лимитов, конфликт версий и сетевые ограничения. Диагностику лучше вести от простого к сложному.
- 🔐 Ошибка авторизации — выйдите и войдите заново, проверьте, тот ли аккаунт выбран в браузере.
- ⏳ Ответы обрываются или отклоняются — возможно, исчерпан дневной лимит бесплатного уровня; подождите сброса квоты или переключитесь на API-ключ.
- 🌐 Таймауты соединения — проверьте прокси, VPN и корпоративный файрвол; в некоторых сетях требуется явная настройка переменных прокси.
- 📦 Конфликты при обновлении — удалите пакет и установите заново:
npm uninstall -g @google/gemini-cli, затем повторная установка.
Если агент «не понимает» проект, проверьте, запущен ли он из корневой папки репозитория, и нет ли слишком больших файлов, которые раздувают контекст. Точные тексты ошибок и их коды зависят от версии пакета, поэтому при нестандартном сбое ориентируйтесь на сообщение в терминале и раздел Issues официального репозитория проекта.
Обновление и безопасная работа
Инструмент активно развивается, и обновления выходят регулярно. Обновить пакет можно той же командой установки — npm подтянет свежую версию. Проверить текущую версию помогает справочная команда внутри сессии или npm list -g @google/gemini-cli.
Что касается безопасности: агент имеет доступ к файлам проекта и может выполнять команды, поэтому запускайте его только в доверенных директориях. Перед тем как разрешить массовое изменение файлов, убедитесь, что проект находится под контролем версий — тогда любые правки легко откатить через git diff и git checkout.
Частые вопросы
Бесплатен ли Gemini CLI?
Для личных аккаунтов Google предусмотрен бесплатный уровень с суточными лимитами запросов. Для интенсивной работы или коммерческих задач используется платный доступ через API-ключ с оплатой по факту потребления.
Работает ли Gemini CLI на Windows?
Да, инструмент работает на Windows, macOS и Linux при наличии Node.js версии 20 или новее. На Windows удобнее всего использовать PowerShell или Windows Terminal.
Чем Gemini CLI отличается от расширения Gemini в редакторе кода?
Расширение для редактора встраивает подсказки в IDE, а Gemini CLI — это самостоятельный агент в терминале, который выполняет многошаговые задачи: читает файлы, запускает команды и редактирует код по вашему запросу.
Может ли агент удалить мои файлы?
Теоретически — да, если вы подтвердите соответствующую команду. По умолчанию агент запрашивает разрешение на потенциально опасные действия. Не отключайте подтверждения без необходимости и храните проект под контролем версий.
Что делать, если исчерпан дневной лимит запросов?
Лимит бесплатного уровня сбрасывается автоматически. Если ждать нельзя, переключитесь на авторизацию через API-ключ из Google AI Studio — тогда квоты будут определяться вашим тарифом в консоли.