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

Разом з 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. Перевірте, що це працює:

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 і в агентах командного рядка, які він запускає, вибирайте навичку, як і будь-яку іншу. Для агента, якого ви запускаєте самостійно, увімкніть Налаштування → Асистент ШІ → Навички → Ділитися навичками з іншими агентами на цьому комп’ютері. Тоді 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
• Агенти командного рядка
• Передперевірки
• Дослідницькі завдання