Outil en ligne de commande

Oleafly est fourni avec oleafly, un outil en ligne de commande qui travaille sur les mêmes projets que l’application. Compilez ou vérifiez un article depuis un terminal, un script ou la CI. Donnez à un agent de code un accès fiable à votre projet. Synchronisez avec un service LaTeX en ligne ou un serveur Oleafly, ou lancez l’agent d’Oleafly sans ouvrir l’application.

Il est fourni dans l’application sur toutes les plateformes. Cette page couvre les commandes d’Oleafly 0.4.8 et suivantes. Les versions antérieures en avaient moins ; fixez donc votre version d’Oleafly dans les scripts qui en dépendent.

Installation

Système	Où l’application la garde	Mettre oleafly sur votre PATH
Windows	oleafly-cli.exe à côté de l’application, dans %LOCALAPPDATA%\Oleafly pour le programme d’installation ou C:\Program Files\Oleafly pour le paquet MSI	Installer sur la ligne Commande de terminal dans Paramètres → Général la copie dans %LOCALAPPDATA%\Oleafly\bin\oleafly.exe et ajoute ce dossier à votre PATH
macOS	Oleafly.app/Contents/MacOS/oleafly-cli	Installer sur la ligne Commande de terminal relie oleafly à /usr/local/bin quand vous pouvez y écrire, sinon à ~/.local/bin
Paquets Linux (.deb, .rpm)	/usr/bin/oleafly-cli	Rien à faire : le paquet installe /usr/bin/oleafly
AppImage Linux	Dans l’AppImage	Installer la copie dans ~/.local/bin/oleafly

Les programmes qu’Oleafly lance, comme son propre terminal et les agents CLI, trouvent toujours oleafly dans leur PATH, même avant que vous l’installiez. La variable OLEAFLY_CLI contient son chemin complet.

Windows

1. Ouvrez Paramètres → Général et choisissez Installer sur la ligne Commande de terminal.
2. Ouvrez une nouvelle fenêtre PowerShell ou Invite de commandes. Les fenêtres déjà ouvertes gardent l’ancien PATH.
3. Vérifiez que cela fonctionne :

Get-Command oleafly
oleafly version

Retirer sur la même ligne supprime la copie et retire à nouveau le dossier de votre PATH. Quand Oleafly se met à jour, il actualise la copie au prochain démarrage.

macOS

Déplacez d’abord Oleafly dans votre dossier Applications. Une copie qui s’exécute depuis l’image disque affiche « Déplacez d’abord Oleafly dans le dossier Applications » au lieu de Installer.

La commande est un lien vers l’application : mettre Oleafly à jour met donc aussi la commande à jour. Si le dossier n’est pas dans votre PATH, la ligne affiche la ligne de configuration à ajouter à votre profil de shell. Vérifiez avec command -v oleafly.

Linux

Les paquets .deb et .rpm mettent oleafly sur votre PATH quand vous les installez. oleafly seul, sans rien après, ouvre l’application.

L’AppImage a besoin d’une copie, car les fichiers à l’intérieur d’une AppImage disparaissent quand elle se ferme. Quand vous remplacez l’AppImage par une plus récente, la ligne propose Mettre à jour. Si ~/.local/bin n’est pas dans votre PATH, la ligne affiche la ligne de configuration à ajouter.

Vérifier que cela fonctionne

oleafly version affiche la version de l’application et les moteurs que la commande utiliserait. oleafly doctor contrôle les moteurs, l’application, Git, la commande de terminal et vos clients MCP, et affiche un correctif pour tout ce qui manque. Il fonctionne aussi hors d’un projet.

Compiler un projet

oleafly . ouvre le dossier courant dans l’application. Toutes les autres commandes travaillent sur le dossier où vous êtes ; -C suivi d’un chemin les dirige ailleurs.

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

• oleafly init fait du dossier courant un projet. --engine accepte tectonic, latexmk, typst ou markdown.
• oleafly new suivi d’un dossier, de --template et d’un identifiant de modèle crée un projet à partir d’un modèle. oleafly templates list --all liste les modèles.
• oleafly build utilise le moteur et les réglages du projet, comme le fait l’application : le Tectonic, le Typst et le Pandoc fournis avec Oleafly, ou le LaTeX que vous avez installé. --main compile un autre document du projet, --compiler choisit le compilateur LaTeX pour les projets latexmk, -o copie le PDF ailleurs et --timeout fixe la limite en secondes.
• Un dossier que vous avez ouvert sur place dans l’application se compile avec le moteur et le document principal que vous y avez choisis, dans le propre dossier de compilation de l’application.
• L’application et la commande ne compilent jamais le même projet en même temps : la seconde attend la première. Une compilation échouée conserve le dernier bon PDF.
• oleafly watch recompile à chaque enregistrement. oleafly log --diagnostics liste les erreurs et les avertissements avec le fichier et la ligne, et oleafly clean supprime la sortie de compilation.

Pour les spécificités de Typst, voir Projets Typst.

L’utiliser depuis un agent de code

Les agents de code travaillent mieux avec trois choses que la commande leur donne : oleafly context pour la carte du projet, --json pour des résultats lisibles, et des codes de sortie qui disent ce qui a mal tourné. Il existe trois façons de connecter un agent.

La compétence oleafly-cli

Oleafly fournit une compétence appelée oleafly-cli. Elle apprend à un agent les commandes, la sortie JSON et les codes de sortie, ainsi que la boucle qui marche le mieux : lire le contexte, modifier, compiler, lire les diagnostics, corriger la première erreur.

Dans le terminal d’Oleafly et les agents CLI qu’il lance, choisissez la compétence comme n’importe quelle autre. Pour un agent que vous lancez vous-même, activez Paramètres → Assistant IA → Compétences → Partager les compétences avec les autres agents de cet ordinateur. Oleafly relie alors ses compétences, oleafly-cli comprise, aux dossiers que lisent les autres agents de code, comme ~/.claude/skills, ~/.codex/skills et ~/.agents/skills. oleafly skills path affiche où se trouvent les compétences, pour les agents qui lisent un autre dossier.

Connecter un agent via MCP

oleafly mcp est un serveur MCP qui communique par l’entrée et la sortie standard. Quand l’application a votre projet ouvert, il transmet les appels au serveur MCP de l’application elle-même, si bien que l’agent obtient tous les outils de l’application et vos demandes d’approbation. Sinon, il fonctionne seul, avec des outils de lecture (état du projet, carte du projet, fichiers, recherche, journaux, rapport de diagnostic, recherche de citations) et compile. Il n’y a ni URL ni jeton à copier, ni Node.js à installer.

Le plus rapide est oleafly mcp config --client suivi de claude-code, claude-desktop, codex, cursor ou gemini. La commande affiche l’entrée pour ce client ; ajoutez --write pour qu’elle soit ajoutée à votre place, avec une sauvegarde du fichier du client. Redémarrez ou reconnectez ensuite le client. Dans un projet, elle écrit les réglages du projet ; ailleurs, elle écrit vos réglages utilisateur, avec le chemin complet de la commande, parce que les applications que vous lancez depuis le bureau peuvent ne pas voir votre PATH.

Claude Code

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

Dans un projet, oleafly mcp config --client claude-code --write ajoute plutôt le serveur au fichier .mcp.json du projet.

Claude Desktop

Claude Desktop lance les serveurs sans dossier de projet, donc son entrée passe toujours par l’application : gardez Oleafly ouvert avec votre projet. Utilisez le chemin complet de oleafly. Sous Windows, doublez chaque barre oblique inverse dans le chemin.

claude_desktop_config.json

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

Le fichier se trouve dans ~/Library/Application Support/Claude sous macOS et %APPDATA%\Claude sous Windows.

Codex

~/.codex/config.toml

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

Cursor

Utilisez ~/.cursor/mcp.json pour tous les projets, ou .cursor/mcp.json dans un seul projet.

~/.cursor/mcp.json

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

Gemini CLI

~/.gemini/settings.json

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

Donner tout le projet à un agent

oleafly context dresse la carte du projet : ses fichiers, son plan, ses étiquettes, ses citations, ses fichiers manquants, ses références non résolues et les problèmes de la dernière compilation. --format md donne du texte à coller dans une invite ; --format json donne la même carte pour un programme.

Vérifier un article avant de le soumettre

oleafly check exécute les contrôles de prévérification sur le projet, avec les mêmes résultats que le panneau Prévérification : références, citations, étiquettes, fichiers manquants, champs de bibliographie, figures et anonymat pour la relecture en aveugle. Les contrôles qui ont besoin du PDF compilé utilisent la dernière compilation.

oleafly lint exécute les contrôles LaTeX et BibTeX et, dans les versions qui l’incluent, l’orthographe et la grammaire. --fix applique les corrections qu’on peut appliquer sans risque.

Les deux acceptent --format human, json ou sarif, et --exit-code les fait sortir avec le code 9 quand ils trouvent des problèmes. SARIF fonctionne avec les services d’analyse de code comme celui de GitHub : écrivez le rapport avec oleafly check --format sarif -o preflight.sarif, envoyez-le avec l’action upload-sarif, et chaque constat s’affiche sur sa ligne dans la pull request.

Synchroniser avec un service LaTeX en ligne

oleafly remote télécharge les projets de votre compte de service LaTeX en ligne et garde un dossier synchronisé avec l’un d’eux, avec la même fusion que l’application.

Se connecter

Les connexions vivent dans le magasin chiffré de l’application : une connexion faite dans l’application fonctionne donc en ligne de commande, et inversement.

• oleafly auth login online --with-token enregistre un jeton Git depuis les paramètres de compte du service. Lier et synchroniser en exigent un.
• oleafly auth login online --from-browser firefox copie votre connexion depuis un navigateur de cet ordinateur, pour lister et télécharger des projets. Firefox fonctionne sur tous les systèmes ; Chrome, Edge et Brave fonctionnent sous macOS. --cookie-stdin lit plutôt un cookie de session.
• oleafly auth login git --host https://gitlab.com enregistre un jeton pour un hôte Git.
• oleafly auth status liste chaque connexion et sa provenance, sans montrer aucun secret.
• oleafly auth logout supprime une connexion.

Gardez les jetons hors de l’historique de votre shell

Les jetons se transmettent sur l’entrée standard, par exemple oleafly auth login online --with-token < token.txt, jamais comme arguments. Dans un terminal, la commande les demande sans afficher ce que vous tapez. oleafly auth token affiche un jeton enregistré pour des scripts : traitez sa sortie comme un mot de passe.

Importer et synchroniser des projets

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

• oleafly remote import télécharge des projets dans de nouveaux dossiers. Il fonctionne avec n’importe quel compte.
• oleafly remote link relie un dossier à son projet en ligne via l’intégration Git du service, ce qui exige un jeton Git.
• oleafly remote sync fusionne les modifications en ligne dans le dossier et envoie les vôtres. --dry-run montre ce qui changerait et --no-push fusionne sans envoyer.
• Quand un fichier a changé des deux côtés, la synchronisation n’écrit rien et sort avec le code 8. Relancez-la avec --resolve suivi du chemin du fichier puis de =local ou =remote, pour chaque fichier.
• oleafly remote diff montre ce qui diffère ; avec --exit-code, il sort avec le code 9 quand des fichiers diffèrent et 8 quand ils sont en conflit. --latexdiff --pdf construit un PDF annoté de vos modifications, avec latexdiff de votre distribution TeX.
• oleafly remote status, oleafly remote unlink et oleafly remote open montrent le lien, le suppriment et ouvrent le projet dans votre navigateur.

Travailler avec un serveur Oleafly

oleafly server sign-in suivi de l’adresse du serveur connecte la ligne de commande avec un code que vous approuvez dans votre navigateur. La ligne de commande est un appareil à part sur le serveur, distinct de l’application.

• oleafly server status et oleafly server projects montrent vos serveurs et les projets partagés.
• oleafly server share montre le lien d’un projet et active ou désactive le partage par lien et les commentaires.
• oleafly server members liste les personnes d’un projet et les ajoute, les retire ou les modifie. Seul le propriétaire peut changer le partage et les membres.
• oleafly server comments liste, ajoute, résout les commentaires et y répond. Un commentaire qui ne peut pas être envoyé tout de suite est conservé et envoyé la fois suivante.

Le premier partage d’un projet se fait dans l’application. Voir Collaboration en direct.

Lancer l’agent d’Oleafly depuis un terminal

oleafly ask répond à une question sur le projet sans rien changer. oleafly agent run effectue une tâche.

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

• L’agent peut toujours lire le projet. --allow ajoute write, commands ou network, et il refuse tout ce que vous n’avez pas autorisé. Il ne s’arrête jamais pour poser une question.
• Les modifications vont d’abord dans un dossier de relecture sous .oleafly/agent-runs/. oleafly agent apply suivi de ce dossier les écrit dans le projet, et --apply sur l’exécution les écrit tout de suite.
• Le fournisseur, le modèle et l’effort viennent des réglages de l’application, ou de --provider, --model et --effort. La clé vient de la variable d’environnement propre au fournisseur, comme ANTHROPIC_API_KEY, ou du magasin chiffré de l’application.
• --json affiche un seul résultat à la fin de l’exécution, et --events ajoute une ligne JSON pour chaque événement pendant que l’agent travaille.

Garder les tâches de recherche en cours après la fermeture

Marquez une tâche de recherche Continuer quand Oleafly est fermé. Quand vous quittez, un petit processus d’arrière-plan reprend ces tâches et leurs exécutions d’expériences continuent. Une étape qui demande votre approbation met la tâche en pause et envoie une notification. Quand vous rouvrez Oleafly, il reprend les tâches et montre ce qui s’est passé. Désactivez cela, ou lancez le processus à l’ouverture de session, sous Paramètres → Recherche → Tâches en arrière-plan. oleafly daemon status montre ce que fait le processus.

Référence des commandes

Chaque commande explique ses options avec --help. La référence complète se trouve dans le dépôt : docs/cli.md (s’ouvre dans un nouvel onglet).

Projets et compilations

Commande	Ce qu’elle fait
oleafly open	Ouvre un dossier dans l’application (oleafly . pour le dossier courant)
oleafly init	Fait du dossier courant un projet
oleafly new	Crée un projet, à partir d’un modèle si vous en nommez un
oleafly templates	Liste les modèles et en montre un
oleafly build	Compile le projet
oleafly watch	Recompile à chaque enregistrement
oleafly clean	Supprime la sortie de compilation
oleafly log	Montre le journal de la dernière compilation ou ses problèmes
oleafly doctor	Contrôle les moteurs, l’application et votre configuration
oleafly version	Montre la version et les moteurs utilisés
oleafly project info	Montre les réglages du projet
oleafly projects list	Liste les projets de l’application
oleafly config	Lit et modifie les réglages du projet et de l’application

Rédaction et références

Commande	Ce qu’elle fait
oleafly cite	Affiche le BibTeX d’un DOI, d’un identifiant arXiv, d’un ISBN ou d’un identifiant PubMed ; --add l’ajoute à la bibliographie
oleafly literature	Cherche dans OpenAlex, Semantic Scholar, Crossref, arXiv et PubMed
oleafly bib check	Trouve les entrées qui ne correspondent à aucune notice réelle
oleafly bib clean	Corrige les clés de citation et supprime les doublons ; --apply écrit les modifications
oleafly stats	Compte les mots, les titres, les figures et les équations
oleafly synctex	Relie une ligne du source au PDF et inversement
oleafly export	Exporte le document vers Word, HTML, Markdown, EPUB et plus encore
oleafly convert	Convertit un fichier vers un autre format
oleafly typst	Liste, installe et supprime des versions de Typst
oleafly checkpoint	Liste, compare et copie les points de contrôle de l’application

Agents et automatisation

Commande	Ce qu’elle fait
oleafly context	Dresse la carte du projet pour une personne ou un agent
oleafly mcp	Lance le serveur MCP ; mcp config configure un client
oleafly skills	Liste les compétences et affiche où elles se trouvent
oleafly ask	Répond à une question sur le projet
oleafly agent	Lance l’agent d’Oleafly sur une tâche
oleafly daemon	Lance et pilote le processus qui garde les tâches en cours

Contrôles

Commande	Ce qu’elle fait
oleafly check	Exécute les contrôles de prévérification
oleafly lint	Exécute les contrôles LaTeX, BibTeX, d’orthographe et de grammaire

Comptes et synchronisation

Commande	Ce qu’elle fait
oleafly auth	Connecte aux services LaTeX en ligne, aux serveurs Oleafly et aux hôtes Git
oleafly remote	Importe, relie et synchronise des projets en ligne
oleafly server	Travaille avec les serveurs Oleafly : projets, partage, membres, commentaires

Shell et aide

Commande	Ce qu’elle fait
oleafly completions	Affiche les complétions de shell pour bash, zsh, fish, PowerShell ou elvish
oleafly man	Affiche la page de manuel
oleafly help exit-codes	Explique les codes de sortie

Options de toutes les commandes

Option	Ce qu’elle fait
-C suivi d’un chemin	Exécute la commande sur un autre dossier de projet
--json	Affiche un seul résultat JSON
--events	Affiche la progression en lignes JSON avant le résultat
--quiet	Affiche seulement le résultat
--log	Affiche none, la fin (tail) ou le journal complet (full) du compilateur
--no-input	Ne pose jamais de question
--color	Utilise la couleur auto, always ou never

Sorties pour les scripts

Sortie JSON

Avec --json, chaque commande affiche un seul objet JSON : schema_version, ok, command, les champs propres à la commande et warnings. Quand une commande échoue, error contient un kind, un code stable et un message. Quand ils aident, il contient aussi un hint, des details et "retryable": true si une nouvelle tentative peut réussir. Vérifiez schema_version avant de vous appuyer sur un champ.

{
  "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 ajoute une ligne JSON par événement de progression avant le résultat.

Codes de sortie

oleafly help exit-codes affiche le même tableau.

Code	Signification
0	Ça a fonctionné
1	Un problème est survenu à l’intérieur d’Oleafly
2	La commande a été mal utilisée, ou elle a besoin de --yes pour continuer
3	Le projet est absent ou invalide, ou un chemin sort du projet
4	Un outil ou l’application Oleafly dont elle a besoin n’est pas installé
5	La compilation a échoué
6	Vous devez vous connecter
7	Le réseau a échoué
8	Autre chose retient le projet, ou une synchronisation a des conflits
9	Un contrôle a trouvé des problèmes
130	Vous avez appuyé sur Ctrl+C

Questions, couleur et journaux

La commande ne pose jamais de question sans terminal. --no-input désactive aussi les questions, tout comme une variable CI ; une commande qui a besoin d’un oui échoue alors avec le code de sortie 2 et demande --yes. NO_COLOR ou --color never désactive la couleur. Les chemins qui sortiraient du projet sont refusés.

Variables d’environnement

Variable	Usage
OLEAFLY_DATA_DIR	Le dossier de données d’Oleafly, quand ce n’est pas ~/.oleafly
OLEAFLY_TECTONIC, OLEAFLY_LATEXMK, OLEAFLY_TYPST, OLEAFLY_PANDOC	Un compilateur à utiliser à la place de celui qu’Oleafly trouve
OLEAFLY_APP	L’application Oleafly que lance oleafly open
OLEAFLY_ONLINE_GIT_TOKEN	Un jeton Git pour le service LaTeX en ligne, utilisé à la place d’un jeton enregistré
OLEAFLY_CLI	Définie par Oleafly pour les programmes qu’il lance : le chemin complet de la commande
CI	Quand elle est définie, la commande ne pose jamais de question
NO_COLOR	Quand elle est définie, la sortie n’a pas de couleur

Dépannage

Ce que vous voyez	Ce qu’il faut essayer
oleafly est introuvable	Ouvrez un nouveau terminal. Vérifiez ensuite avec Get-Command oleafly sous Windows ou command -v oleafly sous macOS et Linux, et ajoutez à votre profil de shell la ligne que montrent les Paramètres
oleafly doctor signale un moteur manquant	Installez-le avec la commande qu’affiche doctor, ou ouvrez le projet une fois dans l’application
Un client MCP ne peut pas démarrer le serveur	Exécutez la commande configurée dans un terminal, utilisez le chemin complet donné par oleafly mcp config, et lancez oleafly doctor
Code de sortie 6	Lancez oleafly auth status, puis reconnectez-vous
Code de sortie 8 pendant une synchronisation	Relancez la synchronisation avec --resolve pour chaque fichier qu’elle liste
Sur macOS, les Paramètres affichent « Déplacez d’abord Oleafly dans le dossier Applications »	Déplacez l’application, ouvrez-la depuis Applications, puis choisissez Installer

Pages liées

• Projets Typst
• Se connecter via MCP
• Agents CLI
• Contrôles de prévérification
• Tâches de recherche