by aloth
Overleaf CLI - pull, push, sync, compile LaTeX projects from your terminal. Git remote helper, MCP server for AI agents, and TypeScript library.
# Add to your Claude Code skills
git clone https://github.com/aloth/olcliGuides for using ai agents skills like olcli.
Last scanned: 7/3/2026
{
"issues": [
{
"type": "npm-audit",
"message": "ajv: ajv has ReDoS when using `$data` option",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "fast-uri: fast-uri vulnerable to path traversal via percent-encoded dot segments",
"severity": "high"
},
{
"type": "npm-audit",
"message": "undici: Undici: Malicious WebSocket 64-bit length overflows parser and crashes the client",
"severity": "high"
}
],
"status": "WARNING",
"scannedAt": "2026-07-03T07:21:13.745Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}See how olcli compares with popular alternatives.
olcli is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by aloth. Overleaf CLI - pull, push, sync, compile LaTeX projects from your terminal. Git remote helper, MCP server for AI agents, and TypeScript library. It has 258 GitHub stars.
olcli returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.
Clone the repository with "git clone https://github.com/aloth/olcli" and add it to your Claude Code skills directory (see the Installation section above). olcli ships a SKILL.md manifest, so compatible agents can discover and load it automatically.
olcli is primarily written in TypeScript. It is open-source under aloth on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh olcli against similar tools.
No comments yet. Be the first to share your thoughts!
Requires a passing catalog security scan.
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
Manage Overleaf LaTeX projects via the olcli CLI, native git remote, or MCP server.
| 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.
# Homebrew (recommended)
brew tap aloth/tap && brew install olcli
# npm
npm install -g @aloth/olcli
Get your session cookie from Overleaf:
overleaf_session2olcli auth --cookie "YOUR_SESSION_COOKIE"
Or sign in through a browser window (SSO, Google, two-factor; olcli keeps only the session cookie):
olcli auth --browser
Verify and debug authentication (instance, account, credential source, masked cookie):
olcli auth status
Clear stored credentials:
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, prefer OVERLEAF_EMAIL/OVERLEAF_PASSWORD over
olcli auth --password: every command reads them, and nothing is written to
disk or to shell history.
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
Use Overleaf projects as native git remotes. No wrapper scripts needed.
# 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:
git clone overleaf::https://overleaf.yourcompany.com/project/<id>
Debug with: GIT_REMOTE_OVERLEAF_DEBUG=1 git push
Built-in Model Context Protocol server for AI assistant integration.
# 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.
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.
olcli pull "My Paper"
cd My_Paper/
olcli project create "My Paper"
olcli project create "Example Paper" --template example
# 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
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.
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.
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
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.
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
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.
olcli download main.tex "My Paper" # Download single file
olcli zip "My Paper" # Download entire project as zip
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
Complete workflow for preparing an arXiv submission:
# 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
| 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) |
.olcli.json) to skip the project argumentolcli push --dry-run or olcli sync --dry-run to preview before applyingpush --dry-run lists files by modification time; olcli diff compares actual contents, so the two lists can differolcli diff --exit-code exits 1 when anything differs and 2 when the run failed, so a pipeline can distinguish drift from breakageolcli pull --force to overwrite local changesolcli sync propagates local deletions to the remote; use --no-delete to opt out per run.aux, .bbl, .log, .synctex.gz etc. are filtered by default. Add custom patterns to a .olignore file (gitignore-style)thesis.pdf next to thesis.tex is auto-ignored; standalone figures/diagram.pdf is preservedolcli auth status to see where credentials are loaded fromolcli --timeout 60000 pull "Big Project" or olcli config set-timeout 60000Work 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.
If olcli saves you time, please star the repository. To reference it in a paper, see Citation.
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.
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.
No supported browser, or a server without a display? Paste the cookie instead:
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. Scripts can set OVERLEAF_SESSION, or OVERLEAF_EMAIL and OVERLEAF_PASSWORD, and skip olcli auth entirely.
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.
sync, and LaTeX build artifacts ignored (ignore rules)--exit-code for CI (docs/DIFF.md)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)-r appendix.tex), or compile outputs such as .bbl for arXiv--apply)git clone overleaf::https://www.overleaf.com/project/<id> (docs/GIT-REMOTE.md)--json on listings, plain output when piped, NO_COLOR, exit codes that mean somethingolcli ships an MCP server, olcli-mcp. Add it to .mcp.json (Claude Code), .cursor/mcp.json (Cursor) or your client's MCP settings:
{
"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):
[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.
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.
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