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

Установите команду oleafly на Windows, macOS или Linux, собирайте и проверяйте проекты из терминала или CI, синхронизируйтесь с онлайн-сервисом LaTeX и подключайте агентов для кода через её сервер MCP и навык.

В составе 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. Проверьте, что всё работает:

```powershell
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` с путём направляет команду в другое место.

```sh
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](/docs/typst/#build-from-the-command-line).

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

Агентам для кода лучше всего работается с тремя вещами, которые даёт команда: `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](/docs/mcp/) приложения, поэтому агент получает все инструменты приложения и ваши запросы на одобрение. В остальных случаях он работает сам, с инструментами чтения (состояние проекта, карта проекта, файлы, поиск, журналы, отчёт doctor, поиск цитат) и `compile`. Копировать URL или токен не нужно, и устанавливать Node.js тоже не нужно.

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

#### Claude Code

```sh
claude mcp add --scope user oleafly -- oleafly mcp
```

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

#### Claude Desktop

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

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "oleafly": {
      "command": "/usr/local/bin/oleafly",
      "args": ["mcp", "--bridge", "always"]
    }
  }
}
```

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

#### Codex

```toml title="~/.codex/config.toml"
[mcp_servers.oleafly]
command = "oleafly"
args = ["mcp"]
tool_timeout_sec = 300
```

#### Cursor

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

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"]
    }
  }
}
```

#### Gemini CLI

```json title="~/.gemini/settings.json"
{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"],
      "timeout": 300000
    }
  }
}
```

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

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

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

`oleafly check` запускает [предпроверку](/docs/preflight/) проекта с теми же результатами, что и панель «Предпроверка»: ссылки, цитаты, метки, отсутствующие файлы, поля библиографии, рисунки и анонимность для слепого рецензирования. Проверки, которым нужен скомпилированный 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` удаляет вход.

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

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

```sh
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` показывает комментарии, добавляет их, отвечает на них и закрывает. Комментарий, который не удалось отправить сразу, сохраняется и отправляется в следующий раз.

Первый раз проектом делятся в приложении. См. [Совместная работа в реальном времени](/docs/collaboration/).

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

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

```sh
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 для каждого события по ходу работы.

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

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

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

Каждая команда объясняет свои параметры по `--help`. Полный справочник находится в репозитории: [docs/cli.md](https://github.com/Oleafly/Oleafly/blob/main/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`, прежде чем полагаться на поле.

```json
{
  "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](/docs/typst/#build-from-the-command-line)
- [Подключение через MCP](/docs/mcp/)
- [CLI-агенты](/docs/cli-agents/)
- [Предпроверка](/docs/preflight/)
- [Исследовательские задачи](/docs/research-tasks/)