Skip to content

CLI 能力地图

这篇文档给出 ChatOL 当前 CLI 能力、对应 Python API 和后续规划边界。下面两棵树由真实 Click 注册表通过 ChatStyle 生成，并由测试与 oleaf --tree / oleaf --tree-brief 保持同步。完整命令示例见 CLI 实战指南。

注册命令树（含签名）

oleaf
├── --help  # Show this message and exit.
├── --version  # Show the version and exit.
├── --tree  # Print the registered CLI tree and exit.
├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
├── --base-url BASE-URL  # Overleaf instance base URL. Defaults to OVERLEAF_SITE_URL.
├── --email EMAIL  # Account email. Defaults to OVERLEAF_ADMIN_EMAIL.
├── --password-stdin  # Read the account password from stdin.
├── --session-stdin  # Read an Overleaf session cookie from stdin.
├── --cookie-name COOKIE-NAME  # Session cookie name. Defaults to overleaf_session2.
├── --timeout TIMEOUT  # HTTP timeout in seconds.
├── admin  # Probe admin routes read-only; never change users or projects.
│   └── doctor [--json]  # Report admin availability as text/JSON; read-only.
├── compile  # Trigger remote compiles and optionally write local artifacts.
│   ├── bundle <PROJECT> [--output-dir OUTPUT-DIR] [--output-type OUTPUT-TYPES] [--include-source-zip] [--json]  # Compile PROJECT once and write artifacts to OUTPUT_DIR.
│   ├── output <PROJECT> <OUTPUT-TYPE> [--output OUTPUT] [--json]  # Compile PROJECT and write OUTPUT_TYPE to OUTPUT.
│   ├── pdf <PROJECT> [--output OUTPUT] [--json]  # Compile PROJECT and download PDF to OUTPUT; local write.
│   └── run <PROJECT> [--json]  # Compile PROJECT and emit metadata; credentials stay hidden.
├── doctor [--json]  # Check login/project access read-only; emit text/JSON without credentials.
├── files  # Read remote files or perform explicit local/remote writes.
│   ├── delete <PROJECT> <REMOTE-PATH> [--apply] [--json]  # Delete REMOTE_PATH only with --apply; destructive remote write.
│   ├── list <PROJECT> [--json]  # List PROJECT files as text/JSON; read-only and credential-free.
│   ├── pull <PROJECT> <OUTPUT-DIR> [--force] [--json]  # Download PROJECT into OUTPUT_DIR; writes local files.
│   ├── upload <PROJECT> <LOCAL-PATH> [--remote-path REMOTE-PATH] [--json]  # Upload LOCAL_PATH to PROJECT root; writes remote content.
│   └── zip <PROJECT> [--output OUTPUT] [--json]  # Download PROJECT zip to OUTPUT; writes one local artifact.
├── projects  # Discover projects read-only; never print credentials.
│   ├── info <PROJECT> [--json]  # Resolve PROJECT as text/JSON; read-only and credential-free.
│   └── list [--json]  # List visible projects as text/JSON; read-only and credential-free.
└── templates  # Create local templates or explicitly upload them.
    ├── init <TEMPLATE> <OUTPUT-DIR> [--force] [--json]  # Write TEMPLATE into OUTPUT_DIR; creates local artifacts.
    ├── list [--json]  # List built-in templates as text/JSON; read-only.
    └── upload <PROJECT> <TEMPLATE-DIR> [--json]  # Upload TEMPLATE_DIR files to PROJECT root; remote write.

注册命令树（精简）

oleaf
├── --help  # Show this message and exit.
├── --version  # Show the version and exit.
├── --tree  # Print the registered CLI tree and exit.
├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
├── --base-url  # Overleaf instance base URL. Defaults to OVERLEAF_SITE_URL.
├── --email  # Account email. Defaults to OVERLEAF_ADMIN_EMAIL.
├── --password-stdin  # Read the account password from stdin.
├── --session-stdin  # Read an Overleaf session cookie from stdin.
├── --cookie-name  # Session cookie name. Defaults to overleaf_session2.
├── --timeout  # HTTP timeout in seconds.
├── admin  # Probe admin routes read-only; never change users or projects.
│   └── doctor  # Report admin availability as text/JSON; read-only.
├── compile  # Trigger remote compiles and optionally write local artifacts.
│   ├── bundle  # Compile PROJECT once and write artifacts to OUTPUT_DIR.
│   ├── output  # Compile PROJECT and write OUTPUT_TYPE to OUTPUT.
│   ├── pdf  # Compile PROJECT and download PDF to OUTPUT; local write.
│   └── run  # Compile PROJECT and emit metadata; credentials stay hidden.
├── doctor  # Check login/project access read-only; emit text/JSON without credentials.
├── files  # Read remote files or perform explicit local/remote writes.
│   ├── delete  # Delete REMOTE_PATH only with --apply; destructive remote write.
│   ├── list  # List PROJECT files as text/JSON; read-only and credential-free.
│   ├── pull  # Download PROJECT into OUTPUT_DIR; writes local files.
│   ├── upload  # Upload LOCAL_PATH to PROJECT root; writes remote content.
│   └── zip  # Download PROJECT zip to OUTPUT; writes one local artifact.
├── projects  # Discover projects read-only; never print credentials.
│   ├── info  # Resolve PROJECT as text/JSON; read-only and credential-free.
│   └── list  # List visible projects as text/JSON; read-only and credential-free.
└── templates  # Create local templates or explicitly upload them.
    ├── init  # Write TEMPLATE into OUTPUT_DIR; creates local artifacts.
    ├── list  # List built-in templates as text/JSON; read-only.
    └── upload  # Upload TEMPLATE_DIR files to PROJECT root; remote write.
CLI Python API 说明
oleaf doctor client_from_env, OverleafClient.list_projects 验证配置和项目列表访问
oleaf projects list chatol.workflows.list_projects 列出当前会话可见项目
oleaf projects info chatol.workflows.get_project 按项目名或 ID 解析项目
oleaf files list chatol.workflows.list_files 列出远端文件实体
oleaf files zip chatol.workflows.download_project_zip 下载项目 zip
oleaf files pull chatol.workflows.pull_project 下载并安全解压项目 zip
oleaf files upload chatol.workflows.upload_file 上传根目录单文件
oleaf files delete chatol.workflows.delete_file 受保护删除远端单文件，必须 --apply
oleaf templates list chatol.workflows.list_templates 列出内置本地模板
oleaf templates init chatol.workflows.write_template 把模板写到本地目录
oleaf templates upload chatol.workflows.upload_template 上传模板目录根层文件
oleaf compile run chatol.workflows.compile_project 触发远端编译
oleaf compile pdf chatol.workflows.download_pdf 编译并下载 PDF
oleaf compile output chatol.workflows.download_output 编译并下载指定产物
oleaf compile bundle chatol.workflows.download_compile_bundle 编译一次并下载多个常用产物
oleaf admin doctor chatol.workflows.admin_status 只读探测管理员入口

文件命令边界

  • files pull 默认不覆盖本地文件；覆盖必须显式 --force。
  • files pull 拒绝 zip-slip 路径逃逸。
  • files upload 当前只支持项目根目录文件；嵌套目录和自动建目录属于后续能力。
  • files delete 当前只删除 doc/file，不删除文件夹，并且必须显式 --apply。
  • 项目页缺失 rootFolder metadata 时，client 使用 Socket.IO 项目树回退解析来获取根目录和文件 ID。
  • 默认 JSON 输出不包含内部编译 URL、项目所有者/更新者元数据。
  • templates upload 只上传模板目录根层文件，不做嵌套目录同步。
  • admin doctor 只读探测，不创建、禁用或删除用户。

规划中的文件操作

oleaf files
├── tree <project>
├── download <project> <remote-path> -o <local-path>
└── rename <project> <old-path> <new-name>

要求：

  • tree 应在 /entities 不可用时复用项目树回退解析。
  • download 应按远端路径精确定位文件。
  • rename 应返回结构化 before/after 结果。

规划中的安全同步

oleaf sync
├── plan <project> <dir>
├── pull <project> <dir>
├── push <project> <dir> --apply
└── sync <project> <dir> --no-delete 默认开启

要求：

  • plan 是默认安全入口。
  • 删除默认不执行。
  • 冲突信息必须可 JSON 序列化。
  • ignore 规则覆盖 LaTeX 产物、临时文件和项目本地 ignore 文件。

规划中的管理员和用户管理

oleaf admin
├── doctor
├── users list/get
├── users create/invite
├── users set-password --password-stdin
├── users disable/enable
├── users delete --apply --transfer-projects-to <user>
├── projects list-all
└── projects transfer <project> --to <user> --apply

管理员能力必须单独做路由、权限和版本探测，不能假定 Overleaf 管理员 API 稳定可用，也不能默认直接写 Mongo。

不纳入当前版本的能力

  • 自动修改 LaTeX 源码并回写 Overleaf。
  • 评论和协作线程管理。
  • Overleaf 服务部署、升级、备份本身。
  • 不受保护的破坏性操作。