# Outil en ligne de commande

Installez la commande oleafly sous Windows, macOS ou Linux, compilez et vérifiez des projets depuis un terminal ou la CI, synchronisez avec un service LaTeX en ligne, et connectez des agents de code via son serveur MCP et sa compétence.

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 :

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

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

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

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

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

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

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

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

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

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

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

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

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

```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` 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](/docs/typst/#build-from-the-command-line)
- [Se connecter via MCP](/docs/mcp/)
- [Agents CLI](/docs/cli-agents/)
- [Contrôles de prévérification](/docs/preflight/)
- [Tâches de recherche](/docs/research-tasks/)