overleaf

Overleaf スキル

olcli CLI、ネイティブの git リモート、または MCP サーバーを使って Overleaf の LaTeX プロジェクトを管理します。

モードの使い分け

モード	最適な用途	方法
CLI (olcli)	対話型ワークフロー、同期、コンパイル、arXiv の準備	olcli pull/push/sync/pdf
Git リモート	バージョン管理、コミット、差分、CI/CD パイプライン	git clone overleaf::… の後、標準の git を使用
MCP サーバー	MCP に対応する AI エージェント（Claude、Cursor、Windsurf）	olcli-mcp の stdio トランスポートで接続

競合検出を伴う双方向同期、コンパイル、コメント管理が必要な場合は、CLI を使用します。適切な git 履歴、ブランチ、標準の git push/pull を使いたい場合は、Git リモートを使用します。AI エージェントが MCP にネイティブ対応しており、シェルコマンドを実行する必要がない場合は、MCP を使用します。

インストール

# Homebrew (recommended)
brew tap aloth/tap && brew install olcli

# npm
npm install -g @aloth/olcli

認証

Overleaf からセッション Cookie を取得します。

1. overleaf.com にログインします
2. DevTools（F12）を開き、［Application］→［Cookies］に移動します
3. overleaf_session2 の値をコピーします

olcli auth --cookie "YOUR_SESSION_COOKIE"

次のコマンドで確認します。

olcli whoami

認証の問題をデバッグします。

olcli check

保存済みの認証情報を消去します。

olcli logout

グローバル設定と、現在のディレクトリにある .olauth ファイルを消去し、それぞれについて報告します。環境変数は子プロセスから解除できないため、OVERLEAF_SESSION と OVERLEAF_EMAIL／OVERLEAF_PASSWORD は黙って無視せずに報告します。これらはディスク上のあらゆる設定よりも優先されます。

無人実行では、olcli auth --password よりも OVERLEAF_EMAIL／OVERLEAF_PASSWORD を使用してください。各コマンドがこれらの環境変数を読み取り、ディスクやシェルの履歴には何も書き込みません。

セルフホストの Overleaf

olcli config set-url https://overleaf.yourcompany.com
olcli config set-cookie-name overleaf.sid   # if different from default
olcli auth --cookie "YOUR_COOKIE"

または、コマンドごとに渡します。olcli --base-url https://overleaf.yourcompany.com list

Git リモートヘルパー

Overleaf のプロジェクトをネイティブの git リモートとして使用します。ラッパースクリプトは不要です。

# Clone
git clone overleaf::https://www.overleaf.com/project/<id>
cd <project>

# Edit, commit, push — standard git workflow
vim main.tex
git add . && git commit -m "update introduction"
git push

# Pull latest from Overleaf
git pull

認証では、OVERLEAF_SESSION 環境変数、現在のディレクトリにある .olauth ファイル、または保存済みの設定（CLI と同じ）を読み取ります。

セルフホストのインスタンスでは、インスタンスの URL をそのまま使用します。

git clone overleaf::https://overleaf.yourcompany.com/project/<id>

GIT_REMOTE_OVERLEAF_DEBUG=1 git push でデバッグします。

MCP サーバー

AI アシスタントと連携するための、組み込みの Model Context Protocol サーバーです。

# Run standalone
olcli-mcp

# Or via npx (the server is the olcli-mcp command of the @aloth/olcli package)
npx -y --package @aloth/olcli olcli-mcp

利用可能な MCP ツール：list_projects、get_project_info、pull_project、push_file、compile、download_pdf、list_comments、get_entities、download_file、add_comment、reply_to_comment、resolve_comment、delete_entity、rename_entity、rename_project、plan_project_renames、compile_with_outputs、diff_project、create_project、accept_tracked_changes、reject_tracked_changes。

compile、download_pdf、compile_with_outputs では、特定のルート文書をコンパイルするための resource_path を省略可能な引数として指定できます。

diff_project は olcli diff に相当する MCP ツールです。読み取り専用で、呼び出しごとにリモートの最新状態を取得し、変更されたファイルごとに path、status、binary、統一形式の patch を含むエントリを返します。パッチテキストを省略するには name_only を指定します。plan_project_renames は一括リネームをプレビューし、適用はしません。

認証では、MCP の設定で OVERLEAF_SESSION 環境変数を設定するか、olcli auth で保存した認証情報を使用します。

よくあるワークフロー

プロジェクトをローカルに取得する

olcli pull "My Paper"
cd My_Paper/

プロジェクトを作成する

olcli project create "My Paper"
olcli project create "Example Paper" --template example

変更を編集して同期する

# After editing files locally
olcli push              # Upload changes only
olcli sync              # Bidirectional sync (pull + push, propagates local deletions)
olcli sync --no-delete  # Sync without propagating local deletions to remote

プッシュ前に変更を確認する

olcli diff                 # unified diff of every changed file
olcli diff --name-only     # changed paths only
olcli diff --file main.tex # a single file
olcli diff --exit-code     # CI gate: 0 same, 1 differs, 2 failed

実行のたびにリモートの最新状態を取得するため、ここでは直近の pull との比較ではなく、その後の push で上書きされる内容が表示されます。a/ はリモート、b/ はローカルです。バイナリファイルはパッチなしで、差異があることだけが報告されます。

--exit-code は diff(1) と同じ終了ステータスを使うため、コマンドの結果に応じてパイプラインを制御できます。0 は差異なし、1 は差異あり、2 は実行自体の失敗を表します。最後のステータスは重要です。これがないと、変更されたファイルと期限切れのセッションをジョブで区別できません。このフラグがない場合、失敗時のステータスは引き続き 1 となるため、既存のスクリプトに影響はありません。

リモートファイルを削除またはリネームする

olcli delete chapters/old.tex          # remove a file from the project
olcli rm figures/old.pdf               # alias
olcli rename old.tex new.tex           # rename a file
olcli mv chapters/draft.tex chapters/intro.tex   # alias

ignore ルールを確認する

olcli ignored              # list active patterns (built-ins + .olignore + .olignore.local)
olcli push --show-ignored  # see what was filtered on this run
olcli sync --no-ignore     # escape hatch: upload everything

PDF のコンパイルとダウンロード

olcli pdf                      # Compile and download
olcli pdf -o paper.pdf         # Custom output name
olcli pdf -r chapters/intro.tex  # Compile a specific root document
olcli compile                  # Just compile (no download)
olcli compile -r appendix.tex  # Compile a specific root document without downloading

-r, --resource <path> は compile、pdf、output で使用でき、指定した .tex ファイルをルート文書としてコンパイルします。プロジェクトに複数の文書が含まれる場合に便利です。

arXiv への投稿用に .bbl をダウンロード

olcli output bbl               # Download compiled .bbl
olcli output bbl -o main.bbl   # Custom filename
olcli output bbl -r appendix.tex
olcli output --list            # List all available outputs

図やアセットをアップロード

olcli upload figure1.png "My Paper"          # Upload to project root
olcli upload diagram.pdf                      # Auto-detect project from .olcli.json
olcli upload figures/diagram.png              # Relative path is preserved remotely
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

リモートパスのルール：相対ローカルパスではディレクトリ部分が保持され、絶対ローカルパスではファイル名のみが使用されます。--to を指定すると、どちらよりも優先されます。

特定のファイルをダウンロード

olcli download main.tex "My Paper"           # Download single file
olcli zip "My Paper"                          # Download entire project as zip

レビューコメント

olcli comments list                          # List all comments (current project)
olcli comments list --status open            # Filter by status (open/resolved/all)
olcli comments list --context                # Include surrounding text
olcli comments add main.tex "Fix this citation" --from 10 --to 15  # Add comment
olcli comments reply <thread-id> "Done!"     # Reply to thread
olcli comments resolve <thread-id>           # Mark as resolved
olcli comments reopen <thread-id>            # Reopen a resolved thread
olcli comments delete <thread-id>            # Delete entire thread

arXiv 投稿ワークフロー

arXiv への投稿を準備するための一連のワークフローです。

# 1. Pull your project
olcli pull "Research Paper"
cd Research_Paper

# 2. Compile to ensure everything builds
olcli compile

# 3. Download the .bbl file (arXiv requires .bbl, not .bib)
olcli output bbl -o main.bbl

# 4. Download any other needed outputs
olcli output aux -o main.aux    # If needed

# 5. Package for submission
zip arxiv.zip *.tex main.bbl figures/*.pdf

# 6. Verify the package compiles locally (optional)
# Then upload arxiv.zip to arxiv.org

コマンドリファレンス

コマンド	説明
olcli auth --cookie <value>	セッション Cookie で認証します
olcli auth --email <e>	パスワードを入力して認証します（セルフホスト環境）
olcli whoami	認証状態を確認します
olcli logout	グローバル設定とローカルの .olauth を消去します
olcli check	設定パスと認証情報の取得元を表示します
olcli list	すべてのプロジェクトを一覧表示します
olcli project create <name>	空のプロジェクトまたはサンプルプロジェクトを作成します
olcli info [project]	プロジェクトの詳細を表示します
olcli pull [project] [dir]	プロジェクトのファイルをダウンロードします
olcli push [dir]	ローカルの変更をアップロードします
olcli sync [dir]	双方向で同期します
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 ignored [dir]	有効な無視パターンを一覧表示します
olcli zip [project]	ZIP アーカイブとしてダウンロードします
olcli compile [project]	コンパイルを実行します
olcli pdf [project]	コンパイルして PDF をダウンロードします
olcli output [type]	コンパイル出力をダウンロードします
olcli comments list [project]	レビューコメントを一覧表示します
olcli comments add <file> <msg>	コメントを追加します
olcli comments reply <id> <body>	スレッドに返信します
olcli comments resolve <id>	スレッドを解決済みにします
olcli comments reopen <id>	スレッドを再開します
olcli comments delete <id>	スレッドを削除します
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 project rename <newname> [project]	プロジェクトの名前を変更します
olcli project rename-bulk	パターンに基づいて複数のプロジェクトの名前を変更します（--apply を指定しない場合はドライランです）

ヒント

• プロジェクトの自動検出：同期済みディレクトリ（.olcli.json を含む）からコマンドを実行すると、プロジェクト引数を省略できます
• ドライラン：olcli push --dry-run または olcli sync --dry-run を使うと、適用前にプレビューできます
• コンテンツのプレビュー：push --dry-run は更新日時順にファイルを一覧表示します。olcli diff は実際の内容を比較するため、2つの一覧は異なる場合があります
• CI のゲート：olcli diff --exit-code は、差分がある場合は 1、実行に失敗した場合は 2 で終了するため、パイプラインで差分と障害を区別できます
• 強制的に上書き：olcli pull --force を使うと、ローカルの変更を上書きできます
• 双方向の削除：olcli sync はローカルでの削除をリモートに反映します。実行ごとに無効にするには --no-delete を使います
• ビルド成果物：.aux、.bbl、.log、.synctex.gz などはデフォルトで除外されます。カスタムパターンは .olignore ファイル（gitignore 形式）に追加します
• PDF のルール：thesis.tex と同じ場所にある thesis.pdf は自動的に無視されます。単独の figures/diagram.pdf は保持されます
• プロジェクト ID：プロジェクト名の代わりにプロジェクト ID（URL に含まれる 24 文字の 16 進数）を使用できます
• 認証のデバッグ：olcli check を実行すると、認証情報の読み込み元を確認できます
• タイムアウト：olcli --timeout 60000 pull "Big Project" または olcli config set-timeout 60000