name: overleaf description: Sync and manage Overleaf LaTeX projects from the command line. Pull projects locally, push changes back, compile PDFs, and download compile outputs like .bbl files for arXiv submissions. Use when working with LaTeX, Overleaf, academic papers, or arXiv. license: MIT metadata: author: aloth version: "1.3" cli: olcli install: brew tap aloth/tap && brew install olcli

Overleaf Skill

Manage Overleaf LaTeX projects via the olcli CLI, native git remote, or MCP server.

When to Use Which Mode

Use CLI when you need bidirectional sync with conflict detection, compilation, or comment management. Use Git remote when you want proper git history, branches, and standard git push/pull. Use MCP when an AI agent has native MCP support and doesn't need to shell out.

Installation

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

# npm
npm install -g @aloth/olcli

Authentication

Get your session cookie from Overleaf:

1. Log into overleaf.com
2. Open DevTools (F12) → Application → Cookies
3. Copy the value of overleaf_session2

olcli auth --cookie "YOUR_SESSION_COOKIE"

Verify with:

olcli whoami

Debug authentication issues:

olcli check

Clear stored credentials:

olcli logout

Clears the global config and the .olauth file in the current directory, and reports each. Environment variables cannot be unset by a child process, so OVERLEAF_SESSION and OVERLEAF_EMAIL/OVERLEAF_PASSWORD are reported rather than silently ignored — they outrank anything on disk.

For unattended use, prefer OVERLEAF_EMAIL/OVERLEAF_PASSWORD over olcli auth --password: every command reads them, and nothing is written to disk or to shell history.

Self-hosted 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"

Or pass per-command: olcli --base-url https://overleaf.yourcompany.com list

Git Remote Helper

Use Overleaf projects as native git remotes. No wrapper scripts needed.

# 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

Authentication: reads OVERLEAF_SESSION env var, ~/.olauth file, or stored config (same as CLI).

For self-hosted instances, just use your instance URL:

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

Debug with: GIT_REMOTE_OVERLEAF_DEBUG=1 git push

MCP Server

Built-in Model Context Protocol server for AI assistant integration.

# Run standalone
olcli-mcp

# Or via npx
npx @aloth/olcli-mcp

Available MCP tools: 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.

compile, download_pdf and compile_with_outputs accept an optional resource_path to compile a specific root document.

diff_project is the MCP counterpart of olcli diff: read-only, fetches the remote fresh on every call, and returns one entry per changed file with path, status, binary and a unified patch. Pass name_only to drop the patch text. plan_project_renames previews bulk renames and never applies them.

Auth: set OVERLEAF_SESSION env var in MCP config, or use stored credentials from olcli auth.

Common Workflows

Pull a project to work locally

olcli pull "My Paper"
cd My_Paper/

Create a project

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

Edit and sync changes

# 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

Review changes before pushing

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

The remote side is fetched fresh each run, so this shows what a subsequent push would overwrite — not a comparison against the last pull. a/ is the remote, b/ is local. Binary files are reported as differing without a patch.

--exit-code uses diff(1)'s statuses so the command can gate a pipeline: 0 nothing differs, 1 something does, 2 the run itself failed. The last one matters — without it a job cannot tell a changed file from an expired session. Failures stay 1 when the flag is absent, so existing scripts are unaffected.

Delete or rename remote files

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

Inspect ignore rules

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

Compile and download 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> works on compile, pdf, and output: it compiles the given .tex file as the root document. Useful when a project contains several documents.

Download .bbl for arXiv submission

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

Upload figures or assets

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

Remote path rules: a relative local path keeps its directory part, an absolute local path collapses to its basename, and --to overrides both.

Download specific files

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

Review comments

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 Submission Workflow

Complete workflow for preparing an arXiv submission:

# 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

Commands Reference

Tips

• Auto-detect project: Run commands from a synced directory (contains .olcli.json) to skip the project argument
• Dry run: Use olcli push --dry-run or olcli sync --dry-run to preview before applying
• Preview content: push --dry-run lists files by modification time; olcli diff compares actual contents, so the two lists can differ
• CI gate: olcli diff --exit-code exits 1 when anything differs and 2 when the run failed, so a pipeline can distinguish drift from breakage
• Force overwrite: Use olcli pull --force to overwrite local changes
• Two-way deletes: olcli sync propagates local deletions to the remote; use --no-delete to opt out per run
• Build artifacts: .aux, .bbl, .log, .synctex.gz etc. are filtered by default. Add custom patterns to a .olignore file (gitignore-style)
• PDF rule: thesis.pdf next to thesis.tex is auto-ignored; standalone figures/diagram.pdf is preserved
• Project ID: You can use project ID instead of name (24-char hex from URL)
• Debug auth: Run olcli check to see where credentials are loaded from
• Timeout: olcli --timeout 60000 pull "Big Project" or olcli config set-timeout 60000

olcli — Overleaf CLI

Command-line interface for Overleaf — Sync, manage, and compile LaTeX projects from your terminal.

Work with Overleaf projects directly from your command line. Edit locally with your favorite editor, version control with Git, and sync seamlessly with Overleaf's cloud compilation.

Features

• 📋 List all your Overleaf projects
• ✨ Create blank or example projects
• ⬇️ Pull project files to local directory for offline editing
• ⬆️ Push local changes back to Overleaf
• 🔄 Sync bidirectionally with smart conflict detection
• 🔍 Diff local files against the live remote before pushing
• 📝 Marked-up revisions — diff --latexdiff produces the struck-through/underlined PDF advisors and journals ask for
• 🔀 Git remote — use Overleaf as a native git remote (docs)
• ✌️ Two-way deletions — files removed locally are deleted on Overleaf on next sync
• 🗑️ Delete and ✏️ rename remote files by path
• 🚫 Smart ignore — LaTeX build artifacts and OS noise filtered automatically; extend with .olignore
• 📄 Compile PDFs using Overleaf's remote compiler
• 📦 Download individual files or full project archives
• 📤 Upload files to projects
• 💬 Review comments — list, add, resolve, reopen, delete, and reply to threads
• 🗂️ Preserve folder structure when pushing nested files
• ⏱️ Configurable timeout for slow connections
• 🔑 Password login for self-hosted instances (no browser required)
• ⚙️ Self-hosted Overleaf/ShareLaTeX support
• 📊 Output compile artifacts (.bbl, .log, .aux for arXiv submissions)
• 🤖 MCP server for AI assistants (docs)

Perfect for:

• Editing LaTeX in your preferred text editor (Vim, VS Code, Emacs, etc.)
• Version control with Git while using Overleaf's compiler
• Automating workflows and CI/CD pipelines
• Offline work with periodic sync

Installation

Homebrew (macOS/Linux)

brew tap aloth/tap
brew install olcli

npm (all platforms)

npm install -g @aloth/olcli

Or use with npx without installation:

npx @aloth/olcli list

For AI agents (via AgentSkills)

npx skills add aloth/olcli

Quick Start

1. Authenticate

Session cookie (overleaf.com and self-hosted):

olcli auth --cookie "your_session_cookie_value"

Email/password (self-hosted without reCAPTCHA):

olcli auth --email "you@example.com"
# prompts for the password, so it stays out of your shell history

The password is not stored unless you pass --save-password. A session cookie is saved either way and is what later commands use; the password only buys an automatic re-login once that cookie expires. For scripts, set OVERLEAF_EMAIL and OVERLEAF_PASSWORD — every command reads them, so a scripted run never needs olcli auth at all.

2. List Projects

olcli list

3. Pull, Edit, Push

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

4. Compile PDF

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

5. Or use native git commands

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

See Git Remote Helper docs for details.

Commands

All commands auto-detect the project when run from a synced directory (contains .olcli.json).

Compile Options

The compile-related commands (compile, pdf, output) accept:

Useful in multi-doc projects: each -r run compiles the file as if it were the main document.

Global Options

Sync Behavior

Pull

• Downloads all files from Overleaf
• Skips local files modified after last pull (won't overwrite your changes)
• Use --force to overwrite local changes

Push

• Uploads files modified after last pull
• Preserves nested folder structure
• Filters out LaTeX build artifacts and OS noise
• Use --all to upload all files, --dry-run to preview

Sync

• Pulls remote changes, then pushes local changes
• Local modifications win if newer
• Propagates local deletions — use --no-delete to opt out
• Use --dry-run to preview without applying

Diff

olcli diff compares the bytes of your local files against the project's current contents and prints a unified 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

The remote side is fetched fresh on every run. The diff describes the project as it is at that moment — which is what a subsequent push would overwrite — not a comparison against your last pull. .olcli.json records remote paths, never remote contents, so there is no stored snapshot to compare against; and the whole project arrives in a single request, the same one pull makes, so fetching fresh costs one round trip rather than one per file. A collaborator editing between diff and push can still change the outcome, which is why the fetch time is printed.

In the output, a/ is the remote and b/ is local: a + line is content push would upload, a - line is content it would overwrite. Files that differ only in bytes that are not text (PDFs, images) are reported as Binary files ... differ. Both sides pass through the same ignore layers, so build artifacts sitting on Overleaf are not reported as locally deleted.

diff --name-only and push --dry-run answer different questions and will disagree. push --dry-run lists files whose modification time is newer than the last pull, because that is what push uploads; diff lists files whose contents actually differ. A file you touched without editing appears in the first and not the second.

Marked-up revisions with latexdiff

A unified diff is the right artifact for a developer and the wrong one for a thesis advisor. --latexdiff marks the same revision up inside the document instead — deletions struck through, additions underlined — which is what advisors and journals ask for.

olcli diff --latexdiff          #