Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aloth--olcli/badge.svg)](/listings/aloth--olcli)

HTML

<a href="/listings/aloth--olcli"><img src="/api/listings/aloth--olcli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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
  1. ---
  2. name: overleaf
  3. 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.
  4. license: MIT
  5. metadata:
  6. author: aloth
  7. version: "1.3"
  8. cli: olcli
  9. install: brew tap aloth/tap && brew install olcli
  10. ---
  11. # Overleaf Skill
  12. Manage Overleaf LaTeX projects via the `olcli` CLI, native git remote, or MCP server.
  13. ## When to Use Which Mode
  14. | Mode | Best for | How |
  15. |------|----------|-----|
  16. | **CLI** (`olcli`) | Interactive workflows, sync, compile, arXiv prep | `olcli pull/push/sync/pdf` |
  17. | **Git remote** | Version control, commits, diffs, CI/CD pipelines | `git clone overleaf::…` then standard git |
  18. | **MCP server** | AI agents with MCP support (Claude, Cursor, Windsurf) | Connect via `olcli-mcp` stdio transport |
  19. 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.
  20. ## Installation
  21. ```bash
  22. # Homebrew (recommended)
  23. brew tap aloth/tap && brew install olcli
  24. # npm
  25. npm install -g @aloth/olcli
  26. ```
  27. ## Authentication
  28. Get your session cookie from Overleaf:
  29. 1. Log into [overleaf.com](https://www.overleaf.com)
  30. 2. Open DevTools (F12) → Application → Cookies
  31. 3. Copy the value of `overleaf_session2`
  32. ```bash
  33. olcli auth --cookie "YOUR_SESSION_COOKIE"
  34. ```
  35. Or sign in through a browser window (SSO, Google, two-factor; olcli keeps only the session cookie):
  36. ```bash
  37. olcli auth --browser
  38. ```
  39. Verify and debug authentication (instance, account, credential source, masked cookie):
  40. ```bash
  41. olcli auth status
  42. ```
  43. Clear stored credentials:
  44. ```bash
  45. olcli logout
  46. ```
  47. Clears the global config and the `.olauth` file in the current directory, and
  48. reports each. Environment variables cannot be unset by a child process, so
  49. `OVERLEAF_SESSION` and `OVERLEAF_EMAIL`/`OVERLEAF_PASSWORD` are reported rather
  50. than silently ignored — they outrank anything on disk.
  51. For unattended use on a self-hosted instance without reCAPTCHA, prefer
  52. `OVERLEAF_EMAIL`/`OVERLEAF_PASSWORD` over `olcli auth --password`: every
  53. command reads them, and nothing is written to disk or to shell history.
  54. overleaf.com requires a captcha for password sign-in, which olcli cannot
  55. complete; use `olcli auth --browser` or `OVERLEAF_SESSION` there.
  56. ### Self-hosted Overleaf
  57. ```bash
  58. olcli config set-url https://overleaf.yourcompany.com
  59. olcli config set-cookie-name overleaf.sid # if different from default
  60. olcli auth --cookie "YOUR_COOKIE"
  61. ```
  62. Or pass per-command: `olcli --base-url https://overleaf.yourcompany.com list`
  63. ## Git Remote Helper
  64. Use Overleaf projects as native git remotes. No wrapper scripts needed.
  65. ```bash
  66. # Clone
  67. git clone overleaf::https://www.overleaf.com/project/<id>
  68. cd <project>
  69. # Edit, commit, push — standard git workflow
  70. vim main.tex
  71. git add . && git commit -m "update introduction"
  72. git push
  73. # Pull latest from Overleaf (a push is refused while Overleaf has edits you
  74. # have not pulled; git push --force overwrites them on purpose)
  75. git pull
  76. ```
  77. Authentication: reads `OVERLEAF_SESSION` env var, the `.olauth` file in the current directory, or stored config (same as CLI).
  78. For self-hosted instances, just use your instance URL:
  79. ```bash
  80. git clone overleaf::https://overleaf.yourcompany.com/project/<id>
  81. ```
  82. Debug with: `GIT_REMOTE_OVERLEAF_DEBUG=1 git push`
  83. ## MCP Server
  84. Built-in Model Context Protocol server for AI assistant integration.
  85. ```bash
  86. # Run standalone
  87. olcli-mcp
  88. # Or via npx (the server is the olcli-mcp command of the @aloth/olcli package)
  89. npx -y --package @aloth/olcli olcli-mcp
  90. ```
  91. 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).
  92. `compile`, `download_pdf` and `compile_with_outputs` accept an optional `resource_path` to compile a specific root document.
  93. `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.
  94. Auth: set `OVERLEAF_SESSION` env var in MCP config, or use stored credentials from `olcli auth`.
  95. ## Common Workflows
  96. ### Pull a project to work locally
  97. ```bash
  98. olcli pull "My Paper"
  99. cd My_Paper/
  100. ```
  101. ### Create a project
  102. ```bash
  103. olcli project create "My Paper"
  104. olcli project create "Example Paper" --template example
  105. ```
  106. ### Edit and sync changes
  107. ```bash
  108. # After editing files locally
  109. olcli push # Upload changes only
  110. olcli sync # Bidirectional sync (pull + push, propagates local deletions)
  111. olcli sync --no-delete # Sync without propagating local deletions to remote
  112. ```
  113. ### Review changes before pushing
  114. ```bash
  115. olcli diff # unified diff of every changed file
  116. olcli diff --name-only # changed paths only
  117. olcli diff --file main.tex # a single file
  118. olcli diff --exit-code # CI gate: 0 same, 1 differs, 2 failed
  119. ```
  120. The remote side is fetched fresh each run, so this shows what a subsequent
  121. `push` would overwrite — not a comparison against the last `pull`. `a/` is the
  122. remote, `b/` is local. Binary files are reported as differing without a patch.
  123. `--exit-code` uses `diff(1)`'s statuses so the command can gate a pipeline:
  124. `0` nothing differs, `1` something does, `2` the run itself failed. The last
  125. one matters — without it a job cannot tell a changed file from an expired
  126. session. Failures stay `1` when the flag is absent, so existing scripts are
  127. unaffected.
  128. ### Delete or rename remote files
  129. ```bash
  130. olcli delete chapters/old.tex # remove a file from the project
  131. olcli rm figures/old.pdf # alias
  132. olcli rename old.tex new.tex # rename a file, it stays in its folder
  133. olcli mv chapters/draft.tex chapters/intro.tex # alias: rename inside chapters/
  134. olcli mv draft.tex chapters/intro.tex # move into chapters/ and rename
  135. olcli mv figures/old.pdf archive/ # move into archive/, keep the name
  136. olcli mv chapters/notes.tex / # move to the project root
  137. ```
  138. `delete` accepts a path. For `rename` (alias `mv`) the destination decides what
  139. happens. A bare name without `/` renames the entity in place: it keeps its
  140. folder. A path with a folder part moves the entity into that folder and gives
  141. it the last part as its name; missing folders are created. A destination ending
  142. in `/` moves the entity and keeps its name, and `/` alone or a leading `/` means
  143. the project root. Files, documents and folders can all be moved.
  144. Nothing is written, and the command exits 1, when the destination already
  145. exists, the source is not found, or a folder would be moved into itself or one
  146. of its subfolders. When both the folder and the name change, olcli renames
  147. first and then moves, or moves first when the new name is already taken in the
  148. old folder; every clash is checked against the project tree before the first
  149. request.
  150. ### Inspect ignore rules
  151. ```bash
  152. olcli ignored # list active patterns (built-ins + .olignore + .olignore.local)
  153. olcli push --show-ignored # see what was filtered on this run
  154. olcli sync --no-ignore # escape hatch: upload everything
  155. ```
  156. ### Compile and download PDF
  157. ```bash
  158. olcli pdf # Compile and download
  159. olcli pdf -o paper.pdf # Custom output name
  160. olcli pdf -r chapters/intro.tex # Compile a specific root document
  161. olcli compile # Just compile (no download)
  162. olcli compile -r appendix.tex # Compile a specific root document without downloading
  163. ```
  164. `-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.
  165. ### Download .bbl for arXiv submission
  166. ```bash
  167. olcli output bbl # Download compiled .bbl
  168. olcli output bbl -o main.bbl # Custom filename
  169. olcli output bbl -r appendix.tex
  170. olcli output --list # List all available outputs
  171. ```
  172. ### Upload figures or assets
  173. ```bash
  174. olcli upload figure1.png "My Paper" # Upload to project root
  175. olcli upload diagram.pdf # Auto-detect project from .olcli.json
  176. olcli upload figures/diagram.png # Relative path is preserved remotely
  177. olcli upload /tmp/build/diagram.png # Absolute path lands in the project root
  178. olcli upload /tmp/build/diagram.png --to figures/diagram.png # Explicit destination
  179. ```
  180. Remote path rules: a relative local path keeps its directory part, an absolute
  181. local path collapses to its basename, and `--to` overrides both.
  182. ### Download specific files
  183. ```bash
  184. olcli download main.tex "My Paper" # Download single file
  185. olcli zip "My Paper" # Download entire project as zip
  186. ```
  187. ### Review comments
  188. ```bash
  189. olcli comments list # List all comments (current project)
  190. olcli comments list --status open # Filter by status (open/resolved/all)
  191. olcli comments list --context # Include surrounding text
  192. olcli comments add main.tex "Fix this citation" --from 10 --to 15 # Add comment
  193. olcli comments reply <thread-id> "Done!" # Reply to thread
  194. olcli comments resolve <thread-id> # Mark as resolved
  195. olcli comments reopen <thread-id> # Reopen a resolved thread
  196. olcli comments delete <thread-id> # Delete entire thread
  197. ```
  198. ## arXiv Submission Workflow
  199. Complete workflow for preparing an arXiv submission:
  200. ```bash
  201. # 1. Pull your project
  202. olcli pull "Research Paper"
  203. cd Research_Paper
  204. # 2. Compile to ensure everything builds
  205. olcli compile
  206. # 3. Download the .bbl file (arXiv requires .bbl, not .bib)
  207. olcli output bbl -o main.bbl
  208. # 4. Download any other needed outputs
  209. olcli output aux -o main.aux # If needed
  210. # 5. Package for submission
  211. zip arxiv.zip *.tex main.bbl figures/*.pdf
  212. # 6. Verify the package compiles locally (optional)
  213. # Then upload arxiv.zip to arxiv.org
  214. ```
  215. ## Commands Reference
  216. | Command | Description |
  217. |---------|-------------|
  218. | `olcli auth --cookie <value>` | Authenticate with session cookie |
  219. | `olcli auth --email <e>` | Authenticate with password, prompted (self-hosted) |
  220. | `olcli auth --browser` | Sign in through a browser window, keep only the session cookie |
  221. | `olcli auth status` | Instance, account, credential source; exits 1 when not signed in |
  222. | `olcli logout` | Clear the global config and the local `.olauth` |
  223. | `olcli list` | List all projects |
  224. | `olcli project create <name>` | Create a blank or example project |
  225. | `olcli info [project]` | Show project details |
  226. | `olcli pull [project] [dir]` | Download project files |
  227. | `olcli push [dir]` | Upload local changes |
  228. | `olcli sync [dir]` | Bidirectional sync |
  229. | `olcli diff [project] [dir]` | Content-level diff of local files vs. the live remote |
  230. | `olcli upload <file> [project]` | Upload a single file (`--to <path>` sets the remote destination) |
  231. | `olcli download <file> [project]` | Download a single file |
  232. | `olcli delete <file> [project]` | Delete a remote file or folder (alias: `rm`) |
  233. | `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 |
  234. | `olcli ignored [dir]` | List active ignore patterns |
  235. | `olcli zip [project]` | Download as zip archive |
  236. | `olcli compile [project]` | Trigger compilation |
  237. | `olcli pdf [project]` | Compile and download PDF |
  238. | `olcli output [type]` | Download compile outputs |
  239. | `olcli comments list [project]` | List review comments |
  240. | `olcli comments add <file> <msg>` | Add a comment |
  241. | `olcli comments reply <id> <body>` | Reply to a thread |
  242. | `olcli comments resolve <id>` | Resolve a thread |
  243. | `olcli comments reopen <id>` | Reopen a thread |
  244. | `olcli comments delete <id>` | Delete a thread |
  245. | `olcli config set-url <url>` | Set self-hosted base URL |
  246. | `olcli config get-url` | Show the configured base URL |
  247. | `olcli config set-cookie-name <name>` | Set cookie name |
  248. | `olcli config get-cookie-name` | Show the configured cookie name |
  249. | `olcli config set-timeout <ms>` | Set HTTP timeout |
  250. | `olcli config get-timeout` | Show the configured HTTP timeout |
  251. | `olcli project rename <newname> [project]` | Rename a project |
  252. | `olcli project rename-bulk` | Rename many projects by pattern (dry-run unless `--apply`) |
  253. ## Tips
  254. - **Auto-detect project**: Run commands from a synced directory (contains `.olcli.json`) to skip the project argument
  255. - **Dry run**: Use `olcli push --dry-run` or `olcli sync --dry-run` to preview before applying
  256. - **Preview content**: `push --dry-run` lists files by modification time; `olcli diff` compares actual contents, so the two lists can differ
  257. - **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
  258. - **Force overwrite**: Use `olcli pull --force` to overwrite local changes
  259. - **Two-way deletes**: `olcli sync` propagates *local* deletions to the remote; use `--no-delete` to opt out per run
  260. - **Build artifacts**: `.aux`, `.bbl`, `.log`, `.synctex.gz` etc. are filtered by default. Add custom patterns to a `.olignore` file (gitignore-style)
  261. - **PDF rule**: `thesis.pdf` next to `thesis.tex` is auto-ignored; standalone `figures/diagram.pdf` is preserved
  262. - **Project ID**: You can use project ID instead of name (24-char hex from URL)
  263. - **Debug auth**: Run `olcli auth status` to see where credentials are loaded from
  264. - **Timeout**: `olcli --timeout 60000 pull "Big Project"` or `olcli config set-timeout 60000`
README.md · README · 249 lines
  1. # olcli: Overleaf CLI
  2. **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.
  3. [![CI](https://github.com/aloth/olcli/actions/workflows/ci.yml/badge.svg)](https://github.com/aloth/olcli/actions/workflows/ci.yml)
  4. [![npm version](https://img.shields.io/npm/v/@aloth/olcli.svg)](https://www.npmjs.com/package/@aloth/olcli)
  5. [![npm downloads](https://img.shields.io/npm/dm/@aloth/olcli.svg)](https://www.npmjs.com/package/@aloth/olcli)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23896243.svg)](https://doi.org/10.5281/zenodo.23896243)
  8. [![Glama MCP server](https://glama.ai/mcp/servers/aloth/olcli/badges/score.svg)](https://glama.ai/mcp/servers/aloth/olcli)
  9. [![AgentSkills](https://img.shields.io/badge/AgentSkills-compatible-blue)](https://agentskills.io)
  10. - **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.
  11. - **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.
  12. - **Works on self-hosted Overleaf Community Edition** with the same commands.
  13. - **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.
  14. - **One package:** command-line tool, git remote helper, MCP server and TypeScript library.
  15. > **If olcli saves you time, please star the repository.** To reference it in a paper, see [Citation](#citation).
  16. <p align="center">
  17. <img src="screenshots/demo.gif" alt="olcli demo" width="600">
  18. </p>
  19. <p align="center">
  20. <img src="screenshots/latexdiff.gif" alt="olcli diff --latexdiff --pdf turns a local edit into a marked-up PDF" width="600">
  21. </p>
  22. ## Install
  23. ```bash
  24. brew install aloth/tap/olcli # Homebrew (macOS, Linux)
  25. npm install -g @aloth/olcli # npm (any platform, Node 20.18.1 or newer)
  26. ```
  27. 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`.
  28. ## Quick start
  29. ```bash
  30. olcli auth --browser # sign in through a browser window
  31. olcli list # your projects
  32. olcli pull "My Thesis" # download into ./My_Thesis
  33. cd My_Thesis
  34. vim main.tex
  35. olcli diff # what would change on Overleaf
  36. olcli push # upload your edits
  37. olcli pdf # compile on Overleaf and download the PDF
  38. ```
  39. `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.
  40. ### Sign in with a session cookie
  41. No supported browser, or a server without a display? Paste the cookie instead:
  42. ```bash
  43. olcli auth --cookie # prompts, input stays hidden
  44. pbpaste | olcli auth --cookie - # or read it from stdin
  45. olcli auth status # instance, account, where the credential comes from
  46. ```
  47. **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.
  48. 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.
  49. ### Self-hosted Overleaf
  50. ```bash
  51. olcli config set-url https://latex.example.org
  52. olcli config set-cookie-name overleaf.sid
  53. olcli auth --browser
  54. ```
  55. 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`.
  56. ## Features
  57. - **Pull, push, sync** with nested folders, local deletions propagated on `sync`, and LaTeX build artifacts ignored ([ignore rules](docs/CONFIGURATION.md#ignoring-files))
  58. - **Diff** local files against the live project before you push, with `--exit-code` for CI ([docs/DIFF.md](docs/DIFF.md))
  59. - **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)
  60. - **Compile and download** the PDF, a single root document (`-r appendix.tex`), or compile outputs such as `.bbl` for arXiv
  61. - **Files:** upload, download, delete, rename and move by path; download the project as a zip
  62. - **Review comments:** list, add, reply, resolve, reopen and delete comment threads
  63. - **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
  64. - **Projects:** create, rename, and bulk-rename by pattern (dry run unless `--apply`)
  65. - **Git remote:** `git clone overleaf::https://www.overleaf.com/project/<id>` ([docs/GIT-REMOTE.md](docs/GIT-REMOTE.md))
  66. - **MCP server** for AI agents; every tool that writes asks you first ([docs/MCP.md](docs/MCP.md))
  67. - **Forgiving project names:** case-insensitive, unique prefixes, "Did you mean" suggestions
  68. - **Scriptable:** `--json` on listings, plain output when piped, `NO_COLOR`, exit codes that mean something
  69. ## Use with Claude Code, Codex and Cursor
  70. olcli ships an MCP server, `olcli-mcp`. Add it to `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor) or your client's MCP settings:
  71. ```json
  72. {
  73. "mcpServers": {
  74. "overleaf": {
  75. "command": "npx",
  76. "args": ["-y", "--package", "@aloth/olcli", "olcli-mcp"]
  77. }
  78. }
  79. }
  80. ```
  81. Codex uses TOML in `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project):
  82. ```toml
  83. [mcp_servers.overleaf]
  84. command = "npx"
  85. args = ["-y", "--package", "@aloth/olcli", "olcli-mcp"]
  86. ```
  87. 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).
  88. ## Commands
  89. Inside a pulled directory (it contains `.olcli.json`), the project argument can be left out. `olcli <command> --help` shows every option with examples.
  90. | Command | Description |
  91. |---------|-------------|
  92. | `olcli auth` | Sign in: `--browser`, `--cookie`, or `--email` |
  93. | `olcli auth status` | Instance, account, credential source; exits 1 when not signed in |
  94. | `olcli logout` | Clear stored credentials |
  95. | `olcli list` | List projects (`--json`, `-n`) |
  96. | `olcli info [project]` | Project details and file list |
  97. | `olcli project create <name>` | Create a blank or example project (`--template`) |
  98. | `olcli project rename <new> [project]` | Rename the project itself |
  99. | `olcli project rename-bulk` | Rename many projects by pattern (dry run unless `--apply`) |
  100. | `olcli pull [project] [dir]` | Download project files |
  101. | `olcli push [dir]` | Upload local changes (`--dry-run`, `--all`, `--delete`) |
  102. | `olcli sync [dir]` | Pull then push, propagating local deletions (`--no-delete`, `--dry-run`) |
  103. | `olcli diff [project] [dir]` | Content diff against the live project (`--name-only`, `--exit-code`, `--latexdiff`, `--pdf`) |
  104. | `olcli upload <file> [project]` | Upload one file (`--to <path>`) |
  105. | `olcli download <file> [project]` | Download one file (`-o`) |
  106. | `olcli delete <file> [project]` | Delete a file or folder (alias `rm`) |
  107. | `olcli rename <old> <new> [project]` | Rename or move a file or folder (alias `mv`) |
  108. | `olcli zip [project]` | Download the project as a zip archive |
  109. | `olcli compile [project]` | Compile on Overleaf (`-r <root.tex>`) |
  110. | `olcli pdf [project]` | Compile and download the PDF (`-o`, `-r`) |
  111. | `olcli output [type]` | Download compile outputs such as `bbl` or `log` (`--list`) |
  112. | `olcli comments list [project]` | List comments (`--status`, `--context`, `--changes`, `--json`) |
  113. | `olcli comments add <file> <message>` | Comment on selected text |
  114. | `olcli comments reply <id> <body>` | Reply to a thread |
  115. | `olcli comments resolve <id>` | Resolve a thread (`reopen` and `delete` too) |
  116. | `olcli changes accept <ids...>` | Accept tracked changes (premium projects) |
  117. | `olcli changes reject <ids...>` | Reject tracked changes; preview unless `--yes` |
  118. | `olcli config set-url <url>` | Set the instance URL (`get-url`, `set-cookie-name`, `set-timeout`) |
  119. | `olcli ignored [dir]` | Show the ignore patterns in effect |
  120. Global options: `--base-url <url>`, `--cookie-name <name>`, `--timeout <ms>`, `--verbose` (print every HTTP request), `--no-color`.
  121. ## How sync works
  122. - `pull` downloads every file and skips local files changed since the last pull; `--force` overwrites them.
  123. - `push` uploads files changed since the last pull and keeps the folder structure. `push --dry-run` lists them; `olcli diff` shows what actually differs.
  124. - `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).
  125. - 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.
  126. ## Examples
  127. ```bash
  128. # Daily thesis workflow
  129. olcli pull "PhD Thesis" thesis && cd thesis
  130. olcli sync && olcli pdf -o draft.pdf
  131. # Marked-up PDF of your local revision for your advisor
  132. olcli diff --latexdiff --pdf
  133. # Fail a CI job when the paper on Overleaf drifted from the repository
  134. olcli diff --exit-code --name-only
  135. # Review comments, with two lines of context
  136. olcli comments list --status open --context 2
  137. # arXiv submission prep
  138. olcli output bbl -o main.bbl
  139. olcli zip -o arxiv-submission.zip
  140. # Back up every project
  141. for proj in $(olcli list --json | jq -r '.[].name'); do
  142. olcli zip "$proj" -o "backups/${proj}.zip"
  143. done
  144. ```
  145. ## Proxy
  146. 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.
  147. ```bash
  148. HTTPS_PROXY=http://proxy.example.org:3128 olcli list
  149. ```
  150. ## Configuration and credentials
  151. 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`.
  152. 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.
  153. ## Library
  154. ```ts
  155. import { OverleafClient } from '@aloth/olcli';
  156. const client = await OverleafClient.fromSessionCookie(cookie);
  157. const projects = await client.listProjects();
  158. const pdf = await client.downloadPdf(projects[0].id);
  159. ```
  160. All exports: [docs/LIBRARY.md](docs/LIBRARY.md).
  161. ## Troubleshooting
  162. - **"Session expired or invalid. Run: olcli auth"**: sessions expire; sign in again. `olcli auth status` tells you which credential was used.
  163. - **Timeouts on large projects:** `olcli config set-timeout 60000`, or `--timeout 60000` once.
  164. - **Compilation fails:** the Overleaf web editor shows the full log; `olcli output log` downloads it.
  165. - **Anything else:** run the command with `--verbose` and include the output (without the cookie) in an issue.
  166. ## Documentation
  167. - [docs/DIFF.md](docs/DIFF.md): diff, latexdiff and the CI gate
  168. - [docs/MCP.md](docs/MCP.md): MCP server, tools and write confirmation
  169. - [docs/GIT-REMOTE.md](docs/GIT-REMOTE.md): Overleaf as a git remote
  170. - [docs/CONFIGURATION.md](docs/CONFIGURATION.md): credentials, environment variables, timeout, ignore rules
  171. - [docs/LIBRARY.md](docs/LIBRARY.md): TypeScript library
  172. - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the client talks to Overleaf (there is no public Overleaf API, so it uses a browser session)
  173. ## Contributing
  174. 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.
  175. ## Citation
  176. 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.
  177. ```bibtex
  178. @software{loth_olcli,
  179. author = {Loth, Alexander},
  180. title = {{olcli}: Command-line interface for Overleaf},
  181. doi = {10.5281/zenodo.23896243},
  182. url = {https://github.com/aloth/olcli}
  183. }
  184. ```
  185. ## License
  186. MIT © [Alexander Loth](https://alexloth.com)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.