# 명령줄 도구

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` | **터미널 명령** 행의 **설치**가 `/usr/local/bin`에 쓸 수 있으면 거기에, 아니면 `~/.local/bin`에 `oleafly`를 링크합니다 |
| Linux 패키지(.deb, .rpm) | `/usr/bin/oleafly-cli` | 할 일 없음: 패키지가 `/usr/bin/oleafly`를 설치합니다 |
| Linux AppImage | AppImage 안 | **설치**가 `~/.local/bin/oleafly`에 복사합니다 |

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를 더 새 것으로 교체하고 나면 행에 **업데이트**가 나타납니다. `~/.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의 터미널과 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` 액션으로 업로드하면, 각 발견 사항이 풀 리퀘스트의 해당 줄에 표시됩니다.

## 온라인 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로, 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` 변수도 마찬가지입니다. 그러면 yes가 필요한 명령은 종료 코드 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/)