Инструмент командной строки

В составе Oleafly поставляется oleafly, инструмент командной строки, который работает с теми же проектами, что и приложение. Собирайте или проверяйте статью из терминала, скрипта или CI. Дайте агенту для кода надёжный доступ к проекту. Синхронизируйтесь с онлайн-сервисом LaTeX или сервером Oleafly либо запускайте агента Oleafly, не открывая приложение.

Он встроен в приложение на каждой платформе. На этой странице описаны команды Oleafly 0.4.8 и новее. В более ранних версиях команд было меньше, поэтому в скриптах, которые от него зависят, закрепляйте версию Oleafly.

Установка

Система	Где приложение его хранит	Как добавить oleafly в PATH
Windows	oleafly-cli.exe рядом с приложением, в %LOCALAPPDATA%\Oleafly для программы установки или C:\Program Files\Oleafly для пакета MSI	Установить в строке Команда для терминала в Настройки → Общие копирует его в %LOCALAPPDATA%\Oleafly\bin\oleafly.exe и добавляет эту папку в PATH
macOS	Oleafly.app/Contents/MacOS/oleafly-cli	Установить в строке Команда для терминала создаёт ссылку oleafly в /usr/local/bin, если там можно писать, а иначе в ~/.local/bin
Пакеты Linux (.deb, .rpm)	/usr/bin/oleafly-cli	Ничего делать не нужно: пакет сам устанавливает /usr/bin/oleafly
AppImage для Linux	Внутри AppImage	Установить копирует его в ~/.local/bin/oleafly

Программы, которые запускает Oleafly, например его собственный терминал и CLI-агенты, всегда находят oleafly в своём PATH, даже пока вы его не установили. Переменная OLEAFLY_CLI содержит его полный путь.

Windows

1. Откройте Настройки → Общие и выберите Установить в строке Команда для терминала.
2. Откройте новое окно PowerShell или командной строки. Уже открытые окна сохраняют прежний PATH.
3. Проверьте, что всё работает:

Get-Command oleafly
oleafly version

Убрать в той же строке удаляет копию и снова убирает папку из PATH. Когда Oleafly обновляется, он обновляет копию при следующем запуске.

macOS

Сначала переместите Oleafly в папку «Программы». Копия, запущенная из образа диска, вместо Установить показывает «Сначала переместите Oleafly в папку „Программы“».

Команда представляет собой ссылку на приложение, поэтому при обновлении Oleafly обновляется и она. Если этой папки нет в PATH, строка показывает, какую строку добавить в профиль оболочки. Проверьте результат командой command -v oleafly.

Linux

Пакеты .deb и .rpm помещают oleafly в PATH при установке. oleafly без аргументов открывает приложение.

AppImage требуется копия, потому что файлы внутри AppImage исчезают, когда он завершает работу. После того как вы замените AppImage более новым, строка предложит Обновить. Если ~/.local/bin нет в PATH, строка показывает, какую строку добавить.

Проверка работы

oleafly version выводит версию приложения и движки, которые использовала бы команда. oleafly doctor проверяет движки, приложение, Git, команду для терминала и ваши клиенты MCP и выводит способ исправить всё, чего не хватает. Он работает и вне проекта.

Сборка проекта

oleafly . открывает текущую папку в приложении. Все остальные команды работают с папкой, в которой вы находитесь; -C с путём направляет команду в другое место.

cd ~/papers/thesis
oleafly init --engine typst
oleafly build
oleafly log --diagnostics
oleafly -C ~/papers/review --json build

• oleafly init делает текущую папку проектом. --engine принимает tectonic, latexmk, typst или markdown.
• oleafly new с папкой, --template и идентификатором шаблона создаёт проект из шаблона. oleafly templates list --all выводит список шаблонов.
• oleafly build использует движок и настройки проекта так же, как приложение: Tectonic, Typst и Pandoc, которые поставляются с Oleafly, или установленный вами LaTeX. --main собирает другой документ проекта, --compiler выбирает компилятор LaTeX для проектов latexmk, -o копирует PDF в другое место, а --timeout задаёт предел в секундах.
• Папка, открытая в приложении прямо с диска, собирается тем движком и главным документом, которые вы там выбрали, в собственную папку сборки приложения.
• Приложение и команда никогда не собирают один проект одновременно: вторая ждёт первую. Неудачная сборка сохраняет последний удачный PDF.
• oleafly watch пересобирает проект при каждом сохранении. oleafly log --diagnostics перечисляет ошибки и предупреждения с файлом и строкой, а oleafly clean удаляет результаты сборки.

Подробности о Typst см. в разделе Проекты Typst.

Использование из агента для кода

Агентам для кода лучше всего работается с тремя вещами, которые даёт команда: oleafly context для карты проекта, --json для результатов, которые они могут прочитать, и коды завершения, сообщающие, что пошло не так. Агента можно подключить тремя способами.

Навык oleafly-cli

В Oleafly входит навык oleafly-cli. Он учит агента командам, формату JSON и кодам завершения, а также циклу, который работает лучше всего: прочитать контекст, внести правку, собрать проект, прочитать диагностику, исправить первую ошибку.

В терминале Oleafly и в CLI-агентах, которые он запускает, выберите навык как любой другой. Для агента, который вы запускаете сами, включите Настройки → ИИ-ассистент → Навыки → Поделиться навыками с другими агентами на этом компьютере. Oleafly свяжет свои навыки, включая oleafly-cli, с папками, которые читают другие агенты для кода, такими как ~/.claude/skills, ~/.codex/skills и ~/.agents/skills. oleafly skills path выводит, где лежат навыки, для агентов, читающих другую папку.

Подключение агента по MCP

oleafly mcp работает как сервер MCP через стандартный ввод и вывод. Когда в приложении открыт ваш проект, он передаёт вызовы собственному серверу MCP приложения, поэтому агент получает все инструменты приложения и ваши запросы на одобрение. В остальных случаях он работает сам, с инструментами чтения (состояние проекта, карта проекта, файлы, поиск, журналы, отчёт doctor, поиск цитат) и compile. Копировать URL или токен не нужно, и устанавливать Node.js тоже не нужно.

Быстрее всего настроить так: oleafly mcp config --client и далее claude-code, claude-desktop, codex, cursor или gemini. Команда выводит запись для этого клиента; добавьте --write, чтобы запись была добавлена за вас, с резервной копией файла клиента. После этого перезапустите клиент или подключите его заново. Внутри проекта она записывает настройки проекта, а в остальных местах ваши пользовательские настройки, с полным путём к команде, потому что приложения, запущенные с рабочего стола, могут не видеть ваш PATH.

Claude Code

claude mcp add --scope user oleafly -- oleafly mcp

Внутри проекта вместо этого oleafly mcp config --client claude-code --write добавляет сервер в .mcp.json проекта.

Claude Desktop

Claude Desktop запускает серверы без папки проекта, поэтому его запись всегда работает через приложение: держите Oleafly открытым с вашим проектом. Используйте полный путь к oleafly. В Windows удвойте каждый обратный слеш в пути.

claude_desktop_config.json

{
  "mcpServers": {
    "oleafly": {
      "command": "/usr/local/bin/oleafly",
      "args": ["mcp", "--bridge", "always"]
    }
  }
}

Файл находится в ~/Library/Application Support/Claude на macOS и в %APPDATA%\Claude в Windows.

Codex

~/.codex/config.toml

[mcp_servers.oleafly]
command = "oleafly"
args = ["mcp"]
tool_timeout_sec = 300

Cursor

Используйте ~/.cursor/mcp.json для всех проектов или .cursor/mcp.json внутри одного проекта.

~/.cursor/mcp.json

{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"]
    }
  }
}

Gemini CLI

~/.gemini/settings.json

{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"],
      "timeout": 300000
    }
  }
}

Передайте агенту весь проект

oleafly context строит карту проекта: его файлы, структуру, метки, цитаты, отсутствующие файлы, неразрешённые ссылки и проблемы последней сборки. --format md выдаёт текст, который можно вставить в промпт; --format json выдаёт ту же карту для программы.

Проверка статьи перед подачей

oleafly check запускает предпроверку проекта с теми же результатами, что и панель «Предпроверка»: ссылки, цитаты, метки, отсутствующие файлы, поля библиографии, рисунки и анонимность для слепого рецензирования. Проверки, которым нужен скомпилированный PDF, используют последнюю сборку.

oleafly lint запускает проверки LaTeX и BibTeX и, в сборках, где они есть, проверку орфографии и грамматики. --fix применяет те исправления, которые безопасно применять.

Обе принимают --format human, json или sarif, а --exit-code заставляет их завершаться с кодом 9, если найдены проблемы. SARIF работает со службами сканирования кода, например GitHub: запишите отчёт командой oleafly check --format sarif -o preflight.sarif, загрузите его действием upload-sarif, и каждая находка появится на своей строке в pull request.

Синхронизация с онлайн-сервисом LaTeX

oleafly remote скачивает проекты из вашей учётной записи онлайн-сервиса LaTeX и синхронизирует папку с таким проектом тем же слиянием, которое использует приложение.

Вход

Данные входа хранятся в зашифрованном хранилище приложения, поэтому вход, выполненный в приложении, работает в командной строке, и наоборот.

• oleafly auth login online --with-token сохраняет токен Git из настроек учётной записи сервиса. Он нужен для привязки и синхронизации.
• oleafly auth login online --from-browser firefox копирует ваш вход из браузера на этом компьютере, чтобы получать список проектов и скачивать их. Firefox работает во всех системах; Chrome, Edge и Brave работают на macOS. --cookie-stdin вместо этого читает cookie сессии.
• oleafly auth login git --host https://gitlab.com сохраняет токен для хоста Git.
• oleafly auth status перечисляет все входы и откуда они взяты, не показывая секретов.
• oleafly auth logout удаляет вход.

Не оставляйте токены в истории оболочки

Токены передаются через стандартный ввод, например oleafly auth login online --with-token < token.txt, и никогда не в аргументах. В терминале команда запрашивает их, не показывая то, что вы вводите. oleafly auth token выводит сохранённый токен для скриптов, поэтому обращайтесь с её выводом как с паролем.

Импорт и синхронизация проектов

oleafly remote list
oleafly remote import 64a1f0c2e5b7 --into ~/papers
cd ~/papers/thesis
oleafly remote link
oleafly remote sync

• oleafly remote import скачивает проекты в новые папки. Работает с любой учётной записью.
• oleafly remote link связывает папку с её онлайн-проектом через интеграцию Git этого сервиса, для которой нужен токен Git.
• oleafly remote sync сливает изменения из онлайн-проекта в папку и отправляет ваши. --dry-run показывает, что изменилось бы, а --no-push сливает, ничего не отправляя.
• Если файл изменился с обеих сторон, синхронизация ничего не записывает и завершается с кодом 8. Запустите её снова с --resolve и путём к файлу, за которым идёт =local или =remote, для каждого файла.
• oleafly remote diff показывает различия; с --exit-code завершается с кодом 9, если файлы различаются, и 8, если они конфликтуют. --latexdiff --pdf собирает PDF с пометками ваших изменений с помощью latexdiff из вашего дистрибутива TeX.
• oleafly remote status, oleafly remote unlink и oleafly remote open показывают связь, удаляют её и открывают проект в браузере.

Работа с сервером Oleafly

oleafly server sign-in с адресом сервера выполняет вход в командной строке по коду, который вы подтверждаете в браузере. Для сервера командная строка считается отдельным устройством, не зависящим от приложения.

• oleafly server status и oleafly server projects показывают ваши серверы и общие проекты.
• oleafly server share показывает ссылку на проект и включает или выключает доступ по ссылке и комментарии.
• oleafly server members перечисляет людей в проекте, добавляет их, удаляет и меняет. Менять доступ и участников может только владелец.
• oleafly server comments показывает комментарии, добавляет их, отвечает на них и закрывает. Комментарий, который не удалось отправить сразу, сохраняется и отправляется в следующий раз.

Первый раз проектом делятся в приложении. См. Совместная работа в реальном времени.

Запуск агента Oleafly из терминала

oleafly ask отвечает на вопрос о проекте, ничего не меняя. oleafly agent run выполняет задачу.

oleafly ask "Which sections cite Smith 2021?"
oleafly agent run --allow write "Fix the overfull boxes in chapter 3"

• Агент всегда может читать проект. --allow добавляет write, commands или network, а всё, что вы не разрешили, он отклоняет. Он никогда не останавливается, чтобы задать вопрос.
• Изменения сначала попадают в папку для проверки в .oleafly/agent-runs/. oleafly agent apply с этой папкой записывает их в проект, а --apply при запуске записывает их сразу.
• Провайдер, модель и усилие берутся из настроек приложения или из --provider, --model и --effort. Ключ берётся из переменной окружения самого провайдера, например ANTHROPIC_API_KEY, или из зашифрованного хранилища приложения.
• --json выводит один результат по завершении запуска, а --events добавляет строку JSON для каждого события по ходу работы.

Продолжение исследовательских задач после выхода

Отметьте исследовательскую задачу параметром Продолжать работу, когда Oleafly закрыт. Когда вы выходите из приложения, небольшой фоновый помощник берёт эти задачи на себя, и их запуски экспериментов продолжаются. Шаг, которому нужно ваше одобрение, приостанавливает задачу и отправляет уведомление. Когда вы снова открываете Oleafly, он забирает задачи обратно и показывает, что произошло. Выключить это или запускать помощника при входе в систему можно в разделе Настройки → Исследования → Фоновые задачи. oleafly daemon status показывает, чем занят помощник.

Справочник команд

Каждая команда объясняет свои параметры по --help. Полный справочник находится в репозитории: docs/cli.md (откроется в новой вкладке).

Проекты и сборки

Команда	Что делает
oleafly open	Открывает папку в приложении (oleafly . для текущей)
oleafly init	Делает текущую папку проектом
oleafly new	Создаёт проект, из шаблона, если вы его указали
oleafly templates	Перечисляет шаблоны и показывает один из них
oleafly build	Собирает проект
oleafly watch	Пересобирает при каждом сохранении
oleafly clean	Удаляет результаты сборки
oleafly log	Показывает журнал последней сборки или её проблемы
oleafly doctor	Проверяет движки, приложение и вашу настройку
oleafly version	Показывает версию и используемые движки
oleafly project info	Показывает настройки проекта
oleafly projects list	Перечисляет проекты приложения
oleafly config	Читает и задаёт настройки проекта и приложения

Письмо и ссылки

Команда	Что делает
oleafly cite	Выводит BibTeX для DOI, идентификатора arXiv, ISBN или PubMed; --add добавляет запись в библиографию
oleafly literature	Ищет в OpenAlex, Semantic Scholar, Crossref, arXiv и PubMed
oleafly bib check	Находит записи, которым не соответствует ни одна реальная публикация
oleafly bib clean	Исправляет ключи цитирования и удаляет дубликаты; --apply записывает изменения
oleafly stats	Считает слова, заголовки, рисунки и формулы
oleafly synctex	Сопоставляет строку исходника с PDF и обратно
oleafly export	Экспортирует документ в Word, HTML, Markdown, EPUB и другие форматы
oleafly convert	Преобразует один файл в другой формат
oleafly typst	Показывает, устанавливает и удаляет версии Typst
oleafly checkpoint	Показывает, сравнивает и копирует контрольные точки приложения

Агенты и автоматизация

Команда	Что делает
oleafly context	Строит карту проекта для человека или агента
oleafly mcp	Запускает сервер MCP; mcp config настраивает клиент
oleafly skills	Перечисляет навыки и выводит, где они лежат
oleafly ask	Отвечает на вопрос о проекте
oleafly agent	Запускает агента Oleafly на задачу
oleafly daemon	Запускает помощника, который продолжает задачи, и управляет им

Проверки

Команда	Что делает
oleafly check	Запускает предпроверку
oleafly lint	Запускает проверки LaTeX, BibTeX, орфографии и грамматики

Учётные записи и синхронизация

Команда	Что делает
oleafly auth	Выполняет вход в онлайн-сервисы LaTeX, серверы Oleafly и хосты Git
oleafly remote	Импортирует, связывает и синхронизирует онлайн-проекты
oleafly server	Работает с серверами Oleafly: проекты, доступ, участники, комментарии

Оболочка и справка

Команда	Что делает
oleafly completions	Выводит автодополнение оболочки для bash, zsh, fish, PowerShell или elvish
oleafly man	Выводит страницу руководства
oleafly help exit-codes	Объясняет коды завершения

Параметры для любой команды

Параметр	Что делает
-C с путём	Выполняет команду для другой папки проекта
--json	Выводит один результат в JSON
--events	Выводит ход выполнения строками JSON перед результатом
--quiet	Выводит только результат
--log	Показывает журнал компилятора: none, tail или full
--no-input	Никогда не задаёт вопросов
--color	Использует цвет auto, always или never

Вывод для скриптов

Вывод в JSON

С --json каждая команда выводит один объект JSON: schema_version, ok, command, собственные поля команды и warnings. Когда команда завершается ошибкой, error содержит kind, постоянный code и message. Если это полезно, там же есть hint, details и "retryable": true, когда повторная попытка может помочь. Проверяйте schema_version, прежде чем полагаться на поле.

{
  "schema_version": 1,
  "type": "result",
  "ok": false,
  "command": "remote sync",
  "error": {
    "kind": "conflict",
    "code": "remote.conflicts",
    "message": "2 files changed both here and online.",
    "hint": "Pick a side with --resolve PATH=local or --resolve PATH=remote, then sync again.",
    "details": { "conflicts": ["main.tex", "refs.bib"] }
  },
  "warnings": []
}

--events добавляет перед результатом по одной строке JSON на каждое событие хода выполнения.

Коды завершения

oleafly help exit-codes выводит ту же таблицу.

Код	Значение
0	Всё получилось
1	Что-то пошло не так внутри Oleafly
2	Команда использована неверно или ей нужен --yes, чтобы продолжить
3	Проект отсутствует или недействителен, либо путь указывает за его пределы
4	Нужный инструмент или приложение Oleafly не установлены
5	Сборка не удалась
6	Нужно войти
7	Сбой сети
8	Проект занят чем-то другим, или при синхронизации есть конфликты
9	Проверка нашла проблемы
130	Вы нажали Ctrl+C

Вопросы, цвет и журналы

Без терминала команда никогда не задаёт вопросов. --no-input тоже отключает вопросы, как и переменная CI; команда, которой нужно «да», тогда завершается с кодом 2 и просит --yes. NO_COLOR или --color never отключают цвет. Пути, выходящие за пределы проекта, отклоняются.

Переменные окружения

Переменная	Назначение
OLEAFLY_DATA_DIR	Папка данных Oleafly, если это не ~/.oleafly
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOC	Компилятор, который нужно использовать вместо найденного Oleafly
OLEAFLY_APP	Приложение Oleafly, которое запускает oleafly open
OLEAFLY_ONLINE_GIT_TOKEN	Токен Git для онлайн-сервиса LaTeX, используется вместо сохранённого
OLEAFLY_CLI	Задаётся Oleafly для запускаемых им программ: полный путь к команде
CI	Если задана, команда никогда не задаёт вопросов
NO_COLOR	Если задана, вывод без цвета

Устранение неполадок

Что вы видите	Что попробовать
oleafly не найден	Откройте новый терминал. Затем проверьте командой Get-Command oleafly в Windows или command -v oleafly на macOS и Linux и добавьте в профиль оболочки строку, которую показывают настройки
oleafly doctor сообщает об отсутствующем движке	Установите его командой, которую выводит doctor, или один раз откройте проект в приложении
Клиент MCP не может запустить сервер	Выполните настроенную команду в терминале, используйте полный путь из oleafly mcp config и запустите oleafly doctor
Код завершения 6	Выполните oleafly auth status, затем войдите снова
Код завершения 8 при синхронизации	Запустите синхронизацию снова с --resolve для каждого файла из списка
На macOS в настройках написано «Сначала переместите Oleafly в папку „Программы“»	Переместите приложение, откройте его из «Программы», затем выберите Установить

Связанные страницы

• Проекты Typst
• Подключение через MCP
• CLI-агенты
• Предпроверка
• Исследовательские задачи