@aloth/olcli

v0.1.5

Published

21 days ago

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

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
📄 Compile PDFs using Overleaf's remote compiler
📦 Download individual files or full project archives
📤 Upload files to projects
📊 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

Quick Start

1. Authenticate with Overleaf

Get your session cookie from Overleaf.com:

Log into overleaf.com
Open Developer Tools (F12 or Cmd+Option+I) → Application/Storage → Cookies
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 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 check | Show config paths and credential sources |

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
Use --all to upload all files
Use --dry-run to preview changes

Sync

Pulls remote changes
Preserves local modifications (local wins if newer)
Pushes local changes to remote
Use --verbose to see detailed file operations

Configuration

Credentials are stored in (checked in order):

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

.olauth File

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

s%3AyourSessionCookieValue...

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

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.