olcli

olcli is a command-line interface for Overleaf, used to sync, manage, and compile LaTeX projects in the terminal. Users can edit files locally with their usual editors, use Git for version control, and sync to Overleaf for cloud compilation.

Main capabilities

• List all Overleaf projects; create blank or example projects.
• Pull project files to a local directory for offline editing; push local changes back to Overleaf; sync bidirectionally with smart conflict detection.
• Before pushing, use diff to compare local files with the online remote content (the remote is re-pulled on every run, a/ is the remote, b/ is the local, + lines are the content that will be uploaded by the push, - lines are the content that will be overwritten).
• Generate PDFs with revision marks: diff --latexdiff outputs strikethrough/underline effects, meeting advisor and journal requirements.
• Use Overleaf as a native Git remote repository (Git remote helper).
• Bidirectional deletion: files deleted locally will be deleted on Overleaf on the next sync (can be disabled with --no-delete).
• Delete or rename remote files by path; intelligently ignore LaTeX build artifacts and system noise, extensible with .olignore.
• Invoke Overleaf's remote compiler to compile PDFs; download a single file or the entire project archive; upload files.
• Review comments: list, add, resolve, reopen, delete, and reply to comment threads.
• Preserve directory structure when pushing nested files; configurable timeout; self-hosted instances can log in with a password (no browser required).
• Support self-hosted Overleaf/ShareLaTeX.
• Output compilation artifacts (.bbl, .log, .aux, convenient for arXiv submissions).
• MCP server for AI assistants.

Use cases

• Edit LaTeX in preferred editors such as Vim, VS Code, and Emacs.
• Use Git for version control while using the Overleaf compiler.
• Automated workflows and CI/CD pipelines.
• Work offline and sync periodically.

Installation and usage

• Homebrew (macOS/Linux); npm (all platforms); can also be run without installation via npx.
• For AI agents (via AgentSkills).
• Authentication: supports session cookies (overleaf.com and self-hosted) and email/password (self-hosted, when there is no reCAPTCHA). The password is saved only when --save-password is passed; the session cookie is saved regardless and used by subsequent commands. OVERLEAF_EMAIL and OVERLEAF_PASSWORD can be set in scripts, are read by all commands, and scripted runs require no olcli auth execution.
• When running commands from an already-synced directory (containing .olcli.json), the project is detected automatically.

Compilation options Compilation-related commands such as compile, pdf, and output support the relevant parameters. In multi-document projects, each -r run compiles the specified file as the main document.

Sync and diff notes

• pull downloads all files on Overleaf, skipping files that have been modified locally since the last pull (it does not overwrite your changes); use --force to overwrite local changes.
• push uploads files that have been modified since the last pull, preserving the nested directory structure, and filters out LaTeX build artifacts and system noise; use --all to upload all files, and use --dry-run to preview.
• sync first pulls remote changes and then pushes local changes, with local taking precedence when local modifications are newer; it propagates local deletions (use --no-delete to opt out); use --dry-run to preview without actually applying.
• diff compares the bytes of local files with the project's current content and prints a unified diff; the remote side is re-pulled on every run and describes the project state at that moment (that is, the content that a subsequent push would overwrite), rather than comparing against the last pull. .olcli.json records remote paths rather than remote content, so there is no stored snapshot to compare against. Non-text files that differ only in bytes (PDFs, images) are reported as Binary files ... differ. Both sides go through the same ignore layer, so build artifacts on Overleaf are not reported as local deletions.
• diff --name-only and push --dry-run answer different questions and may be inconsistent: push --dry-run lists files whose modification time is later than the last pull (that is, what would be pushed); diff lists files whose content actually differs. Files that were merely touched but not edited appear in the former but not the latter.

latexdiff and check mode

• --latexdiff requires latexdiff in PATH, which ships with TeX Live and MacTeX; the rest of olcli diff needs no external tools.
• --pdf compiles on Overleaf, so no local TeX installation is needed. The compile endpoint can only build files that exist in the project, so the marked document is uploaded as olcli-latexdiff.tex next to the root document, compiled, downloaded, and then deleted. The command states this in advance, refuses to overwrite if a file of the same name already exists, and prints the exact olcli rm command if cleanup fails.
• \input and \include are inlined before comparison (exit with --no-flatten). Otherwise the remote compile resolves against the old content in the project, causing the PDF to show every input file as unchanged.
• Output goes to .olcli-diff/ (with a leading dot, so push and sync will not pick it up); -o <path> can redirect it elsewhere. The root document is the .tex file that declares \documentclass; if there are several, specify one with --main <path>. --latexdiff-opt passes other options through verbatim, such as --latexdiff-opt --math-markup=0.
• One limitation: --pdf compiles against the project rather than the working directory, so anything needed for the markup must already be on Overleaf. A locally added .sty or .cls will cause the compile to fail (on failure the compile log is written next to the marked source); a locally added image will not cause failure, Overleaf draws a placeholder box labeled with the missing filename, and the rest of the PDF is fine.
• --exit-code turns the command into a check, using diff(1) status codes. Distinguishing 1 from 2 is the point: without it, a pipeline cannot tell a file change from an expired session cookie. Other olcli commands report failures as 1, and olcli diff still does so without --exit-code, so the flag does not change the behavior existing scripts see. The check covers what is compared: --file main.tex narrows to a single file, similar to git diff --exit-code pathspec; when --file matches no files it is 0 rather than an error. Under --latexdiff it still reportsthe whole project (a changed image is a real difference, even though the marked root document cannot show it). Note that this compares against Overleaf's current state, not against the last pull, so the check is "has anyone diverged from what was committed here", which is worth running on a schedule and worth running on push.

Deletion propagation olcli records the remote file manifest in .olcli.json. On the next sync: missing locally + still present remotely → delete on Overleaf; new locally → upload; modified locally → upload (local wins); present only remotely → download. The first sync skips the deletion phase (there is no previous manifest to compare against).

Ignore rules Later layers override earlier ones, and negation is supported (!important.aux). Special PDF rule: X.pdf is ignored only if X.tex (or .ltx) exists in the same folder.

Credentials and storage

• Credentials are checked in order: the OVERLEAF_SESSION environment variable, the .olauth file in the current directory, the global config (run olcli check to see the exact paths). The global config path depends on the platform, on macOS under ~/Library/Preferences/, on Linux under ~/.config/; olcli auth prints the path it writes to.
• Note: olcli auth --save-local writes .olauth to the current directory (usually your LaTeX project), so add it to that project's .gitignore before committing.
• Everything is stored in plaintext: olcli check reports what exists without printing any secrets; olcli logout clears the global config and the current directory's .olauth, then lists what it removed; it cannot unset environment variables, so if OVERLEAF_SESSION or OVERLEAF_EMAIL/OVERLEAF_PASSWORD is set, it points this out rather than implying you are logged out—these take precedence over anything on disk.

Self-hosting and timeouts You can pass olcli --base-url https://latex.example.org list. Timeout priority: --timeout > OVERLEAF_TIMEOUT > config > default (10000ms).

Library API @aloth/olcli exposes OverleafClient and all public interfaces as a library.

Further documentation MCP server (AI assistant integration: Claude, Cursor, Windsurf); Git Remote Helper (use Overleaf as a native git remote repository); troubleshooting (session expired—get a new cookie from the browser and rerun olcli auth; compilation failed—check the detailed error log in the Overleaf web editor, such as missing macro packages, syntax errors, missing bibliography files).

Architecture notes docs/ARCHITECTURE.md explains how the client works—there is no public Overleaf API, so it authenticates like a browser session. License is MIT © Alexander Loth.