Công cụ dòng lệnh
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ó.
Cài đặt
Phần tiêu đề “Cài đặt”| Hệ thống | Nơi ứng dụng đặt nó | Đặt oleafly lên PATH của bạn |
|---|---|---|
| Windows | oleafly-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 MSI | Install ở 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 |
| macOS | Oleafly.app/Contents/MacOS/oleafly-cli | Install ở 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-cli | Không cần làm gì: gói cài sẵn /usr/bin/oleafly |
| Linux AppImage | Bên trong AppImage | Install 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ó. Chúng cũng tìm thấy TinyTeX của Oleafly, sau bất kỳ bản TeX nào của chính bạn. Tectonic, Typst và Pandoc đi kèm Oleafly không nằm trên PATH đó, nên hãy dùng oleafly build và oleafly export thay vì gọi chúng theo tên.
Windows
Phần tiêu đề “Windows”- Mở Settings → General và chọn Install ở dòng Terminal command.
- 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ũ.
- Kiểm tra xem nó có hoạt động không:
Get-Command oleaflyoleafly versionRemove ở 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.
macOS
Phần tiêu đề “macOS”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.
Linux
Phần tiêu đề “Linux”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.
Các engine cũng nằm lại bên trong AppImage. Bản oleafly đã sao chép dùng được chúng từ terminal tích hợp của Oleafly, nhưng không dùng được từ một terminal bạn tự mở, một CLI agent hay một lệnh mà trợ lý chạy. Với những trường hợp đó, hãy cài Tectonic, Typst và Pandoc, hoặc dùng gói .deb hay .rpm. oleafly doctor cảnh báo về điều này.
Kiểm tra xem nó có hoạt động không
Phần tiêu đề “Kiểm tra xem nó có hoạt động không”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, bản cài TeX của bạn, ứ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ảnh báo khi hoàn toàn không có TeX nào được cài, vì khi đó các dự án latexmk không dựng được. Nó cũng chạy được ngoài một dự án.
Dựng một dự án
Phần tiêu đề “Dựng 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.
cd ~/papers/thesisoleafly init --engine typstoleafly buildoleafly log --diagnosticsoleafly -C ~/papers/review --json buildoleafly initbiến thư mục hiện tại thành một dự án.--enginenhậntectonic,latexmk,typsthoặcmarkdown.oleafly newtheo sau là một thư mục,--templatevà một id mẫu sẽ tạo dự án từ một mẫu.oleafly templates list --allliệt kê các mẫu.oleafly builddù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.--maindựng một tài liệu khác của dự án,--compilerchọn trình biên dịch LaTeX cho các dự án latexmk và-osao chép PDF sang nơi khác.- Một tài liệu Markdown được dựng theo kiểu tài liệu mà front matter của nó nêu, chẳng hạn slide hoặc thư.
- Các dự án latexmk dùng bản phân phối TeX được đánh dấu In use dưới Settings → Engines → LaTeX → Manage TeX distributions, nên bản bạn đã chọn ở đó bằng Use for compiles cũng áp dụng ở đâ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.
- Một thư mục chứa các tệp LaTeX chưa phải là dự án, và bạn chưa từng mở trong ứng dụng, được dựng bằng engine tích hợp sẵn trừ khi có điều gì đó yêu cầu latexmk:
--compiler, một dòng% !TEX programnêupdflatex,lualatex,uplatexhoặcplatex, một lớp tiếng Nhật nhưujarticle, hoặclatex.default_engineđược đặt thànhlatexmkbằngoleafly config. Nếu tài liệu yêu cầu pdfLaTeX hoặc LuaLaTeX mà latexmk không chạy được trên máy tính này, bản dựng ở lại engine tích hợp sẵn và in ra một cảnh báo. - Ứ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.
- Một bản dựng thất bại liệt kê tối đa 20 lỗi, kèm lời giải thích và gợi ý khi Oleafly có. Với
--quiet, nó chỉ liệt kê các lỗi. --timeoutdừng một trình biên dịch sau chừng đó giây, mặc định là 300. Trong lúc engine tích hợp sẵn tải gói, thời gian được tính từ lượt tải gần nhất, tối đa 30 phút, hoặc lâu hơn nếu--timeoutdài hơn.oleafly buildluôn chặn các lệnh shell từ LaTeX, kể cả trong một dự án mà bạn đã chọn Allow external commands trong ứng dụng. Một tài liệu cần chúng, chẳng hạn tài liệu dùng minted hoặc PythonTeX, sẽ thất bại ở đây và nói rõ lý do. Hãy dựng nó trong ứng dụng, hoặc tự chạy latexmk với-shell-escape. Chỉ làm một trong hai khi bạn tin tưởng mọi tệp trong dự án.- Các dự án Quarto và Calepin chỉ dựng được trong ứng dụng.
oleafly buildnói rõ điều đó và nêu lệnhquarto renderhoặccalepin compile, nếu bạn muốn tự chạy công cụ. oleafly watchdựng lại mỗi lần bạn lưu. Khi một bản dựng không bắt đầu được, nó in ra lỗi và gợi ý của lỗi đó, rồi chờ thay đổi tiếp theo của bạn.oleafly log --diagnosticsliệt kê lỗi và cảnh báo kèm tệp và dòng, cònoleafly cleanxóa kết quả dựng.
Về chi tiết riêng của Typst, xem Dự án Typst.
Dùng nó từ một agent lập trình
Phần tiêu đề “Dùng nó từ một agent lập trình”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.
Skill oleafly-cli
Phần tiêu đề “Skill oleafly-cli”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.
Kết nối một agent qua MCP
Phần tiêu đề “Kết nối một agent qua MCP”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.
Khi compile không chạy được vì thiếu một công cụ, lỗi của nó mang cùng gợi ý mà oleafly build in ra, chẳng hạn cách có được TeX, để agent nói cho bạn biết cần cài gì. Các bản dựng trong oleafly agent run báo cáo theo cùng cách.
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.
Claude Code
Phần tiêu đề “Claude Code”claude mcp add --scope user oleafly -- oleafly mcpTrong 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
Phần tiêu đề “Claude Desktop”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.
{ "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
Phần tiêu đề “Codex”[mcp_servers.oleafly]command = "oleafly"args = ["mcp"]tool_timeout_sec = 300Cursor
Phần tiêu đề “Cursor”Dùng ~/.cursor/mcp.json cho mọi dự án, hoặc .cursor/mcp.json bên trong một dự án.
{ "mcpServers": { "oleafly": { "command": "oleafly", "args": ["mcp"] } }}Gemini CLI
Phần tiêu đề “Gemini CLI”{ "mcpServers": { "oleafly": { "command": "oleafly", "args": ["mcp"], "timeout": 300000 } }}Đưa cho agent cả dự án
Phần tiêu đề “Đưa cho agent cả dự án”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.
Kiểm tra bài báo trước khi nộp
Phần tiêu đề “Kiểm tra bài báo trước khi nộp”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.
Đăng nhập
Phần tiêu đề “Đăng nhập”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-tokenlư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 firefoxsao 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-stdinthay vào đó đọc một cookie phiên.oleafly auth login git --host https://gitlab.comlưu một token cho một máy chủ Git.oleafly auth statusliệ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 logoutxóa một lần đăng nhập.
Nhập và đồng bộ dự án
Phần tiêu đề “Nhập và đồng bộ dự án”oleafly remote listoleafly remote import 64a1f0c2e5b7 --into ~/paperscd ~/papers/thesisoleafly remote linkoleafly remote syncoleafly remote importtả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 linkkế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 synchợ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-runcho thấy những gì sẽ thay đổi và--no-pushhợ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
--resolvevà đường dẫn của tệp theo sau là=localhoặc=remotecho từng tệp. oleafly remote diffcho thấy điểm khác nhau; với--exit-codenó thoát với mã 9 khi các tệp khác nhau và 8 khi chúng xung đột.--latexdiff --pdfdự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 unlinkvàoleafly remote openhiển thị liên kết, gỡ nó và mở dự án trong trình duyệt của bạn.
Làm việc với một máy chủ Oleafly
Phần tiêu đề “Làm việc với một máy chủ Oleafly”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 statusvàoleafly server projectshiển thị các máy chủ và các dự án được chia sẻ của bạn.oleafly server sharehiể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 membersliệ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 commentsliệ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.
Chạy agent của Oleafly từ terminal
Phần tiêu đề “Chạy agent của Oleafly từ terminal”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ụ.
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.
--allowthêmwrite,commandshoặcnetwork, 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 applytheo sau là thư mục đó sẽ ghi chúng vào dự án, còn--applykhi 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,--modelvà--effort. Khóa lấy từ biến môi trường riêng của nhà cung cấp, chẳng hạnANTHROPIC_API_KEY, hoặc từ kho mã hóa của ứng dụng. --jsonin ra một kết quả khi lần chạy kết thúc, và--eventsthê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ì.
Những gì chỉ ứng dụng làm được
Phần tiêu đề “Những gì chỉ ứng dụng làm được”Những việc này ở lại trong ứng dụng:
- Cài TinyTeX, dưới Settings → Engines → LaTeX → Manage TeX distributions.
- Dựng một tài liệu LaTeX chạy các lệnh shell, chẳng hạn tài liệu dùng minted hoặc PythonTeX.
- Dựng các tài liệu Quarto và Calepin.
- Chạy lại Biber trong lúc dựng khi tài liệu tham khảo đã cũ.
- Tạo các điểm khôi phục, và khôi phục một điểm đè lên dự án.
- Chia sẻ một dự án trên máy chủ Oleafly lần đầu tiên.
Tham chiếu lệnh
Phần tiêu đề “Tham chiếu lệnh”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).
Dự án và bản dựng
Phần tiêu đề “Dự án và bản dựng”| Lệnh | Chức năng |
|---|---|
oleafly open | Mở một thư mục trong ứng dụng (oleafly . cho thư mục hiện tại) |
oleafly init | Biến thư mục hiện tại thành một dự án |
oleafly new | Tạo một dự án, từ một mẫu nếu bạn nêu tên mẫu |
oleafly templates | Liệt kê các mẫu và hiển thị một mẫu |
oleafly build | Dựng dự án |
oleafly watch | Dựng lại mỗi lần lưu |
oleafly clean | Xóa kết quả dựng |
oleafly log | Hiển thị nhật ký hoặc các vấn đề của bản dựng gần nhất |
oleafly doctor | Kiểm tra các engine, ứng dụng và thiết lập của bạn |
oleafly version | Hiển thị phiên bản và các engine đang dùng |
oleafly project info | Hiển thị cài đặt của dự án |
oleafly projects list | Liệ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 |
Viết và tài liệu tham khảo
Phần tiêu đề “Viết và tài liệu tham khảo”| Lệnh | Chức năng |
|---|---|
oleafly cite | In 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 literature | Tìm trong OpenAlex, Semantic Scholar, Crossref, arXiv và PubMed |
oleafly bib check | Tìm các mục không khớp bản ghi thật nào |
oleafly bib clean | Sử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 export | Xuất tài liệu sang Word, HTML, Markdown, EPUB và hơn nữa, và liệt kê những gì lần xuất đã bỏ qua |
oleafly convert | Chuyển một tệp sang định dạng khác |
oleafly typst | Liệt kê, cài đặt và gỡ các phiên bản Typst |
oleafly checkpoint | Liệt kê, so sánh và sao chép các điểm kiểm tra của ứng dụng |
Agent và tự động hóa
Phần tiêu đề “Agent và tự động hóa”| Lệnh | Chức năng |
|---|---|
oleafly context | Lập bản đồ dự án cho một người hoặc một agent |
oleafly mcp | Chạy máy chủ MCP; mcp config thiết lập một client |
oleafly skills | Liệt kê các skill và in ra nơi chúng nằm |
oleafly ask | Trả lời một câu hỏi về dự án |
oleafly agent | Chạy agent của Oleafly trên một nhiệm vụ |
oleafly daemon | Chạy và điều khiển trình trợ giúp giữ cho các nhiệm vụ tiếp tục chạy |
Kiểm tra
Phần tiêu đề “Kiểm tra”| Lệnh | Chức năng |
|---|---|
oleafly check | Chạy các kiểm tra Preflight |
oleafly lint | Chạy các kiểm tra LaTeX, BibTeX, chính tả và ngữ pháp |
Tài khoản và đồng bộ
Phần tiêu đề “Tài khoản và đồng bộ”| Lệnh | Chứ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 remote | Nhập, liên kết và đồng bộ các dự án trực tuyến |
oleafly server | Làm việc với máy chủ Oleafly: dự án, chia sẻ, thành viên, bình luận |
Shell và trợ giúp
Phần tiêu đề “Shell và trợ giúp”| Lệnh | Chức năng |
|---|---|
oleafly completions | In ra phần tự hoàn thành cho bash, zsh, fish, PowerShell hoặc elvish |
oleafly man | In ra trang hướng dẫn (man page) |
oleafly help exit-codes | Giải thích các mã thoát |
Tùy chọn cho mọi lệnh
Phần tiêu đề “Tùy chọn cho mọi lệnh”| Tùy chọn | Chức năng |
|---|---|
-C theo sau là một đường dẫn | Chạy lệnh trên một thư mục dự án khác |
--json | In ra một kết quả JSON |
--events | In tiến trình dưới dạng các dòng JSON trước kết quả |
--quiet | Chỉ in kết quả |
--log | Hiển thị nhật ký trình biên dịch ở mức none, tail hoặc full |
--no-input | Không bao giờ đặt câu hỏi |
--color | Dùng màu auto, always hoặc never |
Đầu ra cho script
Phần tiêu đề “Đầu ra cho script”Đầu ra JSON
Phần tiêu đề “Đầu ra JSON”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ả.
Mã thoát
Phần tiêu đề “Mã thoát”oleafly help exit-codes in ra cùng bảng này.
| Mã | Ý nghĩa |
|---|---|
| 0 | Đã thành công |
| 1 | Có lỗi bên trong Oleafly |
| 2 | Lệnh bị dùng sai, hoặc cần --yes để tiếp tục |
| 3 | Dự án bị thiếu hoặc không hợp lệ, hoặc một đường dẫn trỏ ra ngoài nó |
| 4 | Một công cụ hoặc ứng dụng Oleafly mà nó cần chưa được cài |
| 5 | Bản dựng thất bại |
| 6 | Bạn cần đăng nhập |
| 7 | Mạng bị lỗi |
| 8 | Có thứ khác đang giữ dự án, hoặc một lần đồng bộ có xung đột |
| 9 | Một kiểm tra đã tìm thấy vấn đề |
| 130 | Bạn đã nhấn Ctrl+C |
Câu hỏi, màu sắc và nhật ký
Phần tiêu đề “Câu hỏi, màu sắc và nhật ký”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ến môi trường
Phần tiêu đề “Biến môi trường”| Biến | Công dụng |
|---|---|
OLEAFLY_DATA_DIR | Thư mục dữ liệu của Oleafly, khi nó không phải ~/.oleafly |
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOC | Mộ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_TOKEN | Một token Git cho dịch vụ LaTeX trực tuyến, dùng thay cho token đã lưu |
OLEAFLY_DOWNLOAD_MIRROR | Nơi các bản tải như TinyTeX và Typst đến từ: automatic, original, hoặc địa chỉ HTTPS của mirror riêng của bạn. Xem Thẻ Sources |
OLEAFLY_TEX_REPOSITORY | Kho TeX Live mà tlmgr cài các gói từ đó |
OLEAFLY_CLI | Do Oleafly đặt cho các chương trình nó khởi chạy: đường dẫn đầy đủ của lệnh |
CI | Khi được đặt, lệnh không bao giờ đặt câu hỏi |
NO_COLOR | Khi được đặt, đầu ra không có màu |
Khắc phục sự cố
Phần tiêu đề “Khắc phục sự cố”| Bạn thấy gì | Nên thử gì |
|---|---|
oleafly không được tìm thấy | Mở 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 engine | Cài nó bằng lệnh mà doctor in ra, hoặc mở dự án trong ứng dụng một lần |
| Không tìm thấy latexmk | Cài TinyTeX trong ứng dụng dưới Settings → Engines → LaTeX → Manage TeX distributions, hoặc cài TeX bằng lệnh mà gợi ý đưa ra. Để dùng engine tích hợp sẵn thay vào đó, chạy oleafly config set engine tectonic trong một dự án, hoặc oleafly config set latex.default_engine tectonic --global cho các thư mục chưa phải dự án |
Một bản dựng latexmk dừng vì thiếu tệp .sty hoặc .cls | Với TeX Live, MacTeX hoặc TinyTeX, gợi ý đưa ra các lệnh tlmgr search và tlmgr install. TeX Live cài từ các gói Debian, Ubuntu hoặc Fedora thì lấy gói từ apt hoặc dnf: trên Debian và Ubuntu, apt-file search theo sau là tên tệp sẽ tìm ra gói. MiKTeX không có gợi ý: hãy cài gói trong MiKTeX Console, rồi dựng lại |
| Một bản dựng dùng minted hoặc PythonTeX thất bại | oleafly build chặn các lệnh shell. Hãy dựng dự án trong ứng dụng sau khi bạn chọn Allow external commands, hoặc tự chạy latexmk với -shell-escape |
| Bản dựng đầu tiên hết thời gian trong lúc các gói đang tải | Hãy dựng lại. Lượt tải tiếp tục từ chỗ nó dừng. --timeout nâng giới hạn lên |
| Một dự án Typst yêu cầu một phiên bản chưa được cài | Chạy oleafly typst install theo sau là phiên bản đó |
| Thiếu một engine trên AppImage của Linux | Các engine của AppImage chỉ dùng được trong terminal tích hợp của Oleafly. Cài Tectonic, Typst và Pandoc, hoặc dùng gói .deb hay .rpm |
| 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 6 | Chạ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 |