# 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

| 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ó.

### Windows

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:

```powershell
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.

### 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

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.

### 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, ứ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.

## 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.

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

## 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

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

`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](/docs/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.

#### Claude Code

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

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.

```json title="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

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

#### Cursor

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

```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
    }
  }
}
```

### Đư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

`oleafly check` chạy các [kiểm tra Preflight](/docs/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

`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

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.

:::caution[Không để token trong lịch sử shell]
Token được đưa vào qua đầu vào chuẩn, chẳng hạn `oleafly auth login online --with-token < token.txt`, không bao giờ làm đối số. Trong terminal, lệnh sẽ hỏi token mà không hiển thị những gì bạn gõ. `oleafly auth token` in ra một token đã lưu cho script, nên hãy coi đầu ra của nó như mật khẩu.
:::

### Nhập và đồng bộ dự án

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

## 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 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](/docs/collaboration/).

## 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ụ.

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

Đánh dấu một [nhiệm vụ nghiên cứu](/docs/research-tasks/) 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ì.

## 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](https://github.com/Oleafly/Oleafly/blob/main/docs/cli.md).

### 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

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

| 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

| 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ộ

| 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

| 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

| 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

### Đầ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.

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

`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ý

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

| 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_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ố

| 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 |
| 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** |

## Các trang liên quan

- [Dự án Typst](/docs/typst/#build-from-the-command-line)
- [Kết nối qua MCP](/docs/mcp/)
- [Các CLI agent](/docs/cli-agents/)
- [Các kiểm tra Preflight](/docs/preflight/)
- [Nhiệm vụ nghiên cứu](/docs/research-tasks/)