Bỏ qua để đến nội dung
Oleaflyv0.4.8

Cài lệnh oleafly trên Windows, macOS hoặc Linux, dựng và kiểm tra dự án từ terminal hoặc CI, đồng bộ với một dịch vụ LaTeX trực tuyến, và kết nối các agent lập trình qua máy chủ MCP và skill của nó.

Oleafly đi kèm oleafly, một công cụ dòng lệnh làm việc trên cùng các dự án với ứng dụng. Dựng hoặc kiểm tra một bài báo từ terminal, một script hoặc CI. Cho một agent lập trình một lối vào dự án của bạn đáng tin cậy. Đồng bộ với một dịch vụ LaTeX trực tuyến hoặc một máy chủ Oleafly, hoặc chạy agent của Oleafly mà không cần mở ứng dụng.

Nó đi kèm bên trong ứng dụng trên mọi nền tảng. Trang này nói về các lệnh trong Oleafly 0.4.8 trở lên. Các phiên bản trước có ít lệnh hơn, nên hãy ghim phiên bản Oleafly trong những script phụ thuộc vào nó.

Hệ thốngNơi ứng dụng đặt nóĐặt oleafly lên PATH của bạn
Windowsoleafly-cli.exe cạnh ứng dụng, trong %LOCALAPPDATA%\Oleafly với chương trình cài đặt hoặc C:\Program Files\Oleafly với gói MSIInstall ở dòng Terminal command trong Settings → General sao chép nó vào %LOCALAPPDATA%\Oleafly\bin\oleafly.exe và thêm thư mục đó vào PATH của bạn
macOSOleafly.app/Contents/MacOS/oleafly-cliInstall ở dòng Terminal command liên kết oleafly vào /usr/local/bin khi bạn ghi được ở đó, nếu không thì vào ~/.local/bin
Gói Linux (.deb, .rpm)/usr/bin/oleafly-cliKhông cần làm gì: gói cài sẵn /usr/bin/oleafly
Linux AppImageBên trong AppImageInstall sao chép nó vào ~/.local/bin/oleafly

Các chương trình do Oleafly khởi chạy, chẳng hạn terminal của chính nó và các CLI agent, luôn tìm thấy oleafly trên PATH, kể cả trước khi bạn cài nó. Biến OLEAFLY_CLI giữ đường dẫn đầy đủ của nó.

  1. Mở Settings → General và chọn Install ở dòng Terminal command.
  2. Mở một cửa sổ PowerShell hoặc Command Prompt mới. Các cửa sổ đã mở từ trước vẫn giữ PATH cũ.
  3. Kiểm tra xem nó có hoạt động không:
Cửa sổ terminal
Get-Command oleafly
oleafly version

Remove ở cùng dòng đó xóa bản sao và gỡ thư mục khỏi PATH của bạn. Khi Oleafly cập nhật, nó làm mới bản sao vào lần khởi động tiếp theo.

Trước tiên hãy chuyển Oleafly vào thư mục Applications của bạn. Một bản chạy từ tệp ảnh đĩa sẽ hiển thị “Move Oleafly to your Applications folder first” thay vì Install.

Lệnh này là một liên kết tới ứng dụng, nên cập nhật Oleafly cũng cập nhật lệnh. Nếu thư mục chưa nằm trên PATH của bạn, dòng này hiển thị dòng cần thêm vào hồ sơ shell của bạn. Kiểm tra bằng command -v oleafly.

Các gói .deb và .rpm đặt oleafly lên PATH của bạn khi bạn cài chúng. oleafly đứng một mình, không có gì theo sau, sẽ mở ứng dụng.

AppImage cần một bản sao, vì các tệp bên trong AppImage biến mất khi nó thoát. Sau khi bạn thay AppImage bằng bản mới hơn, dòng này đưa ra Update. Nếu ~/.local/bin chưa nằm trên PATH của bạn, dòng này hiển thị dòng cần thêm.

oleafly version in ra phiên bản ứng dụng và các engine mà lệnh sẽ dùng. oleafly doctor kiểm tra các engine, ứng dụng, Git, lệnh terminal và các MCP client của bạn, và in ra cách khắc phục cho bất cứ thứ gì còn thiếu. Nó cũng chạy được ngoài một dự án.

oleafly . mở thư mục hiện tại trong ứng dụng. Mọi lệnh khác làm việc trên thư mục bạn đang đứng; -C theo sau là một đường dẫn sẽ trỏ nó sang nơi khác.

Cửa sổ terminal
cd ~/papers/thesis
oleafly init --engine typst
oleafly build
oleafly log --diagnostics
oleafly -C ~/papers/review --json build
  • oleafly init biến thư mục hiện tại thành một dự án. --engine nhận tectonic, latexmk, typst hoặc markdown.
  • oleafly new theo sau là một thư mục, --template và một id mẫu sẽ tạo dự án từ một mẫu. oleafly templates list --all liệt kê các mẫu.
  • oleafly build dùng engine và cài đặt của dự án, giống cách ứng dụng làm: Tectonic, Typst và Pandoc đi kèm Oleafly, hoặc LaTeX bạn đã cài. --main dựng một tài liệu khác của dự án, --compiler chọn trình biên dịch LaTeX cho các dự án latexmk, -o sao chép PDF sang nơi khác và --timeout đặt giới hạn tính bằng giây.
  • Một thư mục bạn mở tại chỗ trong ứng dụng được dựng bằng engine và tài liệu chính bạn đã chọn ở đó, vào thư mục dựng riêng của ứng dụng.
  • Ứng dụng và lệnh không bao giờ dựng cùng một dự án cùng lúc: bên thứ hai chờ bên thứ nhất. Một bản dựng thất bại vẫn giữ PDF tốt gần nhất.
  • oleafly watch dựng lại mỗi lần bạn lưu. oleafly log --diagnostics liệt kê lỗi và cảnh báo kèm tệp và dòng, còn oleafly clean xóa kết quả dựng.

Về chi tiết riêng của Typst, xem Dự án Typst.

Các agent lập trình làm việc tốt nhất với ba thứ mà lệnh này mang lại: oleafly context cho bản đồ của dự án, --json cho kết quả chúng đọc được, và mã thoát cho biết điều gì đã sai. Có ba cách để kết nối một agent.

Oleafly đi kèm một skill tên là oleafly-cli. Nó dạy agent các lệnh, đầu ra JSON, các mã thoát, và vòng lặp hiệu quả nhất: đọc ngữ cảnh, chỉnh sửa, dựng, đọc chẩn đoán, sửa lỗi đầu tiên.

Trong terminal của Oleafly và các CLI agent mà nó khởi chạy, hãy chọn skill này như mọi skill khác. Với một agent bạn tự chạy, hãy bật Settings → AI Assistant → Skills → Share skills with other agents on this computer. Khi đó Oleafly liên kết các skill của nó, gồm cả oleafly-cli, vào những thư mục mà các coding agent khác đọc, chẳng hạn ~/.claude/skills, ~/.codex/skills và ~/.agents/skills. oleafly skills path in ra nơi các skill nằm, cho những agent đọc một thư mục khác.

oleafly mcp là một máy chủ MCP giao tiếp qua đầu vào và đầu ra chuẩn. Khi ứng dụng đang mở dự án của bạn, nó chuyển các lời gọi sang máy chủ MCP của chính ứng dụng, nên agent có mọi công cụ của ứng dụng và các lời nhắc phê duyệt của bạn. Nếu không, nó tự làm việc, với các công cụ đọc (trạng thái dự án, bản đồ dự án, tệp, tìm kiếm, nhật ký, báo cáo doctor, tra cứu trích dẫn) và compile. Không có URL hay token nào để chép và không cần cài Node.js.

Cách thiết lập nhanh nhất là oleafly mcp config --client theo sau là claude-code, claude-desktop, codex, cursor hoặc gemini. Nó in ra mục cho client đó; thêm --write để nó được thêm giúp bạn, kèm bản sao lưu tệp của client. Sau đó hãy khởi động lại hoặc kết nối lại client. Trong một dự án, nó ghi vào cài đặt của dự án; ở nơi khác, nó ghi vào cài đặt người dùng của bạn, kèm đường dẫn đầy đủ của lệnh, vì các ứng dụng bạn khởi chạy từ desktop có thể không thấy PATH của bạn.

Cửa sổ terminal
claude mcp add --scope user oleafly -- oleafly mcp

Trong một dự án, oleafly mcp config --client claude-code --write thay vào đó thêm máy chủ vào .mcp.json của dự án.

Claude Desktop khởi chạy máy chủ mà không có thư mục dự án, nên mục của nó luôn làm việc thông qua ứng dụng: hãy để Oleafly mở cùng dự án của bạn. Dùng đường dẫn đầy đủ tới oleafly. Trên Windows, hãy nhân đôi mọi dấu gạch chéo ngược trong đường dẫn.

claude_desktop_config.json
{
"mcpServers": {
"oleafly": {
"command": "/usr/local/bin/oleafly",
"args": ["mcp", "--bridge", "always"]
}
}
}

Tệp nằm trong ~/Library/Application Support/Claude trên macOS và %APPDATA%\Claude trên Windows.

~/.codex/config.toml
[mcp_servers.oleafly]
command = "oleafly"
args = ["mcp"]
tool_timeout_sec = 300

Dùng ~/.cursor/mcp.json cho mọi dự án, hoặc .cursor/mcp.json bên trong một dự án.

~/.cursor/mcp.json
{
"mcpServers": {
"oleafly": {
"command": "oleafly",
"args": ["mcp"]
}
}
}
~/.gemini/settings.json
{
"mcpServers": {
"oleafly": {
"command": "oleafly",
"args": ["mcp"],
"timeout": 300000
}
}
}

oleafly context lập bản đồ dự án: các tệp, dàn ý, nhãn, trích dẫn, tệp còn thiếu, tham chiếu chưa phân giải và các vấn đề của bản dựng gần nhất. --format md cho văn bản để dán vào một prompt; --format json cho cùng bản đồ đó để một chương trình dùng.

oleafly check chạy các kiểm tra Preflight trên dự án, với cùng kết quả như bảng Preflight: tham chiếu, trích dẫn, nhãn, tệp còn thiếu, các trường thư mục tài liệu tham khảo, hình vẽ và tính ẩn danh cho phản biện kín. Các kiểm tra cần PDF đã biên dịch dùng bản dựng gần nhất.

oleafly lint chạy các kiểm tra LaTeX và BibTeX và, trong những bản phát hành có kèm theo, cả chính tả và ngữ pháp. --fix áp dụng những bản sửa an toàn để áp dụng.

Cả hai nhận --format human, json hoặc sarif, và --exit-code khiến chúng thoát với mã 9 khi tìm thấy vấn đề. SARIF dùng được với các dịch vụ quét mã như của GitHub: ghi báo cáo bằng oleafly check --format sarif -o preflight.sarif, tải lên bằng action upload-sarif, và mỗi phát hiện hiển thị ngay trên dòng của nó trong pull request.

Đồng bộ với một dịch vụ LaTeX trực tuyến

Phần tiêu đề “Đồng bộ với một dịch vụ LaTeX trực tuyến”

oleafly remote tải các dự án từ tài khoản dịch vụ LaTeX trực tuyến của bạn và giữ một thư mục đồng bộ với một dự án, với cùng cách hợp nhất mà ứng dụng dùng.

Các lần đăng nhập nằm trong kho mã hóa của ứng dụng, nên một lần đăng nhập thực hiện trong ứng dụng dùng được trên dòng lệnh và ngược lại.

  • oleafly auth login online --with-token lưu một token Git lấy từ cài đặt tài khoản của dịch vụ. Việc liên kết và đồng bộ cần có token này.
  • oleafly auth login online --from-browser firefox sao chép lần đăng nhập của bạn từ một trình duyệt trên máy tính này, để liệt kê và tải dự án. Firefox dùng được trên mọi hệ thống; Chrome, Edge và Brave dùng được trên macOS. --cookie-stdin thay vào đó đọc một cookie phiên.
  • oleafly auth login git --host https://gitlab.com lưu một token cho một máy chủ Git.
  • oleafly auth status liệt kê mọi lần đăng nhập và nguồn gốc của nó, mà không hiển thị bất kỳ bí mật nào.
  • oleafly auth logout xóa một lần đăng nhập.
Cửa sổ terminal
oleafly remote list
oleafly remote import 64a1f0c2e5b7 --into ~/papers
cd ~/papers/thesis
oleafly remote link
oleafly remote sync
  • oleafly remote import tải các dự án vào những thư mục mới. Nó dùng được với mọi tài khoản.
  • oleafly remote link kết nối một thư mục với dự án trực tuyến của nó thông qua tích hợp Git của dịch vụ, cần có token Git.
  • oleafly remote sync hợp nhất các thay đổi trực tuyến vào thư mục và gửi các thay đổi của bạn. --dry-run cho thấy những gì sẽ thay đổi và --no-push hợp nhất mà không gửi.
  • Khi một tệp thay đổi ở cả hai phía, quá trình đồng bộ không ghi gì và thoát với mã 8. Hãy chạy lại với --resolve và đường dẫn của tệp theo sau là =local hoặc =remote cho từng tệp.
  • oleafly remote diff cho thấy điểm khác nhau; với --exit-code nó thoát với mã 9 khi các tệp khác nhau và 8 khi chúng xung đột. --latexdiff --pdf dựng một PDF có đánh dấu các thay đổi của bạn, dùng latexdiff từ bản phân phối TeX của bạn.
  • oleafly remote status, oleafly remote unlink và oleafly remote open hiển thị liên kết, gỡ nó và mở dự án trong trình duyệt của bạn.

oleafly server sign-in theo sau là địa chỉ của máy chủ sẽ đăng nhập dòng lệnh bằng một mã mà bạn phê duyệt trong trình duyệt. Dòng lệnh là một thiết bị riêng trên máy chủ, tách biệt với ứng dụng.

  • oleafly server status và oleafly server projects hiển thị các máy chủ và các dự án được chia sẻ của bạn.
  • oleafly server share hiển thị liên kết của một dự án và bật hoặc tắt chia sẻ bằng liên kết và bình luận.
  • oleafly server members liệt kê những người trong một dự án và thêm, xóa hoặc thay đổi họ. Chỉ chủ sở hữu mới đổi được chia sẻ và thành viên.
  • oleafly server comments liệt kê, thêm, trả lời và giải quyết bình luận. Một bình luận không gửi được ngay sẽ được giữ lại và gửi vào lần sau.

Việc chia sẻ một dự án lần đầu diễn ra trong ứng dụng. Xem Cộng tác trực tiếp.

oleafly ask trả lời một câu hỏi về dự án mà không thay đổi gì. oleafly agent run thực hiện một nhiệm vụ.

Cửa sổ terminal
oleafly ask "Which sections cite Smith 2021?"
oleafly agent run --allow write "Fix the overfull boxes in chapter 3"
  • Agent luôn đọc được dự án. --allow thêm write, commands hoặc network, và nó từ chối mọi thứ bạn không cho phép. Nó không bao giờ dừng lại để hỏi.
  • Các thay đổi trước hết đi vào một thư mục xem xét trong .oleafly/agent-runs/. oleafly agent apply theo sau là thư mục đó sẽ ghi chúng vào dự án, còn --apply khi chạy sẽ ghi ngay lập tức.
  • Nhà cung cấp, mô hình và mức nỗ lực lấy từ cài đặt của ứng dụng, hoặc từ --provider, --model và --effort. Khóa lấy từ biến môi trường riêng của nhà cung cấp, chẳng hạn ANTHROPIC_API_KEY, hoặc từ kho mã hóa của ứng dụng.
  • --json in ra một kết quả khi lần chạy kết thúc, và --events thêm một dòng JSON cho mỗi sự kiện trong lúc nó làm việc.

Giữ các nhiệm vụ nghiên cứu chạy sau khi bạn thoát

Phần tiêu đề “Giữ các nhiệm vụ nghiên cứu chạy sau khi bạn thoát”

Đánh dấu một nhiệm vụ nghiên cứu là Keep running when Oleafly is closed. Khi bạn thoát, một trình trợ giúp nhỏ chạy nền sẽ tiếp quản các nhiệm vụ đó và các lần chạy thí nghiệm của chúng tiếp tục. Một bước cần bạn phê duyệt sẽ tạm dừng nhiệm vụ và gửi một thông báo. Khi bạn mở lại Oleafly, nó nhận lại các nhiệm vụ và hiển thị những gì đã xảy ra. Tắt tính năng này, hoặc khởi động trình trợ giúp khi bạn đăng nhập, trong Settings → Research → Background tasks. oleafly daemon status cho biết trình trợ giúp đang làm gì.

Mỗi lệnh giải thích các tùy chọn của nó bằng --help. Tài liệu tham chiếu đầy đủ nằm trong kho mã nguồn: docs/cli.md (mở trong thẻ mới).

LệnhChức năng
oleafly openMở một thư mục trong ứng dụng (oleafly . cho thư mục hiện tại)
oleafly initBiến thư mục hiện tại thành một dự án
oleafly newTạo một dự án, từ một mẫu nếu bạn nêu tên mẫu
oleafly templatesLiệt kê các mẫu và hiển thị một mẫu
oleafly buildDựng dự án
oleafly watchDựng lại mỗi lần lưu
oleafly cleanXóa kết quả dựng
oleafly logHiển thị nhật ký hoặc các vấn đề của bản dựng gần nhất
oleafly doctorKiểm tra các engine, ứng dụng và thiết lập của bạn
oleafly versionHiển thị phiên bản và các engine đang dùng
oleafly project infoHiển thị cài đặt của dự án
oleafly projects listLiệt kê các dự án của ứng dụng
oleafly configĐọc và đặt cài đặt dự án và ứng dụng
LệnhChức năng
oleafly citeIn BibTeX cho một DOI, arXiv id, ISBN hoặc PubMed id; --add thêm nó vào thư mục tài liệu tham khảo
oleafly literatureTìm trong OpenAlex, Semantic Scholar, Crossref, arXiv và PubMed
oleafly bib checkTìm các mục không khớp bản ghi thật nào
oleafly bib cleanSửa khóa trích dẫn và xóa mục trùng; --apply ghi các thay đổi
oleafly statsĐếm từ, tiêu đề, hình và phương trình
oleafly synctexÁnh xạ một dòng nguồn sang PDF và ngược lại
oleafly exportXuất tài liệu sang Word, HTML, Markdown, EPUB và hơn nữa
oleafly convertChuyển một tệp sang định dạng khác
oleafly typstLiệt kê, cài đặt và gỡ các phiên bản Typst
oleafly checkpointLiệt kê, so sánh và sao chép các điểm kiểm tra của ứng dụng
LệnhChức năng
oleafly contextLập bản đồ dự án cho một người hoặc một agent
oleafly mcpChạy máy chủ MCP; mcp config thiết lập một client
oleafly skillsLiệt kê các skill và in ra nơi chúng nằm
oleafly askTrả lời một câu hỏi về dự án
oleafly agentChạy agent của Oleafly trên một nhiệm vụ
oleafly daemonChạy và điều khiển trình trợ giúp giữ cho các nhiệm vụ tiếp tục chạy
LệnhChức năng
oleafly checkChạy các kiểm tra Preflight
oleafly lintChạy các kiểm tra LaTeX, BibTeX, chính tả và ngữ pháp
LệnhChức năng
oleafly authĐăng nhập vào các dịch vụ LaTeX trực tuyến, máy chủ Oleafly và máy chủ Git
oleafly remoteNhập, liên kết và đồng bộ các dự án trực tuyến
oleafly serverLàm việc với máy chủ Oleafly: dự án, chia sẻ, thành viên, bình luận
LệnhChức năng
oleafly completionsIn ra phần tự hoàn thành cho bash, zsh, fish, PowerShell hoặc elvish
oleafly manIn ra trang hướng dẫn (man page)
oleafly help exit-codesGiải thích các mã thoát
Tùy chọnChức năng
-C theo sau là một đường dẫnChạy lệnh trên một thư mục dự án khác
--jsonIn ra một kết quả JSON
--eventsIn tiến trình dưới dạng các dòng JSON trước kết quả
--quietChỉ in kết quả
--logHiển thị nhật ký trình biên dịch ở mức none, tail hoặc full
--no-inputKhông bao giờ đặt câu hỏi
--colorDùng màu auto, always hoặc never

Với --json, mọi lệnh in ra một đối tượng JSON: schema_version, ok, command, các trường riêng của lệnh và warnings. Khi một lệnh thất bại, error chứa một kind, một code ổn định và một message. Khi hữu ích, nó còn có một hint, details, và "retryable": true nếu thử lại có thể thành công. Hãy kiểm tra schema_version trước khi dựa vào một trường.

{
"schema_version": 1,
"type": "result",
"ok": false,
"command": "remote sync",
"error": {
"kind": "conflict",
"code": "remote.conflicts",
"message": "2 files changed both here and online.",
"hint": "Pick a side with --resolve PATH=local or --resolve PATH=remote, then sync again.",
"details": { "conflicts": ["main.tex", "refs.bib"] }
},
"warnings": []
}

--events thêm một dòng JSON cho mỗi sự kiện tiến trình trước kết quả.

oleafly help exit-codes in ra cùng bảng này.

MãÝ nghĩa
0Đã thành công
1Có lỗi bên trong Oleafly
2Lệnh bị dùng sai, hoặc cần --yes để tiếp tục
3Dự án bị thiếu hoặc không hợp lệ, hoặc một đường dẫn trỏ ra ngoài nó
4Một công cụ hoặc ứng dụng Oleafly mà nó cần chưa được cài
5Bản dựng thất bại
6Bạn cần đăng nhập
7Mạng bị lỗi
8Có thứ khác đang giữ dự án, hoặc một lần đồng bộ có xung đột
9Một kiểm tra đã tìm thấy vấn đề
130Bạn đã nhấn Ctrl+C

Lệnh không bao giờ đặt câu hỏi khi không có terminal. --no-input cũng tắt các câu hỏi, và một biến CI cũng vậy; khi đó một lệnh cần câu trả lời có sẽ thất bại với mã thoát 2 và yêu cầu --yes. NO_COLOR hoặc --color never tắt màu. Các đường dẫn đi ra ngoài dự án bị từ chối.

BiếnCông dụng
OLEAFLY_DATA_DIRThư mục dữ liệu của Oleafly, khi nó không phải ~/.oleafly
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOCMột trình biên dịch để dùng thay cho cái Oleafly tìm thấy
OLEAFLY_APPỨng dụng Oleafly mà oleafly open khởi chạy
OLEAFLY_ONLINE_GIT_TOKENMột token Git cho dịch vụ LaTeX trực tuyến, dùng thay cho token đã lưu
OLEAFLY_CLIDo Oleafly đặt cho các chương trình nó khởi chạy: đường dẫn đầy đủ của lệnh
CIKhi được đặt, lệnh không bao giờ đặt câu hỏi
NO_COLORKhi được đặt, đầu ra không có màu
Bạn thấy gìNên thử gì
oleafly không được tìm thấyMở một terminal mới. Sau đó kiểm tra bằng Get-Command oleafly trên Windows hoặc command -v oleafly trên macOS và Linux, và thêm dòng mà Settings hiển thị vào hồ sơ shell của bạn
oleafly doctor báo thiếu một engineCài nó bằng lệnh mà doctor in ra, hoặc mở dự án trong ứng dụng một lần
Một MCP client không khởi động được máy chủChạy lệnh đã cấu hình trong terminal, dùng đường dẫn đầy đủ từ oleafly mcp config, và chạy oleafly doctor
Mã thoát 6Chạy oleafly auth status, rồi đăng nhập lại
Mã thoát 8 trong lúc đồng bộChạy lại lần đồng bộ với --resolve cho từng tệp mà nó liệt kê
Trên macOS, Settings báo “Move Oleafly to your Applications folder first”Chuyển ứng dụng, mở nó từ Applications, rồi chọn Install
Xem trước hình ảnh

Không tải được câu trả lời AI

Hãy thử lại, hoặc tìm trong tài liệu.