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

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, compile_with_outputs.

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/

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

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 compile                  # Just compile (no download)

Download .bbl for arXiv submission

olcli output bbl               # Download compiled .bbl
olcli output bbl -o main.bbl   # Custom filename
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

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
• 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
• ⬇️ Pull project files to local directory for offline editing
• ⬆️ Push local changes back to Overleaf
• 🔄 Sync bidirectionally with smart conflict detection
• 🔀 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" --password "your_password"

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

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

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

How deletion propagation works

olcli records a manifest of remote files in .olcli.json. On next sync:

• File missing locally + still on remote → deleted on Overleaf
• File new locally → uploaded
• File modified locally → uploaded (local wins)
• File only on remote → downloaded

First-time syncs skip the deletion phase (no prior manifest to compare).

Ignoring Files

Three layers

Later layers override earlier ones. Negation (!important.aux) is supported.

Special PDF rule

X.pdf is ignored only if X.tex (or .ltx) exists in the same folder.

Inspecting and overriding

olcli ignored                  # list patterns in effect
olcli push --show-ignored      # see what was skipped
olcli sync --no-default-ignore # only .olignore applies
olcli sync --no-ignore         # upload everything

Configuration

Credentials are checked in order:

1. OVERLEAF_SESSION environment variable
2. .olauth file in current directory
3. Global config: ~/.config/olcli-nodejs/config.json

Self-hosted Overleaf

olcli config set-url https://latex.example.org
olcli config set-cookie-name overleaf.sid

Or pass per-command: olcli --base-url https://latex.example.org list

Timeout

olcli config set-timeout 60000          # persist
olcli --timeout 60000 pull "Big Thesis" # one-off
export OVERLEAF_TIMEOUT=60000           # env var

Precedence: --timeout > OVERLEAF_TIMEOUT > config > default (10000ms).

Examples

# Daily thesis workflow
olcli pull "PhD Thesis" thesis && cd thesis
vim chapters/methods.tex
olcli sync && olcli pdf -o draft.pdf

# Quick PDF download
olcli pdf "Conference Paper" -o paper.pdf

# Upload figures
olcli upload figures/diagram.png

# arXiv submission prep
olcli output bbl -o main.bbl
olcli zip -o arxiv-submission.zip

# Backup all projects
for proj in $(olcli list --json | jq -r '.[].name'); do
  olcli zip "$proj" -o "backups/${proj}.zip"
done

Programmatic Usage (Library API)

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

Install

npm install @aloth/olcli

Basic example

import { OverleafClient } from '@aloth/olcli';

const client = await OverleafClient.fromSessionCookie(cookie);

const projects = await client.listProjects();
const info = await client.getProjectInfo(projectId);
const zipBuf = await client.downloadProject(projectId);
const pdfBuf = await client.downloadPdf(projectId);

await client.uploadFile(projectId, null, 'main.tex', readFileSync('main.tex'));

const comments = await client.listComments(projectId, { status: 'open' });

Available exports

import {
  OverleafClient,
  // Types
  Project, ProjectInfo, FolderEntry, DocEntry, FileEntry,
  CommentMessage, ProjectComment, CommentContext, CommentStatus,
  ListCommentsOptions, AddCommentOptions, Credentials, SessionCookiePair,
  // Config utilities
  getBaseUrl, setBaseUrl, getSessionCookie, setSessionCookie,
  getSessionCookieName, setSessionCookieName, getCsrf, setCsrf,
  getLastProject, setLastProject, clearConfig, getConfigPath, saveOlAuth,
  getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials,
  clearPasswordCredentials, type PasswordCredentials,
  // Ignore utilities
  DEFAULT_IGNORE_PATTERNS, loadIgnore, shouldIgnore, buildTexSiblingSet,
  IgnoreContext, LoadIgnoreOptions,
} from '@aloth/olcli';

Further Documentation

• MCP Server — AI assistant integration (Claude, Cursor, Windsurf)
• Git Remote Helper — use Overleaf as a native git remote

Troubleshooting

Session expired — Get a fresh cookie from the browser