olcli

olcli — Overleaf CLI

Overleaf用コマンドラインインターフェース — ターミナルからLaTeXプロジェクトを同期、管理、コンパイルできます。

コマンドラインからOverleafプロジェクトを直接操作できます。お気に入りのエディターでローカル編集し、Gitでバージョン管理しながら、Overleafのクラウドコンパイルとシームレスに同期できます。

機能

• 📋 Overleafプロジェクトをすべて一覧表示
• ✨ 空のプロジェクトやサンプルプロジェクトを作成
• ⬇️ オフライン編集用にプロジェクトファイルをローカルディレクトリへプル
• ⬆️ ローカルの変更をOverleafへプッシュ
• 🔄 スマートな競合検出機能で双方向に同期
• 🔍 プッシュ前にローカルファイルとリモート上の最新ファイルを差分比較
• 📝 マークアップ付き改訂版 — diff --latexdiffを実行すると、指導教員や学術誌が求める取り消し線と下線付きのPDFを生成します
• 🔀 Gitリモート — OverleafをネイティブのGitリモートとして使用できます（ドキュメント）
• ✌️ 双方向の削除 — ローカルで削除したファイルは、次回の同期時にOverleafでも削除されます
• 🗑️ パスを指定してリモートファイルを削除、✏️ 名前変更
• 🚫 スマートな除外 — LaTeXのビルド生成物やOS関連の不要ファイルを自動で除外します。.olignoreで対象を追加できます
• 📄 Overleafのリモートコンパイラーを使ってPDFをコンパイル
• 📦 個別ファイルやプロジェクト全体のアーカイブをダウンロード
• 📤 プロジェクトにファイルをアップロード
• 💬 レビューコメント — スレッドの一覧表示、追加、解決、再開、削除、返信ができます
• 🗂️ ネストされたファイルをプッシュする際にフォルダー構造を保持
• ⏱️ 接続が遅い場合に備えてタイムアウトを設定可能
• 🔑 セルフホスト環境向けのパスワードログイン（ブラウザー不要）
• ⚙️ セルフホスト版Overleaf/ShareLaTeXに対応
• 📊 コンパイル生成物を出力（arXivへの投稿用の.bbl、.log、.aux）
• 🤖 AIアシスタント向けのMCP サーバー（ドキュメント）

次のような用途に最適です：

• 好みのテキストエディター（Vim、VS Code、Emacsなど）でLaTeXを編集する
• Overleafのコンパイラーを使いながらGitでバージョン管理する
• ワークフローやCI/CDパイプラインを自動化する
• オフラインで作業し、定期的に同期する

インストール

Homebrew（macOS/Linux）

brew tap aloth/tap
brew install olcli

npm（すべてのプラットフォーム）

npm install -g @aloth/olcli

インストールせずにnpxで実行することもできます：

npx @aloth/olcli list

AIエージェント向け（AgentSkills経由）

npx skills add aloth/olcli

クイックスタート

1. 認証する

セッションクッキー（overleaf.comおよびセルフホスト環境）：

olcli auth --cookie "your_session_cookie_value"

メールアドレスとパスワード（reCAPTCHAのないセルフホスト環境）：

olcli auth --email "[email protected]"
# prompts for the password, so it stays out of your shell history

--save-passwordを指定しない限り、パスワードは保存されません。どちらの場合もセッションクッキーが保存され、以降のコマンドではこちらが使用されます。パスワードは、セッションクッキーの期限が切れた際に自動で再ログインするためにのみ使われます。スクリプトではOVERLEAF_EMAILとOVERLEAF_PASSWORDを設定してください。これらはすべてのコマンドで読み込まれるため、スクリプトの実行時にolcli authを実行する必要はありません。

2. プロジェクトを一覧表示する

olcli list

3. プル、編集、プッシュする

olcli pull "My Thesis"
cd My_Thesis/
vim main.tex
olcli push

4. PDFをコンパイルする

olcli pdf
# Compile a specific .tex file (for multi-doc projects):
olcli pdf -r appendix.tex

5. またはネイティブのGitコマンドを使う

git clone overleaf::https://www.overleaf.com/project/<id>
cd <project>
# edit, commit, push — standard git workflow
git push

詳しくはGitリモートヘルパーのドキュメントをご覧ください。

コマンド

同期済みディレクトリ（.olcli.json を含むディレクトリ）から実行すると、すべてのコマンドでプロジェクトが自動検出されます。

コマンド	説明
olcli auth	セッション Cookie を設定するか、メールアドレスとパスワードでログインします
olcli whoami	認証状態を確認します
olcli logout	グローバル設定とローカルの .olauth を消去し、それぞれについて報告します
olcli list	すべてのプロジェクトを一覧表示します
olcli info [project]	プロジェクトの詳細とファイル一覧を表示します
olcli pull [project] [dir]	プロジェクトのファイルをローカルディレクトリにダウンロードします
olcli push [dir]	ローカルの変更を Overleaf にアップロードします（--delete を指定すると、ローカルで削除されたファイルも削除されます）
olcli sync [dir]	双方向で同期します（pull + push）
olcli diff [project] [dir]	ローカルファイルとリモート間の内容レベルの変更を表示します
olcli upload <file> [project]	単一のファイルをアップロードします（--to <path> でリモートの保存先を指定します）
olcli download <file> [project]	単一のファイルをダウンロードします
olcli delete <file> [project]	リモートのファイルまたはフォルダーを削除します（別名：rm）
olcli rename <old> <new> [project]	リモートのファイルまたはフォルダーの名前を変更します（別名：mv）
olcli project create <name>	空のプロジェクトまたはサンプルプロジェクトを作成します（--template blank|example）
olcli project rename <new> [project]	プロジェクト自体の名前を変更します（--dry-run）
olcli project rename-bulk	パターンに一致する複数のプロジェクトの名前を変更します（--apply を指定しない場合はドライラン）
olcli compile [project]	PDF のコンパイルを開始します
olcli pdf [project]	コンパイルして PDF をダウンロードします
olcli output [type]	コンパイル出力ファイルをダウンロードします
olcli zip [project]	プロジェクトを zip アーカイブとしてダウンロードします
olcli comments list [project]	コメントを一覧表示します（--status、--context、--concurrency）。--changes を指定すると、追跡された変更も一覧表示します（--json を指定すると、出力は { comments, changes } になります）
olcli changes accept <ids...>	ID を指定して追跡された変更を承認します（--project、--json）
olcli changes reject <ids...>	ID を指定して追跡された変更を却下します。--yes を指定しない場合はプレビューのみです（--project、--json）
olcli comments add <file> <msg>	選択したテキストにコメントを追加します
olcli comments reply <id> <body>	コメントスレッドに返信します
olcli comments resolve <id>	コメントスレッドを解決済みにします
olcli comments reopen <id>	解決済みのスレッドを再開します
olcli comments delete <id>	コメントスレッドを削除します
olcli ignored [dir]	適用されている除外パターンを一覧表示します
olcli config set-url <url>	セルフホスト版のベース URL を設定します
olcli config get-url	設定済みのベース URL を表示します
olcli config set-cookie-name <name>	セッション Cookie 名を設定します
olcli config get-cookie-name	設定済みのセッション Cookie 名を表示します
olcli config set-timeout <ms>	デフォルトの HTTP タイムアウトを設定します
olcli config get-timeout	設定済みの HTTP タイムアウトを表示します
olcli check	設定ファイルのパスと認証情報の取得元を表示します

追跡された変更は Overleaf のプレミアム機能です。 プロジェクトの所有者がプレミアムプランに加入している場合にのみ、そのプロジェクトで利用できます。その場合、招待された共同作業者は自身のプランにかかわらず利用できます。それ以外のプロジェクトには追跡された変更がないため、--changes は空の一覧を返し、changes accept／changes reject は指定された ID が見つからないことを報告します。詳しくは、Overleaf のドキュメントをご覧ください。

コンパイルオプション

コンパイル関連のコマンド（compile、pdf、output）では、次のオプションを指定できます。

フラグ	説明
-r, --resource <path>	特定の .tex ファイルをルート文書としてコンパイルします（例：appendix.tex、folder/test.tex）

複数の文書を含むプロジェクトで便利です。各 -r の実行では、指定したファイルをメイン文書としてコンパイルします。

グローバルオプション

フラグ	説明
--verbose	HTTP リクエストとレスポンスを標準エラー出力に表示します
--base-url <url>	Overleaf インスタンスの URL を上書きします
--cookie-name <name>	セッション Cookie 名を上書きします
--timeout <ms>	HTTP タイムアウトを上書きします（デフォルト：10000）

同期の動作

プル

• Overleaf からすべてのファイルをダウンロードします
• 最後のプル後に変更されたローカルファイルはスキップします（変更を上書きしません）
• --force を使うとローカルの変更を上書きします

プッシュ

• 最後のプル後に変更されたファイルをアップロードします
• ネストされたフォルダー構造を維持します
• LaTeX のビルド成果物と OS の不要なファイルを除外します
• --all を使うとすべてのファイルをアップロードし、--dry-run を使うと事前に確認できます

同期

• リモートの変更をプルしてから、ローカルの変更をプッシュします
• 新しい方のローカルの変更が優先されます
• ローカルでの削除も反映されます — 無効にするには --no-delete を使います
• --dry-run を使うと、適用せずに事前確認できます

差分

olcli diff は、ローカルファイルのバイト列をプロジェクトの現在の内容と比較し、統合差分を表示します。

olcli diff                 # every changed file, as patches
olcli diff --name-only     # just the changed paths
olcli diff --file main.tex # one file
olcli diff -U 8            # wider context
olcli diff --exit-code     # exit 1 if anything differs, for CI

リモート側の内容は実行のたびに最新の状態が取得されます。 差分は、その時点でのプロジェクトの状態を示します。つまり、最後の pull との比較ではなく、その後の push で上書きされる内容との比較です。.olcli.json に記録されるのはリモートの パス であり、リモートの 内容 ではないため、比較対象となる保存済みスナップショットはありません。また、プロジェクト全体は pull と同じ1回のリクエストで取得されるため、最新の内容を取得するのに必要な往復はファイルごとではなく1回です。diff と push の間に共同作業者が編集すると結果が変わる可能性があるため、取得時刻が表示されます。

出力では、a/ がリモート、b/ がローカルです。+ の行は push でアップロードされる内容、- の行は上書きされる内容です。テキスト以外のバイト列（PDF、画像）だけが異なるファイルは、Binary files ... differ として報告されます。両方の側に同じ除外ルールが適用されるため、Overleaf にあるビルド成果物がローカルで削除されたものとして報告されることはありません。

diff --name-only と push --dry-run は異なる問いに答えるため、結果も一致しません。push --dry-run は、push のアップロード対象となる、最後のプル以降に更新日時が新しくなったファイルを一覧表示します。一方、diff は、内容が実際に異なるファイルを一覧表示します。編集せずにファイルを更新した場合、前者には表示されますが、後者には表示されません。

latexdiff による変更履歴のマークアップ

統合差分は開発者には適していますが、論文の指導教員には適していません。--latexdiff を使うと、代わりにドキュメント内で同じ変更箇所をマークアップします。削除箇所には取り消し線を引き、追加箇所には下線を引きます。これは指導教員や学術誌が求める形式です。

olcli diff --latexdiff          # write .olcli-diff/main-diff.tex
olcli diff --latexdiff --pdf    # ...and compile it, download .olcli-diff/main-diff.pdf

PATH 上に latexdiff が必要です。TeX Live と MacTeX に含まれているため、olcli diff で外部ツールが必要になるのはこれだけです。

--pdf は Overleaf 上でコンパイルするため、ローカルに TeX をインストールする必要はありません。 コンパイル用エンドポイントでビルドできるのはプロジェクト内にあるファイルだけです。そのため、マークアップしたドキュメントはルートドキュメントと同じ場所に olcli-latexdiff.tex としてアップロードされ、コンパイルとダウンロードの後に削除されます。コマンドは実行前にその旨を表示し、同名のファイルがすでに存在する場合は上書きを拒否します。クリーンアップに失敗した場合は、実行に使う正確な olcli rm コマンドを表示します。

比較の前に \input と \include をインライン化します（無効にするには --no-flatten を使います）。これを行わないと、リモートでのコンパイル時に、プロジェクト内にある古い内容のファイルが参照され、すべての入力ファイルに変更がないことを示す PDF が気付かないうちに生成されます。

出力先は .olcli-diff/ です。ディレクトリ名の先頭にドットが付いているため、push と sync の対象にはなりません。別の場所に出力するには -o <path> を使います。ルートドキュメントは \documentclass を宣言している .tex ファイルです。複数ある場合は、コマンドに推測させるのではなく --main <path> で1つを指定します。--latexdiff-opt を使うと、それ以外のオプションをそのまま渡せます。例：--latexdiff-opt --math-markup=0。

留意すべき制限が1つあります。--pdf は作業ディレクトリではなくプロジェクトを使ってコンパイルするため、マークアップに必要なファイルはすでに Overleaf 上にある必要があります。ローカルで追加した .sty または .cls があるとコンパイルに失敗し、その場合はコンパイラーログがマークアップ済みソースの隣に書き込まれます。ローカルで追加した 図 があってもコンパイルには失敗しません。Overleaf は欠落しているファイル名を示すプレースホルダーボックスを描画し、PDF の残りの部分は正常に生成されます。

diff を CI ゲートとして使う

--exit-code を指定すると、コマンドは diff(1) と同じ終了ステータスを返すチェックとして動作します。

ステータス	意味
0	差分はありません
1	差分があります
2	実行に失敗しました — 不正なフラグ、セッションなし、プロジェクトにアクセスできない

- name: Fail if the paper on Overleaf has drifted from the repo
  run: olcli diff --exit-code --name-only
  env:
    OVERLEAF_SESSION: ${{ secrets.OVERLEAF_SESSION }}

このフラグの要点は、1 と 2 を区別できることです。 このフラグがないと、パイプラインはファイルが変更されたのか、セッション Cookie の有効期限が切れたのかを判別できません。後者の理由でジョブが失敗すると、ログを読む人は計算されていない差分を探し回ることになります。その他のすべての olcli コマンドは失敗を 1 として報告します。また、--exit-code を指定しない場合、olcli diff も引き続き 1 を返すため、このフラグを追加しても既存のスクリプトから見える動作は変わりません。

ゲートの対象は比較した範囲です。--file main.tex を指定すると、git diff --exit-code のパス指定と同様に、対象を 1 つのファイルに絞り込めます。また、一致するファイルがない --file はエラーではなく 0 になります。--latexdiff を使う場合も、プロジェクト全体を対象に報告します。マークアップされたルートドキュメントには変更された図を表示できなくても、図の変更は実際の差分だからです。

この比較対象は、最後にプルした時点ではなく、現在の Overleaf であることに注意してください。そのため、チェックの目的は「ここでコミットされた内容から誰かが変更を加えていないか」です。プッシュ時だけでなく、定期的に実行する価値があるのはそのためです。

削除の反映方法

olcli はリモートファイルのマニフェストを .olcli.json に記録します。次回の同期では、次のように処理されます。

• ローカルにファイルがなく、リモートにはある → Overleaf で削除
• ローカルに新しいファイルがある → アップロード
• ローカルのファイルが変更されている → アップロード（ローカルを優先）
• リモートにのみファイルがある → ダウンロード

初回の同期では、比較対象となる以前のマニフェストがないため、削除の処理はスキップされます。

ファイルを無視する

3 つのレイヤー

レイヤー	ソース	目的
1	組み込み	LaTeX の中間ファイル、OS の不要ファイル、ビルドディレクトリ。常に有効です。
2	.olignore	プロジェクト単位のパターン（gitignore 構文）。
3	.olignore.local	マシン固有のパターン。

後のレイヤーが前のレイヤーを上書きします。否定パターン（!important.aux）もサポートされています。

PDF に関する特別なルール

X.tex（または .ltx）が同じフォルダーに存在する場合に限り、X.pdf は無視されます。

確認と上書き

olcli ignored                  # list patterns in effect
olcli push --show-ignored      # see what was skipped
olcli sync --no-default-ignore # only .olignore applies
olcli sync --no-ignore         # upload everything

設定

認証情報は次の順序で確認されます。

1. OVERLEAF_SESSION 環境変数
2. カレントディレクトリの .olauth ファイル
3. グローバル設定 — 正確なパスを確認するには olcli check を実行します

グローバル設定のパスはプラットフォームによって異なり（conf が解決します）、ここではハードコードされていません。macOS では ~/Library/Preferences/ の下、Linux では ~/.config/ の下に配置されます。olcli auth は書き込み先のパスを表示します。

⚠️ olcli auth --save-local は、カレントディレクトリに .olauth を書き込みます。通常は LaTeX プロジェクトのディレクトリです。コミットする前に、そのプロジェクトの .gitignore に追加してください。

保存されるものと削除方法

すべての情報はプレーンテキストで保存されるため、ディスク上に何が保存されているか把握しておくことが大切です。

認証情報	デフォルトで保存	場所
セッション Cookie	はい	グローバル設定、または --save-local を指定した場合は .olauth
メールアドレス + パスワード	いいえ — --save-password を指定した場合のみ	グローバル設定

olcli check は、秘密情報を表示せずに、何が存在するかを報告します。

olcli logout は、グローバル設定とカレントディレクトリの .olauth ファイルを削除し、削除した項目を一覧表示します。環境変数は解除できないため、OVERLEAF_SESSION または OVERLEAF_EMAIL/OVERLEAF_PASSWORD が設定されている場合は、ログアウトしたと誤解させる代わりに、そのことを通知します。これらの環境変数はディスク上の情報より優先されます。

セルフホスト版 Overleaf

olcli config set-url https://latex.example.org
olcli config set-cookie-name overleaf.sid

または、コマンドごとに指定します：olcli --base-url https://latex.example.org list

タイムアウト

olcli config set-timeout 60000          # persist
olcli --timeout 60000 pull "Big Thesis" # one-off
export OVERLEAF_TIMEOUT=60000           # env var

優先順位：--timeout > OVERLEAF_TIMEOUT > 設定 > デフォルト（10000ms）。

環境変数

olcli は以下の環境変数を読み取ります。MCP サーバーと Git リモートヘルパーは、同じセッション、パスワード、Cookie 名の変数を読み取ります。フラグがある場合はフラグが環境変数より優先され、環境変数は保存済みの設定より優先されます。

変数	用途
OVERLEAF_SESSION	セッション Cookie の値
OVERLEAF_EMAIL、OVERLEAF_PASSWORD	パスワードログインに使用します。セッション Cookie が設定されていない場合、または拒否された場合に使用されます
OVERLEAF_BASE_URL	インスタンスの URL。--base-url と同様です（デフォルト：https://www.overleaf.com）
OVERLEAF_COOKIE_NAME	セッション Cookie 名。--cookie-name と同様です（デフォルト：overleaf_session2。セルフホストのインスタンスでは overleaf.sid がよく使われます）
OVERLEAF_TIMEOUT	HTTP タイムアウト（ミリ秒）。--timeout と同様です
OLCLI_CONCURRENCY	comments list で並列に取得するドキュメント数（1～8、デフォルト：4）。--concurrency が優先されます
OLCLI_MCP_UNCONFIRMED_WRITES	MCP サーバーのみ：1 にすると書き込み確認を無効にします。docs/MCP.md を参照してください
GIT_REMOTE_OVERLEAF_DEBUG	Git リモートヘルパーのみ：1 にするとプロトコルのデバッグ出力を表示します。docs/GIT-REMOTE.md を参照してください

使用例

# Daily thesis workflow
olcli pull "PhD Thesis" thesis && cd thesis
vim chapters/methods.tex
olcli sync && olcli pdf -o draft.pdf

# Quick PDF download
olcli pdf "Conference Paper" -o paper.pdf

# Compile a specific root document
olcli pdf "Conference Paper" -r appendix.tex -o appendix.pdf
olcli compile "Conference Paper" -r folder/test.tex

# Upload figures
olcli upload figures/diagram.png          # relative path is preserved
olcli upload /tmp/build/diagram.png       # absolute path lands in the project root
olcli upload /tmp/build/diagram.png --to figures/diagram.png   # explicit destination

# arXiv submission prep
olcli output bbl -o main.bbl
olcli output bbl -r folder/test.tex -o main.bbl  # compile artifacts from a specific root doc
olcli zip -o arxiv-submission.zip

# Backup all projects
for proj in $(olcli list --json | jq -r '.[].name'); do
  olcli zip "$proj" -o "backups/${proj}.zip"
done

プログラムからの使用（ライブラリ API）

@aloth/olcli は、OverleafClient とすべての公開インターフェースをライブラリとして公開しています。

インストール

npm install @aloth/olcli

基本的な例

import { OverleafClient } from '@aloth/olcli';

const client = await OverleafClient.fromSessionCookie(cookie);

const created = await client.createProject('My Paper');
const projects = await client.listProjects();
const info = await client.getProjectInfo(projectId);
const zipBuf = await client.downloadProject(projectId);
const pdfBuf = await client.downloadPdf(projectId);

await client.uploadFile(projectId, null, 'main.tex', readFileSync('main.tex'));

const comments = await client.listComments(projectId, { status: 'open' });

利用可能なエクスポート

import {
  OverleafClient,
  // Types
  Project, ProjectInfo, ProjectTemplate, CreateProjectOptions, CreatedProject,
  FolderEntry, DocEntry, FileEntry,
  CommentMessage, ProjectComment, CommentContext, CommentStatus,
  ListCommentsOptions, AddCommentOptions, Credentials, SessionCookiePair,
  // Config utilities
  getBaseUrl, setBaseUrl, getSessionCookie, setSessionCookie,
  getSessionCookieName, setSessionCookieName, getCsrf, setCsrf,
  getLastProject, setLastProject, clearConfig, getConfigPath, saveOlAuth,
  getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials,
  clearPasswordCredentials, type PasswordCredentials,
  // Ignore utilities
  DEFAULT_IGNORE_PATTERNS, loadIgnore, shouldIgnore, buildTexSiblingSet,
  IgnoreContext, LoadIgnoreOptions,
} from '@aloth/olcli';

その他のドキュメント

• MCP サーバー — AI アシスタントとの連携（Claude、Cursor、Windsurf）
  • プロジェクトを変更するツールでは、MCP のエリシテーションを通じて確認を求め、確認なしに書き込みを行いません。エリシテーションに対応していないクライアントには、プレビューと、代わりに実行する olcli コマンドが表示されます。OLCLI_MCP_UNCONFIRMED_WRITES=1 にすると、これを無効にします。書き込みの確認 を参照してください
• Git リモートヘルパー — Overleaf をネイティブの Git リモートとして使用します

トラブルシューティング

セッションの有効期限が切れた場合 — ブラウザーから新しい Cookie を取得し、再度 olcli auth を実行してください。

コンパイルに失敗する場合 — Overleaf のウェブエディターで詳細なエラーログ（不足しているパッケージ、構文エラー、不足している参考文献ファイルなど）を確認してください。

コントリビューション

コントリビューションを歓迎します！イシューを作成するか、プルリクエストを送信してください。

ローカル環境のセットアップ方法、実際の Overleaf アカウントが必要なテスト、プルリクエスト時に CI で行われることについては、CONTRIBUTING.md を参照してください。

docs/ARCHITECTURE.md では、クライアントの仕組みを説明しています。Overleaf には公開 API がないため、ブラウザーセッションとして認証します。

ライセンス

MIT © Alexander Loth