Olcli

olcli — Overleaf CLI

Command-line interface for Overleaf — Sync, manage, and compile LaTeX projects from your terminal.

[](https://www.npmjs.com/package/@aloth/olcli) [](https://aur.archlinux.org/packages/olcli) [](https://opensource.org/licenses/MIT) [](https://agentskills.io)

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 [project] | Upload a single file | | olcli download [project] | Download a single file | | olcli comments list [project] | List comments with source text and file locations (--status, --context) | | olcli comments add [project] | Add a comment to selected text | | olcli comments resolve [project] | Resolve a comment thread | | olcli comments reopen [project] | Reopen a resolved comment thread | | olcli comments delete [project] | Permanently delete a comment thread | | olcli delete [project] | Delete a remote file or folder by path (alias: rm) | | olcli rename [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 | Set a self-hosted Overleaf base URL | | olcli config set-cookie-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 | Override the Overleaf instance base URL (also OVERLEAF_BASE_URL env var or olcli config set-url). | | --cookie-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](#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](#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](#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 —

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aloth
• Source: aloth/olcli
• License: MIT
• Homepage: https://www.npmjs.com/package/@aloth/olcli

Install and usage instructions live in the source repository linked above.