コマンドラインツール

Windows、macOS、Linux に oleafly コマンドをインストールし、ターミナルや CI からプロジェクトをビルドしてチェックし、オンラインの LaTeX サービスと同期し、その MCP サーバーとスキルでコーディングエージェントを接続します。

Oleafly には oleafly というコマンドラインツールが付属しており、アプリと同じプロジェクトを扱えます。ターミナル、スクリプト、CI から論文をビルドしたりチェックしたりできます。コーディングエージェントに、プロジェクトへの確実な入り口を与えられます。オンラインの LaTeX サービスや Oleafly サーバーと同期したり、アプリを開かずに Oleafly のエージェントを実行したりもできます。

どのプラットフォームでも、アプリの中に同梱されています。このページでは、Oleafly 0.4.8 以降のコマンドを説明します。それより前のバージョンにはコマンドが少ないので、依存するスクリプトでは Oleafly のバージョンを固定してください。

インストール

システム	アプリが置いている場所	`oleafly` を PATH に通す
Windows	アプリの隣にある `oleafly-cli.exe`。セットアップ用プログラムなら `%LOCALAPPDATA%\Oleafly`、MSI パッケージなら `C:\Program Files\Oleafly`	設定 → 一般のターミナルコマンドの行でインストールを選ぶと、`%LOCALAPPDATA%\Oleafly\bin\oleafly.exe` にコピーされ、そのフォルダが PATH に追加されます
macOS	`Oleafly.app/Contents/MacOS/oleafly-cli`	ターミナルコマンドの行でインストールを選ぶと、`/usr/local/bin` に書き込める場合はそこに、書き込めない場合は `~/.local/bin` に、`oleafly` がリンクされます
Linux パッケージ（.deb、.rpm）	`/usr/bin/oleafly-cli`	何もする必要はありません。パッケージが `/usr/bin/oleafly` をインストールします
Linux の AppImage	AppImage の中	インストールを選ぶと、`~/.local/bin/oleafly` にコピーされます

Oleafly が起動するプログラム、たとえば Oleafly 自身のターミナルや CLI エージェントは、インストール前でも、PATH 上に必ず oleafly を見つけられます。OLEAFLY_CLI 変数には、そのフルパスが入っています。

Windows

設定 → 一般を開き、ターミナルコマンドの行でインストールを選びます。
新しい PowerShell またはコマンドプロンプトのウィンドウを開きます。すでに開いているウィンドウは、古い PATH のままです。
動作を確認します。

Get-Command oleafly
oleafly version

同じ行の取り除くは、コピーを削除し、そのフォルダを PATH からも外します。Oleafly を更新すると、次に起動したときにコピーが更新されます。

macOS

先に Oleafly を「アプリケーション」フォルダに移動してください。ディスクイメージから実行しているコピーでは、インストールの代わりに「先に Oleafly を『アプリケーション』フォルダに移動してから、ここでコマンドをインストールしてください。」と表示されます。

コマンドはアプリへのリンクなので、Oleafly を更新するとコマンドも更新されます。そのフォルダが PATH にない場合は、shell のプロファイルに追加する行が、その行に表示されます。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、テンプレートの ID を続けると、テンプレートからプロジェクトを作成します。oleafly templates list --all でテンプレートを一覧できます。
oleafly build は、アプリと同じように、プロジェクトのエンジンと設定を使います。Oleafly に付属の Tectonic、Typst、Pandoc、またはインストールした LaTeX です。--main はプロジェクトの別の文書をビルドし、--compiler は latexmk プロジェクトの LaTeX コンパイラを選び、-o は PDF を別の場所にコピーし、--timeout は制限時間を秒で指定します。
アプリでその場で開いたフォルダは、そこで選んだエンジンとメイン文書でビルドされ、出力はアプリ自身のビルドフォルダに置かれます。
アプリとコマンドが同じプロジェクトを同時にビルドすることはありません。あとから始めたほうが、先のものを待ちます。ビルドが失敗しても、最後に成功した PDF は残ります。
oleafly watch は、保存するたびに再ビルドします。oleafly log --diagnostics は、エラーと警告をファイルと行つきで一覧し、oleafly clean はビルドの出力を削除します。

Typst に固有の点については、Typst プロジェクトを参照してください。

コーディングエージェントから使う

コーディングエージェントは、このコマンドが提供する 3 つのものがあると、いちばんよく働きます。プロジェクトの地図になる oleafly context、読み取れる結果になる --json、何が問題だったかを伝える終了コードです。エージェントを接続する方法は 3 つあります。

oleafly-cli スキル

Oleafly には oleafly-cli というスキルが付属しています。コマンド、JSON 出力、終了コードと、いちばんうまくいく手順をエージェントに教えます。コンテキストを読み、編集し、ビルドし、診断を読み、最初のエラーを直す、という流れです。

Oleafly のターミナルと、Oleafly が起動する CLI エージェントでは、ほかのスキルと同じようにこのスキルを選びます。自分で実行するエージェントには、設定 → AI アシスタント → スキル → このコンピュータのほかのエージェントとスキルを共有をオンにします。すると 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 では、パスのバックスラッシュをすべて二重にします。

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

ファイルは、macOS では ~/Library/Application Support/Claude、Windows では %APPDATA%\Claude にあります。

Codex

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

Cursor

すべてのプロジェクトには ~/.cursor/mcp.json を、1 つのプロジェクトだけなら、その中の .cursor/mcp.json を使います。

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

Gemini CLI

{
  "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 アクションでアップロードすると、各指摘がプルリクエストの該当行に表示されます。

オンラインの 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 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 は、TeX ディストリビューションの latexdiff を使って、変更箇所に印を付けた PDF を作成します。
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 は、実行が終わったときに結果を 1 つ出力し、--events は、動作中のイベントごとに JSON の行を追加します。

終了後も調査タスクを動かし続ける

リサーチタスクのOleafly を閉じても実行を続けるをオンにします。Oleafly を終了すると、小さなバックグラウンドヘルパーがそれらのタスクを引き継ぎ、実験の実行が続きます。あなたの承認が必要なステップに来ると、タスクは一時停止し、通知が届きます。もう一度 Oleafly を開くと、タスクが Oleafly に戻り、何が起きたかが表示されます。これをオフにしたり、サインイン時にヘルパーを起動したりするには、設定 → 研究 → バックグラウンドタスクを開きます。oleafly daemon status は、ヘルパーが何をしているかを表示します。

コマンドリファレンス

すべてのコマンドは、--help でオプションを説明します。完全なリファレンスはリポジトリにあります。docs/cli.md （新しいタブで開きます）

プロジェクトとビルド

コマンド	内容
`oleafly open`	フォルダをアプリで開く（現在のフォルダなら `oleafly .`）
`oleafly init`	現在のフォルダをプロジェクトにする
`oleafly new`	プロジェクトを作成する。テンプレートを指定した場合はそこから作成する
`oleafly templates`	テンプレートを一覧し、1 つを表示する
`oleafly build`	プロジェクトをビルドする
`oleafly watch`	保存するたびに再ビルドする
`oleafly clean`	ビルドの出力を削除する
`oleafly log`	最後のビルドのログまたは問題を表示する
`oleafly doctor`	エンジン、アプリ、環境を確認する
`oleafly version`	バージョンと、使用中のエンジンを表示する
`oleafly project info`	プロジェクトの設定を表示する
`oleafly projects list`	アプリのプロジェクトを一覧する
`oleafly config`	プロジェクトとアプリの設定を取得、変更する

執筆と参考文献

コマンド	内容
`oleafly cite`	DOI、arXiv の ID、ISBN、PubMed の ID の BibTeX を表示する。`--add` で参考文献に追加する
`oleafly literature`	OpenAlex、Semantic Scholar、Crossref、arXiv、PubMed を検索する
`oleafly bib check`	実在する記録と一致しない項目を見つける
`oleafly bib clean`	引用キーを直し、重複を取り除く。`--apply` で変更を書き込む
`oleafly stats`	語数、見出し、図、数式を数える
`oleafly synctex`	ソースの行を PDF に対応づけ、PDF からソースにも戻す
`oleafly export`	文書を Word、HTML、Markdown、EPUB などに書き出す
`oleafly convert`	1 つのファイルを別の形式に変換する
`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 サーバーを扱う。プロジェクト、共有、メンバー、コメント

shell とヘルプ

コマンド	内容
`oleafly completions`	bash、zsh、fish、PowerShell、elvish 向けの shell 補完を表示する
`oleafly man`	マニュアルページを表示する
`oleafly help exit-codes`	終了コードを説明する

すべてのコマンドのオプション

オプション	内容
`-C` に続けてパス	コマンドを別のプロジェクトのフォルダで実行する
`--json`	JSON の結果を 1 つ出力する
`--events`	結果の前に、進捗を JSON の行として出力する
`--quiet`	結果だけを出力する
`--log`	コンパイラのログを `none`、`tail`、`full` のいずれかで表示する
`--no-input`	質問を一切しない
`--color`	色を `auto`、`always`、`never` のいずれかで使う

スクリプト向けの出力

JSON 出力

--json を付けると、すべてのコマンドが 1 つの 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 の行を 1 行ずつ追加します。

終了コード

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 open` が起動する Oleafly アプリ
`OLEAFLY_ONLINE_GIT_TOKEN`	オンラインの LaTeX サービス用の Git トークン。保存済みのものの代わりに使われる
`OLEAFLY_CLI`	Oleafly が起動するプログラムのために設定する。コマンドのフルパス
`CI`	設定されていると、コマンドは質問をしない
`NO_COLOR`	設定されていると、出力に色が付かない

トラブルシューティング

症状	試すこと
`oleafly` が見つからない	新しいターミナルを開きます。そのうえで、Windows では `Get-Command oleafly`、macOS と Linux では `command -v oleafly` で確認し、設定に表示される行を shell のプロファイルに追加します
`oleafly doctor` がエンジンの不足を報告する	doctor が表示するコマンドでインストールするか、アプリで一度プロジェクトを開きます
MCP クライアントがサーバーを起動できない	設定したコマンドをターミナルで実行し、`oleafly mcp config` が出力するフルパスを使い、`oleafly doctor` を実行します
終了コード 6	`oleafly auth status` を実行し、もう一度サインインします
同期中の終了コード 8	一覧されたファイルごとに `--resolve` を付けて、もう一度同期を実行します
macOS では、設定に「先に Oleafly を『アプリケーション』フォルダに移動してから、ここでコマンドをインストールしてください。」と表示される	アプリを移動し、アプリケーションから開いて、インストールを選びます