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

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.

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

`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

`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 và `-o` sao 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](/docs/writing/markdown/#document-types) 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 program` nêu `pdflatex`, `lualatex`, `uplatex` hoặc `platex`, một lớp tiếng Nhật như `ujarticle`, hoặc `latex.default_engine` được đặt thành `latexmk` bằng `oleafly 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.
- `--timeout` dừ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 `--timeout` dài hơn.
- `oleafly build` luô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 build` nói rõ điều đó và nêu lệnh `quarto render` hoặc `calepin compile`, nếu bạn muốn tự chạy công cụ.
- `oleafly watch` dự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 --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.

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

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

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

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

| 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_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](/docs/settings/downloads/#sources-tab) |
| `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ố

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

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