overleaf
Sync and manage Overleaf LaTeX projects from the command line. Pull projects locally, push changes back, compile PDFs, and download compile outputs like .bbl files for arXiv submissions. Use when working with LaTeX, Overleaf, academic papers, or arXiv.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/aloth--olcli)HTML
<a href="/listings/aloth--olcli"><img src="/api/listings/aloth--olcli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
brew install aloth/tap/olcli # Homebrew (macOS, Linux) npm install -g @aloth/olcli # npm (any platform, Node 20.18.1 or newer)
On Linux with Nix: `nix run github:aloth/olcli -- --help`. Without installing: `npx @aloth/olcli list`. For AI agents through AgentSkills: `npx skills add aloth/olcli`.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 341 lines
- ---
- name: overleaf
- description: Sync and manage Overleaf LaTeX projects from the command line. Pull projects locally, push changes back, compile PDFs, and download compile outputs like .bbl files for arXiv submissions. Use when working with LaTeX, Overleaf, academic papers, or arXiv.
- license: MIT
- metadata:
- author: aloth
- version: "1.3"
- cli: olcli
- install: brew tap aloth/tap && brew install olcli
- ---
- # Overleaf Skill
- Manage Overleaf LaTeX projects via the `olcli` CLI, native git remote, or MCP server.
- ## When to Use Which Mode
- | Mode | Best for | How |
- |------|----------|-----|
- | **CLI** (`olcli`) | Interactive workflows, sync, compile, arXiv prep | `olcli pull/push/sync/pdf` |
- | **Git remote** | Version control, commits, diffs, CI/CD pipelines | `git clone overleaf::…` then standard git |
- | **MCP server** | AI agents with MCP support (Claude, Cursor, Windsurf) | Connect via `olcli-mcp` stdio transport |
- Use **CLI** when you need bidirectional sync with conflict detection, compilation, or comment management. Use **Git remote** when you want proper git history, branches, and standard `git push/pull`. Use **MCP** when an AI agent has native MCP support and doesn't need to shell out.
- ## Installation
- ```bash
- # Homebrew (recommended)
- brew tap aloth/tap && brew install olcli
- # npm
- npm install -g @aloth/olcli
- ```
- ## Authentication
- Get your session cookie from Overleaf:
- 1. Log into [overleaf.com](https://www.overleaf.com)
- 2. Open DevTools (F12) → Application → Cookies
- 3. Copy the value of `overleaf_session2`
- ```bash
- olcli auth --cookie "YOUR_SESSION_COOKIE"
- ```
- Or sign in through a browser window (SSO, Google, two-factor; olcli keeps only the session cookie):
- ```bash
- olcli auth --browser
- ```
- Verify and debug authentication (instance, account, credential source, masked cookie):
- ```bash
- olcli auth status
- ```
- Clear stored credentials:
- ```bash
- olcli logout
- ```
- Clears the global config and the `.olauth` file in the current directory, and
- reports each. Environment variables cannot be unset by a child process, so
- `OVERLEAF_SESSION` and `OVERLEAF_EMAIL`/`OVERLEAF_PASSWORD` are reported rather
- than silently ignored — they outrank anything on disk.
- For unattended use on a self-hosted instance without reCAPTCHA, prefer
- `OVERLEAF_EMAIL`/`OVERLEAF_PASSWORD` over `olcli auth --password`: every
- command reads them, and nothing is written to disk or to shell history.
- overleaf.com requires a captcha for password sign-in, which olcli cannot
- complete; use `olcli auth --browser` or `OVERLEAF_SESSION` there.
- ### Self-hosted Overleaf
- ```bash
- olcli config set-url https://overleaf.yourcompany.com
- olcli config set-cookie-name overleaf.sid # if different from default
- olcli auth --cookie "YOUR_COOKIE"
- ```
- Or pass per-command: `olcli --base-url https://overleaf.yourcompany.com list`
- ## Git Remote Helper
- Use Overleaf projects as native git remotes. No wrapper scripts needed.
- ```bash
- # Clone
- git clone overleaf::https://www.overleaf.com/project/<id>
- cd <project>
- # Edit, commit, push — standard git workflow
- vim main.tex
- git add . && git commit -m "update introduction"
- git push
- # Pull latest from Overleaf (a push is refused while Overleaf has edits you
- # have not pulled; git push --force overwrites them on purpose)
- git pull
- ```
- Authentication: reads `OVERLEAF_SESSION` env var, the `.olauth` file in the current directory, or stored config (same as CLI).
- For self-hosted instances, just use your instance URL:
- ```bash
- git clone overleaf::https://overleaf.yourcompany.com/project/<id>
- ```
- Debug with: `GIT_REMOTE_OVERLEAF_DEBUG=1 git push`
- ## MCP Server
- Built-in Model Context Protocol server for AI assistant integration.
- ```bash
- # Run standalone
- olcli-mcp
- # Or via npx (the server is the olcli-mcp command of the @aloth/olcli package)
- npx -y --package @aloth/olcli olcli-mcp
- ```
- Available MCP tools: `list_projects`, `get_project_info`, `pull_project`, `push_file`, `compile`, `download_pdf`, `list_comments`, `get_entities`, `download_file`, `add_comment`, `reply_to_comment`, `resolve_comment`, `delete_entity`, `rename_entity`, `rename_project`, `plan_project_renames`, `compile_with_outputs`, `diff_project`, `create_project`, `accept_tracked_changes`, `reject_tracked_changes`, `suggest_changes` (experimental).
- `compile`, `download_pdf` and `compile_with_outputs` accept an optional `resource_path` to compile a specific root document.
- `diff_project` is the MCP counterpart of `olcli diff`: read-only, fetches the remote fresh on every call, and returns one entry per changed file with `path`, `status`, `binary` and a unified `patch`. Pass `name_only` to drop the patch text. `plan_project_renames` previews bulk renames and never applies them.
- Auth: set `OVERLEAF_SESSION` env var in MCP config, or use stored credentials from `olcli auth`.
- ## Common Workflows
- ### Pull a project to work locally
- ```bash
- olcli pull "My Paper"
- cd My_Paper/
- ```
- ### Create a project
- ```bash
- olcli project create "My Paper"
- olcli project create "Example Paper" --template example
- ```
- ### Edit and sync changes
- ```bash
- # After editing files locally
- olcli push # Upload changes only
- olcli sync # Bidirectional sync (pull + push, propagates local deletions)
- olcli sync --no-delete # Sync without propagating local deletions to remote
- ```
- ### Review changes before pushing
- ```bash
- olcli diff # unified diff of every changed file
- olcli diff --name-only # changed paths only
- olcli diff --file main.tex # a single file
- olcli diff --exit-code # CI gate: 0 same, 1 differs, 2 failed
- ```
- The remote side is fetched fresh each run, so this shows what a subsequent
- `push` would overwrite — not a comparison against the last `pull`. `a/` is the
- remote, `b/` is local. Binary files are reported as differing without a patch.
- `--exit-code` uses `diff(1)`'s statuses so the command can gate a pipeline:
- `0` nothing differs, `1` something does, `2` the run itself failed. The last
- one matters — without it a job cannot tell a changed file from an expired
- session. Failures stay `1` when the flag is absent, so existing scripts are
- unaffected.
- ### Delete or rename remote files
- ```bash
- olcli delete chapters/old.tex # remove a file from the project
- olcli rm figures/old.pdf # alias
- olcli rename old.tex new.tex # rename a file, it stays in its folder
- olcli mv chapters/draft.tex chapters/intro.tex # alias: rename inside chapters/
- olcli mv draft.tex chapters/intro.tex # move into chapters/ and rename
- olcli mv figures/old.pdf archive/ # move into archive/, keep the name
- olcli mv chapters/notes.tex / # move to the project root
- ```
- `delete` accepts a path. For `rename` (alias `mv`) the destination decides what
- happens. A bare name without `/` renames the entity in place: it keeps its
- folder. A path with a folder part moves the entity into that folder and gives
- it the last part as its name; missing folders are created. A destination ending
- in `/` moves the entity and keeps its name, and `/` alone or a leading `/` means
- the project root. Files, documents and folders can all be moved.
- Nothing is written, and the command exits 1, when the destination already
- exists, the source is not found, or a folder would be moved into itself or one
- of its subfolders. When both the folder and the name change, olcli renames
- first and then moves, or moves first when the new name is already taken in the
- old folder; every clash is checked against the project tree before the first
- request.
- ### Inspect ignore rules
- ```bash
- olcli ignored # list active patterns (built-ins + .olignore + .olignore.local)
- olcli push --show-ignored # see what was filtered on this run
- olcli sync --no-ignore # escape hatch: upload everything
- ```
- ### Compile and download PDF
- ```bash
- olcli pdf # Compile and download
- olcli pdf -o paper.pdf # Custom output name
- olcli pdf -r chapters/intro.tex # Compile a specific root document
- olcli compile # Just compile (no download)
- olcli compile -r appendix.tex # Compile a specific root document without downloading
- ```
- `-r, --resource <path>` works on `compile`, `pdf`, and `output`: it compiles the given `.tex` file as the root document. Useful when a project contains several documents.
- ### Download .bbl for arXiv submission
- ```bash
- olcli output bbl # Download compiled .bbl
- olcli output bbl -o main.bbl # Custom filename
- olcli output bbl -r appendix.tex
- olcli output --list # List all available outputs
- ```
- ### Upload figures or assets
- ```bash
- olcli upload figure1.png "My Paper" # Upload to project root
- olcli upload diagram.pdf # Auto-detect project from .olcli.json
- olcli upload figures/diagram.png # Relative path is preserved remotely
- olcli upload /tmp/build/diagram.png # Absolute path lands in the project root
- olcli upload /tmp/build/diagram.png --to figures/diagram.png # Explicit destination
- ```
- Remote path rules: a relative local path keeps its directory part, an absolute
- local path collapses to its basename, and `--to` overrides both.
- ### Download specific files
- ```bash
- olcli download main.tex "My Paper" # Download single file
- olcli zip "My Paper" # Download entire project as zip
- ```
- ### Review comments
- ```bash
- olcli comments list # List all comments (current project)
- olcli comments list --status open # Filter by status (open/resolved/all)
- olcli comments list --context # Include surrounding text
- olcli comments add main.tex "Fix this citation" --from 10 --to 15 # Add comment
- olcli comments reply <thread-id> "Done!" # Reply to thread
- olcli comments resolve <thread-id> # Mark as resolved
- olcli comments reopen <thread-id> # Reopen a resolved thread
- olcli comments delete <thread-id> # Delete entire thread
- ```
- ## arXiv Submission Workflow
- Complete workflow for preparing an arXiv submission:
- ```bash
- # 1. Pull your project
- olcli pull "Research Paper"
- cd Research_Paper
- # 2. Compile to ensure everything builds
- olcli compile
- # 3. Download the .bbl file (arXiv requires .bbl, not .bib)
- olcli output bbl -o main.bbl
- # 4. Download any other needed outputs
- olcli output aux -o main.aux # If needed
- # 5. Package for submission
- zip arxiv.zip *.tex main.bbl figures/*.pdf
- # 6. Verify the package compiles locally (optional)
- # Then upload arxiv.zip to arxiv.org
- ```
- ## Commands Reference
- | Command | Description |
- |---------|-------------|
- | `olcli auth --cookie <value>` | Authenticate with session cookie |
- | `olcli auth --email <e>` | Authenticate with password, prompted (self-hosted) |
- | `olcli auth --browser` | Sign in through a browser window, keep only the session cookie |
- | `olcli auth status` | Instance, account, credential source; exits 1 when not signed in |
- | `olcli logout` | Clear the global config and the local `.olauth` |
- | `olcli list` | List all projects |
- | `olcli project create <name>` | Create a blank or example project |
- | `olcli info [project]` | Show project details |
- | `olcli pull [project] [dir]` | Download project files |
- | `olcli push [dir]` | Upload local changes |
- | `olcli sync [dir]` | Bidirectional sync |
- | `olcli diff [project] [dir]` | Content-level diff of local files vs. the live remote |
- | `olcli upload <file> [project]` | Upload a single file (`--to <path>` sets the remote destination) |
- | `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 or move a remote file or folder (alias: `mv`); `<new>` with a folder part moves, a trailing `/` moves and keeps the name |
- | `olcli ignored [dir]` | List active ignore patterns |
- | `olcli zip [project]` | Download as zip archive |
- | `olcli compile [project]` | Trigger compilation |
- | `olcli pdf [project]` | Compile and download PDF |
- | `olcli output [type]` | Download compile outputs |
- | `olcli comments list [project]` | List review comments |
- | `olcli comments add <file> <msg>` | Add a comment |
- | `olcli comments reply <id> <body>` | Reply to a thread |
- | `olcli comments resolve <id>` | Resolve a thread |
- | `olcli comments reopen <id>` | Reopen a thread |
- | `olcli comments delete <id>` | Delete a thread |
- | `olcli config set-url <url>` | Set self-hosted base URL |
- | `olcli config get-url` | Show the configured base URL |
- | `olcli config set-cookie-name <name>` | Set cookie name |
- | `olcli config get-cookie-name` | Show the configured cookie name |
- | `olcli config set-timeout <ms>` | Set HTTP timeout |
- | `olcli config get-timeout` | Show the configured HTTP timeout |
- | `olcli project rename <newname> [project]` | Rename a project |
- | `olcli project rename-bulk` | Rename many projects by pattern (dry-run unless `--apply`) |
- ## Tips
- - **Auto-detect project**: Run commands from a synced directory (contains `.olcli.json`) to skip the project argument
- - **Dry run**: Use `olcli push --dry-run` or `olcli sync --dry-run` to preview before applying
- - **Preview content**: `push --dry-run` lists files by modification time; `olcli diff` compares actual contents, so the two lists can differ
- - **CI gate**: `olcli diff --exit-code` exits 1 when anything differs and 2 when the run failed, so a pipeline can distinguish drift from breakage
- - **Force overwrite**: Use `olcli pull --force` to overwrite local changes
- - **Two-way deletes**: `olcli sync` propagates *local* deletions to the remote; use `--no-delete` to opt out per run
- - **Build artifacts**: `.aux`, `.bbl`, `.log`, `.synctex.gz` etc. are filtered by default. Add custom patterns to a `.olignore` file (gitignore-style)
- - **PDF rule**: `thesis.pdf` next to `thesis.tex` is auto-ignored; standalone `figures/diagram.pdf` is preserved
- - **Project ID**: You can use project ID instead of name (24-char hex from URL)
- - **Debug auth**: Run `olcli auth status` to see where credentials are loaded from
- - **Timeout**: `olcli --timeout 60000 pull "Big Project"` or `olcli config set-timeout 60000`
README.md · README · 249 lines
- # olcli: Overleaf CLI
- **Work on Overleaf projects from your terminal while your coauthors keep using the Overleaf web editor.** Pull, push, sync, diff and compile LaTeX projects; read and answer review comments; use Overleaf as a git remote; give AI agents an MCP server that asks you before it writes.
- [](https://github.com/aloth/olcli/actions/workflows/ci.yml)
- [](https://www.npmjs.com/package/@aloth/olcli)
- [](https://www.npmjs.com/package/@aloth/olcli)
- [](https://opensource.org/licenses/MIT)
- [](https://doi.org/10.5281/zenodo.23896243)
- [](https://glama.ai/mcp/servers/aloth/olcli)
- [](https://agentskills.io)
- - **Coauthors change nothing.** They keep editing, commenting and compiling in the browser; you work in Vim, VS Code, Emacs or an agent and sync with the same project.
- - **Works on the free Overleaf plan.** Pull, push, sync, diff, latexdiff, compile, PDF and output downloads, file operations, zip, comment listing and the git remote helper were checked on a free overleaf.com account. Tracked changes are the exception: Overleaf itself only offers them in premium projects.
- - **Works on self-hosted Overleaf Community Edition** with the same commands.
- - **No git token, no paid plan.** olcli signs in with your normal Overleaf session. Overleaf's own Git integration is a premium feature; olcli's git remote helper is not tied to it.
- - **One package:** command-line tool, git remote helper, MCP server and TypeScript library.
- > **If olcli saves you time, please star the repository.** To reference it in a paper, see [Citation](#citation).
- <p align="center">
- <img src="screenshots/demo.gif" alt="olcli demo" width="600">
- </p>
- <p align="center">
- <img src="screenshots/latexdiff.gif" alt="olcli diff --latexdiff --pdf turns a local edit into a marked-up PDF" width="600">
- </p>
- ## Install
- ```bash
- brew install aloth/tap/olcli # Homebrew (macOS, Linux)
- npm install -g @aloth/olcli # npm (any platform, Node 20.18.1 or newer)
- ```
- On Linux with Nix: `nix run github:aloth/olcli -- --help`. Without installing: `npx @aloth/olcli list`. For AI agents through AgentSkills: `npx skills add aloth/olcli`.
- ## Quick start
- ```bash
- olcli auth --browser # sign in through a browser window
- olcli list # your projects
- olcli pull "My Thesis" # download into ./My_Thesis
- cd My_Thesis
- vim main.tex
- olcli diff # what would change on Overleaf
- olcli push # upload your edits
- olcli pdf # compile on Overleaf and download the PDF
- ```
- `olcli auth --browser` opens the login page in Chrome, Edge, Chromium or Brave with a new temporary profile (never your own), waits until you have signed in, and keeps only the session cookie. It works with SSO, Google, ORCID and two-factor logins, and olcli never sees your password. It needs Node 22 or newer; set `OLCLI_BROWSER` when your browser is not found.
- ### Sign in with a session cookie
- No supported browser, or a server without a display? Paste the cookie instead:
- ```bash
- olcli auth --cookie # prompts, input stays hidden
- pbpaste | olcli auth --cookie - # or read it from stdin
- olcli auth status # instance, account, where the credential comes from
- ```
- **Get your session cookie:** sign in to Overleaf in a browser, open the developer tools (F12), then Application (Chrome, Edge) or Storage (Firefox), Cookies, and copy the value of `overleaf_session2` (`overleaf.sid` on most self-hosted instances). A value on the command line also works but lands in your shell history.
- Self-hosted instances without reCAPTCHA also accept `olcli auth --email you@example.com`, which prompts for the password. overleaf.com requires a captcha for password sign-in, which olcli cannot complete, so use `olcli auth --browser` or `olcli auth --cookie` there; on a terminal, a refused password sign-in offers the browser sign-in instead. Scripts can set `OVERLEAF_SESSION`, or on self-hosted instances without reCAPTCHA `OVERLEAF_EMAIL` and `OVERLEAF_PASSWORD`, and skip `olcli auth` entirely.
- ### Self-hosted Overleaf
- ```bash
- olcli config set-url https://latex.example.org
- olcli config set-cookie-name overleaf.sid
- olcli auth --browser
- ```
- Or per command: `olcli --base-url https://latex.example.org list`. The MCP server and the git remote helper read `OVERLEAF_BASE_URL` and `OVERLEAF_COOKIE_NAME`.
- ## Features
- - **Pull, push, sync** with nested folders, local deletions propagated on `sync`, and LaTeX build artifacts ignored ([ignore rules](docs/CONFIGURATION.md#ignoring-files))
- - **Diff** local files against the live project before you push, with `--exit-code` for CI ([docs/DIFF.md](docs/DIFF.md))
- - **Marked-up revisions:** `olcli diff --latexdiff --pdf` builds the struck-through and underlined PDF advisors and journals ask for, compiled on Overleaf, no local TeX needed (needs `latexdiff` on PATH)
- - **Compile and download** the PDF, a single root document (`-r appendix.tex`), or compile outputs such as `.bbl` for arXiv
- - **Files:** upload, download, delete, rename and move by path; download the project as a zip
- - **Review comments:** list, add, reply, resolve, reopen and delete comment threads
- - **Tracked changes:** list suggested insertions and deletions, accept or reject them. Track changes is an Overleaf premium feature: it is only available in projects whose owner has a premium plan, and invited collaborators on any plan can then use it. In other projects there are no tracked changes to list
- - **Projects:** create, rename, and bulk-rename by pattern (dry run unless `--apply`)
- - **Git remote:** `git clone overleaf::https://www.overleaf.com/project/<id>` ([docs/GIT-REMOTE.md](docs/GIT-REMOTE.md))
- - **MCP server** for AI agents; every tool that writes asks you first ([docs/MCP.md](docs/MCP.md))
- - **Forgiving project names:** case-insensitive, unique prefixes, "Did you mean" suggestions
- - **Scriptable:** `--json` on listings, plain output when piped, `NO_COLOR`, exit codes that mean something
- ## Use with Claude Code, Codex and Cursor
- olcli ships an MCP server, `olcli-mcp`. Add it to `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor) or your client's MCP settings:
- ```json
- {
- "mcpServers": {
- "overleaf": {
- "command": "npx",
- "args": ["-y", "--package", "@aloth/olcli", "olcli-mcp"]
- }
- }
- }
- ```
- Codex uses TOML in `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project):
- ```toml
- [mcp_servers.overleaf]
- command = "npx"
- args = ["-y", "--package", "@aloth/olcli", "olcli-mcp"]
- ```
- The server uses the session stored by `olcli auth`; set `OVERLEAF_SESSION` in `env` instead if you prefer. Every tool that changes a project (push a file, delete, rename, comment, accept or reject tracked changes, create a project) shows you what it will do and writes only after you confirm it in the client. The server tells the agent that project content, such as comments and document text, is data and not instructions. Details, the full tool list and clients without confirmation support: [docs/MCP.md](docs/MCP.md).
- ## Commands
- Inside a pulled directory (it contains `.olcli.json`), the project argument can be left out. `olcli <command> --help` shows every option with examples.
- | Command | Description |
- |---------|-------------|
- | `olcli auth` | Sign in: `--browser`, `--cookie`, or `--email` |
- | `olcli auth status` | Instance, account, credential source; exits 1 when not signed in |
- | `olcli logout` | Clear stored credentials |
- | `olcli list` | List projects (`--json`, `-n`) |
- | `olcli info [project]` | Project details and file list |
- | `olcli project create <name>` | Create a blank or example project (`--template`) |
- | `olcli project rename <new> [project]` | Rename the project itself |
- | `olcli project rename-bulk` | Rename many projects by pattern (dry run unless `--apply`) |
- | `olcli pull [project] [dir]` | Download project files |
- | `olcli push [dir]` | Upload local changes (`--dry-run`, `--all`, `--delete`) |
- | `olcli sync [dir]` | Pull then push, propagating local deletions (`--no-delete`, `--dry-run`) |
- | `olcli diff [project] [dir]` | Content diff against the live project (`--name-only`, `--exit-code`, `--latexdiff`, `--pdf`) |
- | `olcli upload <file> [project]` | Upload one file (`--to <path>`) |
- | `olcli download <file> [project]` | Download one file (`-o`) |
- | `olcli delete <file> [project]` | Delete a file or folder (alias `rm`) |
- | `olcli rename <old> <new> [project]` | Rename or move a file or folder (alias `mv`) |
- | `olcli zip [project]` | Download the project as a zip archive |
- | `olcli compile [project]` | Compile on Overleaf (`-r <root.tex>`) |
- | `olcli pdf [project]` | Compile and download the PDF (`-o`, `-r`) |
- | `olcli output [type]` | Download compile outputs such as `bbl` or `log` (`--list`) |
- | `olcli comments list [project]` | List comments (`--status`, `--context`, `--changes`, `--json`) |
- | `olcli comments add <file> <message>` | Comment on selected text |
- | `olcli comments reply <id> <body>` | Reply to a thread |
- | `olcli comments resolve <id>` | Resolve a thread (`reopen` and `delete` too) |
- | `olcli changes accept <ids...>` | Accept tracked changes (premium projects) |
- | `olcli changes reject <ids...>` | Reject tracked changes; preview unless `--yes` |
- | `olcli config set-url <url>` | Set the instance URL (`get-url`, `set-cookie-name`, `set-timeout`) |
- | `olcli ignored [dir]` | Show the ignore patterns in effect |
- Global options: `--base-url <url>`, `--cookie-name <name>`, `--timeout <ms>`, `--verbose` (print every HTTP request), `--no-color`.
- ## How sync works
- - `pull` downloads every file and skips local files changed since the last pull; `--force` overwrites them.
- - `push` uploads files changed since the last pull and keeps the folder structure. `push --dry-run` lists them; `olcli diff` shows what actually differs.
- - `sync` pulls, then pushes. Local edits win when they are newer, and a file you deleted locally is deleted on Overleaf (`--no-delete` to opt out; `sync --dry-run --verbose` to preview).
- - Before a push, `olcli diff` compares against the project as it is on Overleaf right now, so you see a coauthor's newer edit before you overwrite it.
- ## Examples
- ```bash
- # Daily thesis workflow
- olcli pull "PhD Thesis" thesis && cd thesis
- olcli sync && olcli pdf -o draft.pdf
- # Marked-up PDF of your local revision for your advisor
- olcli diff --latexdiff --pdf
- # Fail a CI job when the paper on Overleaf drifted from the repository
- olcli diff --exit-code --name-only
- # Review comments, with two lines of context
- olcli comments list --status open --context 2
- # arXiv submission prep
- olcli output bbl -o main.bbl
- olcli zip -o arxiv-submission.zip
- # Back up every project
- for proj in $(olcli list --json | jq -r '.[].name'); do
- olcli zip "$proj" -o "backups/${proj}.zip"
- done
- ```
- ## Proxy
- olcli honors `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` and `NO_PROXY` (lower-case names take precedence) for every request. https:// instances are reached through a CONNECT tunnel, so the proxy never sees the session cookie. `localhost` and loopback addresses are always reached directly. `--verbose` names the proxy used for each request.
- ```bash
- HTTPS_PROXY=http://proxy.example.org:3128 olcli list
- ```
- ## Configuration and credentials
- Credentials are read in this order: `OVERLEAF_SESSION`, then `.olauth` in the current directory (written by `olcli auth --save-local`), then the global config. `olcli auth status` shows which one is used and where it lives. The session cookie is stored in plaintext; a password only when you pass `--save-password`. `olcli logout` clears the global config and `.olauth`.
- Every environment variable, the timeout setting and the ignore rules (`.olignore`, `.olignore.local`) are described in [docs/CONFIGURATION.md](docs/CONFIGURATION.md). `olcli --help` lists the variables too.
- ## Library
- ```ts
- import { OverleafClient } from '@aloth/olcli';
- const client = await OverleafClient.fromSessionCookie(cookie);
- const projects = await client.listProjects();
- const pdf = await client.downloadPdf(projects[0].id);
- ```
- All exports: [docs/LIBRARY.md](docs/LIBRARY.md).
- ## Troubleshooting
- - **"Session expired or invalid. Run: olcli auth"**: sessions expire; sign in again. `olcli auth status` tells you which credential was used.
- - **Timeouts on large projects:** `olcli config set-timeout 60000`, or `--timeout 60000` once.
- - **Compilation fails:** the Overleaf web editor shows the full log; `olcli output log` downloads it.
- - **Anything else:** run the command with `--verbose` and include the output (without the cookie) in an issue.
- ## Documentation
- - [docs/DIFF.md](docs/DIFF.md): diff, latexdiff and the CI gate
- - [docs/MCP.md](docs/MCP.md): MCP server, tools and write confirmation
- - [docs/GIT-REMOTE.md](docs/GIT-REMOTE.md): Overleaf as a git remote
- - [docs/CONFIGURATION.md](docs/CONFIGURATION.md): credentials, environment variables, timeout, ignore rules
- - [docs/LIBRARY.md](docs/LIBRARY.md): TypeScript library
- - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the client talks to Overleaf (there is no public Overleaf API, so it uses a browser session)
- ## Contributing
- Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, which tests need a real Overleaf account, and what CI checks on a pull request.
- ## Citation
- If you use olcli in your research, please cite it. GitHub's "Cite this repository" button in the sidebar gives the reference in APA and BibTeX, from [CITATION.cff](CITATION.cff). The DOI [10.5281/zenodo.23896243](https://doi.org/10.5281/zenodo.23896243) always resolves to the latest version.
- ```bibtex
- @software{loth_olcli,
- author = {Loth, Alexander},
- title = {{olcli}: Command-line interface for Overleaf},
- doi = {10.5281/zenodo.23896243},
- url = {https://github.com/aloth/olcli}
- }
- ```
- ## License
- MIT © [Alexander Loth](https://alexloth.com)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.