# Інструмент командного рядка

Встановіть команду 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, як-от його власний термінал і агенти командного рядка, завжди знаходять `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 і в агентах командного рядка, які він запускає, вибирайте навичку, як і будь-яку іншу. Для агента, якого ви запускаєте самостійно, увімкніть **Налаштування → Асистент ШІ → Навички → Ділитися навичками з іншими агентами на цьому комп’ютері**. Тоді 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/)
- [Агенти командного рядка](/docs/cli-agents/)
- [Передперевірки](/docs/preflight/)
- [Дослідницькі завдання](/docs/research-tasks/)