olcli

olcli — Overleaf CLI

Overleaf 命令行界面 — 在终端中同步、管理和编译 LaTeX 项目。

直接通过命令行操作 Overleaf 项目。使用你喜欢的编辑器在本地编辑，通过 Git 进行版本控制，并与 Overleaf 的云端编译无缝同步。

功能

• 📋 列出所有 Overleaf 项目
• ✨ 创建空白项目或示例项目
• ⬇️ 拉取项目文件到本地目录，以便离线编辑
• ⬆️ 推送本地更改回 Overleaf
• 🔄 同步双向内容，并智能检测冲突
• 🔍 比较差异，推送前将本地文件与远程实时版本进行比较
• 📝 带标注的修订稿 — diff --latexdiff 可生成带删除线和下划线的 PDF，满足导师和期刊的要求
• 🔀 Git 远程仓库 — 将 Overleaf 用作原生 Git 远程仓库（文档）
• ✌️ 双向删除 — 本地删除的文件会在下次同步时从 Overleaf 删除
• 🗑️ 按路径删除和 ✏️ 重命名远程文件
• 🚫 智能忽略 — 自动过滤 LaTeX 构建产物和操作系统杂项；可通过 .olignore 扩展规则
• 📄 使用 Overleaf 的远程编译器编译 PDF
• 📦 下载单个文件或完整项目归档
• 📤 将文件上传到项目
• 💬 审阅评论 — 列出、添加、解决、重新打开、删除评论并回复讨论串
• 🗂️ 推送嵌套文件时保留文件夹结构
• ⏱️ 针对慢速连接的可配置超时
• 🔑 面向自托管实例的密码登录（无需浏览器）
• ⚙️ 支持自托管 Overleaf/ShareLaTeX
• 📊 输出编译产物（用于 arXiv 投稿的 .bbl、.log、.aux）
• 🤖 面向 AI 助手的 MCP 服务（文档）

适用于：

• 在你偏好的文本编辑器（Vim、VS Code、Emacs 等）中编辑 LaTeX
• 使用 Overleaf 编译器的同时通过 Git 进行版本控制
• 自动化工作流和 CI/CD 流水线
• 离线工作并定期同步

安装

Homebrew（macOS/Linux）

brew tap aloth/tap
brew install olcli

npm（所有平台）

npm install -g @aloth/olcli

也可以使用 npx，无需安装：

npx @aloth/olcli list

用于 AI Agent（通过 AgentSkills）

npx skills add aloth/olcli

快速入门

1. 身份验证

会话 Cookie（overleaf.com 和自托管实例）：

olcli auth --cookie "your_session_cookie_value"

电子邮件/密码（不使用 reCAPTCHA 的自托管实例）：

olcli auth --email "[email protected]"
# prompts for the password, so it stays out of your shell history

除非传入 --save-password，否则不会存储密码。无论是否保存密码，都会保存会话 Cookie，后续命令会使用该 Cookie；密码只用于在 Cookie 过期后自动重新登录。对于脚本，可设置 OVERLEAF_EMAIL 和 OVERLEAF_PASSWORD——每条命令都会读取这些变量，因此脚本运行时无需执行 olcli auth。

2. 列出项目

olcli list

3. 拉取、编辑、推送

olcli pull "My Thesis"
cd My_Thesis/
vim main.tex
olcli push

4. 编译 PDF

olcli pdf
# Compile a specific .tex file (for multi-doc projects):
olcli pdf -r appendix.tex

5. 或使用原生 Git 命令

git clone overleaf::https://www.overleaf.com/project/<id>
cd <project>
# edit, commit, push — standard git workflow
git push

详见 Git 远程辅助程序文档。

命令

在已同步的目录（包含 .olcli.json）中运行时，所有命令都会自动检测项目。

命令	描述
olcli auth	设置会话 Cookie，或使用电子邮件和密码登录
olcli whoami	检查身份验证状态
olcli logout	清除全局配置和本地 .olauth，并分别报告
olcli list	列出所有项目
olcli info [project]	显示项目详情和文件列表
olcli pull [project] [dir]	将项目文件下载到本地目录
olcli push [dir]	将本地更改上传到 Overleaf（--delete 也会删除本地已删除的文件）
olcli sync [dir]	双向同步（拉取 + 推送）
olcli diff [project] [dir]	显示本地文件与远程文件之间的内容级更改
olcli upload <file> [project]	上传单个文件（--to <path> 设置远程目标路径）
olcli download <file> [project]	下载单个文件
olcli delete <file> [project]	删除远程文件或文件夹（别名：rm）
olcli rename <old> <new> [project]	重命名远程文件或文件夹（别名：mv）
olcli project create <name>	创建空白项目或示例项目（--template blank|example）
olcli project rename <new> [project]	重命名项目本身（--dry-run）
olcli project rename-bulk	按模式批量重命名项目（除非使用 --apply，否则仅试运行）
olcli compile [project]	触发 PDF 编译
olcli pdf [project]	编译并下载 PDF
olcli output [type]	下载编译输出文件
olcli zip [project]	将项目下载为 zip 压缩包
olcli comments list [project]	列出评论（--status、--context、--concurrency）；--changes 还会列出已跟踪的更改（使用 --json 时，输出格式为 { comments, changes }）
olcli changes accept <ids...>	按 ID 接受已跟踪的更改（--project、--json）
olcli changes reject <ids...>	按 ID 拒绝已跟踪的更改；除非使用 --yes，否则仅预览（--project、--json）
olcli comments add <file> <msg>	为选中的文本添加评论
olcli comments reply <id> <body>	回复评论讨论串
olcli comments resolve <id>	解决评论讨论串
olcli comments reopen <id>	重新打开已解决的讨论串
olcli comments delete <id>	删除评论讨论串
olcli ignored [dir]	列出当前生效的忽略模式
olcli config set-url <url>	设置可自托管实例的基础 URL
olcli config get-url	显示已配置的基础 URL
olcli config set-cookie-name <name>	设置会话 Cookie 名称
olcli config get-cookie-name	显示已配置的会话 Cookie 名称
olcli config set-timeout <ms>	设置默认 HTTP 超时
olcli config get-timeout	显示已配置的 HTTP 超时
olcli check	显示配置路径和凭据来源

已跟踪的更改是 Overleaf 的高级功能。 只有项目所有者拥有高级方案的项目才能使用此功能；受邀协作者无论自己的方案如何，都可以使用此功能。在其他项目中，不会有已跟踪的更改，因此 --changes 会返回空列表，而 changes accept/changes reject 会报告找不到这些 ID。详情请参阅 Overleaf 文档。

编译选项

与编译相关的命令（compile、pdf、output）支持：

标志	描述
-r, --resource <path>	将指定的 .tex 文件编译为根文档（例如 appendix.tex、folder/test.tex）

适用于包含多个文档的项目：每次运行 -r，都会将指定文件作为主文档进行编译。

全局选项

标志	描述
--verbose	将 HTTP 请求和响应打印到标准错误
--base-url <url>	覆盖 Overleaf 实例 URL
--cookie-name <name>	覆盖会话 Cookie 名称
--timeout <ms>	覆盖 HTTP 超时（默认值：10000）

同步行为

拉取

• 下载 Overleaf 中的所有文件
• 跳过自上次拉取后修改过的本地文件（不会覆盖你的更改）
• 使用 --force 覆盖本地更改

推送

• 上传自上次拉取后修改过的文件
• 保留嵌套文件夹结构
• 过滤掉 LaTeX 构建产物和操作系统杂项
• 使用 --all 上传所有文件，使用 --dry-run 预览

同步

• 拉取远程更改，然后推送本地更改
• 如果本地修改较新，则以本地修改为准
• 会传播本地删除——使用 --no-delete 关闭此行为
• 使用 --dry-run 预览但不应用更改

差异

olcli diff 会比较本地文件与项目当前内容的字节，并输出统一差异。

olcli diff                 # every changed file, as patches
olcli diff --name-only     # just the changed paths
olcli diff --file main.tex # one file
olcli diff -U 8            # wider context
olcli diff --exit-code     # exit 1 if anything differs, for CI

每次运行都会重新获取远程内容。 差异反映的是项目在当时的状态——也就是后续 push 会覆盖的内容——而不是与你上次 pull 的内容进行比较。.olcli.json 只记录远程路径，从不记录远程内容，因此没有存储快照可供比较；整个项目会通过单个请求获取，和 pull 使用的请求相同，所以重新获取只需一次往返，而非每个文件一次。协作者在 diff 和 push 之间进行编辑，仍可能改变结果，因此命令会打印获取时间。

在输出中，a/ 是远程内容，b/ 是本地内容：+ 行表示 push 会上传的内容，- 行表示 push 会覆盖的内容。仅在非文本字节上不同的文件（PDF、图像）会显示为 Binary files ... differ。两侧都会经过相同的忽略规则，因此不会把 Overleaf 上的构建产物报告为本地已删除。

diff --name-only 和 push --dry-run 回答的是不同问题，结果也会不同。push --dry-run 会列出修改时间晚于上次拉取的文件，因为这就是 push 会上传的内容；diff 会列出内容确实不同的文件。一个仅被触碰但未编辑的文件会出现在前者中，而不会出现在后者中。

使用 latexdiff 标记修订

统一差异适合开发者，却不适合论文导师。--latexdiff 会在文档中标记同一修订——删除内容加删除线，新增内容加下划线——这正是导师和期刊所要求的格式。

olcli diff --latexdiff          # write .olcli-diff/main-diff.tex
olcli diff --latexdiff --pdf    # ...and compile it, download .olcli-diff/main-diff.pdf

需要在 PATH 中安装 latexdiff。它随 TeX Live 和 MacTeX 一同提供；olcli diff 的其他功能都不需要外部工具。

--pdf 会在 Overleaf 上编译，因此你无需本地安装 TeX。 编译端点只能编译项目中的文件，因此标记后的文档会以 olcli-latexdiff.tex 的名称上传到根文档旁边，进行编译和下载，然后删除。命令会在执行前说明此操作；如果同名文件已存在，则会拒绝覆盖；如果清理本身失败，还会打印确切的 olcli rm 命令。

比较前会内联处理 \input 和 \include（使用 --no-flatten 可关闭此行为）。否则，远程编译会将它们解析为项目中现有的文件——也就是旧内容——并悄悄生成一份显示所有输入文件都未更改的 PDF。

输出会写入 .olcli-diff/；目录名带点，因此 push 和 sync 都不会将其纳入处理；使用 -o <path> 可将输出放到其他位置。根文档是声明了 \documentclass 的 .tex 文件；如果有多个此类文件，可使用 --main <path> 指定一个，而不是让命令自行猜测。--latexdiff-opt 会将其他选项原样传递，例如 --latexdiff-opt --math-markup=0。

还有一个需要注意的限制：--pdf 是基于项目而非工作目录进行编译，因此标记所需的所有文件都必须已在 Overleaf 上。你在本地添加的 .sty 或 .cls 文件会导致编译失败——发生这种情况时，编译器日志会写在标记后源文件旁边。你在本地添加的图像不会导致编译失败；Overleaf 会绘制一个标有缺失文件名的占位框，其余 PDF 内容不受影响。

使用 diff 作为 CI 门禁

--exit-code 会将命令变为检查，并使用 diff(1) 采用的状态码：

状态	含义
0	没有差异
1	存在差异
2	运行失败——参数错误、没有会话或项目无法访问

- name: Fail if the paper on Overleaf has drifted from the repo
  run: olcli diff --exit-code --name-only
  env:
    OVERLEAF_SESSION: ${{ secrets.OVERLEAF_SESSION }}

状态码 1 和 2 的区分正是这个标志的意义所在。 没有它，流水线就无法区分文件已更改和会话 Cookie 已过期；如果后一种情况导致任务失败，查看日志的人就会去寻找一个根本没有计算过的差异。其他所有 olcli 命令都以 1 表示失败；如果未指定 --exit-code，olcli diff 也仍然如此，因此添加该标志不会改变现有脚本的行为。

门禁会检查实际参与比较的内容：--file main.tex 会将范围缩小到单个文件，效果与 git diff --exit-code 的路径规范相同；如果 --file 没有匹配到任何文件，结果是 0，而不是错误。在 --latexdiff 模式下，它仍会检查整个项目——图像发生更改也是真实差异，即使带标记的根文档无法显示这一点。

请注意，此比较的对象是当前的 Overleaf，而不是你上次拉取时的状态；因此，这项检查回答的是“是否有人提交了与此处内容不同的更改”，这也是它适合定期运行、而不仅仅是在推送时运行的原因。

删除如何同步

olcli 会在 .olcli.json 中记录远程文件清单。下次同步时：

• 本地文件缺失，远程仍存在 → 在 Overleaf 上删除
• 本地新增文件 → 上传
• 本地文件已修改 → 上传（以本地为准）
• 仅存在于远程的文件 → 下载

首次同步会跳过删除阶段（没有先前的清单可供比较）。

忽略文件

三个层级

层级	来源	用途
1	内置	LaTeX 中间文件、操作系统杂项、构建目录。始终启用。
2	.olignore	项目级模式（gitignore 语法）。
3	.olignore.local	机器特定的模式。

后面的层级会覆盖前面的层级。支持否定规则（!important.aux）。

特殊 PDF 规则

只有在同一文件夹中存在 X.tex（或 .ltx）时，才会忽略 X.pdf。

检查与覆盖

olcli ignored                  # list patterns in effect
olcli push --show-ignored      # see what was skipped
olcli sync --no-default-ignore # only .olignore applies
olcli sync --no-ignore         # upload everything

配置

凭据按以下顺序检查：

1. OVERLEAF_SESSION 环境变量
2. 当前目录中的 .olauth 文件
3. 全局配置——运行 olcli check 查看确切路径

全局配置路径取决于平台（由 conf 解析），因此这里不硬编码：在 macOS 上，路径位于 ~/Library/Preferences/ 下；在 Linux 上，位于 ~/.config/ 下。olcli auth 会打印它写入的路径。

⚠️ olcli auth --save-local 会将 .olauth 写入当前目录，通常也就是你的 LaTeX 项目目录。提交之前，请将其加入该项目的 .gitignore。

存储内容及清除方法

所有内容都以明文存储，因此了解磁盘上保存了什么很重要：

凭据	默认存储	位置
会话 Cookie	是	全局配置，或使用 --save-local 时存入 .olauth
电子邮件和密码	否——仅在使用 --save-password 时存储	全局配置

olcli check 会报告已存在的内容，但不会打印任何秘密信息。

olcli logout 会清除全局配置以及当前目录中的 .olauth 文件，然后列出已删除的内容。它无法取消设置环境变量，因此，如果设置了 OVERLEAF_SESSION 或 OVERLEAF_EMAIL/OVERLEAF_PASSWORD，它会明确说明，而不会让你误以为自己已退出登录——这些环境变量的优先级高于磁盘上的任何内容。

自托管 Overleaf

olcli config set-url https://latex.example.org
olcli config set-cookie-name overleaf.sid

或者按命令传入：olcli --base-url https://latex.example.org list

超时

olcli config set-timeout 60000          # persist
olcli --timeout 60000 pull "Big Thesis" # one-off
export OVERLEAF_TIMEOUT=60000           # env var

优先级：--timeout > OVERLEAF_TIMEOUT > 配置 > 默认值（10000ms）。

环境变量

olcli 会读取以下变量。MCP 服务和 git 远程辅助程序读取相同的会话、密码和 Cookie 名称变量。如果存在对应的标志，标志优先于变量，变量优先于已存储的配置。

变量	用途
OVERLEAF_SESSION	会话 Cookie 值
OVERLEAF_EMAIL、OVERLEAF_PASSWORD	密码登录；未设置会话 Cookie 或会话 Cookie 被拒绝时使用
OVERLEAF_BASE_URL	实例 URL，与 --base-url 类似（默认值：https://www.overleaf.com）
OVERLEAF_COOKIE_NAME	会话 Cookie 名称，与 --cookie-name 类似（默认值：overleaf_session2；自托管实例通常使用 overleaf.sid）
OVERLEAF_TIMEOUT	HTTP 超时时间（毫秒），与 --timeout 类似
OLCLI_CONCURRENCY	comments list 并行获取的文档数，范围为 1 至 8（默认值：4）；--concurrency 优先
OLCLI_MCP_UNCONFIRMED_WRITES	仅用于 MCP 服务：设为 1 可关闭写入确认，参见 docs/MCP.md
GIT_REMOTE_OVERLEAF_DEBUG	仅用于 git 远程辅助程序：设为 1 可输出协议调试信息，参见 docs/GIT-REMOTE.md

示例

# Daily thesis workflow
olcli pull "PhD Thesis" thesis && cd thesis
vim chapters/methods.tex
olcli sync && olcli pdf -o draft.pdf

# Quick PDF download
olcli pdf "Conference Paper" -o paper.pdf

# Compile a specific root document
olcli pdf "Conference Paper" -r appendix.tex -o appendix.pdf
olcli compile "Conference Paper" -r folder/test.tex

# Upload figures
olcli upload figures/diagram.png          # relative path is preserved
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

# arXiv submission prep
olcli output bbl -o main.bbl
olcli output bbl -r folder/test.tex -o main.bbl  # compile artifacts from a specific root doc
olcli zip -o arxiv-submission.zip

# Backup all projects
for proj in $(olcli list --json | jq -r '.[].name'); do
  olcli zip "$proj" -o "backups/${proj}.zip"
done

编程使用（库 API）

@aloth/olcli 将 OverleafClient 和所有公共接口作为库开放使用。

安装

npm install @aloth/olcli

基本示例

import { OverleafClient } from '@aloth/olcli';

const client = await OverleafClient.fromSessionCookie(cookie);

const created = await client.createProject('My Paper');
const projects = await client.listProjects();
const info = await client.getProjectInfo(projectId);
const zipBuf = await client.downloadProject(projectId);
const pdfBuf = await client.downloadPdf(projectId);

await client.uploadFile(projectId, null, 'main.tex', readFileSync('main.tex'));

const comments = await client.listComments(projectId, { status: 'open' });

可用导出项

import {
  OverleafClient,
  // Types
  Project, ProjectInfo, ProjectTemplate, CreateProjectOptions, CreatedProject,
  FolderEntry, DocEntry, FileEntry,
  CommentMessage, ProjectComment, CommentContext, CommentStatus,
  ListCommentsOptions, AddCommentOptions, Credentials, SessionCookiePair,
  // Config utilities
  getBaseUrl, setBaseUrl, getSessionCookie, setSessionCookie,
  getSessionCookieName, setSessionCookieName, getCsrf, setCsrf,
  getLastProject, setLastProject, clearConfig, getConfigPath, saveOlAuth,
  getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials,
  clearPasswordCredentials, type PasswordCredentials,
  // Ignore utilities
  DEFAULT_IGNORE_PATTERNS, loadIgnore, shouldIgnore, buildTexSiblingSet,
  IgnoreContext, LoadIgnoreOptions,
} from '@aloth/olcli';

更多文档

• MCP 服务 — AI 助手集成（Claude、Cursor、Windsurf）
  • 更改项目的工具会通过 MCP elicitation 请求你确认；未经确认不会写入任何内容。不支持 elicitation 的客户端会收到预览和可供运行的 olcli 命令。设为 OLCLI_MCP_UNCONFIRMED_WRITES=1 可关闭此功能。参见写入确认
• Git 远程辅助程序 — 将 Overleaf 用作原生 git 远程仓库

故障排除

会话已过期 — 从浏览器获取新的 Cookie，然后再次运行 olcli auth。

编译失败 — 查看 Overleaf 网页编辑器中的详细错误日志（缺少软件包、语法错误、缺少参考文献文件）。

参与贡献

欢迎贡献！请提交 issue 或拉取请求。

请参阅 CONTRIBUTING.md，了解本地环境配置、哪些测试需要真实的 Overleaf 账号，以及拉取请求的 CI 流程。

docs/ARCHITECTURE.md 说明了客户端的工作原理 — Overleaf 没有公开 API，因此客户端会以浏览器会话进行身份验证。

许可证

MIT © Alexander Loth