Herramienta de línea de comandos

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:

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.

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.

Ú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 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

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.

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

~/.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.

~/.cursor/mcp.json

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

Gemini CLI

~/.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 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.

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

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.

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.

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 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 (se abre en una pestaña nueva).

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.

{
  "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
• Conéctate mediante MCP
• Agentes de línea de comandos
• Comprobaciones de Preflight
• Tareas de investigación