Skip to content
Oleaflyv0.4.12

Install the oleafly command on Windows, macOS or Linux, build and check projects from a terminal or CI, sync with an online LaTeX service, and connect coding agents through its MCP server and skill.

Oleafly comes with oleafly, a command-line tool that works on the same projects as the app. Build or check a paper from a terminal, a script or CI. Give a coding agent a reliable way into your project. Sync with an online LaTeX service or an Oleafly server, or run the Oleafly agent without opening the app.

It ships inside the app on every platform. This page covers the commands in Oleafly 0.4.8 and later. Earlier versions had fewer, so pin your Oleafly version in scripts that depend on it.

SystemWhere the app keeps itPut oleafly on your PATH
Windowsoleafly-cli.exe next to the app, in %LOCALAPPDATA%\Oleafly for the setup program or C:\Program Files\Oleafly for the MSI packageInstall on the Terminal command row in Settings → General copies it to %LOCALAPPDATA%\Oleafly\bin\oleafly.exe and adds that folder to your PATH
macOSOleafly.app/Contents/MacOS/oleafly-cliInstall on the Terminal command row links oleafly into /usr/local/bin when you can write there, otherwise into ~/.local/bin
Linux packages (.deb, .rpm)/usr/bin/oleafly-cliNothing to do: the package installs /usr/bin/oleafly
Linux AppImageInside the AppImageInstall copies it to ~/.local/bin/oleafly

Programs that Oleafly starts, such as its own terminal and the CLI agents, always find oleafly on their PATH, even before you install it. The OLEAFLY_CLI variable holds its full path. They also find Oleafly’s TinyTeX, after any TeX of your own. The Tectonic, Typst and Pandoc that come with Oleafly aren’t on that PATH, so use oleafly build and oleafly export rather than calling them by name.

  1. Open Settings → General and choose Install on the Terminal command row.
  2. Open a new PowerShell or Command Prompt window. Windows that were already open keep the old PATH.
  3. Check that it works:
Terminal window
Get-Command oleafly
oleafly version

Remove on the same row deletes the copy and takes the folder off your PATH again. When Oleafly updates, it refreshes the copy the next time it starts.

Move Oleafly to your Applications folder first. A copy that runs from the disk image shows “Move Oleafly to your Applications folder first” instead of Install.

The command is a link to the app, so updating Oleafly updates the command too. If the folder isn’t on your PATH, the row shows the line to add to your shell profile. Check it with command -v oleafly.

The .deb and .rpm packages put oleafly on your PATH when you install them. oleafly with nothing after it opens the app.

The AppImage needs a copy, because the files inside an AppImage go away when it quits. After you replace the AppImage with a newer one, the row offers Update. If ~/.local/bin isn’t on your PATH, the row shows the line to add.

The engines stay inside the AppImage too. The copied oleafly can use them from Oleafly’s built-in terminal, but not from a terminal you open yourself, a CLI agent or a command the assistant runs. For those, install Tectonic, Typst and Pandoc, or use the .deb or .rpm package. oleafly doctor warns about this.

oleafly version prints the app version and the engines the command would use. oleafly doctor checks the engines, your TeX installation, the app, Git, the terminal command and your MCP clients, and prints a fix for anything missing. It warns when no TeX is installed at all, because latexmk projects can’t build then. It works outside a project too.

oleafly . opens the current folder in the app. Every other command works on the folder you’re in; -C followed by a path points it somewhere else.

Terminal window
cd ~/papers/thesis
oleafly init --engine typst
oleafly build
oleafly log --diagnostics
oleafly -C ~/papers/review --json build
  • oleafly init makes the current folder a project. --engine takes tectonic, latexmk, typst or markdown.
  • oleafly new followed by a folder and --template and a template id creates a project from a template. oleafly templates list --all lists the templates.
  • oleafly build uses the project’s engine and settings, the same way the app does: the Tectonic, Typst and Pandoc that come with Oleafly, or the LaTeX you installed. --main builds another document of the project, --compiler picks the LaTeX compiler for latexmk projects and -o copies the PDF somewhere else.
  • A Markdown document builds as the document type its front matter names, such as slides or a letter.
  • latexmk projects use the TeX distribution marked In use under Settings → Engines → LaTeX → Manage TeX distributions, so a distribution you picked there with Use for compiles applies here too.
  • A folder you opened in place in the app builds with the engine and main document you chose there, into the app’s own build folder.
  • A folder of LaTeX files that isn’t a project yet, and that you never opened in the app, builds with the built-in engine unless something asks for latexmk: --compiler, a % !TEX program line naming pdflatex, lualatex, uplatex or platex, a Japanese class such as ujarticle, or latex.default_engine set to latexmk with oleafly config. If the document asks for pdfLaTeX or LuaLaTeX and latexmk can’t run on this computer, the build stays on the built-in engine and prints a warning.
  • The app and the command never build the same project at once: the second one waits for the first. A failed build keeps the last good PDF.
  • A failed build lists up to 20 errors, with an explanation and hints where Oleafly has them. With --quiet it lists only the errors.
  • --timeout stops a compiler after that many seconds, 300 by default. While the built-in engine downloads packages, the time counts from the last download, for up to 30 minutes, or longer if --timeout is longer.
  • oleafly build always blocks shell commands from LaTeX, even in a project where you chose Allow external commands in the app. A document that needs them, such as one that uses minted or PythonTeX, fails here and says why. Build it in the app, or run latexmk yourself with -shell-escape. Do either only if you trust every file in the project.
  • Quarto and Calepin projects build only in the app. oleafly build says so and names the quarto render or calepin compile command, if you’d rather run the tool yourself.
  • oleafly watch rebuilds every time you save. When a build can’t start, it prints the error and its hint, then waits for your next change. oleafly log --diagnostics lists errors and warnings with file and line, and oleafly clean removes the build output.

For Typst specifics, see Typst projects.

Coding agents work best with three things the command gives them: oleafly context for the project’s map, --json for results they can read, and exit codes that say what went wrong. There are three ways to connect an agent.

Oleafly ships a skill called oleafly-cli. It teaches an agent the commands, the JSON output and the exit codes, and the loop that works best: read the context, edit, build, read the diagnostics, fix the first error.

In Oleafly’s terminal and the CLI agents it starts, pick the skill like any other. For an agent you run on your own, turn on Settings → AI Assistant → Skills → Share skills with other agents on this computer. Oleafly then links its skills, oleafly-cli included, into the folders other coding agents read, such as ~/.claude/skills, ~/.codex/skills and ~/.agents/skills. oleafly skills path prints where the skills are, for agents that read another folder.

oleafly mcp is an MCP server that talks over standard input and output. When the app has your project open, it passes calls on to the app’s own MCP server, so the agent gets every app tool and your approval prompts. Otherwise it works on its own, with read tools (project status, the project map, files, search, logs, the doctor report, citation lookup) and compile. There is no URL or token to copy and no Node.js to install.

When compile can’t run because a tool is missing, its error carries the same hint oleafly build prints, such as how to get TeX, so the agent can tell you what to install. Builds during oleafly agent run report the same way.

The quickest setup is oleafly mcp config --client followed by claude-code, claude-desktop, codex, cursor or gemini. It prints the entry for that client; add --write to have it added for you, with a backup of the client’s file. Restart or reconnect the client afterwards. Inside a project it writes the project’s settings; elsewhere it writes your user settings, with the command’s full path, because apps you start from the desktop may not see your PATH.

Terminal window
claude mcp add --scope user oleafly -- oleafly mcp

Inside a project, oleafly mcp config --client claude-code --write adds the server to the project’s .mcp.json instead.

Claude Desktop starts servers without a project folder, so its entry always works through the app: keep Oleafly open with your project. Use the full path to oleafly. On Windows, double every backslash in the path.

claude_desktop_config.json
{
"mcpServers": {
"oleafly": {
"command": "/usr/local/bin/oleafly",
"args": ["mcp", "--bridge", "always"]
}
}
}

The file is in ~/Library/Application Support/Claude on macOS and %APPDATA%\Claude on Windows.

~/.codex/config.toml
[mcp_servers.oleafly]
command = "oleafly"
args = ["mcp"]
tool_timeout_sec = 300

Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project.

~/.cursor/mcp.json
{
"mcpServers": {
"oleafly": {
"command": "oleafly",
"args": ["mcp"]
}
}
}
~/.gemini/settings.json
{
"mcpServers": {
"oleafly": {
"command": "oleafly",
"args": ["mcp"],
"timeout": 300000
}
}
}

oleafly context maps the project: its files, outline, labels, citations, missing files, unresolved references and the last build’s problems. --format md gives text to paste into a prompt; --format json gives the same map for a program.

oleafly check runs the Preflight checks on the project, with the same results as the Preflight panel: references, citations, labels, missing files, bibliography fields, figures and anonymity for blind review. Checks that need the compiled PDF use the last build.

oleafly lint runs the LaTeX and BibTeX checks and, in the builds that include it, spelling and grammar. --fix applies the fixes that are safe to apply.

Both take --format human, json or sarif, and --exit-code makes them exit with 9 when they find problems. SARIF works with code-scanning services such as GitHub’s: write the report with oleafly check --format sarif -o preflight.sarif, upload it with the upload-sarif action, and each finding shows on its line in the pull request.

oleafly remote downloads projects from your online LaTeX service account and keeps a folder in sync with one, with the same merge the app uses.

Sign-ins live in the app’s encrypted store, so a sign-in made in the app works on the command line and the other way round.

  • oleafly auth login online --with-token saves a Git token from the service’s account settings. Linking and syncing need one.
  • oleafly auth login online --from-browser firefox copies your sign-in from a browser on this computer, for listing and downloading projects. Firefox works on every system; Chrome, Edge and Brave work on macOS. --cookie-stdin reads a session cookie instead.
  • oleafly auth login git --host https://gitlab.com saves a token for a Git host.
  • oleafly auth status lists every sign-in and where it came from, without showing any secret.
  • oleafly auth logout removes a sign-in.
Terminal window
oleafly remote list
oleafly remote import 64a1f0c2e5b7 --into ~/papers
cd ~/papers/thesis
oleafly remote link
oleafly remote sync
  • oleafly remote import downloads projects into new folders. It works with any account.
  • oleafly remote link connects a folder to its online project through the service’s Git integration, which needs a Git token.
  • oleafly remote sync merges online changes into the folder and sends yours. --dry-run shows what would change and --no-push merges without sending.
  • When a file changed on both sides, the sync writes nothing and exits with 8. Run it again with --resolve and the file’s path followed by =local or =remote for each file.
  • oleafly remote diff shows what differs; with --exit-code it exits with 9 when files differ and 8 when they conflict. --latexdiff --pdf builds a marked-up PDF of your changes, using latexdiff from your TeX distribution.
  • oleafly remote status, oleafly remote unlink and oleafly remote open show the link, remove it and open the project in your browser.

oleafly server sign-in followed by the server’s address signs the command line in with a code you approve in your browser. The command line is its own device on the server, apart from the app.

  • oleafly server status and oleafly server projects show your servers and shared projects.
  • oleafly server share shows a project’s link and turns link sharing and comments on or off.
  • oleafly server members lists the people on a project and adds, removes or changes them. Only the owner can change sharing and members.
  • oleafly server comments lists, adds, replies to and resolves comments. A comment that can’t be sent right away is kept and sent the next time.

Sharing a project for the first time happens in the app. See Live collaboration.

oleafly ask answers a question about the project without changing anything. oleafly agent run does a task.

Terminal window
oleafly ask "Which sections cite Smith 2021?"
oleafly agent run --allow write "Fix the overfull boxes in chapter 3"
  • The agent can always read the project. --allow adds write, commands or network, and it refuses anything you didn’t allow. It never stops to ask a question.
  • Changes go to a review folder in .oleafly/agent-runs/ first. oleafly agent apply followed by that folder writes them into the project, and --apply on the run writes them straight away.
  • The provider, model and effort come from the app’s settings, or from --provider, --model and --effort. The key comes from the provider’s own environment variable, such as ANTHROPIC_API_KEY, or from the app’s encrypted store.
  • --json prints one result when the run ends, and --events adds a JSON line for each event as it works.

Keep research tasks running after you quit

Section titled “Keep research tasks running after you quit”

Mark a research task Keep running when Oleafly is closed. When you quit, a small background helper takes those tasks over and their experiment runs keep going. A step that needs your approval pauses the task and sends a notification. When you open Oleafly again, it takes the tasks back and shows what happened. Turn this off, or start the helper when you sign in, under Settings → Research → Background tasks. oleafly daemon status shows what the helper is doing.

These stay in the app:

  • Installing TinyTeX, under Settings → Engines → LaTeX → Manage TeX distributions.
  • Building a LaTeX document that runs shell commands, such as one that uses minted or PythonTeX.
  • Building Quarto and Calepin documents.
  • Running Biber again during a build when the bibliography is out of date.
  • Creating checkpoints, and restoring one over the project.
  • Sharing a project on an Oleafly server for the first time.

Every command explains its options with --help. The full reference is in the repository: docs/cli.md (opens in a new tab).

CommandWhat it does
oleafly openOpens a folder in the app (oleafly . for the current one)
oleafly initMakes the current folder a project
oleafly newCreates a project, from a template if you name one
oleafly templatesLists templates and shows one
oleafly buildBuilds the project
oleafly watchRebuilds on every save
oleafly cleanRemoves the build output
oleafly logShows the last build’s log or its problems
oleafly doctorChecks engines, the app and your setup
oleafly versionShows the version and the engines in use
oleafly project infoShows the project’s settings
oleafly projects listLists the app’s projects
oleafly configGets and sets project and app settings
CommandWhat it does
oleafly citePrints BibTeX for a DOI, arXiv id, ISBN or PubMed id; --add adds it to the bibliography
oleafly literatureSearches OpenAlex, Semantic Scholar, Crossref, arXiv and PubMed
oleafly bib checkFinds entries that match no real record
oleafly bib cleanFixes citation keys and removes duplicates; --apply writes the changes
oleafly statsCounts words, headings, figures and equations
oleafly synctexMaps a source line to the PDF and back
oleafly exportExports the document to Word, HTML, Markdown, EPUB and more, and lists what the export left out
oleafly convertConverts one file to another format
oleafly typstLists, installs and removes Typst versions
oleafly checkpointLists, compares and copies the app’s checkpoints
CommandWhat it does
oleafly contextMaps the project for a person or an agent
oleafly mcpRuns the MCP server; mcp config sets up a client
oleafly skillsLists the skills and prints where they are
oleafly askAnswers a question about the project
oleafly agentRuns the Oleafly agent on a task
oleafly daemonRuns and controls the helper that keeps tasks going
CommandWhat it does
oleafly checkRuns the Preflight checks
oleafly lintRuns the LaTeX, BibTeX, spelling and grammar checks
CommandWhat it does
oleafly authSigns in to online LaTeX services, Oleafly servers and Git hosts
oleafly remoteImports, links and syncs online projects
oleafly serverWorks with Oleafly servers: projects, sharing, members, comments
CommandWhat it does
oleafly completionsPrints shell completions for bash, zsh, fish, PowerShell or elvish
oleafly manPrints the manual page
oleafly help exit-codesExplains the exit codes
OptionWhat it does
-C followed by a pathRuns the command on another project folder
--jsonPrints one JSON result
--eventsPrints progress as JSON lines before the result
--quietPrints only the result
--logShows none, the tail or the full compiler log
--no-inputNever asks a question
--colorUses color auto, always or never

With --json, every command prints one JSON object: schema_version, ok, command, the command’s own fields and warnings. When a command fails, error holds a kind, a stable code and a message. When they help, it also has a hint, details, and "retryable": true if trying again may work. Check schema_version before you rely on a field.

{
"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 adds one JSON line per progress event before the result.

oleafly help exit-codes prints the same table.

CodeMeaning
0It worked
1Something inside Oleafly went wrong
2The command was used wrongly, or it needs --yes to go ahead
3The project is missing or invalid, or a path points outside it
4A tool or the Oleafly app it needs isn’t installed
5The build failed
6You need to sign in
7The network failed
8Something else holds the project, or a sync has conflicts
9A check found problems
130You pressed Ctrl+C

The command never asks a question without a terminal. --no-input turns questions off too, and so does a CI variable; a command that needs a yes then fails with exit code 2 and asks for --yes. NO_COLOR or --color never turns color off. Paths that would leave the project are refused.

VariableUse
OLEAFLY_DATA_DIROleafly’s data folder, when it isn’t ~/.oleafly
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOCA compiler to use instead of the one Oleafly finds
OLEAFLY_APPThe Oleafly app that oleafly open starts
OLEAFLY_ONLINE_GIT_TOKENA Git token for the online LaTeX service, used instead of a saved one
OLEAFLY_DOWNLOAD_MIRRORWhere downloads such as TinyTeX and Typst come from: automatic, original, or your own mirror’s HTTPS address. See Sources tab
OLEAFLY_TEX_REPOSITORYThe TeX Live repository tlmgr installs packages from
OLEAFLY_CLISet by Oleafly for programs it starts: the command’s full path
CIWhen set, the command never asks a question
NO_COLORWhen set, output has no color
What you seeWhat to try
oleafly isn’t foundOpen a new terminal. Then check with Get-Command oleafly on Windows or command -v oleafly on macOS and Linux, and add the line that Settings shows to your shell profile
oleafly doctor reports a missing engineInstall it with the command doctor prints, or open the project in the app once
latexmk isn’t foundInstall TinyTeX in the app under Settings → Engines → LaTeX → Manage TeX distributions, or install TeX with the command the hint gives. To use the built-in engine instead, run oleafly config set engine tectonic in a project, or oleafly config set latex.default_engine tectonic --global for folders that aren’t projects
A latexmk build stops on a missing .sty or .cls fileWith TeX Live, MacTeX or TinyTeX, the hint gives the tlmgr search and tlmgr install commands. TeX Live installed from Debian, Ubuntu or Fedora packages takes its packages from apt or dnf instead: on Debian and Ubuntu, apt-file search followed by the file name finds the package. MiKTeX gets no hint: install the package in MiKTeX Console, then build again
A build that uses minted or PythonTeX failsoleafly build blocks shell commands. Build the project in the app after you choose Allow external commands, or run latexmk yourself with -shell-escape
A first build times out while packages downloadBuild again. The download picks up where it stopped. --timeout raises the limit
A Typst project asks for a version that isn’t installedRun oleafly typst install followed by that version
An engine is missing on a Linux AppImageThe AppImage’s engines work only in Oleafly’s built-in terminal. Install Tectonic, Typst and Pandoc, or use the .deb or .rpm package
An MCP client can’t start the serverRun the configured command in a terminal, use the full path from oleafly mcp config, and run oleafly doctor
Exit code 6Run oleafly auth status, then sign in again
Exit code 8 during a syncRun the sync again with --resolve for each file it lists
On macOS, Settings says “Move Oleafly to your Applications folder first”Move the app, open it from Applications, then choose Install
Image preview

AI answers couldn’t load

Try again, or search the documentation.