Overleaf Pull-Only Sync CLI

This project introduces a small background worker that keeps and up-to-date copy your the last active overleaf projects offline (by default the last 10). There's also a handy manual sync command to pull the updates manually. This project is not an automatic two-way merge! It works by pulling via the git-integration, making it save from accidentially pushing work in progress.

For Users — Quick Start Install and setup

pip install 'overleaf-pull[qt]'
overleaf-pull init --install

Manual sync and status

overleaf-pull run-once   # full sync now
overleaf-pull status     # health + last run + timers

Customize (optional)

# Scheduler cadence and mode (dynamic by default)
overleaf-pull set-interval 30m
overleaf-pull install-scheduler --mode dynamic   # or --mode full

# Other knobs
overleaf-pull set-count 20
overleaf-pull set-base-dir /path/to/Overleaf
overleaf-pull set-git-token   # set once to avoid prompts

Overview

• Pull-only tool that periodically clones/pulls your latest Overleaf projects into a local directory.
• Discovers projects via cookies captured during setup (Qt login recommended) or manual paste; Firefox cookies can be read automatically.
• Lists projects via PyOverleaf; syncs using Git.
• Runs in the background as a macOS LaunchAgent or Linux systemd user timer.

Requirements

• macOS or Linux with Git installed.
• Python 3.10+.
• Dependencies are installed automatically via pip. Optional extras: [qt] for PySide6 (Qt login).
• Overleaf Git integration enabled on your account to allow cloning/pulling via git.overleaf.com.

Details for Users

Install

pip install overleaf-pull
# Optional Qt login support:
pip install 'overleaf-pull[qt]'

Setup Wizard

overleaf-pull init --install

• Prompts for the base directory, interval (30m/1h/12h/24h), count (default 10), browser/profile, and host (default www.overleaf.com).
• Offers a Qt browser login to capture cookies automatically (default Yes if PySide6 is installed). Falls back to optional manual cookie paste.
• Prompts for your Overleaf Git authentication token (required for cloning/pulling and background runs). It will offer to open Overleaf in your browser to fetch it.
• Installs a background job (LaunchAgent on macOS, systemd user timer on Linux).
• Runs a validation sync before installing the scheduler, to confirm access.

Manual Sync Run once now:

overleaf-pull run-once

• Runs a full sync of the latest projects (not dynamic).
• Manual sync (with optional overrides):

overleaf-pull sync --count 5 --base-dir ~/Overleaf --browser firefox

• Store or clear cookies in config:
• Folder naming preference:

overleaf-pull set-name-suffix off   # Use display name only
overleaf-pull set-name-suffix on    # Default: append a short ID to avoid collisions

This affects the local folder names only; project display names on Overleaf remain unchanged.

overleaf-pull set-cookie "name=value; other=value2"
overleaf-pull clear-cookie

• Browser-assisted cookie capture (like olbrowserlogin):

overleaf-pull browser-login
# This opens Overleaf in your browser and guides you to copy document.cookie.

Required cookies

• At minimum: overleaf_session2 and GCLB must be present in your Cookie header for authenticated requests.
• document.cookie cannot see HttpOnly cookies; copy the full Cookie header from the Network tab for a request to your Overleaf host.

Qt browser login (optional)

• Use a built-in Qt browser to log in and auto-capture cookies.

pip install 'overleaf-pull[qt]'
overleaf-pull browser-login-qt

During setup, if PySide6 is present, the tool offers the Qt login flow by default.

Git authentication token

• Overleaf requires a Git auth token for git clone/git pull.
• Generate a token in your Overleaf account (see the Git integration/authentication tokens page or the Git instructions shown in your project UI), then set it:

overleaf-pull set-git-token
# Paste your token when prompted

# Clear it if needed
overleaf-pull clear-git-token

• With a token set, the tool will use URLs like https://git:<TOKEN>@git.overleaf.com/<PROJECT_ID> automatically. Status

overleaf-pull status

• Shows a summary of repo health and the last background run.
• Displays per-project timers indicating when each is next due.
• Prints the current scheduler configuration: interval and mode (dynamic/full). Customize
• Install or remove background job:

overleaf-pull install-scheduler
overleaf-pull uninstall-scheduler

Scheduler modes

• The scheduler supports two modes:
  • dynamic: Runs only projects that are due based on per-project backoff (min 30m, doubles until 24h; resets to 30m on changes).
  • full: Always runs a full sync on each trigger.
• Examples:

# 30-minute dynamic cadence
overleaf-pull set-interval 30m
overleaf-pull install-scheduler --mode dynamic

# 30-minute full cadence
overleaf-pull set-interval 30m
overleaf-pull install-scheduler --mode full

Installing the scheduler is idempotent: it uninstalls any existing instance first, then reinstalls to ensure only one scheduler is active. For Developers

Publish to PyPI (CI)

• This repo includes a GitHub Actions workflow that publishes on tags v* using PyPI Trusted Publishers (OIDC).
• Trigger a release:

git tag v0.1.0
git push origin v0.1.0

• The workflow builds sdist/wheel and publishes without storing secrets.
• Adjust interval or latest count:

overleaf-pull set-interval 30m
overleaf-pull set-count 20

• Change base directory:

overleaf-pull set-base-dir /path/to/Overleaf

macOS Logs

• Logs: ~/Library/Logs/overleaf_pull/runner.log

Linux Logs

• journalctl --user -u overleaf-pull.timer -u overleaf-pull.service
• And ~/.local/state/overleaf_pull/logs/ if configured.

Notes

• This tool is pull-only; it never pushes to Overleaf.
• Safari cookie access may require permissions; Firefox is often more reliable for unattended use.
• If Safari access fails, paste Overleaf cookies once via set-cookie to avoid elevated access.
• Desktop notifications are emitted on sync failures, including authentication/key expiration and potential Overleaf API compatibility issues.
• Use Git credential helpers for smooth pulls:

git config --global credential.helper osxkeychain   # macOS
git config --global credential.helper libsecret     # Linux

Background runs

• To avoid interactive Git prompts in schedulers, set an Overleaf Git token once:

overleaf-pull set-git-token

• Without a token, new clones will fail with 403; existing repos may also fail if their remotes lack the token. Prompts are disabled in background.

Dynamic scheduling (per-project backoff)

• The background worker runs on a frequent cadence (e.g., every 30 minutes).
• Each project has its own timer with exponential backoff:
  • Minimum interval: 30 minutes. Doubles on no changes, up to 24 hours.
  • Resets to 30 minutes when changes are detected and pulled.
• The status command shows the next-due times for the latest projects.

Development

• Create a local environment and install from source:

python3 -m venv .venv
. .venv/bin/activate
pip install -e .
# Optional Qt support
pip install PySide6

• Conda alternative:

conda env create -f environment.yml
conda activate overleaf-sync
pip install -e .