/olcli

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

| Mode | Best for | How | |------|----------|-----| | **CLI** (`olcli`) | Interactive workflows, sync, compile, arXiv prep | `olcli pull/push/sync/pdf` | | **Git remote** | Version control, commits, diffs, CI/CD pipelines | `git clone overleaf::…` then standard git | | **MCP server** | AI agents with MCP support (Claude, Cursor, Windsurf) | Connect via `olcli-mcp` stdio transport |

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](https://www.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: u