命令列工具

Oleafly 隨附 oleafly，這是一個在與應用程式相同的專案上運作的命令列工具。可以從終端機、腳本或 CI 建置或檢查論文。讓程式設計代理程式有可靠的方式進入你的專案。與線上 LaTeX 服務或 Oleafly 伺服器同步，或是不開啟應用程式就執行 Oleafly 代理程式。

它在每個平台上都包含在應用程式裡。本頁涵蓋 Oleafly 0.4.8 及更新版本中的指令。較早的版本指令比較少，所以依賴它的腳本請固定你的 Oleafly 版本。

安裝

系統	應用程式把它放在哪裡	把 oleafly 放到你的 PATH 上
Windows	oleafly-cli.exe 就在應用程式旁邊：安裝程式版在 %LOCALAPPDATA%\Oleafly，MSI 套件版在 C:\Program Files\Oleafly	在設定 → 一般的終端機指令這一列選擇安裝，會把它複製到 %LOCALAPPDATA%\Oleafly\bin\oleafly.exe，並把該資料夾加到你的 PATH
macOS	Oleafly.app/Contents/MacOS/oleafly-cli	在終端機指令這一列選擇安裝，若你有寫入權限，會把 oleafly 連結到 /usr/local/bin，否則連結到 ~/.local/bin
Linux 套件（.deb、.rpm）	/usr/bin/oleafly-cli	不必做任何事：套件會安裝 /usr/bin/oleafly
Linux AppImage	AppImage 內部	安裝會把它複製到 ~/.local/bin/oleafly

Oleafly 啟動的程式，例如它自己的終端機和 CLI 代理程式，即使你還沒安裝，也一律能在 PATH 上找到 oleafly。OLEAFLY_CLI 變數保存它的完整路徑。

Windows

1. 開啟設定 → 一般，在終端機指令這一列選擇安裝。
2. 開啟新的 PowerShell 或命令提示字元視窗。已經開啟的視窗仍使用舊的 PATH。
3. 確認它能運作：

Get-Command oleafly
oleafly version

同一列的移除會刪除這份副本，並把該資料夾從你的 PATH 移除。Oleafly 更新後，會在下次啟動時更新這份副本。

macOS

請先把 Oleafly 移到「應用程式」資料夾。從磁碟映像檔執行的副本會顯示「請先將 Oleafly 移到『應用程式』檔案夾」，而不是安裝。

這個指令是指向應用程式的連結，所以更新 Oleafly 時指令也會跟著更新。如果該資料夾不在你的 PATH 中，這一列會顯示要加入 shell 設定檔的那一行。用 command -v oleafly 檢查。

Linux

.deb 和 .rpm 套件在你安裝時，就會把 oleafly 放到你的 PATH 上。只輸入 oleafly 而後面沒有任何內容，會開啟應用程式。

AppImage 需要一份副本，因為 AppImage 內部的檔案在它結束時就會消失。你把 AppImage 換成較新的之後，這一列會提供更新。如果 ~/.local/bin 不在你的 PATH 中，這一列會顯示要加入的那一行。

確認它能運作

oleafly version 會印出應用程式版本，以及這個指令會使用的引擎。oleafly doctor 會檢查引擎、應用程式、Git、終端機指令和你的 MCP 用戶端，並針對缺少的項目印出修正方式。它在專案之外也能運作。

建置專案

oleafly . 會在應用程式中開啟目前的資料夾。其他每個指令都作用於你所在的資料夾；-C 加上路徑，則讓它改為指向別處。

cd ~/papers/thesis
oleafly init --engine typst
oleafly build
oleafly log --diagnostics
oleafly -C ~/papers/review --json build

• oleafly init 會把目前的資料夾變成專案。--engine 可接受 tectonic、latexmk、typst 或 markdown。
• oleafly new 後面接資料夾、--template 和範本 ID，會從範本建立專案。oleafly templates list --all 會列出所有範本。
• oleafly build 會使用專案的引擎與設定，方式和應用程式相同：使用 Oleafly 隨附的 Tectonic、Typst 和 Pandoc，或是你安裝的 LaTeX。--main 建置專案中的另一份文件，--compiler 為 latexmk 專案選擇 LaTeX 編譯器，-o 把 PDF 複製到別處，--timeout 以秒為單位設定時限。
• 你在應用程式中就地開啟的資料夾，會用你在那裡選擇的引擎和主要文件建置，輸出到應用程式自己的建置資料夾。
• 應用程式和指令絕不會同時建置同一個專案：後來的會等前一個完成。建置失敗時，會保留上一份良好的 PDF。
• oleafly watch 會在你每次儲存時重新建置。oleafly log --diagnostics 會列出錯誤與警告，並附上檔案和行號，oleafly clean 則會移除建置輸出。

Typst 的細節，請參閱 Typst 專案。

從程式設計代理程式使用

這個指令給程式設計代理程式三樣東西，讓它們發揮得最好：用 oleafly context 取得專案的地圖、用 --json 取得它們讀得懂的結果，以及說明哪裡出錯的結束代碼。連接代理程式有三種方式。

oleafly-cli 技能

Oleafly 隨附一個名為 oleafly-cli 的技能。它教代理程式認識這些指令、JSON 輸出和結束代碼，以及最有效的循環：讀取上下文、編輯、建置、讀取診斷訊息、修正第一個錯誤。

在 Oleafly 的終端機，以及它啟動的 CLI 代理程式中，像選擇其他技能一樣選擇這個技能。對於你自己執行的代理程式，請開啟設定 → AI 助理 → 技能 → 與這台電腦上的其他代理程式共用技能。Oleafly 接著會把它的技能（包括 oleafly-cli）連結到其他程式設計代理程式會讀取的資料夾，例如 ~/.claude/skills、~/.codex/skills 和 ~/.agents/skills。對於會讀取其他資料夾的代理程式，oleafly skills path 會印出技能所在的位置。

透過 MCP 連接代理程式

oleafly mcp 是透過標準輸入與輸出溝通的 MCP 伺服器。當應用程式開啟了你的專案時，它會把呼叫轉交給應用程式自己的 MCP 伺服器，所以代理程式能使用應用程式的每一項工具，也會遇到你的核准提示。否則它會自己運作，提供讀取工具（專案狀態、專案地圖、檔案、搜尋、記錄、doctor 報告、引用查詢）和 compile。不必複製 URL 或權杖，也不必安裝 Node.js。

最快的設定方式是 oleafly mcp config --client 後面接 claude-code、claude-desktop、codex、cursor 或 gemini。它會印出該用戶端的設定項目；加上 --write 會替你加入，並備份用戶端的檔案。之後請重新啟動或重新連線用戶端。在專案內，它會寫入專案的設定；在其他地方，它會寫入你的使用者設定，並使用指令的完整路徑，因為從桌面啟動的應用程式可能看不到你的 PATH。

Claude Code

claude mcp add --scope user oleafly -- oleafly mcp

在專案內，oleafly mcp config --client claude-code --write 會改為把伺服器加到專案的 .mcp.json。

Claude Desktop

Claude Desktop 啟動伺服器時沒有專案資料夾，所以它的設定項目一律透過應用程式運作：請讓 Oleafly 保持開啟並開著你的專案。請使用 oleafly 的完整路徑。在 Windows 上，路徑中的每個反斜線都要重複一次。

claude_desktop_config.json

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

這個檔案在 macOS 上位於 ~/Library/Application Support/Claude，在 Windows 上位於 %APPDATA%\Claude。

Codex

~/.codex/config.toml

[mcp_servers.oleafly]
command = "oleafly"
args = ["mcp"]
tool_timeout_sec = 300

Cursor

~/.cursor/mcp.json 適用於每個專案，.cursor/mcp.json 則只適用於單一專案。

~/.cursor/mcp.json

{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"]
    }
  }
}

Gemini CLI

~/.gemini/settings.json

{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"],
      "timeout": 300000
    }
  }
}

讓代理程式了解整個專案

oleafly context 會繪製出專案的地圖：它的檔案、大綱、標籤、引用、缺少的檔案、未解析的參照，以及上次建置的問題。--format md 提供可貼進提示詞的文字；--format json 則提供給程式使用的同一份地圖。

投稿前檢查論文

oleafly check 會對專案執行預檢，結果與預檢面板相同：參照、引用、標籤、缺少的檔案、參考文獻欄位、圖片，以及盲審所需的匿名性。需要編譯後 PDF 的檢查會使用上次的建置。

oleafly lint 會執行 LaTeX 和 BibTeX 檢查，在包含此功能的版本中還會檢查拼字與文法。--fix 會套用可以安全套用的修正。

兩者都接受 --format human、json 或 sarif，而 --exit-code 會讓它們在發現問題時以代碼 9 結束。SARIF 可搭配 GitHub 這類程式碼掃描服務：用 oleafly check --format sarif -o preflight.sarif 寫出報告，再用 upload-sarif action 上傳，每個發現都會顯示在 pull request 中對應的那一行。

與線上 LaTeX 服務同步

oleafly remote 會從你的線上 LaTeX 服務帳號下載專案，並讓資料夾與其中一個專案保持同步，使用的合併方式與應用程式相同。

登入

登入資訊存放在應用程式的加密儲存空間中，所以在應用程式中完成的登入可用於命令列，反過來也一樣。

• oleafly auth login online --with-token 會儲存從該服務的帳號設定取得的 Git 權杖。連結與同步都需要它。
• oleafly auth login online --from-browser firefox 會從這台電腦上的瀏覽器複製你的登入資訊，用於列出與下載專案。Firefox 在每個系統上都能使用；Chrome、Edge 和 Brave 則在 macOS 上可用。--cookie-stdin 則改為讀取工作階段 Cookie。
• oleafly auth login git --host https://gitlab.com 會為 Git 主機儲存權杖。
• oleafly auth status 會列出每個登入以及它的來源，不會顯示任何機密。
• oleafly auth logout 會移除一個登入。

別讓權杖留在 shell 歷史記錄中

權杖要透過標準輸入送入，例如 oleafly auth login online --with-token < token.txt，絕不要當作引數。在終端機中，指令會在不顯示你所輸入內容的情況下詢問權杖。oleafly auth token 會為腳本印出已儲存的權杖，所以請把它的輸出當作密碼對待。

匯入與同步專案

oleafly remote list
oleafly remote import 64a1f0c2e5b7 --into ~/papers
cd ~/papers/thesis
oleafly remote link
oleafly remote sync

• oleafly remote import 會把專案下載到新的資料夾。任何帳號都適用。
• oleafly remote link 會透過該服務的 Git 整合，把資料夾連結到它的線上專案，這需要 Git 權杖。
• oleafly remote sync 會把線上的變更合併進資料夾，並送出你的變更。--dry-run 顯示會有什麼變更，--no-push 則只合併、不送出。
• 當某個檔案在兩邊都有變更時，同步不會寫入任何內容，並以代碼 8 結束。請再執行一次，對每個檔案加上 --resolve，後面接該檔案的路徑，再接 =local 或 =remote。
• oleafly remote diff 會顯示差異；加上 --exit-code 時，檔案不同會以代碼 9 結束，發生衝突則以代碼 8 結束。--latexdiff --pdf 會用你 TeX 發行版中的 latexdiff，建置標示出你的變更的 PDF。
• oleafly remote status、oleafly remote unlink 和 oleafly remote open 分別顯示連結、移除連結，以及在瀏覽器中開啟專案。

使用 Oleafly 伺服器

oleafly server sign-in 後面接伺服器的位址，會用你在瀏覽器中核准的代碼讓命令列登入。在伺服器上，命令列是獨立於應用程式之外的另一台裝置。

• oleafly server status 和 oleafly server projects 會顯示你的伺服器和共用專案。
• oleafly server share 會顯示專案的連結，並開啟或關閉連結共用與留言。
• oleafly server members 會列出專案上的成員，並加入、移除或變更他們。只有擁有者可以變更共用設定與成員。
• oleafly server comments 會列出、新增、回覆並解決留言。無法立刻送出的留言會先保留，下次再送出。

第一次共用專案要在應用程式中進行。請參閱即時協作。

在終端機執行 Oleafly 代理程式

oleafly ask 會回答關於專案的問題，不會變更任何內容。oleafly agent run 則會執行一項任務。

oleafly ask "Which sections cite Smith 2021?"
oleafly agent run --allow write "Fix the overfull boxes in chapter 3"

• 代理程式一律可以讀取專案。--allow 會加入 write、commands 或 network，而任何你沒有允許的事它都會拒絕。它絕不會停下來詢問問題。
• 變更會先送到 .oleafly/agent-runs/ 中的審閱資料夾。oleafly agent apply 後面接該資料夾，會把變更寫入專案；在執行時加上 --apply 則會立刻寫入。
• 供應商、模型和強度來自應用程式的設定，或來自 --provider、--model 和 --effort。金鑰來自供應商自己的環境變數，例如 ANTHROPIC_API_KEY，或來自應用程式的加密儲存空間。
• --json 會在執行結束時印出一個結果，--events 則在它工作時，為每個事件多印一行 JSON。

結束後讓研究任務繼續執行

把研究任務標記為Oleafly 關閉後繼續執行。你結束時，會有一個小型背景輔助程式接手這些任務，它們的實驗執行也會繼續進行。需要你核准的步驟會讓任務暫停，並傳送通知。你再次開啟 Oleafly 時，它會收回這些任務，並顯示發生了什麼事。要關閉這項功能，或在你登入時啟動輔助程式，請到設定 → 研究 → 背景任務。oleafly daemon status 會顯示輔助程式正在做什麼。

指令參考

每個指令都可以用 --help 查看它的選項說明。完整參考資料在儲存庫中：docs/cli.md （在新分頁開啟）。

專案與建置

指令	功能
oleafly open	在應用程式中開啟資料夾（oleafly . 為目前的資料夾）
oleafly init	把目前的資料夾變成專案
oleafly new	建立專案，如果你指定了範本，就從範本建立
oleafly templates	列出範本並顯示其中一個
oleafly build	建置專案
oleafly watch	每次儲存時重新建置
oleafly clean	移除建置輸出
oleafly log	顯示上次建置的記錄或它的問題
oleafly doctor	檢查引擎、應用程式和你的設定
oleafly version	顯示版本和使用中的引擎
oleafly project info	顯示專案的設定
oleafly projects list	列出應用程式的專案
oleafly config	取得與設定專案和應用程式的設定

寫作與參考文獻

指令	功能
oleafly cite	印出 DOI、arXiv ID、ISBN 或 PubMed ID 的 BibTeX；--add 會把它加到參考文獻
oleafly literature	搜尋 OpenAlex、Semantic Scholar、Crossref、arXiv 和 PubMed
oleafly bib check	找出不符合任何真實記錄的項目
oleafly bib clean	修正引用鍵並移除重複項目；--apply 會寫入變更
oleafly stats	統計字數、標題、圖片和公式
oleafly synctex	把原始碼的某一行對應到 PDF，也能反向對應
oleafly export	把文件匯出為 Word、HTML、Markdown、EPUB 等格式
oleafly convert	把一個檔案轉換為另一種格式
oleafly typst	列出、安裝和移除 Typst 版本
oleafly checkpoint	列出、比較和複製應用程式的檢查點

代理程式與自動化

指令	功能
oleafly context	為人或代理程式繪製專案地圖
oleafly mcp	執行 MCP 伺服器；mcp config 會設定用戶端
oleafly skills	列出技能並印出它們的位置
oleafly ask	回答關於專案的問題
oleafly agent	讓 Oleafly 代理程式執行任務
oleafly daemon	執行並控制讓任務持續進行的輔助程式

檢查

指令	功能
oleafly check	執行預檢
oleafly lint	執行 LaTeX、BibTeX、拼字和文法檢查

帳號與同步

指令	功能
oleafly auth	登入線上 LaTeX 服務、Oleafly 伺服器和 Git 主機
oleafly remote	匯入、連結並同步線上專案
oleafly server	使用 Oleafly 伺服器：專案、共用、成員、留言

Shell 與說明

指令	功能
oleafly completions	印出 bash、zsh、fish、PowerShell 或 elvish 的 shell 自動完成
oleafly man	印出手冊頁面
oleafly help exit-codes	說明結束代碼

每個指令都有的選項

選項	功能
-C 後面接路徑	對另一個專案資料夾執行指令
--json	印出一個 JSON 結果
--events	在結果之前，以 JSON 行的形式印出進度
--quiet	只印出結果
--log	顯示 none、tail 或 full 的編譯器記錄
--no-input	絕不詢問問題
--color	使用 auto、always 或 never 的顏色

給腳本使用的輸出

JSON 輸出

使用 --json 時，每個指令都會印出一個 JSON 物件：schema_version、ok、command、該指令自己的欄位，以及 warnings。指令失敗時，error 內含 kind、穩定的 code 和 message。有幫助時，它還會有 hint、details，以及在重試可能有效時的 "retryable": true。在你依賴某個欄位之前，請先檢查 schema_version。

{
  "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 會在結果之前，為每個進度事件加上一行 JSON。

結束代碼

oleafly help exit-codes 會印出同一份表格。

代碼	意義
0	成功
1	Oleafly 內部出了問題
2	指令用法不對，或需要 --yes 才能繼續
3	專案不存在或無效，或路徑指向專案之外
4	它需要的工具或 Oleafly 應用程式沒有安裝
5	建置失敗
6	你需要登入
7	網路發生故障
8	專案被其他程式佔用，或同步發生衝突
9	檢查發現了問題
130	你按了 Ctrl+C

提問、顏色與記錄

沒有終端機時，指令絕不會詢問問題。--no-input 也會關閉詢問，設定了 CI 變數也一樣；需要你回答「是」的指令，這時會以結束代碼 2 失敗，並要求加上 --yes。NO_COLOR 或 --color never 會關閉顏色。會離開專案的路徑一律被拒絕。

環境變數

變數	用途
OLEAFLY_DATA_DIR	Oleafly 存放資料的資料夾，當它不是 ~/.oleafly 時
OLEAFLY_TECTONIC、OLEAFLY_LATEXMK、OLEAFLY_TYPST、OLEAFLY_PANDOC	要使用的編譯器，用來取代 Oleafly 找到的那一個
OLEAFLY_APP	oleafly open 所啟動的 Oleafly 應用程式
OLEAFLY_ONLINE_GIT_TOKEN	線上 LaTeX 服務的 Git 權杖，用來取代已儲存的權杖
OLEAFLY_CLI	由 Oleafly 為它所啟動的程式設定：指令的完整路徑
CI	設定後，指令絕不會詢問問題
NO_COLOR	設定後，輸出沒有顏色

疑難排解

你看到的情況	可以試試
找不到 oleafly	開啟新的終端機。然後在 Windows 上用 Get-Command oleafly，在 macOS 和 Linux 上用 command -v oleafly 檢查，並把設定中顯示的那一行加到你的 shell 設定檔
oleafly doctor 回報缺少引擎	用 doctor 印出的指令安裝它，或在應用程式中開啟一次專案
MCP 用戶端無法啟動伺服器	在終端機中執行設定好的指令，使用 oleafly mcp config 提供的完整路徑，並執行 oleafly doctor
結束代碼 6	執行 oleafly auth status，然後重新登入
同步時出現結束代碼 8	對它列出的每個檔案，加上 --resolve 再同步一次
在 macOS 上，設定中顯示「請先將 Oleafly 移到『應用程式』檔案夾」	移動應用程式，從「應用程式」開啟它，然後選擇安裝

相關頁面

• Typst 專案
• 透過 MCP 連接
• CLI 代理程式
• 預檢
• 研究任務