Command-line tool

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.

Install

System	Where the app keeps it	Put oleafly on your PATH
Windows	oleafly-cli.exe next to the app, in %LOCALAPPDATA%\Oleafly for the setup program or C:\Program Files\Oleafly for the MSI package	Install on the Terminal command row in Settings → General copies it to %LOCALAPPDATA%\Oleafly\bin\oleafly.exe and adds that folder to your PATH
macOS	Oleafly.app/Contents/MacOS/oleafly-cli	Install 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-cli	Nothing to do: the package installs /usr/bin/oleafly
Linux AppImage	Inside the AppImage	Install 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.

Windows

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:

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.

macOS

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.

Linux

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.

Check that it works

oleafly version prints the app version and the engines the command would use. oleafly doctor checks the engines, the app, Git, the terminal command and your MCP clients, and prints a fix for anything missing. It works outside a project too.

Build a project

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.

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, -o copies the PDF somewhere else and --timeout sets the limit in seconds.
• 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.
• 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.
• oleafly watch rebuilds every time you save. oleafly log --diagnostics lists errors and warnings with file and line, and oleafly clean removes the build output.

For Typst specifics, see Typst projects.

Use it from a coding agent

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.

The oleafly-cli skill

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.

Connect an agent over MCP

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.

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.

Claude Code

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

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

~/.codex/config.toml

[mcp_servers.oleafly]
command = "oleafly"
args = ["mcp"]
tool_timeout_sec = 300

Cursor

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

~/.cursor/mcp.json

{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"]
    }
  }
}

Gemini CLI

~/.gemini/settings.json

{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"],
      "timeout": 300000
    }
  }
}

Give an agent the whole project

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.

Check a paper before you submit

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.

Sync with an online LaTeX service

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 in

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.

Keep tokens out of your shell history

Tokens go in on standard input, for example oleafly auth login online --with-token < token.txt, never as arguments. In a terminal, the command asks for them without showing what you type. oleafly auth token prints a saved token for scripts, so treat its output like a password.

Import and sync projects

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.

Work with an Oleafly server

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.

Run the Oleafly agent from a terminal

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

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

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.

Command reference

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

Projects and builds

Command	What it does
oleafly open	Opens a folder in the app (oleafly . for the current one)
oleafly init	Makes the current folder a project
oleafly new	Creates a project, from a template if you name one
oleafly templates	Lists templates and shows one
oleafly build	Builds the project
oleafly watch	Rebuilds on every save
oleafly clean	Removes the build output
oleafly log	Shows the last build’s log or its problems
oleafly doctor	Checks engines, the app and your setup
oleafly version	Shows the version and the engines in use
oleafly project info	Shows the project’s settings
oleafly projects list	Lists the app’s projects
oleafly config	Gets and sets project and app settings

Writing and references

Command	What it does
oleafly cite	Prints BibTeX for a DOI, arXiv id, ISBN or PubMed id; --add adds it to the bibliography
oleafly literature	Searches OpenAlex, Semantic Scholar, Crossref, arXiv and PubMed
oleafly bib check	Finds entries that match no real record
oleafly bib clean	Fixes citation keys and removes duplicates; --apply writes the changes
oleafly stats	Counts words, headings, figures and equations
oleafly synctex	Maps a source line to the PDF and back
oleafly export	Exports the document to Word, HTML, Markdown, EPUB and more
oleafly convert	Converts one file to another format
oleafly typst	Lists, installs and removes Typst versions
oleafly checkpoint	Lists, compares and copies the app’s checkpoints

Agents and automation

Command	What it does
oleafly context	Maps the project for a person or an agent
oleafly mcp	Runs the MCP server; mcp config sets up a client
oleafly skills	Lists the skills and prints where they are
oleafly ask	Answers a question about the project
oleafly agent	Runs the Oleafly agent on a task
oleafly daemon	Runs and controls the helper that keeps tasks going

Checks

Command	What it does
oleafly check	Runs the Preflight checks
oleafly lint	Runs the LaTeX, BibTeX, spelling and grammar checks

Accounts and sync

Command	What it does
oleafly auth	Signs in to online LaTeX services, Oleafly servers and Git hosts
oleafly remote	Imports, links and syncs online projects
oleafly server	Works with Oleafly servers: projects, sharing, members, comments

Shell and help

Command	What it does
oleafly completions	Prints shell completions for bash, zsh, fish, PowerShell or elvish
oleafly man	Prints the manual page
oleafly help exit-codes	Explains the exit codes

Options for every command

Option	What it does
-C followed by a path	Runs the command on another project folder
--json	Prints one JSON result
--events	Prints progress as JSON lines before the result
--quiet	Prints only the result
--log	Shows none, the tail or the full compiler log
--no-input	Never asks a question
--color	Uses color auto, always or never

Output for scripts

JSON output

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.

Exit codes

oleafly help exit-codes prints the same table.

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

Questions, color and logs

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.

Environment variables

Variable	Use
OLEAFLY_DATA_DIR	Oleafly’s data folder, when it isn’t ~/.oleafly
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOC	A compiler to use instead of the one Oleafly finds
OLEAFLY_APP	The Oleafly app that oleafly open starts
OLEAFLY_ONLINE_GIT_TOKEN	A Git token for the online LaTeX service, used instead of a saved one
OLEAFLY_CLI	Set by Oleafly for programs it starts: the command’s full path
CI	When set, the command never asks a question
NO_COLOR	When set, output has no color

Troubleshooting

What you see	What to try
oleafly isn’t found	Open 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 engine	Install it with the command doctor prints, or open the project in the app once
An MCP client can’t start the server	Run the configured command in a terminal, use the full path from oleafly mcp config, and run oleafly doctor
Exit code 6	Run oleafly auth status, then sign in again
Exit code 8 during a sync	Run 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

Related pages

• Typst projects
• Connect via MCP
• CLI agents
• Preflight checks
• Research tasks