Рассказ фронтендера

Gemini CLI. Часть 1

•читать 17 мин• 9
AICLIMCPAgentgemini

cover.webp

Что такое Gemini CLI

Gemini CLI - это инструмент с открытым исходным кодом, выпущенный Google. Он работает как диалоговый агент прямо в терминале: принимает команды на естественном языке, анализирует вашу кодовую базу, выполняет shell-команды и решает многошаговые задачи. По сути, это ответ Google на Claude Code от Anthropic.

Gemini CLI использует архитектуру ReAct (Reason and Act) - он рассуждает, выбирает нужный инструмент и действует. Инструмент поддерживает интерфейс в стиле REPL с двумя типами команд:

  • Slash-команды (/ – префикс) – управление сессией, инструментами и настройками.
  • Bang-команды (! – префикс) – прямое выполнение shell-команд.

Ключевые возможности:

  • Анализ и рефакторинг кода – понимает существующий проект, объясняет сложные участки, генерирует функции.
  • Отладка – находит баги, предлагает исправления, автоматически создаёт тесты.
  • Выполнение команд – запускает git, npm, pip и другие утилиты прямо из CLI.
  • Интеграция с Google Search – получает актуальную информацию из сети в реальном времени.
  • Поддержка MCP (Model Context Protocol) – подключается к внешним базам данных и сторонним инструментам
  • Работа с Google Drive, Docs, Sheets – подтягивает данные по ссылке без ручного копирования.
  • Работа с вашей Gmail-почтой.
  • Умеет читать разные файлы, даже PDF.

По лимитам пока так, но эти лимиты могут измениться и пока вы читаете эту статью возможно они уже изменились.

ХарактеристикаЗначение
Контекстное окно1 миллион токенов
Запросов в минуту60
Запросов в день1 000
ЦенаБесплатно (личный Google-аккаунт)
ПлатформыWindows, macOS, Linux

Чтобы просмотреть статистику использования можно вызвать команду

/stats

Установка

Установка достаточно простая, если у вас есть homebrew (кстати, доступен не только на macOS, но и на linux), то просто можете выполнить команду:

brew install gemini-cli

Если нет, то нужно установить Node.js и вызвать команду:

npm install -g @google/gemini-cli

После того как установили Gemini, его можно запустить командой:

gemini

Инструмент предложит авторизоваться через личный Google-аккаунт, после чего вы сразу получаете бесплатный доступ. Затем получите что-то такое:

8b7628d5f154dedf62cc6a33d37a4884.png

По умолчанию Gemini CLI работает в безопасном режиме: любые действия, которые могут изменить систему (запись файлов, выполнение команд и т. д.), требуют подтверждения. Перед выполнением инструмент покажет diff или команду и спросит разрешение (Y/n). Это защищает от нежелательных изменений.

Конфигурирование

Вы можете настроить Gemini CLI под себя командой /settings. Откроется большой список настроек.

19143aa5559b4300b93aaea108a25590.png

Также можно настроить через файл settings.json. Настройки применяются в следующем порядке приоритета:

  • Проект: .gemini/settings.json (переопределяет пользовательские).
  • Пользователь: ~/.gemini/settings.json.
  • Система: /etc/gemini-cli/settings.json (применяется ко всем пользователям, имеет наивысший приоритет).

Пример settings.json:

{
  "theme": "GitHub",
  "autoAccept": false,
  "sandbox": "docker",
  "vimMode": true,
  "checkpointing": { "enabled": true },
  "fileFiltering": { "respectGitIgnore": true },
  "usageStatisticsEnabled": true,
  "includeDirectories": ["../shared-library", "~/common-utils"],
  "chatCompression": { "contextPercentageThreshold": 0.6 },
  "customThemes": {
    "MyCustomTheme": {
      "name": "MyCustomTheme", "type": "custom",
      "Background": "#181818", "Foreground": "#F8F8F2",
      "LightBlue": "#82AAFF", "AccentBlue": "#61AFEF", "AccentPurple": "#C678DD",
      "AccentCyan": "#56B6C2", "AccentGreen": "#98C379", "AccentYellow": "#E5C07B",
      "AccentRed": "#E06C75", "Comment": "#5C6370", "Gray": "#ABB2BF"
    }
  }
}

Подробнее о настройке можно узнать в документации

API-ключ и лимиты

По умолчанию Gemini CLI работает через ваш личный Google-аккаунт с бесплатными лимитами. Если вам нужно больше запросов или вы хотите использовать корпоративный аккаунт, можно подключить собственный API-ключ через Google AI Studio. Получив ключ, установите переменную окружения:

# Linux / macOS
export GEMINI_API_KEY="ваш_ключ"

# Windows (PowerShell)
$env:GEMINI_API_KEY="ваш_ключ"

Или добавьте её в settings.json:

{
  "apiKey": "ваш_ключ"
}

При использовании собственного ключа лимиты определяются вашим тарифным планом в Google AI Studio, а не бесплатными ограничениями личного аккаунта.

Советы по использованию

Рассмотрим советы по использованию инструмента и его скрытые возможности.

Используем GEMINI.md

Используйте файл GEMINI.md, чтобы предоставлять инструкции модели и адаптировать её под ваш проект. Используйте команду /init для создания начального файла GEMINI.md для вашего проекта.

CLI объединяет файлы GEMINI.md из нескольких расположений. Более специфичные файлы переопределяют общие. Порядок загрузки следующий:

  • Глобальный контекст: ~/.gemini/GEMINI.md (для инструкций, которые применяются ко всем вашим проектам).
  • Контекст проекта / Родительских директорий: CLI ищет файлы GEMINI.md начиная с вашей текущей директории и вверх до корневой папки проекта.
  • Контекст поддиректорий: CLI также сканирует поддиректории на наличие файлов GEMINI.md, что позволяет задавать инструкции для конкретных компонентов.

Примечание: Используйте команду /memory show, чтобы увидеть итоговый объединенный контекст, который отправляется модели.

Пример GEMINI.md с использованием импортов:

# Главный контекст проекта: My Awesome App
 
## Общие инструкции
- Весь код на Python должен соответствовать стандарту PEP 8.
- Используйте отступ в 2 пробела для всех новых файлов.
 
## Руководства по стилю для конкретных компонентов
@./src/frontend/react-style-guide.md
@./src/backend/fastapi-style-guide.md

Не забывайте добавлять .geminiignore

Создайте файл .geminiignore в корне вашего проекта, чтобы исключить файлы и директории из инструментов Gemini, аналогично .gitignore.

/backups/
*.log
secret-config.json
.env

Создаем кастомные команды

Мы познакомились с командой /settings, но мы можем создавать кастомные команды сами. Например, можно сделать команду /test:gen, которая генерирует юнит-тесты по описанию, или /db:reset, которая удаляет и заново создаёт тестовую базу данных.

Gemini CLI поддерживает кастомные slash-команды, которые задаются в простых конфигурационных файлах. По сути, это заранее подготовленные шаблоны промптов. Чтобы создать такую команду, добавьте каталог commands/ либо в ~/.gemini/ (для глобальных команд), либо в .gemini/ вашего проекта.

Внутри commands/ создавайте отдельный TOML-файл на каждую новую команду. Имя файла определяет имя команды: например, файл test/gen.toml создаёт команду /test:gen.

Рассмотрим пример. Пусть вам нужна команда, генерирующая юнит-тест по текстовому описанию требования. Создайте файл:

# Invoked as: /test:gen "Description of the test"  
description = "Generates a unit test based on a requirement."  
prompt = """  
You are an expert test engineer. Based on the following requirement, please write a comprehensive unit test using the Jest framework.

Requirement: {{args}}  
"""

Теперь, после перезагрузки или перезапуска Gemini CLI вы можете просто ввести:

/test:gen "Ensure the login button redirects to the dashboard upon success"

Gemini CLI распознает /test:gen и подставит {{args}} из шаблона промпта в виде переданного аргумента. Команд может быть множество, дайте волю фантазии.

Песочница (Sandbox)

В примере settings.json выше есть параметр "sandbox": "docker" – разберём, что он делает.

По умолчанию Gemini CLI выполняет shell-команды напрямую на вашей системе. Это удобно, но потенциально опасно: агент с широкими правами может случайно (или не случайно) изменить что-то важное. Режим sandbox решает эту проблему - все команды выполняются внутри изолированного Docker-контейнера, а не на хост-системе.

Чтобы включить:

{
  "sandbox": "docker"
}

Для этого на машине должен быть установлен и запущен Docker (как установить можно почитать тут). После включения Gemini будет запускать все shell-команды внутри контейнера - ваша файловая система и системные настройки останутся нетронутыми. Это особенно полезно, если вы даёте агенту широкие задачи или используете режим --yolo, который описан ниже.

Расширяем возможности с MCP

MCP позволяют расширить возможности Gemini. Gemini CLI поставляется с несколькими MCP-серверами по умолчанию (например, дающими доступ к Google Search, песочницам для выполнения кода и т.п.), также можно добавить свои.

Например, через Figma MCP можно подключить агента к вашему проекту, чтобы он мог получать данные напрямую из макетов. Чтобы добавить MCP сервер необходимо открыть settings.json и добавить туда:

"mcpServers": {
  "myserver": {
    "command": "python3",
    "args": ["-m", "my_mcp_server", "--port", "8080"],
    "cwd": "./mcp_tools/python",
    "timeout": 15000
  }
}

или через команду:

gemini mcp add myserver --command "python3 my_mcp_server.py" --port 8080

Инструменты сервера становятся доступны в Gemini CLI сразу после его запуска. Полезные команды:

# Проверить все настроенные MCP-серверы (внутри сессии Gemini CLI)
/mcp

# Посмотреть список серверов и их инструменты
gemini mcp list

# Удалить сервер
gemini mcp remove <name>

После изменения конфигурации нужно перезапустить Gemini CLI, чтобы новые настройки вступили в силу. Главные площадки для поиска готовых серверов:

  • mcpservers.org – агрегатор с поиском по категориям и тегам
  • mcp.so – крупнейшая коллекция, включает серверы из awesome-mcp-servers
  • glama.ai/mcp/servers – актуальный реестр, обновляется ежедневно
  • pulsemcp.com – популярный агрегатор с рейтингами
  • mcpserverhub.net – есть русский интерфейс

Читаем Google Docs и многое другое

Допустим, нам нужно передать агенту данные из документа. Вместо того чтобы копировать текст вручную, мы можем просто отправить ссылку. Если Workspace MCP-сервер уже настроен, Gemini CLI самостоятельно получит и прочитает файл. Например:

Резюмируй требования из этого дизайн-документа: https://docs.google.com/document/d/<id>

Также мы можем читать файлы из нашего Google Drive. Есть два основных варианта:

felores/gdrive-mcp-server

  • open-source, read-only доступ, автоматически конвертирует Google Docs → Markdown, Sheets → CSV, Presentations → Text

sonickarnati/gemini-mcp-google-tools

  • комплексный сервер: Drive + Gmail + Google Calendar + Scholar

Для простого чтения файлов рекомендуется gdrive-mcp-server - он легче и сфокусирован именно на Google Drive.

@ - передаем файлы и изображения

Чтобы не описывать содержимое файла или изображения словами, можно указать его напрямую нашему агенту с помощью символа @.

Объясни мне что происходит в этом коде: @./src/main.js

Несколько замечаний о том, как эффективно использовать @:

  • Ограничения по размеру файлов – обладает огромным контекстом (до 1 млн токенов), поэтому можно включать довольно крупные файлы или много файлов одновременно. Но очень большие файлы могут быть усечены.
  • Автоматическое игнорирование: По умолчанию Gemini CLI учитывает .gitignore и .geminiignore при сборе содержимого директорий.
  • Можно указывать несколько ссылок сразу:
Сравни @./foo.py и @./bar.py и скажи мне в чем разница.

Используйте Gemini CLI для настройки системы

Если у вас возникают проблемы с ОС вы можете открыть терминал и попросить Gemini устранить проблему.

Примеры:

  • найти и исправить проблему в .bashrc;
  • попросить поправить PATH если команда не запускается;
  • диагностика ошибок в системе;
  • настройка рабочей станции – попросить установить программы и настроить их например docker, git и пр

Но будьте аккуратны, нужно смотреть, что делает Gemini. Если он просит вас подтвердить какую-то команду, но вы не знаете, что она делает – попросите объяснить вам эту команду и что она делает.

Отключаем подтверждение запросов

В Gemini есть режим который позволяет выполнять действия без вашего участия – YOLO (You Only Live Once) - включается флагом --yolo.

gemini --yolo

Важно помнить, что Gemini может выполнить абсолютно любую команду – в том числе опасную вроде rm -rf / - не спрашивая вас.

Запускаем Gemini в фоне

Headless-режим позволяет запускть Gemini CLI в фоновом режиме чтобы использовать возможности нейросети в автоматизированных задачах, скриптах и CI/CD-пайплайнах без участия человека.

Вот пример – автоматическая генерация Commit Message. Вместо того чтобы придумывать описание коммита, можно попросить Gemini прочитать ваши проиндексированные изменения и написать сообщение за вас.

git diff --staged | gemini -p "Напиши лаконичный commit message на английском языке в формате Conventional Commits для этих изменений."

или еще вот – ревью кода перед отправкой:

cat server.js | gemini -p "Сделай ревью этого Node.js кода. Укажи на потенциальные уязвимости, проблемы с производительностью и предложи рефакторинг."

Сохраняем и возобновляем чат сессии

Gemini CLI позволяет сохранять чаты и возвращаться к ним позже. Основные команды управления сессиями:

  • /chat save <имя_сессии> – cохранить текущую сессию. Сохраняет всю текущую историю переписки (контекст) под заданным тегом/именем. Если такое имя уже существует, оно будет перезаписано. Пример: /chat save fix-docker-bug

  • /chat list – Посмотреть список сохраненных сессий. Выводит список всех ранее сохраненных чатов (чекпоинтов), которые доступны для загрузки.

  • /chat resume <имя_сессии> – Возобновить сессию. Загружает выбранную историю сообщений в ваш текущий контекст. Вы сможете продолжить диалог с того же места. Пример: /chat resume fix-docker-bug

  • /chat delete <имя_сессии> – Удалить сессию. Удаляет сохраненный чекпоинт, чтобы он не занимал место и не засорял список. Пример: /chat delete fix-docker-bug

Несколько директорий

Если ваш проект состоит из нескольких папок, например frontend и backend, вы можете запустить Gemini так, чтобы он получил доступ не к одной папке, а к двум. Есть два варианта:

  1. Флаг --include-directories при запуске
gemini --include-directories "../backend:../frontend"
  1. Постоянная настройка в проекте в settings.json - includeDirectories

Когда включён режим нескольких директорий, Gemini учитывает файлы во всех подключённых локациях. Команда /directory show отображает, какие директории используются в рабочем пространстве. Также можно добавлять директории во время сессии с помощью команды /directory add <path>.

Сжимаем переписку

Если вы долго общаетесь с Gemini, то можете упереться в предел длины контекста. Помните, что у языковых моделей есть фиксированное окно контекста – если выйти за его пределы, модель забывает ранние сообщения. Используйте /compress, чтобы кратко пересказать переписку и заменить всю историю компактным резюме.

Мультимодальность

Помните, что Gemini работает не только с текстом – он также может работать с изображениями, диаграммами и PDF-файлами. Чтобы обратиться к файлу, в промпте можно использовать символ @.

Что изображено на этой картинке @./picture.png

Также мы можем передать результат её работы как изображение и указать на ошибки, которые она допустила, – что очень удобно.

Используйте чекпоинты и /restore как кнопку “Отменить”

Иногда Gemini может вносить изменения в файлах, которые вас не устраивают, – в таком случае вы можете откатиться к предыдущему состоянию. Чекпоинты можно включить в настройках или при запуске Gemini.

gemini --checkpointing

или в настройках "checkpointing": { "enabled": true } в settings.json.

И использовать команду /restore – возврощает рабочую директорию к сохраненному чекпоинту.

Еще полезные команды:

  • /restore list (или просто /restore без аргументов), чтобы увидеть список недавних чекпоинтов с отметками времени и описаниями.

  • /restore <id>, чтобы откатиться к конкретному чекпоинту. Если id не указан и есть только один доступный чекпоинт, он будет восстановлен по умолчанию.

Память

Команды /memory позволяют сохранять важную информацию в долговременную память ИИ (в файл GEMINI.md), чтобы он учитывал её в текущих и будущих сессиях. Функция памяти работает как растущая база знаний. Она компенсирует "забывчивость" модели в длинных диалогах и избавляет вас от необходимости повторять одни и те же вводные данные.

Основные команды:

  • /memory add "<текст>" - сохранить факт, настройку или договоренность.
  • /memory show - вывести всё содержимое памяти.
  • /memory refresh - обновить контекст, если вы редактировали файл GEMINI.md вручную.

Для чего это полезно:

  • Технические данные: быстрое сохранение портов, токенов и критичных настроек конфигурации.
  • Журнал решений: фиксация стиля кода или выбранных библиотек, чтобы ИИ не противоречил принятым правилам.
  • Глобальные настройки: сохранение личных предпочтений общения (например, вашего имени и тона) в глобальный файл ~/.gemini/GEMINI.md, который работает для всех проектов.

Реальный воркфлоу

Допустим, нам нужно с нуля написать небольшой REST API на NestJS – простой сервис задач (To-Do) с Prisma и SQLite. Пройдём весь путь: от запуска Gemini CLI и настройки контекста до отката изменений и автоматической генерации commit message.

Шаг 1. Готовим проект

Создадим NestJS-приложение через официальный CLI и сразу подключаем Prisma:

npx @nestjs/cli new todo-api --package-manager npm --skip-git=false
cd todo-api
npm install prisma @prisma/client class-validator class-transformer
npx prisma init --datasource-provider sqlite

Шаг 2. Конфигурируем Gemini для проекта

Заранее положим конфиги, чтобы при первом запуске сразу работали песочница и чекпоинты. .gemini/settings.json:

{
  "theme": "GitHub",
  "sandbox": "docker",
  "checkpointing": { "enabled": true },
  "fileFiltering": { "respectGitIgnore": true },
  "chatCompression": { "contextPercentageThreshold": 0.7 }
}

Создаем .geminiignore – отрезаем от агента то, что ему трогать не нужно:

node_modules/
dist/
coverage/
*.log
.env
*.db
prisma/migrations/

Кастомная команда для генерации тестов – .gemini/commands/test/gen.toml:

description = "Генерирует Jest-тест по описанию требования."
prompt = """
Ты — опытный QA-инженер. Напиши Jest-тест по требованию ниже.
Для unit-тестов используй @nestjs/testing (Test.createTestingModule) и моки PrismaService.
Для e2e — supertest поверх INestApplication.
Покрой happy path и хотя бы один негативный сценарий.

Требование: {{args}}
"""

Шаг 3. Первый запуск и GEMINI.md

Запускаем агента, в консоли вводим:

gemini

Внутри сессии вызываем /init – Gemini осмотрит папку и сгенерирует базовый GEMINI.md. Дополним его правилами проекта, чтобы агент сразу понимал стиль:

# Todo API

Небольшой REST API на NestJS + Prisma + SQLite.

## Соглашения
- TypeScript strict mode, никаких `any`.
- Все эндпоинты префиксуем `/api/v1`.
- ID задач — `cuid` через Prisma, не autoincrement.
- Даты — UTC, ISO 8601.
- Валидация — `class-validator` + `ValidationPipe` глобально (`whitelist: true`, `forbidNonWhitelisted: true`).
- Бизнес-логика — в сервисах, контроллер только разруливает HTTP.
- Тесты — Jest, юнит-тесты рядом с файлом (`*.spec.ts`), e2e — в `/test`.
- Коммиты — Conventional Commits.

## Структура
- `/src` — модули, контроллеры, сервисы
- `/prisma` — `schema.prisma` и миграции
- `/test` — e2e-тесты

Проверяем:

/memory show

Шаг 4. Разработка скелета

Даём Gemini первое крупное задание со ссылкой на контекст через @:

Сгенерируй ресурс tasks через `nest g resource tasks --no-spec` и реализуй CRUD
по правилам из @./GEMINI.md.

В @./prisma/schema.prisma добавь модель Task:
id (String, cuid), title (String), description (String?), done (Boolean, @default(false)),
createdAt (DateTime, @default(now())).

Создай PrismaModule + PrismaService, подключи в TasksModule.
DTO — с class-validator. Контроллер — под /api/v1/tasks.
Не забудь миграцию: `npx prisma migrate dev --name init`.

Gemini покажет план, дифы и попросит подтверждение на каждый файл. Внутри Docker-песочницы он же выполнит установку зависимостей и миграцию. Запускаем сервер прямо из CLI командой:

!npm run start:dev

Если что-то падает – просим исправить, не выходя из сессии:

Сервер ругается на DI при старте — посмотри логи и поправь.

Шаг 5. Тесты через кастомную команду

Используем заранее подготовленную команду:

/test:gen "POST /api/v1/tasks создаёт задачу и возвращает 201 с cuid в теле"
/test:gen "GET /api/v1/tasks/:id для несуществующего id возвращает 404"
/test:gen "PATCH /api/v1/tasks/:id с done=true меняет статус и возвращает обновлённую задачу"

Запускаем оба слоя:

!npm run test
!npm run test:e2e

Шаг 6. Сохраняем важное в память

Чтобы в будущих сессиях агент не задавал одни и те же вопросы, фиксируем ключевые решения:

/memory add "ORM — только Prisma, TypeORM не используем."
/memory add "Ошибки отдаём в формате RFC 7807 через кастомный exception filter."
/memory add "Логирование — pino через nestjs-pino, console.log запрещён."

Эти записи попадут в ~/.gemini/GEMINI.md или в локальный GEMINI.md и подтянутся автоматически при следующем запуске.

Шаг 7. Сохраняем чат-сессию

Закончили большой кусок работы – фиксируем переписку, чтобы можно было вернуться:

/chat save todo-api-mvp

Шаг 8. Эксперимент и откат через /restore

Решили проверить гипотезу, что на Fastify будет быстрее и красивее, чем на дефолтном Express. Просим:

Переведи приложение с Express на Fastify-адаптер NestJS.
Обнови main.ts, типы Request/Response, middleware и e2e-тесты.

Агент массово правит файлы – но e2e-тесты падают из-за разницы в supertest, сторонняя либа не поддерживает Fastify, профит сомнительный. Откатываемся:

/restore list
/restore <id_до_эксперимента>

Рабочая директория возвращается к состоянию до изменений – без git reset --hard и ручного восстановления файлов. Это и есть та самая «кнопка Отменить».

Шаг 9. Коммит через headless-режим

Изменения, которые остались, нас устраивают. Коммит делаем, но текст пусть пишет Gemini:

git add .
git diff --staged | gemini -p "Напиши лаконичный commit message в формате Conventional Commits на английском. Только сообщение, без пояснений и markdown."

Удобно завернуть в git alias или pre-commit hook – больше никогда не придётся придумывать chore: stuff.

Шаг 10. Сжимаем контекст и продолжаем

Сессия разрослась, лимит токенов поджимает. Ужимаем историю:

/compress

Gemini заменит длинную переписку компактным резюме, и можно работать дальше - например, попросить добавить JWT-аутентификацию через @nestjs/passport или прикрутить Swagger через @nestjs/swagger.

Шаг 11. На следующий день - возврат к работе

Открываем терминал, идём в проект, запускаем:

gemini

Внутри:

/chat list
/chat resume todo-api-mvp

Контекст загружен, GEMINI.md подтянулся, память на месте, кастомные команды доступны – можно сразу продолжать с того же места, где закончили.

Мы разобрали основы Gemini CLI: установку, первые команды и ключевые возможности инструмента. Главный вывод - это мощный способ работать с моделями Google прямо из терминала, не переключаясь в браузер и не прерывая рабочий процесс.

В следующей статье разберём субагентов – один из самых интересных механизмов Gemini CLI, который позволяет делегировать задачи и строить сложные автоматизированные цепочки.

Устанавливаем и экспериментируем перед следующей частью!