# Ferramenta de linha de comando

Instale o comando oleafly no Windows, no macOS ou no Linux, compile e verifique projetos a partir de um terminal ou da CI, sincronize com um serviço de LaTeX online e conecte agentes de código por meio do servidor MCP e da habilidade dele.

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:

```powershell
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.

```sh
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](/docs/typst/#build-from-the-command-line).

## 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](/docs/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

```sh
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.

```json title="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

```toml title="~/.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.

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "oleafly": {
      "command": "oleafly",
      "args": ["mcp"]
    }
  }
}
```

#### Gemini CLI

```json title="~/.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](/docs/preflight/) 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.

:::caution[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

```sh
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](/docs/collaboration/).

## 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.

```sh
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](/docs/research-tasks/) 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](https://github.com/Oleafly/Oleafly/blob/main/docs/cli.md).

### 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.

```json
{
  "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](/docs/typst/#build-from-the-command-line)
- [Conecte-se via MCP](/docs/mcp/)
- [Agentes de CLI](/docs/cli-agents/)
- [Verificações de pré-submissão](/docs/preflight/)
- [Tarefas de pesquisa](/docs/research-tasks/)