Agent Skills › Oleafly/Oleafly › oleafly-cli

oleafly-cli

GitHub

oleafly-cli 用于在终端或 AI Agent 中构建、诊断和检查 Oleafly LaTeX/Typst/Markdown 项目。支持编译错误修复、结构分析、字数统计、格式导出及引用管理，旨在自动化文档处理流程。

src-tauri/resources/skills/oleafly-cli/SKILL.md Oleafly/Oleafly

触发场景

用户要求修复无法编译的文档需要获取项目结构如文件列表、大纲、引用状态执行文档字数统计或导出为 Word/HTML 等格式进行参考文献查找或清理

安装

npx skills add Oleafly/Oleafly --skill oleafly-cli -g -y

更多选项

非标准路径

npx skills add https://github.com/Oleafly/Oleafly/tree/main/src-tauri/resources/skills/oleafly-cli -g -y

不安装直接使用

npx skills use Oleafly/Oleafly@oleafly-cli

指定 Agent (Claude Code)

npx skills add Oleafly/Oleafly --skill oleafly-cli -a claude-code -g -y

安装 repo 全部 skill

npx skills add Oleafly/Oleafly --all -g -y

预览 repo 内 skill

npx skills add Oleafly/Oleafly --list

SKILL.md

Frontmatter

{
    "name": "oleafly-cli",
    "license": "MIT",
    "metadata": {
        "oleafly": {
            "tier": "native",
            "phase": "tooling",
            "tools": [
                "run_command",
                "read_file",
                "replace_in_file"
            ]
        },
        "version": "1.0.0",
        "skill-author": "Oleafly"
    },
    "description": "Build, diagnose and inspect an Oleafly LaTeX, Typst or Markdown project from a terminal or a coding agent with the oleafly command. Use for compile errors and build logs, the project's outline, labels and citations, word counts, exports to Word or HTML, citation lookup and bibliography cleanup, Typst versions, checkpoints, and setting up Oleafly's MCP server for an AI client.",
    "allowed-tools": "Bash(oleafly:*) Read Edit",
    "compatibility": "Needs the oleafly command from Oleafly 0.4.8 or later."
}

The oleafly command

oleafly builds and inspects Oleafly projects outside the app, with the app's own compilers and settings. A project built here builds the same way in the app.

When to use it

The user asks you to fix a document that doesn't compile.
You need the project's structure: files, outline, labels, citations, missing files, unresolved references.
You need a word count, an export (Word, HTML, EPUB, slides), a citation's BibTeX, or a bibliography check.
The user wants Oleafly's MCP server in their AI client.

Ground rules

Always pass --json (before or after the command). Read one JSON object from stdout.
Check ok. When it is false, act on error.code and follow error.hint. Don't guess from error.message.
The exit code tells you what kind of fix is needed (table below). A build failure (5) means fix the document; a missing tool (4) means tell the user what to install; a busy project (8) means wait and retry.
Never pass --yes, --apply or --force unless the user said to go ahead. Without them, commands that change files only show what they would do.
Don't edit anything inside .oleafly/. It belongs to the app.
Run commands from the project folder, or pass -C <folder>.
Don't start oleafly agent run or oleafly ask unless the user asks for it. They run another AI agent on the user's keys and cost them money.

The fix loop

oleafly --json context            # learn the project once
# edit the sources
oleafly --json build              # compile
oleafly --json log --diagnostics  # errors and warnings with file and line
# fix the first error, then build again

Fix the first error only, then build again. Later errors are often caused by the first one. Stop when build.ok is true and build.errors is empty.

Commands

Command	What it does
`oleafly build [--main FILE] [-o PATH]`	Compile the project. `build.errors` lists the problems.
`oleafly watch`	Rebuild on every change (Ctrl+C stops).
`oleafly log [--diagnostics] [--tail N]`	The last build's log, or its diagnostics.
`oleafly context`	Files, outline, labels, citations, missing files, last build.
`oleafly doctor`	What is installed and what is missing, with fixes.
`oleafly stats [--files]`	Words, headings, figures and equations.
`oleafly synctex forward --file F --line N`	Where a source line is in the PDF (LaTeX).
`oleafly synctex inverse --page N --x X --y Y`	The source line at a PDF point (LaTeX).
`oleafly export --to docx`	Export the main document (docx, html, md, txt, pptx, epub, typst, tex; Typst also pdf, png, svg).
`oleafly convert FILE --to latex`	Convert one file (latex, markdown, typst, html, docx).
`oleafly cite <doi or arXiv id> [--add]`	BibTeX for a DOI, arXiv id, ISBN or PubMed id; `--add` adds it to the project's .bib.
`oleafly literature "<query>"`	Search OpenAlex, Semantic Scholar, Crossref, arXiv and PubMed.
`oleafly bib check`	Entries whose DOI or title matches no real record (exit 9).
`oleafly bib clean`	Preview key fixes and duplicate removal (`--apply` with the user's go-ahead).
`oleafly typst versions`	Typst versions, which are installed, which is the default.
`oleafly checkpoint list`	The app's checkpoints of this project; `diff ID` compares one with now.
`oleafly config get main`	A project setting (`name`, `main`, `engine`, `compiler`, `typst.version`, `compile_dir`).
`oleafly new DIR --template ID`	A new project from a template (`oleafly templates list --all`).
`oleafly mcp config --client claude-code`	The MCP entry for an AI client (`--write` adds it).
`oleafly auth status`	Saved sign-ins for online LaTeX services, collaboration servers and Git hosts (never the secrets).
`oleafly remote status`	Whether this folder is linked to an online project, and which token sync would use.
`oleafly remote diff --name-only`	Files that differ from the online project; `sync` merges both ways (only with the user's go-ahead).
`oleafly server comments list`	Open comment threads on this shared project.
`oleafly check [--exit-code]`	The app's Preflight checks before submission (exit 9 with `--exit-code` when errors remain).
`oleafly lint [PATH]`	LaTeX, BibTeX, spelling and grammar problems; `--fix` only with the user's go-ahead.
`oleafly daemon status`	Whether Oleafly's background helper is running research tasks after the app closed.

Exit codes

Code	Meaning	What to do
0	It worked.	Continue.
1	A bug in Oleafly.	Report it to the user with the message.
2	The command was used wrongly, or needs `--yes`.	Fix the arguments; ask before adding `--yes`.
3	The project is missing or invalid, or a path is outside it.	Check the folder and `project.json`.
4	A tool or the app isn't installed, no AI provider is set up, or a file outside the project couldn't be read or written.	Tell the user what to install or set up (see `hint`).
5	The build failed.	Read `build.errors` and fix the first one.
6	Sign-in needed.	Ask the user to sign in.
7	The network failed.	Retry later; it may be offline.
8	The project is busy (another build, the app).	Wait a moment and retry.
9	A check found problems.	Report or fix the findings.
10	An agent run reached its step or time limit.	Report what was done; raise the limit only if the user asks.
130	Interrupted.	Stop.

MCP

oleafly mcp is an MCP server on stdio. It bridges to the running app when the app has the project open (the app's tools and approvals), else it serves read tools and compile on its own. oleafly mcp config --client <client> prints the settings entry for claude-code, claude-desktop, codex, cursor or gemini.

Windows

The command is oleafly.exe, installed in %LOCALAPPDATA%\Oleafly\bin. After installing, only new terminals find it.
In PowerShell, quote arguments with spaces in double quotes, and pass --json output to ConvertFrom-Json.

references/json-contract.md describes the JSON result, the error object, progress events and the fields of the build, context and log results.

版本历史

afd83e2 当前 2026-11-02 08:54

元信息

文件数: 0
版本: afd83e2
Hash: 22235513
收录时间: 2026-11-02 08:54

oleafly-cli

oleafly-cli

触发场景

安装

SKILL.md

The oleafly command

When to use it

Ground rules

The fix loop

Commands

Exit codes

MCP

Windows

More

版本历史

同 Skill 集合

元信息

文库