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

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

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

# Compile a specific root document
olcli pdf "Conference Paper" -r appendix.tex -o appendix.pdf
olcli compile "Conference Paper" -r folder/test.tex

# Upload figures
olcli upload figures/diagram.png          # relative path is preserved
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

# arXiv submission prep
olcli output bbl -o main.bbl
olcli output bbl -r folder/test.tex -o main.bbl  # compile artifacts from a specific root doc
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 and run olcli auth again.

Compilation fails — Check the Overleaf web editor for detailed error logs (missing packages, syntax errors, missing bibliography files).

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT © Alexander Loth