# Herramienta de línea de comandos

Instala el comando oleafly en Windows, macOS o Linux, compila y revisa proyectos desde un terminal o CI, sincroniza con un servicio de LaTeX en línea y conecta agentes de programación mediante su servidor MCP y su habilidad.

Oleafly incluye `oleafly`, una herramienta de línea de comandos que trabaja sobre los mismos proyectos que la app. Compila o revisa un artículo desde un terminal, un script o CI. Dale a un agente de programación una entrada fiable a tu proyecto. Sincroniza con un servicio de LaTeX en línea o con un servidor de Oleafly, o ejecuta el agente de Oleafly sin abrir la app.

Viene dentro de la app en todas las plataformas. Esta página trata los comandos de Oleafly 0.4.8 y posteriores. Las versiones anteriores tenían menos, así que fija tu versión de Oleafly en los scripts que dependan de ella.

## Instalación

| Sistema | Dónde lo guarda la app | Pon `oleafly` en tu PATH |
|---|---|---|
| Windows | `oleafly-cli.exe` junto a la app, en `%LOCALAPPDATA%\Oleafly` con el programa de instalación o en `C:\Program Files\Oleafly` con el paquete MSI | **Instalar** en la fila **Comando de terminal** de **Ajustes → General** lo copia en `%LOCALAPPDATA%\Oleafly\bin\oleafly.exe` y añade esa carpeta a tu PATH |
| macOS | `Oleafly.app/Contents/MacOS/oleafly-cli` | **Instalar** en la fila **Comando de terminal** enlaza `oleafly` en `/usr/local/bin` cuando puedes escribir ahí y, si no, en `~/.local/bin` |
| Paquetes de Linux (.deb, .rpm) | `/usr/bin/oleafly-cli` | No hay nada que hacer: el paquete instala `/usr/bin/oleafly` |
| AppImage de Linux | Dentro del AppImage | **Instalar** lo copia en `~/.local/bin/oleafly` |

Los programas que inicia Oleafly, como su propio terminal y los agentes de línea de comandos, siempre encuentran `oleafly` en su PATH, incluso antes de que lo instales. La variable `OLEAFLY_CLI` contiene su ruta completa.

### Windows

1. Abre **Ajustes → General** y elige **Instalar** en la fila **Comando de terminal**.
2. Abre una ventana nueva de PowerShell o del Símbolo del sistema. Las ventanas que ya estaban abiertas conservan el PATH anterior.
3. Comprueba que funciona:

```powershell
Get-Command oleafly
oleafly version
```

**Quitar** en la misma fila elimina la copia y vuelve a quitar la carpeta de tu PATH. Cuando Oleafly se actualiza, refresca la copia la próxima vez que se inicia.

### macOS

Primero mueve Oleafly a la carpeta Aplicaciones. Una copia que se ejecuta desde la imagen de disco muestra «Primero mueve Oleafly a la carpeta Aplicaciones» en lugar de **Instalar**.

El comando es un enlace a la app, así que al actualizar Oleafly también se actualiza el comando. Si la carpeta no está en tu PATH, la fila muestra la línea que debes añadir al perfil de tu shell. Compruébalo con `command -v oleafly`.

### Linux

Los paquetes .deb y .rpm ponen `oleafly` en tu PATH al instalarlos. `oleafly` sin nada detrás abre la app.

El AppImage necesita una copia, porque los archivos de dentro de un AppImage desaparecen cuando se cierra. Después de sustituir el AppImage por uno más reciente, la fila ofrece **Actualizar**. Si `~/.local/bin` no está en tu PATH, la fila muestra la línea que debes añadir.

### Comprueba que funciona

`oleafly version` imprime la versión de la app y los motores que usaría el comando. `oleafly doctor` comprueba los motores, la app, Git, el comando de terminal y tus clientes MCP, e imprime una solución para lo que falte. Funciona también fuera de un proyecto.

## Compila un proyecto

`oleafly .` abre la carpeta actual en la app. Cualquier otro comando trabaja sobre la carpeta en la que estás; `-C` seguido de una ruta lo dirige a otra.

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

- `oleafly init` convierte la carpeta actual en un proyecto. `--engine` admite `tectonic`, `latexmk`, `typst` o `markdown`.
- `oleafly new` seguido de una carpeta, de `--template` y del id de una plantilla crea un proyecto a partir de una plantilla. `oleafly templates list --all` enumera las plantillas.
- `oleafly build` usa el motor y los ajustes del proyecto, igual que la app: el Tectonic, el Typst y el Pandoc que vienen con Oleafly, o el LaTeX que instalaste. `--main` compila otro documento del proyecto, `--compiler` elige el compilador de LaTeX para los proyectos de latexmk, `-o` copia el PDF a otro sitio y `--timeout` fija el límite en segundos.
- Una carpeta que abriste en su sitio en la app se compila con el motor y el documento principal que elegiste allí, en la propia carpeta de compilación de la app.
- La app y el comando nunca compilan el mismo proyecto a la vez: el segundo espera al primero. Una compilación fallida conserva el último PDF correcto.
- `oleafly watch` recompila cada vez que guardas. `oleafly log --diagnostics` enumera los errores y las advertencias con su archivo y su línea, y `oleafly clean` elimina la salida de la compilación.

Para los detalles de Typst, consulta [Proyectos de Typst](/docs/typst/#build-from-the-command-line).

## Úsalo desde un agente de programación

Los agentes de programación trabajan mejor con tres cosas que les da el comando: `oleafly context` para el mapa del proyecto, `--json` para resultados que puedan leer y códigos de salida que dicen qué fue mal. Hay tres formas de conectar un agente.

### La habilidad oleafly-cli

Oleafly incluye una habilidad llamada `oleafly-cli`. Enseña a un agente los comandos, la salida JSON y los códigos de salida, y el ciclo que mejor funciona: leer el contexto, editar, compilar, leer los diagnósticos y corregir el primer error.

En el terminal de Oleafly y en los agentes de línea de comandos que inicia, elige la habilidad como cualquier otra. Para un agente que ejecutas por tu cuenta, activa **Ajustes → Asistente de IA → Habilidades → Compartir las habilidades con otros agentes de este equipo**. Oleafly enlaza entonces sus habilidades, `oleafly-cli` incluida, en las carpetas que leen otros agentes de programación, como `~/.claude/skills`, `~/.codex/skills` y `~/.agents/skills`. `oleafly skills path` imprime dónde están las habilidades, para los agentes que leen otra carpeta.

### Conecta un agente mediante MCP

`oleafly mcp` es un servidor MCP que se comunica por la entrada y la salida estándar. Cuando la app tiene tu proyecto abierto, pasa las llamadas al [servidor MCP](/docs/mcp/) de la propia app, de modo que el agente recibe todas las herramientas de la app y tus avisos de aprobación. Si no, funciona por su cuenta, con herramientas de lectura (estado del proyecto, mapa del proyecto, archivos, búsqueda, registros, informe de doctor, consulta de citas) y `compile`. No hay ninguna URL ni ningún token que copiar, ni Node.js que instalar.

La configuración más rápida es `oleafly mcp config --client` seguido de `claude-code`, `claude-desktop`, `codex`, `cursor` o `gemini`. Imprime la entrada para ese cliente; añade `--write` para que la añada por ti, con una copia de seguridad del archivo del cliente. Reinicia o vuelve a conectar el cliente después. Dentro de un proyecto escribe los ajustes del proyecto; fuera de uno escribe tus ajustes de usuario, con la ruta completa del comando, porque las apps que inicias desde el escritorio pueden no ver tu PATH.

#### Claude Code

```sh
claude mcp add --scope user oleafly -- oleafly mcp
```

Dentro de un proyecto, `oleafly mcp config --client claude-code --write` añade el servidor al `.mcp.json` del proyecto en su lugar.

#### Claude Desktop

Claude Desktop inicia los servidores sin una carpeta de proyecto, así que su entrada siempre trabaja a través de la app: mantén Oleafly abierto con tu proyecto. Usa la ruta completa de `oleafly`. En Windows, duplica cada barra invertida de la ruta.

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

El archivo está en `~/Library/Application Support/Claude` en macOS y en `%APPDATA%\Claude` en Windows.

#### Codex

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

#### Cursor

Usa `~/.cursor/mcp.json` para todos los proyectos, o `.cursor/mcp.json` dentro de uno solo.

```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
    }
  }
}
```

### Dale a un agente todo el proyecto

`oleafly context` traza el mapa del proyecto: sus archivos, su esquema, las etiquetas, las citas, los archivos que faltan, las referencias sin resolver y los problemas de la última compilación. `--format md` da texto para pegar en un prompt; `--format json` da el mismo mapa para un programa.

## Revisa un artículo antes de enviarlo

`oleafly check` ejecuta las [comprobaciones de Preflight](/docs/preflight/) en el proyecto, con los mismos resultados que el panel de Preflight: referencias, citas, etiquetas, archivos que faltan, campos de la bibliografía, figuras y anonimato para la revisión ciega. Las comprobaciones que necesitan el PDF compilado usan la última compilación.

`oleafly lint` ejecuta las comprobaciones de LaTeX y BibTeX y, en las compilaciones que lo incluyen, la ortografía y la gramática. `--fix` aplica las correcciones que es seguro aplicar.

Los dos admiten `--format human`, `json` o `sarif`, y `--exit-code` hace que terminen con 9 cuando encuentran problemas. SARIF funciona con servicios de análisis de código como el de GitHub: escribe el informe con `oleafly check --format sarif -o preflight.sarif`, súbelo con la acción `upload-sarif` y cada hallazgo aparece en su línea en el pull request.

## Sincroniza con un servicio de LaTeX en línea

`oleafly remote` descarga proyectos de tu cuenta del servicio de LaTeX en línea y mantiene una carpeta sincronizada con uno, con la misma fusión que usa la app.

### Inicia sesión

Los inicios de sesión viven en el almacén cifrado de la app, así que un inicio de sesión hecho en la app funciona en la línea de comandos y al revés.

- `oleafly auth login online --with-token` guarda un token de Git de los ajustes de la cuenta del servicio. Para enlazar y sincronizar hace falta uno.
- `oleafly auth login online --from-browser firefox` copia tu inicio de sesión de un navegador de este ordenador, para enumerar y descargar proyectos. Firefox funciona en todos los sistemas; Chrome, Edge y Brave funcionan en macOS. `--cookie-stdin` lee en su lugar una cookie de sesión.
- `oleafly auth login git --host https://gitlab.com` guarda un token para un host de Git.
- `oleafly auth status` enumera todos los inicios de sesión y de dónde vienen, sin mostrar ningún secreto.
- `oleafly auth logout` elimina un inicio de sesión.

:::caution[Evita que los tokens queden en el historial del shell]
Los tokens se introducen por la entrada estándar, por ejemplo `oleafly auth login online --with-token < token.txt`, nunca como argumentos. En un terminal, el comando los pide sin mostrar lo que escribes. `oleafly auth token` imprime un token guardado para los scripts, así que trata su salida como una contraseña.
:::

### Importa y sincroniza proyectos

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

- `oleafly remote import` descarga proyectos en carpetas nuevas. Funciona con cualquier cuenta.
- `oleafly remote link` conecta una carpeta con su proyecto en línea mediante la integración de Git del servicio, que necesita un token de Git.
- `oleafly remote sync` fusiona los cambios en línea en la carpeta y envía los tuyos. `--dry-run` muestra qué cambiaría y `--no-push` fusiona sin enviar.
- Cuando un archivo cambió en los dos lados, la sincronización no escribe nada y termina con 8. Vuelve a ejecutarla con `--resolve` y la ruta del archivo seguida de `=local` o `=remote` para cada archivo.
- `oleafly remote diff` muestra qué difiere; con `--exit-code` termina con 9 cuando los archivos difieren y con 8 cuando entran en conflicto. `--latexdiff --pdf` genera un PDF marcado con tus cambios, con el latexdiff de tu distribución de TeX.
- `oleafly remote status`, `oleafly remote unlink` y `oleafly remote open` muestran el enlace, lo eliminan y abren el proyecto en tu navegador.

## Trabaja con un servidor de Oleafly

`oleafly server sign-in` seguido de la dirección del servidor inicia sesión en la línea de comandos con un código que apruebas en tu navegador. La línea de comandos es un dispositivo propio en el servidor, distinto de la app.

- `oleafly server status` y `oleafly server projects` muestran tus servidores y los proyectos compartidos.
- `oleafly server share` muestra el enlace de un proyecto y activa o desactiva el uso compartido por enlace y los comentarios.
- `oleafly server members` enumera a las personas de un proyecto y las añade, las quita o las cambia. Solo el propietario puede cambiar el uso compartido y los miembros.
- `oleafly server comments` enumera, añade, responde y resuelve comentarios. Un comentario que no se puede enviar enseguida se guarda y se envía la próxima vez.

Compartir un proyecto por primera vez se hace en la app. Consulta [Colaboración en tiempo real](/docs/collaboration/).

## Ejecuta el agente de Oleafly desde un terminal

`oleafly ask` responde una pregunta sobre el proyecto sin cambiar nada. `oleafly agent run` hace una tarea.

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

- El agente siempre puede leer el proyecto. `--allow` añade `write`, `commands` o `network`, y rechaza todo lo que no permitiste. Nunca se detiene a hacer una pregunta.
- Los cambios van primero a una carpeta de revisión en `.oleafly/agent-runs/`. `oleafly agent apply` seguido de esa carpeta los escribe en el proyecto, y `--apply` en la ejecución los escribe de inmediato.
- El proveedor, el modelo y el esfuerzo vienen de los ajustes de la app, o de `--provider`, `--model` y `--effort`. La clave viene de la variable de entorno del propio proveedor, como `ANTHROPIC_API_KEY`, o del almacén cifrado de la app.
- `--json` imprime un único resultado cuando termina la ejecución, y `--events` añade una línea JSON por cada evento mientras trabaja.

### Mantén las tareas de investigación en marcha después de salir

Marca una [tarea de investigación](/docs/research-tasks/) con **Seguir ejecutándose con Oleafly cerrado**. Cuando sales, un pequeño ayudante en segundo plano se hace cargo de esas tareas y sus ejecuciones de experimentos siguen adelante. Un paso que necesita tu aprobación pausa la tarea y envía una notificación. Cuando vuelves a abrir Oleafly, recupera las tareas y muestra lo que pasó. Desactiva esto, o inicia el ayudante cuando inicies sesión, en **Ajustes → Investigación → Tareas en segundo plano**. `oleafly daemon status` muestra lo que está haciendo el ayudante.

## Referencia de comandos

Cada comando explica sus opciones con `--help`. La referencia completa está en el repositorio: [docs/cli.md](https://github.com/Oleafly/Oleafly/blob/main/docs/cli.md).

### Proyectos y compilaciones

| Comando | Qué hace |
|---|---|
| `oleafly open` | Abre una carpeta en la app (`oleafly .` para la actual) |
| `oleafly init` | Convierte la carpeta actual en un proyecto |
| `oleafly new` | Crea un proyecto, a partir de una plantilla si indicas una |
| `oleafly templates` | Enumera las plantillas y muestra una |
| `oleafly build` | Compila el proyecto |
| `oleafly watch` | Recompila en cada guardado |
| `oleafly clean` | Elimina la salida de la compilación |
| `oleafly log` | Muestra el registro de la última compilación o sus problemas |
| `oleafly doctor` | Comprueba los motores, la app y tu configuración |
| `oleafly version` | Muestra la versión y los motores en uso |
| `oleafly project info` | Muestra los ajustes del proyecto |
| `oleafly projects list` | Enumera los proyectos de la app |
| `oleafly config` | Lee y define los ajustes del proyecto y de la app |

### Escritura y referencias

| Comando | Qué hace |
|---|---|
| `oleafly cite` | Imprime BibTeX para un DOI, un id de arXiv, un ISBN o un id de PubMed; `--add` lo añade a la bibliografía |
| `oleafly literature` | Busca en OpenAlex, Semantic Scholar, Crossref, arXiv y PubMed |
| `oleafly bib check` | Encuentra entradas que no coinciden con ningún registro real |
| `oleafly bib clean` | Corrige las claves de cita y elimina duplicados; `--apply` escribe los cambios |
| `oleafly stats` | Cuenta palabras, títulos, figuras y ecuaciones |
| `oleafly synctex` | Lleva una línea del código al PDF y al revés |
| `oleafly export` | Exporta el documento a Word, HTML, Markdown, EPUB y más |
| `oleafly convert` | Convierte un archivo a otro formato |
| `oleafly typst` | Enumera, instala y quita versiones de Typst |
| `oleafly checkpoint` | Enumera, compara y copia los puntos de control de la app |

### Agentes y automatización

| Comando | Qué hace |
|---|---|
| `oleafly context` | Traza el mapa del proyecto para una persona o un agente |
| `oleafly mcp` | Ejecuta el servidor MCP; `mcp config` configura un cliente |
| `oleafly skills` | Enumera las habilidades e imprime dónde están |
| `oleafly ask` | Responde una pregunta sobre el proyecto |
| `oleafly agent` | Ejecuta el agente de Oleafly en una tarea |
| `oleafly daemon` | Ejecuta y controla el ayudante que mantiene las tareas en marcha |

### Comprobaciones

| Comando | Qué hace |
|---|---|
| `oleafly check` | Ejecuta las comprobaciones de Preflight |
| `oleafly lint` | Ejecuta las comprobaciones de LaTeX, BibTeX, ortografía y gramática |

### Cuentas y sincronización

| Comando | Qué hace |
|---|---|
| `oleafly auth` | Inicia sesión en servicios de LaTeX en línea, servidores de Oleafly y hosts de Git |
| `oleafly remote` | Importa, enlaza y sincroniza proyectos en línea |
| `oleafly server` | Trabaja con servidores de Oleafly: proyectos, uso compartido, miembros, comentarios |

### Shell y ayuda

| Comando | Qué hace |
|---|---|
| `oleafly completions` | Imprime el autocompletado de shell para bash, zsh, fish, PowerShell o elvish |
| `oleafly man` | Imprime la página del manual |
| `oleafly help exit-codes` | Explica los códigos de salida |

### Opciones de todos los comandos

| Opción | Qué hace |
|---|---|
| `-C` seguido de una ruta | Ejecuta el comando en otra carpeta de proyecto |
| `--json` | Imprime un único resultado JSON |
| `--events` | Imprime el progreso como líneas JSON antes del resultado |
| `--quiet` | Imprime solo el resultado |
| `--log` | Muestra el registro del compilador: `none`, el `tail` o el `full` |
| `--no-input` | Nunca hace una pregunta |
| `--color` | Usa color `auto`, `always` o `never` |

## Salida para scripts

### Salida JSON

Con `--json`, cada comando imprime un único objeto JSON: `schema_version`, `ok`, `command`, los campos propios del comando y `warnings`. Cuando un comando falla, `error` contiene un `kind`, un `code` estable y un `message`. Cuando ayudan, también incluye un `hint`, `details` y `"retryable": true` si volver a intentarlo puede funcionar. Comprueba `schema_version` antes de fiarte de un 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` añade una línea JSON por cada evento de progreso antes del resultado.

### Códigos de salida

`oleafly help exit-codes` imprime la misma tabla.

| Código | Significado |
|---|---|
| 0 | Funcionó |
| 1 | Algo falló dentro de Oleafly |
| 2 | El comando se usó mal, o necesita `--yes` para seguir adelante |
| 3 | Falta el proyecto o no es válido, o una ruta apunta fuera de él |
| 4 | No está instalada una herramienta o la app de Oleafly que necesita |
| 5 | La compilación falló |
| 6 | Tienes que iniciar sesión |
| 7 | La red falló |
| 8 | Otra cosa tiene bloqueado el proyecto, o una sincronización tiene conflictos |
| 9 | Una comprobación encontró problemas |
| 130 | Pulsaste Ctrl+C |

### Preguntas, color y registros

El comando nunca hace una pregunta sin un terminal. `--no-input` también desactiva las preguntas, y lo mismo hace una variable `CI`; un comando que necesita un sí falla entonces con el código de salida 2 y pide `--yes`. `NO_COLOR` o `--color never` desactiva el color. Se rechazan las rutas que saldrían del proyecto.

### Variables de entorno

| Variable | Uso |
|---|---|
| `OLEAFLY_DATA_DIR` | La carpeta de datos de Oleafly, cuando no es `~/.oleafly` |
| `OLEAFLY_TECTONIC`, `OLEAFLY_LATEXMK`, `OLEAFLY_TYPST`, `OLEAFLY_PANDOC` | Un compilador que se usa en lugar del que encuentra Oleafly |
| `OLEAFLY_APP` | La app de Oleafly que inicia `oleafly open` |
| `OLEAFLY_ONLINE_GIT_TOKEN` | Un token de Git para el servicio de LaTeX en línea, que se usa en lugar de uno guardado |
| `OLEAFLY_CLI` | La define Oleafly para los programas que inicia: la ruta completa del comando |
| `CI` | Cuando está definida, el comando nunca hace una pregunta |
| `NO_COLOR` | Cuando está definida, la salida no lleva color |

## Solución de problemas

| Qué ves | Qué probar |
|---|---|
| No se encuentra `oleafly` | Abre un terminal nuevo. Después comprueba con `Get-Command oleafly` en Windows o `command -v oleafly` en macOS y Linux, y añade al perfil de tu shell la línea que muestran los Ajustes |
| `oleafly doctor` informa de que falta un motor | Instálalo con el comando que imprime doctor, o abre una vez el proyecto en la app |
| Un cliente MCP no puede iniciar el servidor | Ejecuta en un terminal el comando configurado, usa la ruta completa de `oleafly mcp config` y ejecuta `oleafly doctor` |
| Código de salida 6 | Ejecuta `oleafly auth status` y vuelve a iniciar sesión |
| Código de salida 8 durante una sincronización | Vuelve a ejecutar la sincronización con `--resolve` para cada archivo que enumera |
| En macOS, Ajustes dice «Primero mueve Oleafly a la carpeta Aplicaciones» | Mueve la app, ábrela desde Aplicaciones y elige **Instalar** |

## Páginas relacionadas

- [Proyectos de Typst](/docs/typst/#build-from-the-command-line)
- [Conéctate mediante MCP](/docs/mcp/)
- [Agentes de línea de comandos](/docs/cli-agents/)
- [Comprobaciones de Preflight](/docs/preflight/)
- [Tareas de investigación](/docs/research-tasks/)