olcli

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

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).

Tracked changes are an Overleaf premium feature. They are only available in projects whose owner has a premium plan; invited collaborators can then use them regardless of their own plan. In other projects there are no tracked changes, so --changes returns an empty list and changes accept/changes reject report the ids as not found. See the Overleaf documentation for details.

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          # write .olcli-diff/main-diff.tex

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

Requires latexdiff on your PATH. It ships with TeX Live and MacTeX; nothing else in olcli diff needs an external tool.

`--pdf` compiles on Overleaf, so you do not need a local TeX installation. The compile endpoint can only build a file that is in the project, so the marked-up document is uploaded as olcli-latexdiff.tex next to your root document, compiled, downloaded, and then removed. The command says so before it does it, refuses to overwrite a file of that name if one already exists, and prints the exact olcli rm command if the cleanup itself fails.

\input and \include are inlined before comparing (--no-flatten to opt out). Without that, a remote compile would resolve those against the files sitting in the project — the old content — and quietly produce a PDF showing every input file as unchanged.

Output goes to .olcli-diff/, which is dotted so that push and sync never pick it up; -o puts it elsewhere. The root document is the .tex file d