명령줄 도구
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 변수에 그 전체 경로가 들어 있습니다. 이런 프로그램은 직접 설치한 TeX가 있으면 그 뒤에서 Oleafly의 TinyTeX도 찾습니다. Oleafly에 들어 있는 Tectonic, Typst, Pandoc은 그 PATH에 없으므로, 이름으로 직접 부르지 말고 oleafly build와 oleafly export를 쓰세요.
Windows
섹션 제목: “Windows”- 설정 → 일반을 열고 터미널 명령 행에서 설치를 선택합니다.
- 새 PowerShell 또는 명령 프롬프트 창을 엽니다. 이미 열려 있던 창은 이전 PATH를 유지합니다.
- 작동하는지 확인합니다.
Get-Command oleaflyoleafly version같은 행의 제거는 사본을 삭제하고 그 폴더를 PATH에서 다시 뺍니다. Oleafly가 업데이트되면 다음에 시작할 때 사본을 새로 고칩니다.
macOS
섹션 제목: “macOS”먼저 Oleafly를 응용 프로그램 폴더로 옮기세요. 디스크 이미지에서 실행 중인 사본에는 설치 대신 “먼저 Oleafly를 응용 프로그램 폴더로 옮긴 다음 여기에서 명령을 설치하세요”가 표시됩니다.
명령은 앱에 대한 링크이므로 Oleafly를 업데이트하면 명령도 함께 업데이트됩니다. 그 폴더가 PATH에 없으면 행에 shell 프로필에 추가할 줄이 표시됩니다. command -v oleafly로 확인하세요.
Linux
섹션 제목: “Linux”.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/thesisoleafly init --engine typstoleafly buildoleafly log --diagnosticsoleafly -C ~/papers/review --json buildoleafly 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-cli 스킬
섹션 제목: “oleafly-cli 스킬”Oleafly에는 oleafly-cli라는 스킬이 들어 있습니다. 에이전트에게 명령, JSON 출력, 종료 코드, 그리고 가장 잘 통하는 반복 절차를 가르칩니다. 맥락을 읽고, 편집하고, 빌드하고, 진단을 읽고, 첫 번째 오류를 고치는 순서입니다.
Oleafly의 터미널과 Oleafly가 시작하는 CLI 에이전트에서는 다른 스킬처럼 이 스킬을 고르면 됩니다. 직접 실행하는 에이전트에는 설정 → AI 어시스턴트 → 스킬 → 이 컴퓨터의 다른 에이전트와 스킬 공유를 켜세요. 그러면 Oleafly가 oleafly-cli를 포함한 스킬을 ~/.claude/skills, ~/.codex/skills, ~/.agents/skills 같은 다른 코딩 에이전트가 읽는 폴더에 연결합니다. 다른 폴더를 읽는 에이전트를 위해 oleafly skills path가 스킬이 있는 위치를 출력합니다.
MCP로 에이전트 연결
섹션 제목: “MCP로 에이전트 연결”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 Code
섹션 제목: “Claude Code”claude mcp add --scope user oleafly -- oleafly mcp프로젝트 안에서 oleafly mcp config --client claude-code --write를 실행하면 서버가 대신 프로젝트의 .mcp.json에 추가됩니다.
Claude Desktop
섹션 제목: “Claude Desktop”Claude Desktop은 프로젝트 폴더 없이 서버를 시작하므로, 이 항목은 언제나 앱을 거쳐 작동합니다. 프로젝트를 연 채로 Oleafly를 켜 두세요. oleafly의 전체 경로를 쓰세요. Windows에서는 경로의 백슬래시를 모두 두 번씩 쓰세요.
{ "mcpServers": { "oleafly": { "command": "/usr/local/bin/oleafly", "args": ["mcp", "--bridge", "always"] } }}파일은 macOS에서는 ~/Library/Application Support/Claude에, Windows에서는 %APPDATA%\Claude에 있습니다.
Codex
섹션 제목: “Codex”[mcp_servers.oleafly]command = "oleafly"args = ["mcp"]tool_timeout_sec = 300Cursor
섹션 제목: “Cursor”모든 프로젝트에는 ~/.cursor/mcp.json을, 한 프로젝트 안에서만 쓰려면 .cursor/mcp.json을 쓰세요.
{ "mcpServers": { "oleafly": { "command": "oleafly", "args": ["mcp"] } }}Gemini CLI
섹션 제목: “Gemini CLI”{ "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 액션으로 업로드하면, 각 발견 사항이 풀 리퀘스트의 해당 줄에 표시됩니다.
온라인 LaTeX 서비스와 동기화
섹션 제목: “온라인 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은 로그인을 제거합니다.
프로젝트 가져오기와 동기화
섹션 제목: “프로젝트 가져오기와 동기화”oleafly remote listoleafly remote import 64a1f0c2e5b7 --into ~/paperscd ~/papers/thesisoleafly remote linkoleafly remote syncoleafly 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 서버와 작업하기”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 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과 도움말
섹션 제목: “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을 주면 모든 명령이 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 | 성공했습니다 |
| 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_DOWNLOAD_MIRROR | TinyTeX나 Typst 같은 다운로드를 받아 오는 곳: automatic, original, 또는 내 미러의 HTTPS 주소. 다운로드 소스 탭을 참고하세요 |
OLEAFLY_TEX_REPOSITORY | tlmgr이 패키지를 설치해 오는 TeX Live 저장소 |
OLEAFLY_CLI | Oleafly가 시작하는 프로그램에 설정해 주는 명령의 전체 경로 |
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를 실행하세요 |
| 종료 코드 6 | oleafly auth status를 실행한 다음 다시 로그인하세요 |
| 동기화 중 종료 코드 8 | 나열된 파일마다 --resolve를 주어 동기화를 다시 실행하세요 |
| macOS에서 설정에 “먼저 Oleafly를 응용 프로그램 폴더로 옮긴 다음 여기에서 명령을 설치하세요”가 표시됨 | 앱을 옮기고 응용 프로그램에서 연 다음 설치를 선택하세요 |