콘텐츠로 이동
Oleaflyv0.4.12

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

Oleafly가 시작하는 프로그램, 예를 들어 Oleafly의 터미널과 CLI 에이전트는 설치하기 전에도 항상 PATH에서 oleafly를 찾을 수 있습니다. OLEAFLY_CLI 변수에 그 전체 경로가 들어 있습니다. 이런 프로그램은 직접 설치한 TeX가 있으면 그 뒤에서 Oleafly의 TinyTeX도 찾습니다. Oleafly에 들어 있는 Tectonic, Typst, Pandoc은 그 PATH에 없으므로, 이름으로 직접 부르지 말고 oleafly build와 oleafly export를 쓰세요.

  1. 설정 → 일반을 열고 터미널 명령 행에서 설치를 선택합니다.
  2. 새 PowerShell 또는 명령 프롬프트 창을 엽니다. 이미 열려 있던 창은 이전 PATH를 유지합니다.
  3. 작동하는지 확인합니다.
터미널 창
Get-Command oleafly
oleafly version

같은 행의 제거는 사본을 삭제하고 그 폴더를 PATH에서 다시 뺍니다. Oleafly가 업데이트되면 다음에 시작할 때 사본을 새로 고칩니다.

먼저 Oleafly를 응용 프로그램 폴더로 옮기세요. 디스크 이미지에서 실행 중인 사본에는 설치 대신 “먼저 Oleafly를 응용 프로그램 폴더로 옮긴 다음 여기에서 명령을 설치하세요”가 표시됩니다.

명령은 앱에 대한 링크이므로 Oleafly를 업데이트하면 명령도 함께 업데이트됩니다. 그 폴더가 PATH에 없으면 행에 shell 프로필에 추가할 줄이 표시됩니다. command -v oleafly로 확인하세요.

.deb와 .rpm 패키지는 설치할 때 oleafly를 PATH에 넣습니다. 뒤에 아무것도 붙이지 않은 oleafly는 앱을 엽니다.

AppImage는 종료하면 그 안의 파일이 사라지므로 사본이 필요합니다. AppImage를 더 새 것으로 교체하고 나면 행에 업데이트가 나타납니다. ~/.local/bin이 PATH에 없으면 행에 추가할 줄이 표시됩니다.

엔진도 AppImage 안에 남아 있습니다. 복사한 oleafly는 Oleafly의 내장 터미널에서는 그 엔진을 쓸 수 있지만, 직접 연 터미널, CLI 에이전트, 어시스턴트가 실행하는 명령에서는 쓸 수 없습니다. 그런 곳에서는 Tectonic, Typst, Pandoc을 설치하거나 .deb 또는 .rpm 패키지를 쓰세요. oleafly doctor가 이를 경고합니다.

oleafly version은 앱 버전과 명령이 사용할 엔진을 출력합니다. oleafly doctor는 엔진, TeX 설치, 앱, Git, 터미널 명령, MCP 클라이언트를 점검하고, 빠진 것에는 해결 방법을 출력합니다. TeX가 아예 설치되어 있지 않으면 latexmk 프로젝트를 빌드할 수 없으므로 경고합니다. 프로젝트 밖에서도 작동합니다.

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를 다른 곳에 복사합니다.
  • Markdown 문서는 프런트 매터에 적힌 문서 유형대로 빌드됩니다. 슬라이드나 편지가 그 예입니다.
  • latexmk 프로젝트는 설정 → 엔진 → LaTeX → TeX 배포판 관리에서 사용 중으로 표시된 TeX 배포판을 쓰므로, 거기서 컴파일에 사용으로 고른 배포판이 여기에도 적용됩니다.
  • 앱에서 제자리에 연 폴더는 앱에서 고른 엔진과 주 문서로, 앱 자체의 빌드 폴더에 빌드됩니다.
  • 아직 프로젝트가 아니고 앱에서 연 적도 없는 LaTeX 파일 폴더는, 무언가가 latexmk를 요청하지 않는 한 내장 엔진으로 빌드됩니다. 요청하는 방법은 --compiler, pdflatex, lualatex, uplatex, platex 중 하나를 지정하는 % !TEX program 줄, ujarticle 같은 일본어 클래스, 또는 oleafly config로 latex.default_engine을 latexmk로 설정하는 것입니다. 문서가 pdfLaTeX나 LuaLaTeX를 요청하는데 이 컴퓨터에서 latexmk를 실행할 수 없으면, 빌드는 내장 엔진에 머물고 경고를 출력합니다.
  • 앱과 명령은 같은 프로젝트를 동시에 빌드하지 않습니다. 나중 쪽이 먼저 쪽을 기다립니다. 빌드가 실패해도 마지막으로 성공한 PDF는 남습니다.
  • 빌드가 실패하면 오류를 최대 20개까지 나열하며, Oleafly가 가진 설명과 힌트를 함께 보여 줍니다. --quiet를 주면 오류만 나열합니다.
  • --timeout은 그 초가 지나면 컴파일러를 멈추며, 기본값은 300초입니다. 내장 엔진이 패키지를 내려받는 동안에는 마지막 다운로드부터 시간을 세며, 최대 30분까지 이어지고 --timeout이 더 길면 그 시간까지 이어집니다.
  • oleafly build는 앱에서 외부 명령 허용을 선택한 프로젝트에서도 LaTeX의 shell 명령을 항상 막습니다. minted나 PythonTeX를 쓰는 문서처럼 shell 명령이 필요한 문서는 여기서 실패하고 이유를 알려 줍니다. 앱에서 빌드하거나, latexmk를 -shell-escape로 직접 실행하세요. 프로젝트의 모든 파일을 신뢰할 때만 둘 중 하나를 하세요.
  • Quarto와 Calepin 프로젝트는 앱에서만 빌드됩니다. oleafly build가 그렇게 알려 주고, 도구를 직접 실행하고 싶다면 quarto render나 calepin compile 명령을 알려 줍니다.
  • oleafly watch는 저장할 때마다 다시 빌드합니다. 빌드를 시작할 수 없으면 오류와 힌트를 출력한 뒤 다음 변경을 기다립니다. oleafly log --diagnostics는 오류와 경고를 파일과 줄 번호와 함께 나열하고, oleafly clean은 빌드 출력을 지웁니다.

Typst 관련 내용은 Typst 프로젝트를 참고하세요.

코딩 에이전트는 명령이 주는 세 가지가 있을 때 가장 잘 일합니다. 프로젝트 지도인 oleafly context, 읽을 수 있는 결과를 위한 --json, 무엇이 잘못됐는지 알려 주는 종료 코드입니다. 에이전트를 연결하는 방법은 세 가지입니다.

Oleafly에는 oleafly-cli라는 스킬이 들어 있습니다. 에이전트에게 명령, JSON 출력, 종료 코드, 그리고 가장 잘 통하는 반복 절차를 가르칩니다. 맥락을 읽고, 편집하고, 빌드하고, 진단을 읽고, 첫 번째 오류를 고치는 순서입니다.

Oleafly의 터미널과 Oleafly가 시작하는 CLI 에이전트에서는 다른 스킬처럼 이 스킬을 고르면 됩니다. 직접 실행하는 에이전트에는 설정 → AI 어시스턴트 → 스킬 → 이 컴퓨터의 다른 에이전트와 스킬 공유를 켜세요. 그러면 Oleafly가 oleafly-cli를 포함한 스킬을 ~/.claude/skills, ~/.codex/skills, ~/.agents/skills 같은 다른 코딩 에이전트가 읽는 폴더에 연결합니다. 다른 폴더를 읽는 에이전트를 위해 oleafly skills path가 스킬이 있는 위치를 출력합니다.

oleafly mcp는 표준 입력과 표준 출력으로 통신하는 MCP 서버입니다. 앱에 프로젝트가 열려 있으면 호출을 앱 자체의 MCP 서버로 넘기므로, 에이전트는 앱의 모든 도구와 승인 프롬프트를 그대로 받습니다. 그렇지 않으면 읽기 도구(프로젝트 상태, 프로젝트 지도, 파일, 검색, 로그, doctor 보고서, 인용 조회)와 compile만으로 스스로 작동합니다. 복사할 URL이나 토큰도, 설치할 Node.js도 없습니다.

도구가 없어서 compile을 실행할 수 없으면, 그 오류에는 TeX를 구하는 방법 같은 oleafly build가 출력하는 것과 같은 힌트가 담겨 있으므로 에이전트가 무엇을 설치해야 하는지 알려 줄 수 있습니다. oleafly agent run 중의 빌드도 같은 방식으로 보고합니다.

가장 빠른 설정은 oleafly mcp config --client 뒤에 claude-code, claude-desktop, codex, cursor, gemini 중 하나를 붙이는 것입니다. 그 클라이언트용 항목을 출력하며, --write를 더하면 클라이언트 파일을 백업한 뒤 항목을 대신 추가해 줍니다. 그 뒤 클라이언트를 다시 시작하거나 다시 연결하세요. 프로젝트 안에서는 프로젝트 설정에, 그 밖에서는 사용자 설정에 쓰며, 데스크톱에서 시작한 앱은 PATH를 보지 못할 수 있으므로 명령의 전체 경로를 넣습니다.

터미널 창
claude mcp add --scope user oleafly -- oleafly mcp

프로젝트 안에서 oleafly mcp config --client claude-code --write를 실행하면 서버가 대신 프로젝트의 .mcp.json에 추가됩니다.

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/config.toml
[mcp_servers.oleafly]
command = "oleafly"
args = ["mcp"]
tool_timeout_sec = 300

모든 프로젝트에는 ~/.cursor/mcp.json을, 한 프로젝트 안에서만 쓰려면 .cursor/mcp.json을 쓰세요.

~/.cursor/mcp.json
{
"mcpServers": {
"oleafly": {
"command": "oleafly",
"args": ["mcp"]
}
}
}
~/.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 액션으로 업로드하면, 각 발견 사항이 풀 리퀘스트의 해당 줄에 표시됩니다.

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은 로그인을 제거합니다.
터미널 창
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 server sign-in 뒤에 서버 주소를 붙이면 브라우저에서 승인하는 코드로 명령줄을 로그인시킵니다. 명령줄은 서버에서 앱과 별개의 기기로 취급됩니다.

  • oleafly server status와 oleafly server projects는 내 서버와 공유 프로젝트를 보여 줍니다.
  • oleafly server share는 프로젝트의 링크를 보여 주고 링크 공유와 댓글을 켜거나 끕니다.
  • oleafly server members는 프로젝트 참여자를 나열하고 추가, 제거, 변경합니다. 공유와 참여자는 소유자만 바꿀 수 있습니다.
  • oleafly server comments는 댓글을 나열, 추가, 답글, 해결 처리합니다. 바로 보낼 수 없는 댓글은 보관했다가 다음에 보냅니다.

프로젝트를 처음 공유하는 일은 앱에서 합니다. 실시간 공동 작업을 참고하세요.

터미널에서 Oleafly 에이전트 실행

섹션 제목: “터미널에서 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는 도우미가 하는 일을 보여 줍니다.

다음은 앱에서만 할 수 있습니다.

  • 설정 → 엔진 → LaTeX → TeX 배포판 관리에서 TinyTeX 설치하기.
  • minted나 PythonTeX를 쓰는 문서처럼 shell 명령을 실행하는 LaTeX 문서 빌드하기.
  • Quarto와 Calepin 문서 빌드하기.
  • 참고문헌이 최신이 아닐 때 빌드 중 Biber를 다시 실행하기.
  • 체크포인트를 만들고, 프로젝트 위에 하나를 복원하기.
  • Oleafly 서버에서 프로젝트를 처음 공유하기.

모든 명령은 --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 citeDOI, arXiv id, ISBN, PubMed id의 BibTeX를 출력합니다. --add는 참고문헌에 추가합니다
oleafly literatureOpenAlex, 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 typstTypst 버전을 나열, 설치, 제거합니다
oleafly checkpoint앱의 체크포인트를 나열, 비교, 복사합니다
명령하는 일
oleafly context사람이나 에이전트를 위해 프로젝트의 지도를 만듭니다
oleafly mcpMCP 서버를 실행합니다. mcp config는 클라이언트를 설정합니다
oleafly skills스킬을 나열하고 있는 위치를 출력합니다
oleafly ask프로젝트에 대한 질문에 답합니다
oleafly agent작업에 Oleafly 에이전트를 실행합니다
oleafly daemon작업을 계속 실행하는 도우미를 실행하고 제어합니다
명령하는 일
oleafly check프리플라이트 검사를 실행합니다
oleafly lintLaTeX, BibTeX, 맞춤법, 문법 검사를 실행합니다
명령하는 일
oleafly auth온라인 LaTeX 서비스, Oleafly 서버, Git 호스트에 로그인합니다
oleafly remote온라인 프로젝트를 가져오고, 연결하고, 동기화합니다
oleafly serverOleafly 서버로 작업합니다: 프로젝트, 공유, 참여자, 댓글
명령하는 일
oleafly completionsbash, zsh, fish, PowerShell, elvish용 shell 자동 완성을 출력합니다
oleafly man매뉴얼 페이지를 출력합니다
oleafly help exit-codes종료 코드를 설명합니다
옵션하는 일
-C 뒤에 경로다른 프로젝트 폴더에서 명령을 실행합니다
--jsonJSON 결과 하나를 출력합니다
--events결과 앞에 진행 상황을 JSON 줄로 출력합니다
--quiet결과만 출력합니다
--log컴파일러 로그를 none, tail, full 중 하나로 보여 줍니다
--no-input절대 질문하지 않습니다
--color색을 auto, always, never로 씁니다

--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성공했습니다
1Oleafly 내부에서 문제가 생겼습니다
2명령을 잘못 썼거나, 계속하려면 --yes가 필요합니다
3프로젝트가 없거나 올바르지 않거나, 경로가 프로젝트 밖을 가리킵니다
4필요한 도구나 Oleafly 앱이 설치되어 있지 않습니다
5빌드가 실패했습니다
6로그인해야 합니다
7네트워크가 실패했습니다
8다른 것이 프로젝트를 쓰고 있거나, 동기화에 충돌이 있습니다
9검사에서 문제를 찾았습니다
130Ctrl+C를 눌렀습니다

명령은 터미널이 없으면 질문하지 않습니다. --no-input도 질문을 끄고, CI 변수도 마찬가지입니다. 그러면 yes가 필요한 명령은 종료 코드 2로 실패하며 --yes를 요구합니다. NO_COLOR나 --color never는 색을 끕니다. 프로젝트 밖으로 나가는 경로는 거부됩니다.

변수용도
OLEAFLY_DATA_DIR~/.oleafly가 아닐 때 Oleafly의 데이터 폴더
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOCOleafly가 찾은 것 대신 쓸 컴파일러
OLEAFLY_APPoleafly open이 시작하는 Oleafly 앱
OLEAFLY_ONLINE_GIT_TOKEN저장된 토큰 대신 쓰는, 온라인 LaTeX 서비스용 Git 토큰
OLEAFLY_DOWNLOAD_MIRRORTinyTeX나 Typst 같은 다운로드를 받아 오는 곳: automatic, original, 또는 내 미러의 HTTPS 주소. 다운로드 소스 탭을 참고하세요
OLEAFLY_TEX_REPOSITORYtlmgr이 패키지를 설치해 오는 TeX Live 저장소
OLEAFLY_CLIOleafly가 시작하는 프로그램에 설정해 주는 명령의 전체 경로
CI설정하면 명령이 절대 질문하지 않습니다
NO_COLOR설정하면 출력에 색이 없습니다
증상해 볼 일
oleafly를 찾을 수 없음새 터미널을 여세요. 그다음 Windows에서는 Get-Command oleafly, macOS와 Linux에서는 command -v oleafly로 확인하고, 설정에 표시된 줄을 shell 프로필에 추가하세요
oleafly doctor가 빠진 엔진을 알려 줌doctor가 출력하는 명령으로 설치하거나, 프로젝트를 앱에서 한 번 여세요
latexmk를 찾을 수 없음앱의 설정 → 엔진 → LaTeX → TeX 배포판 관리에서 TinyTeX를 설치하거나, 힌트가 알려 주는 명령으로 TeX를 설치하세요. 대신 내장 엔진을 쓰려면 프로젝트에서 oleafly config set engine tectonic을, 프로젝트가 아닌 폴더에는 oleafly config set latex.default_engine tectonic --global을 실행하세요
latexmk 빌드가 없는 .sty나 .cls 파일에서 멈춤TeX Live, MacTeX, TinyTeX에서는 힌트가 tlmgr search와 tlmgr install 명령을 알려 줍니다. Debian, Ubuntu, Fedora 패키지로 설치한 TeX Live는 대신 apt나 dnf로 패키지를 받습니다. Debian과 Ubuntu에서는 apt-file search 뒤에 파일 이름을 붙이면 패키지를 찾아 줍니다. MiKTeX에는 힌트가 없습니다. MiKTeX Console에서 패키지를 설치한 다음 다시 빌드하세요
minted나 PythonTeX를 쓰는 빌드가 실패함oleafly build는 shell 명령을 막습니다. 외부 명령 허용을 선택한 뒤 앱에서 프로젝트를 빌드하거나, latexmk를 -shell-escape로 직접 실행하세요
첫 빌드가 패키지를 내려받는 동안 시간 초과됨다시 빌드하세요. 다운로드는 멈춘 지점부터 이어집니다. --timeout으로 제한을 늘릴 수 있습니다
Typst 프로젝트가 설치되지 않은 버전을 요구함oleafly typst install 뒤에 그 버전을 붙여 실행하세요
Linux AppImage에서 엔진이 없음AppImage의 엔진은 Oleafly의 내장 터미널에서만 작동합니다. Tectonic, Typst, Pandoc을 설치하거나 .deb 또는 .rpm 패키지를 쓰세요
MCP 클라이언트가 서버를 시작하지 못함설정된 명령을 터미널에서 실행하고, oleafly mcp config가 출력한 전체 경로를 쓰고, oleafly doctor를 실행하세요
종료 코드 6oleafly auth status를 실행한 다음 다시 로그인하세요
동기화 중 종료 코드 8나열된 파일마다 --resolve를 주어 동기화를 다시 실행하세요
macOS에서 설정에 “먼저 Oleafly를 응용 프로그램 폴더로 옮긴 다음 여기에서 명령을 설치하세요”가 표시됨앱을 옮기고 응용 프로그램에서 연 다음 설치를 선택하세요
이미지 미리보기

AI 답변을 불러오지 못했습니다

다시 시도하거나 문서를 검색하세요.