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

Full Overleaf command-line access:

• 📋 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
• ✌️ Two-way deletions — files removed locally are deleted on Overleaf on the next sync (opt out with --no-delete)
• 🗑️ Delete and ✏️ rename remote files by path
• 🚫 Smart ignore — LaTeX build artifacts (.aux, .bbl, .log, .synctex.gz, …) and OS noise are filtered out automatically; extend with .olignore (gitignore-style)
• 📄 Compile PDFs using Overleaf's remote compiler
• 📦 Download individual files or full project archives
• 📤 Upload files to projects
• 💬 Review comments — list comments with source locations, add, resolve, reopen, and delete threads
• 🗂️ Preserve folder structure when pushing nested files
• ⚙️ Support self-hosted Overleaf/ShareLaTeX instances via configurable base URL and session cookie name
• 📊 Output compile artifacts (.bbl, .log, .aux for arXiv submissions)

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
• Collaborative projects where some prefer CLI, others prefer web

Installation

Homebrew (macOS/Linux)

brew tap aloth/tap
brew install olcli

npm (all platforms)

Install globally to use the olcli command anywhere:

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

Arch Linux

The package is available on the Arch User Repository (AUR).

You can install it using your preferred AUR helper (such as yay or paru):

yay -S olcli
# or
paru -S olcli

Manual Installation:

If you prefer not to use an AUR helper, you can build and install the package manually using makepkg:
code Bash

git clone https://aur.archlinux.org/olcli.git
cd olcli
makepkg -si

Quick Start

1. Authenticate with Overleaf

Get your session cookie from Overleaf.com:

1. Log into overleaf.com
2. Open Developer Tools (F12 or Cmd+Option+I) → Application/Storage → Cookies
3. Copy the value of overleaf_session2

Store it with olcli:

olcli auth --cookie "your_session_cookie_value"

Tip: The cookie stays valid for weeks. Just refresh it when authentication fails.

2. List Your Projects

olcli list

See all your Overleaf projects with IDs and last modified dates.

3. Pull a Project Locally

Download any project to work on it locally:

olcli pull "My Thesis"
cd My_Thesis/

Now you can edit .tex files with your preferred editor (Vim, VS Code, Emacs, etc.).

4. Edit Locally, Sync to Overleaf

# Edit files locally with your favorite editor
vim main.tex

# Push changes back to Overleaf
olcli push

# Or sync bidirectionally (pull + push in one command)
olcli sync

Your collaborators can continue using the Overleaf web editor — changes sync seamlessly.

5. Compile and Download PDF

Use Overleaf's remote compiler from the command line:

olcli pdf

The compiled PDF downloads automatically to your current directory.

Commands

All commands auto-detect the project when run from a synced directory (contains .olcli.json).

Command	Description
olcli auth	Set session cookie
olcli whoami	Check authentication status
olcli logout	Clear stored credentials
olcli list	List all projects
olcli info [project]	Show project details and file list
olcli pull [project] [dir]	Download project files to local directory
olcli push [dir]	Upload local changes to Overleaf
olcli sync [dir]	Bidirectional sync (pull + push)
olcli upload <file> [project]	Upload a single file
olcli download <file> [project]	Download a single file
olcli comments list [project]	List comments with source text and file locations (--status, --context)
olcli comments add <file> <message> [project]	Add a comment to selected text
olcli comments resolve <threadId> [project]	Resolve a comment thread
olcli comments reopen <threadId> [project]	Reopen a resolved comment thread
olcli comments delete <threadId> [project]	Permanently delete a comment thread
olcli delete <file> [project]	Delete a remote file or folder by path (alias: rm)
olcli rename <oldname> <newname> [project]	Rename a remote file or folder by path (alias: mv)
olcli ignored [dir]	List ignore patterns currently in effect
olcli zip [project]	Download project as zip archive
olcli compile [project]	Trigger PDF compilation
olcli pdf [project]	Compile and download PDF
olcli output [type]	Download compile output files
olcli config set-url <url>	Set a self-hosted Overleaf base URL
olcli config set-cookie-name <name>	Set the session cookie name
olcli check	Show config paths and credential sources

Review comments

olcli comments list "My Paper" --status open --context 2
olcli comments list "My Paper" --status resolved --json
olcli comments add main.tex "Please clarify this definition" "My Paper" --text "A Skill is"
olcli comments add main.tex "Check this sentence" "My Paper" --line 42 --column 1 --length 20 --json
olcli comments resolve 6a1a5fedbf90b811e1000001 "My Paper" --json
olcli comments reopen 6a1a5fedbf90b811e1000001 "My Paper"
olcli comments delete 6a1a5fedbf90b811e1000001 "My Paper" --json

Global options

These flags work with every command and may be placed before or after the command name:

Flag	Description
--verbose	Print every HTTP request, status, content-type, and (on errors) a response-body snippet to stderr. Useful for debugging failed compiles, 404s on pdf/output, auth issues, or unexpected upload behavior.
--base-url <url>	Override the Overleaf instance base URL (also OVERLEAF_BASE_URL env var or olcli config set-url).
--cookie-name <name>	Override the session cookie name (default overleaf_session2; older instances use overleaf.sid).

Examples:

olcli --verbose pdf                    # see every request the compile makes
olcli pdf --verbose                    # same thing, flag after command
olcli --verbose sync                   # debug a sync that's misbehaving
olcli --verbose upload figures/a.png   # confirm the file is placed in figures/

Use Cases

Local Editing with Overleaf Compilation

Work offline in your favorite editor, push when ready, compile remotely:

olcli pull "Research Paper"
cd Research_Paper
vim introduction.tex
git commit -am "Update intro"
olcli push
olcli pdf

Git Version Control + Overleaf

Keep your LaTeX project in Git while using Overleaf's compiler:

olcli pull "My Thesis" thesis
cd thesis
git init
git add .
git commit -m "Initial import from Overleaf"

# Daily workflow
vim chapters/methods.tex
git commit -am "Draft methods section"
olcli sync  # Sync with Overleaf
olcli pdf

Automated Workflows

Integrate Overleaf compilation into CI/CD:

#!/bin/bash
olcli auth --cookie "$OVERLEAF_SESSION"
olcli pull "Automated Report"
./generate-data.py > tables/results.tex
olcli push
olcli pdf -o report-$(date +%Y-%m-%d).pdf

arXiv Submissions

Download the .bbl file for arXiv submissions:

olcli output bbl --project "My Paper"
# Downloads: bbl

List all available compile output files:

olcli output --list
# Available output files:
#   aux          output.aux
#   bbl          output.bbl
#   blg          output.blg
#   log          output.log
#   ...

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 when uploading
• Filters out LaTeX build artifacts and OS noise (see Ignoring files)
• Use --all to upload all files
• Use --dry-run to preview changes
• Use --show-ignored to see what was filtered out

Sync

• Pulls remote changes
• Preserves local modifications (local wins if newer)
• Pushes local changes to remote
• Propagates local deletions to the remote — if you delete a file locally, it's deleted on Overleaf on the next sync. Use --no-delete to opt out.
• Filters out LaTeX build artifacts and OS noise
• Use --verbose to see detailed file operations (see Global options)
• Use --dry-run to preview without applying

How deletion propagation works

On every sync, olcli records a manifest of remote files in .olcli.json. The next sync compares the manifest against your local working tree:

• File missing locally and still present on remote → deleted on Overleaf
• File new locally → uploaded
• File modified locally after last pull → uploaded (local wins)
• File only on remote → downloaded

First-time syncs skip the deletion phase (no manifest exists yet to distinguish "never had it" from "deleted it").

Ignoring files

olcli automatically filters local files through a layered ignore list before uploading. This keeps LaTeX build artifacts (from local pdflatex/latexmk runs) and OS noise out of your Overleaf project.

Three layers

Layer	File	Purpose
1	(built-in)	LaTeX intermediates (.aux, .bbl, .log, .fls, .synctex.gz, beamer/biber/glossaries/minted), OS noise (.DS_Store, Thumbs.db, *.swp), common build dirs (build/, out/, _minted-*/). Always on; opt out with --no-default-ignore.
2	.olignore	Project-level patterns, gitignore syntax. Commit alongside your .tex sources.
3	.olignore.local	Machine-specific patterns. Add to .gitignore.

Later layers override earlier ones, just like git. Negation (!important.aux) is supported.

Special PDF rule

X.pdf is ignored only if a same-named X.tex (or .ltx) exists in the same folder. So thesis.pdf next to thesis.tex is filtered, but a hand-uploaded figures/diagram.pdf still syncs.

Example .olignore

# Drafts that should never reach Overleaf
*.draft.tex
notes/
chapters/scratch/

# But keep this one auxiliary file
!important.aux

Inspecting and overriding

olcli ignored                  # list patterns currently in effect
olcli push --show-ignored      # see what was skipped on this run
olcli sync --no-default-ignore # only .olignore applies
olcli sync --no-ignore         # escape hatch — upload everything

Configuration

Credentials are stored in (checked in order):

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

.olauth File

For project-specific credentials, create .olauth in your project directory:

s%3AyourSessionCookieValue...

Self-hosted Overleaf / ShareLaTeX

You can point olcli at a self-hosted instance and override the session cookie name. Both flags are documented under Global options and can be combined with any command.

olcli --base-url https://latex.example.org list
olcli --base-url https://latex.example.org --cookie-name overleaf.sid whoami

Persist these settings in olcli config so you don't have to repeat them:

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

Examples

Work on a thesis

# Initial setup
olcli pull "PhD Thesis" thesis
cd thesis

# Daily workflow
vim chapters/introduction.tex
olcli sync
olcli pdf -o draft.pdf

Quick PDF download

olcli pdf "Conference Paper" -o paper.pdf

Download a single file

olcli download main.tex "My Project"

Upload figures

cd my-project
olcli upload figures/diagram.png

Backup all projects

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

Prepare for arXiv

cd my-paper
olcli output bbl -o main.bbl
olcli zip -o arxiv-submission.zip

Programmatic Usage (Library API)

@aloth/olcli exposes OverleafClient and all public interfaces as a proper library so you can use it in your own scripts, tools, and AI agents.

Install

npm install @aloth/olcli

Basic example

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

// Create a client from an Overleaf session cookie
const client = await OverleafClient.fromSessionCookie(cookie);

// List all projects
const projects = await client.listProjects();
console.log(projects);

// Get detailed info (file tree) for a project
const info = await client.getProjectInfo(projectId);

// Download project as a zip buffer
const zipBuf = await client.downloadProject(projectId);

// Compile and download PDF
const pdfBuf = await client.downloadPdf(projectId);

// Upload a file
import { readFileSync } from 'node:fs';
await client.uploadFile(projectId, null, 'main.tex', readFileSync('main.tex'));

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

Available exports

import {
  // Core client
  OverleafClient,

  // Types / interfaces
  Project, ProjectInfo, FolderEntry, DocEntry, FileEntry,
  CommentMessage, ProjectComment, CommentContext, CommentStatus,
  ListCommentsOptions, AddCommentOptions, Credentials,

  // Configuration utilities
  getBaseUrl, setBaseUrl, getSessionCookie, setSessionCookie,
  getSessionCookieName, setSessionCookieName, getCsrf, setCsrf,
  getLastProject, setLastProject, clearConfig, getConfigPath, saveOlAuth,

  // Ignore utilities
  DEFAULT_IGNORE_PATTERNS, loadIgnore, shouldIgnore, buildTexSiblingSet,
  IgnoreContext, LoadIgnoreOptions,
} from '@aloth/olcli';

---

MCP Server

@aloth/olcli ships an MCP (Model Context Protocol) server so AI assistants like Claude Desktop, Cursor, and Windsurf can interact with your Overleaf projects directly.

MCP tools

Tool	Description
list_projects	List all Overleaf projects
get_project_info	Get file tree and metadata for a project
pull_project	Download and extract a project to a local directory
push_file	Upload a local file to a project
compile	Compile a project and get the PDF URL
download_pdf	Compile a project and save the PDF locally
list_comments	List review comments (filter: all / open / resolved)
get_entities	Get a flat list of all files in a project
download_file	Download a specific file by its remote path
add_comment	Add a review comment to a document
resolve_comment	Mark a comment thread as resolved
delete_entity	Delete a file or document by path
rename_entity	Rename a file or document
compile_with_outputs	Compile and return all output files (PDF, BBL, logs…)

Authentication

The MCP server reads your session cookie in this order:

1. OVERLEAF_SESSION environment variable — set in your MCP config (recommended)
2. .olauth file in cwd — written by olcli auth
3. Stored config — written by olcli auth

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@aloth/olcli-mcp"],
      "env": {
        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
      }
    }
  }
}

Or if you have olcli installed globally (npm install -g @aloth/olcli):

{
  "mcpServers": {
    "overleaf": {
      "command": "olcli-mcp",
      "env": {
        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@aloth/olcli-mcp"],
      "env": {
        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@aloth/olcli-mcp"],
      "env": {
        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
      }
    }
  }
}

Getting your session cookie

1. Open Overleaf in your browser and log in
2. Open DevTools → Application (Chrome) or Storage (Firefox) → Cookies
3. Find overleaf_session2 (or sharelatex.sid for self-hosted)
4. Copy the value — that's your OVERLEAF_SESSION

Or run olcli auth and then the MCP server will pick it up automatically.

Self-hosted Overleaf

Set OVERLEAF_BASE_URL in your MCP env:

"env": {
  "OVERLEAF_SESSION": "<cookie>",
  "OVERLEAF_BASE_URL": "https://overleaf.yourcompany.com"
}

---

Troubleshooting

Session expired

If you get authentication errors, your session cookie may have expired. Get a fresh one from the browser and run olcli auth again.

Compilation fails

Check the Overleaf web editor for detailed error logs. Common issues:

• Missing packages
• Syntax errors in .tex files
• Missing bibliography files

Contributing

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

License

MIT © Alexander Loth