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.
- 📋 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,.auxfor 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
brew tap aloth/tap
brew install olclinpm install -g @aloth/olcliOr use with npx without installation:
npx @aloth/olcli listnpx skills add aloth/olcliSession 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"olcli listolcli pull "My Thesis"
cd My_Thesis/
vim main.tex
olcli pusholcli pdfgit clone overleaf::https://www.overleaf.com/project/<id>
cd <project>
# edit, commit, push — standard git workflow
git pushSee Git Remote Helper docs for details.
All commands auto-detect the project when run from a synced directory (contains .olcli.json).
| Command | Description |
|---|---|
olcli auth |
Set session cookie or login with email/password |
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 delete <file> [project] |
Delete a remote file or folder (alias: rm) |
olcli rename <old> <new> [project] |
Rename a remote file or folder (alias: mv) |
olcli compile [project] |
Trigger PDF compilation |
olcli pdf [project] |
Compile and download PDF |
olcli output [type] |
Download compile output files |
olcli zip [project] |
Download project as zip archive |
olcli comments list [project] |
List comments (--status, --context) |
olcli comments add <file> <msg> |
Add a comment to selected text |
olcli comments reply <id> <body> |
Reply to a comment thread |
olcli comments resolve <id> |
Resolve a comment thread |
olcli comments reopen <id> |
Reopen a resolved thread |
olcli comments delete <id> |
Delete a comment thread |
olcli ignored [dir] |
List ignore patterns in effect |
olcli config set-url <url> |
Set self-hosted base URL |
olcli config set-cookie-name <name> |
Set session cookie name |
olcli config set-timeout <ms> |
Set default HTTP timeout |
olcli check |
Show config paths and credential sources |
| Flag | Description |
|---|---|
--verbose |
Print HTTP requests and responses to stderr |
--base-url <url> |
Override Overleaf instance URL |
--cookie-name <name> |
Override session cookie name |
--timeout <ms> |
Override HTTP timeout (default: 10000) |
- Downloads all files from Overleaf
- Skips local files modified after last pull (won't overwrite your changes)
- Use
--forceto overwrite local changes
- Uploads files modified after last pull
- Preserves nested folder structure
- Filters out LaTeX build artifacts and OS noise
- Use
--allto upload all files,--dry-runto preview
- Pulls remote changes, then pushes local changes
- Local modifications win if newer
- Propagates local deletions — use
--no-deleteto opt out - Use
--dry-runto preview without applying
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).
| Layer | Source | Purpose |
|---|---|---|
| 1 | Built-in | LaTeX intermediates, OS noise, build dirs. Always on. |
| 2 | .olignore |
Project-level patterns (gitignore syntax). |
| 3 | .olignore.local |
Machine-specific patterns. |
Later layers override earlier ones. Negation (!important.aux) is supported.
X.pdf is ignored only if X.tex (or .ltx) exists in the same folder.
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 everythingCredentials are checked in order:
OVERLEAF_SESSIONenvironment variable.olauthfile in current directory- Global config:
~/.config/olcli-nodejs/config.json
olcli config set-url https://latex.example.org
olcli config set-cookie-name overleaf.sidOr pass per-command: olcli --base-url https://latex.example.org list
olcli config set-timeout 60000 # persist
olcli --timeout 60000 pull "Big Thesis" # one-off
export OVERLEAF_TIMEOUT=60000 # env varPrecedence: --timeout > OVERLEAF_TIMEOUT > config > default (10000ms).
# 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@aloth/olcli exposes OverleafClient and all public interfaces as a library.
npm install @aloth/olcliimport { 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' });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';- MCP Server — AI assistant integration (Claude, Cursor, Windsurf)
- Git Remote Helper — use Overleaf as a native git remote
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).
Contributions are welcome! Please open an issue or submit a pull request.
MIT © Alexander Loth