콘텐츠로 이동
Oleaflyv0.4.8

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 변수에 그 전체 경로가 들어 있습니다.

  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에 없으면 행에 추가할 줄이 표시됩니다.

oleafly version은 앱 버전과 명령이 사용할 엔진을 출력합니다. oleafly doctor는 엔진, 앱, Git, 터미널 명령, MCP 클라이언트를 점검하고, 빠진 것에는 해결 방법을 출력합니다. 프로젝트 밖에서도 작동합니다.

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를 다른 곳에 복사하고, --timeout은 제한 시간을 초 단위로 정합니다.
  • 앱에서 제자리에 연 폴더는 앱에서 고른 엔진과 주 문서로, 앱 자체의 빌드 폴더에 빌드됩니다.
  • 앱과 명령은 같은 프로젝트를 동시에 빌드하지 않습니다. 나중 쪽이 먼저 쪽을 기다립니다. 빌드가 실패해도 마지막으로 성공한 PDF는 남습니다.
  • 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도 없습니다.

가장 빠른 설정은 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는 도우미가 하는 일을 보여 줍니다.

모든 명령은 --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_CLIOleafly가 시작하는 프로그램에 설정해 주는 명령의 전체 경로
CI설정하면 명령이 절대 질문하지 않습니다
NO_COLOR설정하면 출력에 색이 없습니다
증상해 볼 일
oleafly를 찾을 수 없음새 터미널을 여세요. 그다음 Windows에서는 Get-Command oleafly, macOS와 Linux에서는 command -v oleafly로 확인하고, 설정에 표시된 줄을 shell 프로필에 추가하세요
oleafly doctor가 빠진 엔진을 알려 줌doctor가 출력하는 명령으로 설치하거나, 프로젝트를 앱에서 한 번 여세요
MCP 클라이언트가 서버를 시작하지 못함설정된 명령을 터미널에서 실행하고, oleafly mcp config가 출력한 전체 경로를 쓰고, oleafly doctor를 실행하세요
종료 코드 6oleafly auth status를 실행한 다음 다시 로그인하세요
동기화 중 종료 코드 8나열된 파일마다 --resolve를 주어 동기화를 다시 실행하세요
macOS에서 설정에 “먼저 Oleafly를 응용 프로그램 폴더로 옮긴 다음 여기에서 명령을 설치하세요”가 표시됨앱을 옮기고 응용 프로그램에서 연 다음 설치를 선택하세요
이미지 미리보기

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

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