Ferramenta de linha de comando

O Oleafly traz o oleafly, uma ferramenta de linha de comando que trabalha nos mesmos projetos que o aplicativo. Compile ou verifique um artigo a partir de um terminal, de um script ou da CI. Dê a um agente de código um caminho confiável para o seu projeto. Sincronize com um serviço de LaTeX online ou com um servidor Oleafly, ou rode o agente do Oleafly sem abrir o aplicativo.

Ele vem dentro do aplicativo em todas as plataformas. Esta página cobre os comandos do Oleafly 0.4.8 e posteriores. As versões anteriores tinham menos, então fixe a sua versão do Oleafly nos scripts que dependem disso.

Instalar

Sistema	Onde o aplicativo o guarda	Coloque o oleafly no seu PATH
Windows	oleafly-cli.exe ao lado do aplicativo, em %LOCALAPPDATA%\Oleafly para o programa de instalação ou em C:\Program Files\Oleafly para o pacote MSI	Instalar na linha Comando de terminal em Configurações → Geral o copia para %LOCALAPPDATA%\Oleafly\bin\oleafly.exe e adiciona essa pasta ao seu PATH
macOS	Oleafly.app/Contents/MacOS/oleafly-cli	Instalar na linha Comando de terminal cria um link do oleafly em /usr/local/bin quando você pode gravar lá e, se não, em ~/.local/bin
Pacotes do Linux (.deb, .rpm)	/usr/bin/oleafly-cli	Nada a fazer: o pacote instala /usr/bin/oleafly
AppImage do Linux	Dentro do AppImage	Instalar o copia para ~/.local/bin/oleafly

Os programas que o Oleafly inicia, como o terminal dele e os agentes de CLI, sempre encontram o oleafly no PATH, mesmo antes de você instalá-lo. A variável OLEAFLY_CLI guarda o caminho completo dele.

Windows

1. Abra Configurações → Geral e escolha Instalar na linha Comando de terminal.
2. Abra uma nova janela do PowerShell ou do Prompt de Comando. As janelas que já estavam abertas mantêm o PATH antigo.
3. Confira se funciona:

Get-Command oleafly
oleafly version

Remover, na mesma linha, apaga a cópia e tira a pasta do seu PATH de novo. Quando o Oleafly se atualiza, ele renova a cópia na próxima vez que inicia.

macOS

Mova o Oleafly para a pasta Aplicativos primeiro. Uma cópia que roda a partir da imagem de disco mostra “Primeiro mova o Oleafly para a pasta Aplicativos” no lugar de Instalar.

O comando é um link para o aplicativo, então atualizar o Oleafly atualiza o comando também. Se a pasta não está no seu PATH, a configuração mostra a linha a adicionar ao perfil do seu shell. Confira com command -v oleafly.

Linux

Os pacotes .deb e .rpm colocam o oleafly no seu PATH quando você os instala. oleafly sem nada depois dele abre o aplicativo.

O AppImage precisa de uma cópia, porque os arquivos dentro de um AppImage somem quando ele encerra. Depois que você troca o AppImage por um mais novo, a linha oferece Atualizar. Se ~/.local/bin não está no seu PATH, a configuração mostra a linha a adicionar.

Confira se funciona

oleafly version imprime a versão do aplicativo e os motores que o comando usaria. oleafly doctor confere os motores, o aplicativo, o Git, o comando de terminal e os seus clientes MCP, e imprime uma correção para tudo que estiver faltando. Funciona também fora de um projeto.

Compile um projeto

oleafly . abre a pasta atual no aplicativo. Todos os outros comandos trabalham na pasta em que você está; -C seguido de um caminho os aponta para outro lugar.

cd ~/papers/thesis
oleafly init --engine typst
oleafly build
oleafly log --diagnostics
oleafly -C ~/papers/review --json build

• oleafly init torna a pasta atual um projeto. --engine aceita tectonic, latexmk, typst ou markdown.
• oleafly new seguido de uma pasta, de --template e do id de um modelo cria um projeto a partir de um modelo. oleafly templates list --all lista os modelos.
• oleafly build usa o motor e as configurações do projeto, do mesmo jeito que o aplicativo: o Tectonic, o Typst e o Pandoc que acompanham o Oleafly, ou o LaTeX que você instalou. --main compila outro documento do projeto, --compiler escolhe o compilador LaTeX para projetos latexmk, -o copia o PDF para outro lugar e --timeout define o limite em segundos.
• Uma pasta que você abriu no próprio local, no aplicativo, compila com o motor e o documento principal que você escolheu lá, na pasta de compilação do próprio aplicativo.
• O aplicativo e o comando nunca compilam o mesmo projeto ao mesmo tempo: o segundo espera o primeiro. Uma compilação que falha mantém o último PDF bom.
• oleafly watch recompila a cada vez que você salva. oleafly log --diagnostics lista erros e avisos com arquivo e linha, e oleafly clean remove a saída da compilação.

Para os detalhes do Typst, veja Projetos Typst.

Use a partir de um agente de código

Os agentes de código trabalham melhor com três coisas que o comando dá a eles: oleafly context para o mapa do projeto, --json para resultados que eles conseguem ler e códigos de saída que dizem o que deu errado. Há três maneiras de conectar um agente.

A habilidade oleafly-cli

O Oleafly traz uma habilidade chamada oleafly-cli. Ela ensina a um agente os comandos, a saída JSON, os códigos de saída e o ciclo que funciona melhor: ler o contexto, editar, compilar, ler os diagnósticos e corrigir o primeiro erro.

No terminal do Oleafly e nos agentes de CLI que ele inicia, escolha a habilidade como qualquer outra. Para um agente que você executa por conta própria, ligue Configurações → Assistente de IA → Habilidades → Compartilhar habilidades com outros agentes deste computador. O Oleafly então vincula as suas habilidades, a oleafly-cli inclusa, às pastas que outros agentes de código leem, como ~/.claude/skills, ~/.codex/skills e ~/.agents/skills. oleafly skills path imprime onde as habilidades estão, para agentes que leem outra pasta.

Conecte um agente por MCP

oleafly mcp é um servidor MCP que conversa por entrada e saída padrão. Quando o aplicativo está com o seu projeto aberto, ele repassa as chamadas ao servidor MCP do próprio aplicativo, então o agente recebe todas as ferramentas do aplicativo e os seus pedidos de aprovação. Caso contrário, ele funciona sozinho, com ferramentas de leitura (status do projeto, o mapa do projeto, arquivos, busca, logs, o relatório do doctor, consulta de citações) e compile. Não há URL nem token para copiar e nenhum Node.js para instalar.

A configuração mais rápida é oleafly mcp config --client seguido de claude-code, claude-desktop, codex, cursor ou gemini. Ele imprime a entrada para esse cliente; acrescente --write para que ela seja adicionada para você, com um backup do arquivo do cliente. Reinicie ou reconecte o cliente depois. Dentro de um projeto, ele grava nas configurações do projeto; fora dele, grava nas suas configurações de usuário, com o caminho completo do comando, porque os aplicativos que você inicia pela área de trabalho podem não enxergar o seu PATH.

Claude Code

claude mcp add --scope user oleafly -- oleafly mcp

Dentro de um projeto, oleafly mcp config --client claude-code --write adiciona o servidor ao .mcp.json do projeto no lugar.

Claude Desktop

O Claude Desktop inicia servidores sem uma pasta de projeto, então a entrada dele sempre funciona por meio do aplicativo: mantenha o Oleafly aberto com o seu projeto. Use o caminho completo do oleafly. No Windows, dobre cada barra invertida do caminho.

claude_desktop_config.json

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

O arquivo fica em ~/Library/Application Support/Claude no macOS e em %APPDATA%\Claude no Windows.

Codex

~/.codex/config.toml

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

Cursor

Use ~/.cursor/mcp.json para todos os projetos, ou .cursor/mcp.json dentro de um projeto.

~/.cursor/mcp.json

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

Gemini CLI

~/.gemini/settings.json

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

Dê o projeto inteiro a um agente

oleafly context mapeia o projeto: os arquivos, o esboço, os rótulos, as citações, os arquivos ausentes, as referências não resolvidas e os problemas da última compilação. --format md dá um texto para colar em um prompt; --format json dá o mesmo mapa para um programa.

Verifique um artigo antes de submeter

oleafly check roda as verificações de pré-submissão no projeto, com os mesmos resultados do painel de Pré-verificação: referências, citações, rótulos, arquivos ausentes, campos da bibliografia, figuras e anonimato para revisão cega. As verificações que precisam do PDF compilado usam a última compilação.

oleafly lint roda as verificações de LaTeX e BibTeX e, nos builds que os incluem, ortografia e gramática. --fix aplica as correções que são seguras de aplicar.

Os dois aceitam --format human, json ou sarif, e --exit-code faz com que saiam com 9 quando encontram problemas. O SARIF funciona com serviços de varredura de código, como o do GitHub: grave o relatório com oleafly check --format sarif -o preflight.sarif, envie-o com a ação upload-sarif e cada achado aparece na própria linha no pull request.

Sincronize com um serviço de LaTeX online

oleafly remote baixa projetos da sua conta de um serviço de LaTeX online e mantém uma pasta sincronizada com um deles, com a mesma mesclagem que o aplicativo usa.

Faça login

Os logins ficam no armazenamento criptografado do aplicativo, então um login feito no aplicativo vale na linha de comando e vice-versa.

• oleafly auth login online --with-token salva um token do Git das configurações da conta do serviço. Vincular e sincronizar exigem um.
• oleafly auth login online --from-browser firefox copia o seu login de um navegador deste computador, para listar e baixar projetos. O Firefox funciona em todos os sistemas; o Chrome, o Edge e o Brave funcionam no macOS. --cookie-stdin lê um cookie de sessão no lugar.
• oleafly auth login git --host https://gitlab.com salva um token para um host Git.
• oleafly auth status lista todos os logins e de onde vieram, sem mostrar nenhum segredo.
• oleafly auth logout remove um login.

Mantenha os tokens fora do histórico do seu shell

Os tokens entram pela entrada padrão, por exemplo oleafly auth login online --with-token < token.txt, nunca como argumentos. Em um terminal, o comando os pede sem mostrar o que você digita. oleafly auth token imprime um token salvo para scripts, então trate a saída dele como uma senha.

Importe e sincronize projetos

oleafly remote list
oleafly remote import 64a1f0c2e5b7 --into ~/papers
cd ~/papers/thesis
oleafly remote link
oleafly remote sync

• oleafly remote import baixa projetos para pastas novas. Funciona com qualquer conta.
• oleafly remote link conecta uma pasta ao projeto online dela pela integração com Git do serviço, que exige um token do Git.
• oleafly remote sync mescla as mudanças online na pasta e envia as suas. --dry-run mostra o que mudaria e --no-push mescla sem enviar.
• Quando um arquivo mudou nos dois lados, a sincronização não grava nada e sai com 8. Rode de novo com --resolve e o caminho do arquivo seguido de =local ou =remote para cada arquivo.
• oleafly remote diff mostra o que difere; com --exit-code, sai com 9 quando há arquivos diferentes e com 8 quando há conflito. --latexdiff --pdf gera um PDF marcado com as suas alterações, usando o latexdiff da sua distribuição TeX.
• oleafly remote status, oleafly remote unlink e oleafly remote open mostram o vínculo, o removem e abrem o projeto no seu navegador.

Trabalhe com um servidor Oleafly

oleafly server sign-in seguido do endereço do servidor conecta a linha de comando com um código que você aprova no navegador. A linha de comando é um dispositivo próprio no servidor, separado do aplicativo.

• oleafly server status e oleafly server projects mostram os seus servidores e os projetos compartilhados.
• oleafly server share mostra o link de um projeto e liga ou desliga o compartilhamento por link e os comentários.
• oleafly server members lista as pessoas de um projeto e as adiciona, remove ou altera. Só o dono pode mudar o compartilhamento e os membros.
• oleafly server comments lista, adiciona, responde e resolve comentários. Um comentário que não pode ser enviado na hora é guardado e enviado da próxima vez.

Compartilhar um projeto pela primeira vez acontece no aplicativo. Veja Colaboração ao vivo.

Execute o agente do Oleafly em um terminal

oleafly ask responde a uma pergunta sobre o projeto sem alterar nada. oleafly agent run executa uma tarefa.

oleafly ask "Which sections cite Smith 2021?"
oleafly agent run --allow write "Fix the overfull boxes in chapter 3"

• O agente sempre pode ler o projeto. --allow acrescenta write, commands ou network, e ele recusa tudo o que você não permitiu. Ele nunca para para fazer uma pergunta.
• As alterações vão primeiro para uma pasta de revisão em .oleafly/agent-runs/. oleafly agent apply seguido dessa pasta as grava no projeto, e --apply na execução as grava de imediato.
• O provedor, o modelo e o esforço vêm das configurações do aplicativo, ou de --provider, --model e --effort. A chave vem da variável de ambiente do próprio provedor, como ANTHROPIC_API_KEY, ou do armazenamento criptografado do aplicativo.
• --json imprime um resultado quando a execução termina, e --events acrescenta uma linha JSON para cada evento enquanto ele trabalha.

Mantenha as tarefas de pesquisa rodando depois de sair

Marque uma tarefa de pesquisa com Continuar rodando com o Oleafly fechado. Quando você sai, um pequeno processo auxiliar em segundo plano assume essas tarefas e as execuções dos experimentos continuam. Uma etapa que precisa da sua aprovação pausa a tarefa e envia uma notificação. Quando você abre o Oleafly de novo, ele retoma as tarefas e mostra o que aconteceu. Desligue isto, ou inicie o processo auxiliar quando você entrar na sessão, em Configurações → Pesquisa → Tarefas em segundo plano. oleafly daemon status mostra o que o processo auxiliar está fazendo.

Referência de comandos

Cada comando explica as suas opções com --help. A referência completa está no repositório: docs/cli.md (abre em uma nova guia).

Projetos e compilações

Comando	O que faz
oleafly open	Abre uma pasta no aplicativo (oleafly . para a atual)
oleafly init	Torna a pasta atual um projeto
oleafly new	Cria um projeto, a partir de um modelo se você nomear um
oleafly templates	Lista os modelos e mostra um
oleafly build	Compila o projeto
oleafly watch	Recompila a cada salvamento
oleafly clean	Remove a saída da compilação
oleafly log	Mostra o log da última compilação ou os problemas dela
oleafly doctor	Confere os motores, o aplicativo e a sua configuração
oleafly version	Mostra a versão e os motores em uso
oleafly project info	Mostra as configurações do projeto
oleafly projects list	Lista os projetos do aplicativo
oleafly config	Lê e define configurações do projeto e do aplicativo

Escrita e referências

Comando	O que faz
oleafly cite	Imprime BibTeX para um DOI, um id do arXiv, um ISBN ou um id do PubMed; --add o adiciona à bibliografia
oleafly literature	Busca no OpenAlex, no Semantic Scholar, no Crossref, no arXiv e no PubMed
oleafly bib check	Encontra entradas que não correspondem a nenhum registro real
oleafly bib clean	Corrige chaves de citação e remove duplicatas; --apply grava as alterações
oleafly stats	Conta palavras, títulos, figuras e equações
oleafly synctex	Mapeia uma linha do código-fonte para o PDF e de volta
oleafly export	Exporta o documento para Word, HTML, Markdown, EPUB e mais
oleafly convert	Converte um arquivo para outro formato
oleafly typst	Lista, instala e remove versões do Typst
oleafly checkpoint	Lista, compara e copia os pontos de verificação do aplicativo

Agentes e automação

Comando	O que faz
oleafly context	Mapeia o projeto para uma pessoa ou um agente
oleafly mcp	Roda o servidor MCP; mcp config configura um cliente
oleafly skills	Lista as habilidades e imprime onde elas estão
oleafly ask	Responde a uma pergunta sobre o projeto
oleafly agent	Roda o agente do Oleafly em uma tarefa
oleafly daemon	Roda e controla o processo auxiliar que mantém as tarefas em andamento

Verificações

Comando	O que faz
oleafly check	Roda as verificações da Pré-verificação
oleafly lint	Roda as verificações de LaTeX, BibTeX, ortografia e gramática

Contas e sincronização

Comando	O que faz
oleafly auth	Faz login em serviços de LaTeX online, servidores Oleafly e hosts Git
oleafly remote	Importa, vincula e sincroniza projetos online
oleafly server	Trabalha com servidores Oleafly: projetos, compartilhamento, membros, comentários

Shell e ajuda

Comando	O que faz
oleafly completions	Imprime os autocompletares do shell para bash, zsh, fish, PowerShell ou elvish
oleafly man	Imprime a página de manual
oleafly help exit-codes	Explica os códigos de saída

Opções de todos os comandos

Opção	O que faz
-C seguido de um caminho	Roda o comando em outra pasta de projeto
--json	Imprime um resultado JSON
--events	Imprime o progresso como linhas JSON antes do resultado
--quiet	Imprime só o resultado
--log	Mostra o log do compilador: none, o tail ou o full
--no-input	Nunca faz uma pergunta
--color	Usa cor auto, always ou never

Saída para scripts

Saída JSON

Com --json, cada comando imprime um objeto JSON: schema_version, ok, command, os campos do próprio comando e warnings. Quando um comando falha, error traz um kind, um code estável e uma message. Quando ajudam, ele traz também um hint, details e "retryable": true se tentar de novo puder funcionar. Confira schema_version antes de depender de um campo.

{
  "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 acrescenta uma linha JSON por evento de progresso antes do resultado.

Códigos de saída

oleafly help exit-codes imprime a mesma tabela.

Código	Significado
0	Funcionou
1	Algo deu errado dentro do Oleafly
2	O comando foi usado de forma errada, ou precisa de --yes para prosseguir
3	O projeto está ausente ou é inválido, ou um caminho aponta para fora dele
4	Uma ferramenta ou o aplicativo Oleafly de que ele precisa não está instalado
5	A compilação falhou
6	Você precisa fazer login
7	A rede falhou
8	Outra coisa está usando o projeto, ou uma sincronização tem conflitos
9	Uma verificação encontrou problemas
130	Você pressionou Ctrl+C

Perguntas, cor e logs

O comando nunca faz uma pergunta sem um terminal. --no-input também desliga as perguntas, e uma variável CI também; um comando que precisa de um sim então falha com o código de saída 2 e pede --yes. NO_COLOR ou --color never desliga a cor. Caminhos que sairiam do projeto são recusados.

Variáveis de ambiente

Variável	Uso
OLEAFLY_DATA_DIR	A pasta de dados do Oleafly, quando não é ~/.oleafly
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOC	Um compilador a usar no lugar do que o Oleafly encontra
OLEAFLY_APP	O aplicativo Oleafly que oleafly open inicia
OLEAFLY_ONLINE_GIT_TOKEN	Um token do Git para o serviço de LaTeX online, usado no lugar de um salvo
OLEAFLY_CLI	Definida pelo Oleafly para os programas que ele inicia: o caminho completo do comando
CI	Quando definida, o comando nunca faz uma pergunta
NO_COLOR	Quando definida, a saída não tem cor

Solução de problemas

O que você vê	O que tentar
oleafly não é encontrado	Abra um novo terminal. Depois confira com Get-Command oleafly no Windows ou command -v oleafly no macOS e no Linux, e adicione ao perfil do seu shell a linha que as Configurações mostram
oleafly doctor informa um motor ausente	Instale-o com o comando que o doctor imprime, ou abra o projeto no aplicativo uma vez
Um cliente MCP não consegue iniciar o servidor	Execute o comando configurado em um terminal, use o caminho completo de oleafly mcp config e rode oleafly doctor
Código de saída 6	Rode oleafly auth status e faça login de novo
Código de saída 8 durante uma sincronização	Rode a sincronização de novo com --resolve para cada arquivo que ela lista
No macOS, as Configurações dizem “Primeiro mova o Oleafly para a pasta Aplicativos”	Mova o aplicativo, abra-o a partir de Aplicativos e depois escolha Instalar

Páginas relacionadas

• Projetos Typst
• Conecte-se via MCP
• Agentes de CLI
• Verificações de pré-submissão
• Tarefas de pesquisa