overleaf

Overleaf 技能

通过 olcli CLI、原生 git 远程仓库或 MCP 服务管理 Overleaf LaTeX 项目。

何时使用哪种模式

模式	最适合	用法
CLI (olcli)	交互式工作流、同步、编译、arXiv 准备	olcli pull/push/sync/pdf
Git 远程仓库	版本控制、提交、差异、CI/CD 流水线	git clone overleaf::…，然后使用标准 git
MCP 服务	支持 MCP 的 AI Agent（Claude、Cursor、Windsurf）	通过 olcli-mcp stdio 传输连接

需要具备冲突检测的双向同步、编译或评论管理时，请使用 CLI。需要规范的 git 历史记录、分支和标准 git push/pull 时，请使用 Git 远程仓库。AI Agent 原生支持 MCP 且无需调用 shell 时，请使用 MCP。

安装

# Homebrew (recommended)
brew tap aloth/tap && brew install olcli

# npm
npm install -g @aloth/olcli

身份验证

从 Overleaf 获取会话 Cookie：

1. 登录 overleaf.com
2. 打开 DevTools（F12）→ Application → Cookies
3. 复制 overleaf_session2 的值

olcli auth --cookie "YOUR_SESSION_COOKIE"

使用以下命令验证：

olcli whoami

调试身份验证问题：

olcli check

清除已存储的凭据：

olcli logout

此命令会清除全局配置和当前目录中的 .olauth 文件，并逐一报告。子进程无法取消设置环境变量，因此会报告 OVERLEAF_SESSION 和 OVERLEAF_EMAIL/OVERLEAF_PASSWORD，而不是静默忽略它们——它们的优先级高于任何磁盘上的设置。

无人值守使用时，建议使用 OVERLEAF_EMAIL/OVERLEAF_PASSWORD，而不是 olcli auth --password：每条命令都会读取这些变量，且不会将任何内容写入磁盘或 shell 历史记录。

自托管 Overleaf

olcli config set-url https://overleaf.yourcompany.com
olcli config set-cookie-name overleaf.sid   # if different from default
olcli auth --cookie "YOUR_COOKIE"

也可以按命令传入：olcli --base-url https://overleaf.yourcompany.com list

Git 远程仓库助手

将 Overleaf 项目用作原生 git 远程仓库。无需包装脚本。

# 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
git pull

身份验证：读取 OVERLEAF_SESSION 环境变量、当前目录中的 .olauth 文件或已存储的配置（与 CLI 相同）。

对于自托管实例，只需使用实例 URL：

git clone overleaf::https://overleaf.yourcompany.com/project/<id>

使用 GIT_REMOTE_OVERLEAF_DEBUG=1 git push 进行调试。

MCP 服务

用于集成 AI 助手的内置 Model Context Protocol 服务。

# 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

可用的 MCP 工具：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 和 compile_with_outputs 接受可选的 resource_path，用于编译指定的根文档。

diff_project 是 olcli diff 对应的 MCP 工具：只读，每次调用都会重新获取远程内容，并为每个变更文件返回一个条目，包含 path、status、binary 和统一格式的 patch。传入 name_only 可省略补丁文本。plan_project_renames 可预览批量重命名，但不会实际应用。

身份验证：在 MCP 配置中设置 OVERLEAF_SESSION 环境变量，或使用 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

每次运行都会重新获取最新的远程内容，因此这里显示的是后续 push 将覆盖的内容，而不是与上次 pull 的比较结果。a/ 表示远程内容，b/ 表示本地内容。二进制文件只会报告存在差异，不会提供补丁。

--exit-code 使用 diff(1) 的状态码，因此命令可用于控制流水线：0 表示没有差异，1 表示存在差异，2 表示运行本身失败。最后一种情况很重要——否则，任务无法区分文件已更改和会话已过期。未指定此标志时，失败仍返回 1，因此不会影响现有脚本。

删除或重命名远程文件

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
olcli mv chapters/draft.tex chapters/intro.tex   # alias

检查忽略规则

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

编译并下载 PDF

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> 可用于 compile、pdf 和 output：将指定的 .tex 文件编译为根文档。适用于项目包含多个文档的情况。

下载用于 arXiv 投稿的 .bbl 文件

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

远程路径规则：相对本地路径会保留其目录部分，绝对本地路径会缩减为文件名，而 --to 会覆盖这两种规则。

下载指定文件

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

arXiv 投稿工作流

准备 arXiv 投稿的完整工作流：

# 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

命令参考

命令	描述
olcli auth --cookie <value>	使用会话 Cookie 进行身份验证
olcli auth --email <e>	使用密码进行身份验证，密码会通过提示输入（可自托管）
olcli whoami	检查身份验证状态
olcli logout	清除全局配置和本地 .olauth
olcli check	显示配置路径和凭据来源
olcli list	列出所有项目
olcli project create <name>	创建空白项目或示例项目
olcli info [project]	显示项目详情
olcli pull [project] [dir]	下载项目文件
olcli push [dir]	上传本地更改
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 ignored [dir]	列出当前生效的忽略模式
olcli zip [project]	下载为 zip 压缩包
olcli compile [project]	触发编译
olcli pdf [project]	编译并下载 PDF
olcli output [type]	下载编译输出
olcli comments list [project]	列出审阅评论
olcli comments add <file> <msg>	添加评论
olcli comments reply <id> <body>	回复讨论串
olcli comments resolve <id>	解决讨论串
olcli comments reopen <id>	重新打开讨论串
olcli comments delete <id>	删除讨论串
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 project rename <newname> [project]	重命名项目
olcli project rename-bulk	按模式批量重命名项目（除非使用 --apply，否则为试运行）

提示

• 自动检测项目：在已同步的目录（包含 .olcli.json）中运行命令，即可跳过项目参数
• 试运行：使用 olcli push --dry-run 或 olcli sync --dry-run，在应用更改前预览
• 预览内容：push --dry-run 按修改时间列出文件；olcli diff 比较实际内容，因此两份列表可能不同
• CI 门禁：当存在差异时，olcli diff --exit-code 会以状态码 1 退出；运行失败时则以状态码 2 退出，因此流水线可以区分偏差与故障
• 强制覆盖：使用 olcli pull --force 覆盖本地更改
• 双向删除：olcli sync 会将本地删除操作同步到远程；使用 --no-delete 可在本次运行中选择不执行此操作
• 构建产物：默认会过滤 .aux、.bbl、.log、.synctex.gz 等文件。可在 .olignore 文件中添加自定义模式（gitignore 风格）
• PDF 规则：与 thesis.tex 同目录的 thesis.pdf 会自动忽略；独立的 figures/diagram.pdf 则会保留
• 项目 ID：可以使用项目 ID 代替名称（从 URL 中获取的 24 位十六进制字符串）
• 调试身份验证：运行 olcli check，查看凭据的加载位置
• 超时：运行 olcli --timeout 60000 pull "Big Project" 或 olcli config set-timeout 60000