# 命令列工具

在 Windows、macOS 或 Linux 上安裝 oleafly 指令，從終端機或 CI 建置與檢查專案，與線上 LaTeX 服務同步，並透過它的 MCP 伺服器和技能連接程式設計代理程式。

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. 確認它能運作：

```powershell
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` 加上路徑，則讓它改為指向別處。

```sh
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 專案](/docs/typst/#build-from-the-command-line)。

## 從程式設計代理程式使用

這個指令給程式設計代理程式三樣東西，讓它們發揮得最好：用 `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 伺服器](/docs/mcp/)，所以代理程式能使用應用程式的每一項工具，也會遇到你的核准提示。否則它會自己運作，提供讀取工具（專案狀態、專案地圖、檔案、搜尋、記錄、doctor 報告、引用查詢）和 `compile`。不必複製 URL 或權杖，也不必安裝 Node.js。

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

#### Claude Code

```sh
claude mcp add --scope user oleafly -- oleafly mcp
```

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

#### Claude Desktop

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

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

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

#### Codex

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

#### Cursor

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

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"]
    }
  }
}
```

#### Gemini CLI

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

### 讓代理程式了解整個專案

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

## 投稿前檢查論文

`oleafly check` 會對專案執行[預檢](/docs/preflight/)，結果與預檢面板相同：參照、引用、標籤、缺少的檔案、參考文獻欄位、圖片，以及盲審所需的匿名性。需要編譯後 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` 會移除一個登入。

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

### 匯入與同步專案

```sh
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` 會列出、新增、回覆並解決留言。無法立刻送出的留言會先保留，下次再送出。

第一次共用專案要在應用程式中進行。請參閱[即時協作](/docs/collaboration/)。

## 在終端機執行 Oleafly 代理程式

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

```sh
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。

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

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

## 指令參考

每個指令都可以用 `--help` 查看它的選項說明。完整參考資料在儲存庫中：[docs/cli.md](https://github.com/Oleafly/Oleafly/blob/main/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`。

```json
{
  "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 專案](/docs/typst/#build-from-the-command-line)
- [透過 MCP 連接](/docs/mcp/)
- [CLI 代理程式](/docs/cli-agents/)
- [預檢](/docs/preflight/)
- [研究任務](/docs/research-tasks/)