overleaf · v1.3 · 2026-11-07 · sha256 da51a11f0e2c5a1d
overleaf v1.3A
Immutable. This exact content never changes and is served at /api/v1/blob/da51a11f0e2c5a1d.
--- 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 ```bash # 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` ```bash olcli auth --cookie "YOUR_SESSION_COOKIE" ``` Or sign in through a browser window (SSO, Google, two-factor; olcli keeps only the session cookie): ```bash olcli auth --browser ``` Verify and debug authentication (instance, account, credential source, masked cookie): ```bash olcli auth status ``` Clear stored credentials: ```bash 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 ```bash 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. ```bash # 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 (a push is refused while Overleaf has edits you # have not pulled; git push --force overwrites them on purpose) git pull ``` Authentication: reads `OVERLEAF_SESSION` env var, the `.olauth` file in the current directory, or stored config (same as CLI). For self-hosted instances, just use your instance URL: ```bash 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. ```bash # 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 ``` 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`, `accept_tracked_changes`, `reject_tracked_changes`. `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 ```bash olcli pull "My Paper" cd My_Paper/ ``` ### Create a project ```bash olcli project create "My Paper" olcli project create "Example Paper" --template example ``` ### Edit and sync changes ```bash # 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 ```bash 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 ```bash 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, it stays in its folder olcli mv chapters/draft.tex chapters/intro.tex # alias: rename inside chapters/ olcli mv draft.tex chapters/intro.tex # move into chapters/ and rename olcli mv figures/old.pdf archive/ # move into archive/, keep the name olcli mv chapters/notes.tex / # move to the project root ``` `delete` accepts a path. For `rename` (alias `mv`) the destination decides what happens. A bare name without `/` renames the entity in place: it keeps its folder. A path with a folder part moves the entity into that folder and gives it the last part as its name; missing folders are created. A destination ending in `/` moves the entity and keeps its name, and `/` alone or a leading `/` means the project root. Files, documents and folders can all be moved. Nothing is written, and the command exits 1, when the destination already exists, the source is not found, or a folder would be moved into itself or one of its subfolders. When both the folder and the name change, olcli renames first and then moves, or moves first when the new name is already taken in the old folder; every clash is checked against the project tree before the first request. ### Inspect ignore rules ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash olcli download main.tex "My Paper" # Download single file olcli zip "My Paper" # Download entire project as zip ``` ### Review comments ```bash 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: ```bash # 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 | Command | Description | |---------|-------------| | `olcli auth --cookie <value>` | Authenticate with session cookie | | `olcli auth --email <e>` | Authenticate with password, prompted (self-hosted) | | `olcli auth --browser` | Sign in through a browser window, keep only the session cookie | | `olcli auth status` | Instance, account, credential source; exits 1 when not signed in | | `olcli logout` | Clear the global config and the local `.olauth` | | `olcli list` | List all projects | | `olcli project create <name>` | Create a blank or example project | | `olcli info [project]` | Show project details | | `olcli pull [project] [dir]` | Download project files | | `olcli push [dir]` | Upload local changes | | `olcli sync [dir]` | Bidirectional sync | | `olcli diff [project] [dir]` | Content-level diff of local files vs. the live remote | | `olcli upload <file> [project]` | Upload a single file (`--to <path>` sets the remote destination) | | `olcli download <file> [project]` | Download a single file | | `olcli delete <file> [project]` | Delete a remote file or folder (alias: `rm`) | | `olcli rename <old> <new> [project]` | Rename or move a remote file or folder (alias: `mv`); `<new>` with a folder part moves, a trailing `/` moves and keeps the name | | `olcli ignored [dir]` | List active ignore patterns | | `olcli zip [project]` | Download as zip archive | | `olcli compile [project]` | Trigger compilation | | `olcli pdf [project]` | Compile and download PDF | | `olcli output [type]` | Download compile outputs | | `olcli comments list [project]` | List review comments | | `olcli comments add <file> <msg>` | Add a comment | | `olcli comments reply <id> <body>` | Reply to a thread | | `olcli comments resolve <id>` | Resolve a thread | | `olcli comments reopen <id>` | Reopen a thread | | `olcli comments delete <id>` | Delete a thread | | `olcli config set-url <url>` | Set self-hosted base URL | | `olcli config get-url` | Show the configured base URL | | `olcli config set-cookie-name <name>` | Set cookie name | | `olcli config get-cookie-name` | Show the configured cookie name | | `olcli config set-timeout <ms>` | Set HTTP timeout | | `olcli config get-timeout` | Show the configured HTTP timeout | | `olcli project rename <newname> [project]` | Rename a project | | `olcli project rename-bulk` | Rename many projects by pattern (dry-run unless `--apply`) | ## 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 auth status` to see where credentials are loaded from - **Timeout**: `olcli --timeout 60000 pull "Big Project"` or `olcli config set-timeout 60000`