Utiliser Cursor CLI : le guide pas à pas

Pour utiliser Cursor CLI, installez-la avec curl https://cursor.com/install -fsS | bash, connectez-vous avec agent login, placez-vous dans un dossier de projet et lancez agent. Vous décrivez une tâche ; l’agent de Cursor lit votre code, modifie des fichiers et exécute des commandes une fois que vous les avez approuvées. Pour les scripts et la CI, agent -p "votre tâche" exécute un seul prompt sans l’interface interactive.

Voilà la boucle de base. Ce guide couvre le reste : les trois modes, le mode print, les modèles, les fichiers de règles, les serveurs MCP, les permissions, la façon dont la CLI consomme le quota de votre forfait Cursor, ses limites et son usage aux côtés d’autres CLI de code. Tout ce qui suit s’appuie sur la documentation officielle de Cursor, en octobre 2026.

Ce qu’est Cursor CLI

Cursor CLI amène l’agent de l’éditeur Cursor dans votre terminal. Elle utilise le même compte, les mêmes modèles, les mêmes règles et les mêmes réglages MCP que l’éditeur : si votre équipe utilise déjà Cursor, la CLI se comporte comme tout le monde s’y attend. Elle tourne partout où il y a un terminal : un serveur joint en SSH, un runner de CI ou un panneau à côté d’un autre agent.

Une précision sur le nom : la commande s’appelait cursor-agent. En janvier 2026, Cursor a fait de agent la commande principale, et cursor-agent fonctionne toujours comme alias. Les anciens guides et outils qui appellent cursor-agent ne cassent donc pas ; ce guide utilise agent.

Si vous hésitez encore entre Cursor et un agent pensé pour le terminal, Claude Code vs Cursor compare les deux. Cet article part du principe que vous avez choisi Cursor et voulez l’utiliser depuis le terminal.

Étape 1 : installer Cursor CLI

Vérifiez l’installation :

agent --version

Si votre shell ne trouve pas agent, ajoutez ~/.local/bin à votre PATH et ouvrez un nouveau terminal. La CLI se met à jour toute seule par défaut ; pour le faire à la main, agent update suffit.

Étape 2 : se connecter

agent login     # ouvre le navigateur
agent status    # indique le compte connecté
agent logout

Sur une machine sans navigateur, définissez NO_OPEN_BROWSER=1 : agent login affiche alors l’URL au lieu de l’ouvrir. Pour la CI et les scripts, créez une clé d’API dans le tableau de bord Cursor, rubrique API Keys, et passez-la via la variable d’environnement CURSOR_API_KEY ou avec --api-key.

Étape 3 : la session interactive

Lancez l’agent dans un projet, avec ou sans premier prompt :

cd my-project
agent
agent "add input validation to the signup form"

La CLI a trois modes, et Shift+Tab passe de l’un à l’autre :

Une bonne habitude dès que la tâche n’est pas triviale : commencer en Plan, se mettre d’accord sur l’approche, puis passer en Agent pour la mise en œuvre. Quelques autres gestes du quotidien :

• @ choisit des fichiers à joindre à votre message.
• Ctrl+R permet de relire les modifications de l’agent.
• Shift+Enter (ou Ctrl+J) insère un saut de ligne ; flèche haut parcourt vos messages précédents.
• Les commandes shell attendent un y/n avant de s’exécuter.
• /model change de modèle ; /clear démarre une conversation vierge ; /summarize résume une longue conversation.
• Deux fois Ctrl+D pour quitter.

Les conversations sont enregistrées. agent ls les liste, agent resume (ou --continue) revient à la dernière et --resume="chat-id" en ouvre une précise. Dans la session, /resume, /fork et /rewind font ce que leur nom indique.

Deux bonus méritent d’être connus. Commencez un message par & et la conversation est confiée à un Cursor Cloud Agent qui continue de travailler en votre absence ; vous la reprenez sur cursor.com/agents. Et -w (ou --worktree nom) fait tourner l’agent dans un nouveau worktree Git sous ~/.cursor/worktrees/, sans toucher à votre copie de travail actuelle.

Étape 4 : le mode print pour les scripts et la CI

Le mode print exécute un seul prompt puis s’arrête. Vous pouvez ainsi appeler la CLI depuis des scripts, des hooks Git et des pipelines de CI :

# Une question en lecture seule, réponse en texte brut
agent -p "summarize what changed in src/billing since the last release"

# Appliquer les changements (sans --force, ils sont seulement proposés)
agent -p --force "add JSDoc comments to every exported function in src/utils"

# Sortie lisible par machine pour un autre outil
agent -p --output-format json "list the TODO comments in this repo"

Les options qui comptent ici :

• --force (alias --yolo) laisse l’agent écrire des fichiers et exécuter des commandes sans demander, sauf si une règle de refus les bloque. C’est l’interrupteur qui permet au mode print de vraiment modifier quelque chose.
• --output-format accepte text (par défaut), json ou stream-json. Associez stream-json à --stream-partial-output pour recevoir le texte au fil de sa génération.
• --trust fait confiance à l’espace de travail sans demander ; --approve-mcps approuve les serveurs MCP configurés.
• --model et --workspace fixent le modèle et le dossier.

Cursor documente aussi l’exécution de la CLI dans GitHub Actions. Si vous utilisez --force en CI, traitez-le comme n’importe quel agent sans surveillance : une clé d’API au périmètre restreint, un runner jetable et des changements qui arrivent sur une branche pour relecture.

Étape 5 : choisir un modèle

agent models                   # modèles accessibles à votre compte
agent --model <model-id>       # démarrer avec un modèle précis

Dans la session, /model ouvre le sélecteur et /model grok filtre la liste. Si vous ne précisez pas de modèle, la CLI utilise celui réglé sur votre compte. Les modèles proposés dépendent de votre forfait (voir la partie tarifs plus bas) : tous les forfaits payants incluent les modèles propres à Cursor, tandis que les modèles tiers demandent Premium ou plus.

Étape 6 : règles, AGENTS.md et CLAUDE.md

Cursor CLI utilise le même système de règles que l’éditeur. Les règles se trouvent dans .cursor/rules, et la CLI lit aussi AGENTS.md et CLAUDE.md à la racine du projet, qu’elle applique également comme des règles. Depuis la version d’octobre 2026, les fichiers AGENTS.md des sous-dossiers s’appliquent quand l’agent modifie des fichiers dans ces dossiers.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- Never edit files in src/generated/.

Si plusieurs agents travaillent sur le même dépôt, AGENTS.md est le fichier que tous lisent : c’est donc le bon endroit pour les règles communes. agent generate-rule crée une nouvelle règle Cursor de manière interactive. Pour savoir quoi mettre dans ces fichiers, lisez Comment écrire CLAUDE.md et AGENTS.md.

Étape 7 : les serveurs MCP

Les serveurs MCP donnent de nouveaux outils à l’agent : un navigateur, un gestionnaire de tickets, une base de données. Cursor CLI lit le même mcp.json que l’éditeur : .cursor/mcp.json pour le projet et ~/.cursor/mcp.json pour tous les projets. Ce que vous avez configuré dans l’éditeur est donc déjà disponible dans la CLI.

agent mcp list                 # serveurs configurés et leur état
agent mcp list-tools <id>      # outils proposés par un serveur
agent mcp login <id>           # connexion à un serveur qui utilise OAuth
agent mcp disable <id>         # le désactiver sans le supprimer

Dans la session, /mcp list affiche la même chose. Chaque serveur ajoute ses outils au contexte de l’agent : ne gardez activés que ceux dont vous avez besoin.

Étape 8 : permissions et configuration

Les réglages globaux se trouvent dans ~/.cursor/cli-config.json (sous Windows, %USERPROFILE%\.cursor\cli-config.json). Un projet peut ajouter un .cursor/cli.json qui ne contient que des permissions. Les deux sont en JSON pur, sans commentaires.

{
  "permissions": {
    "allow": ["Shell(git)", "Shell(ls)", "Read(src/**/*.ts)", "Write(package.json)", "Mcp(datadog:*)"],
    "deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)"]
  }
}

Chaque entrée désigne un outil et un motif : Shell(...), Read(...), Write(...), WebFetch(domaine) et Mcp(serveur:outil). Le refus l’emporte sur l’autorisation. Le fichier global définit aussi le mode d’approbation (allowlist, auto-review ou unrestricted), les réglages de sandbox et l’ajout éventuel d’une ligne « Made with Cursor » aux commits.

Le lien entre Cursor CLI et votre forfait Cursor

Il n’y a pas d’abonnement séparé pour la CLI. Elle utilise votre compte Cursor et, en octobre 2026, Cursor est vendu dans The X Subscription, avec Grok et X. Chaque forfait payant comprend un quota unique pour les modèles propres à Cursor (Grok 4.7, Grok 4.6, Grok 4.5 et Composer 2.5). L’éditeur, la CLI, les Cloud Agents et les apps Grok puisent tous dedans, et il se renouvelle chaque semaine.

Ce que cela change quand vous utilisez la CLI :

• Chaque modèle consomme le quota à son propre rythme. L’usage restant et la date du prochain renouvellement apparaissent dans les réglages de l’éditeur et dans le tableau de bord d’usage.
• Claude, GPT et Gemini ne sont pas inclus dans le quota. À partir de Premium, vous les payez dès la première requête au prix catalogue de l’API, sur un crédit prépayé. Plus et Free n’y ont pas accès.
• Plus n’inclut ni Cloud Agents ni Auto. Confier une conversation à un Cloud Agent avec & demande Premium ou plus.
• Les anciens forfaits continuent de fonctionner. Pro, Pro+, Ultra, Start et les sièges Teams Standard ou Premium sont des forfaits historiques et gardent leurs deux quotas mensuels et l’usage à la demande.

Les limites à connaître

• Le Shell Mode a un délai maximal de 30 secondes. /shell exécute des commandes directement, mais ne peut pas faire tourner de serveurs longue durée ni gérer des invites interactives, et cd n’est pas conservé d’une commande à l’autre.
• Le mode print est prudent par défaut. Sans --force, il propose les modifications au lieu de les écrire, ce qui surprend presque tout le monde la première fois.
• Les fichiers de configuration sont en JSON strict. Un commentaire ou une virgule en trop dans cli-config.json les rend invalides.
• Une conversation par terminal. La CLI a les worktrees et les Cloud Agents, mais aucune vue intégrée qui affiche plusieurs agents locaux en même temps.

Les pièges courants

• command not found: agent. ~/.local/bin n’est pas dans votre PATH.
• Un outil appelle encore cursor-agent. Aucun souci, l’alias reste en place. Seule la documentation est passée à agent.
• Le modèle voulu n’apparaît pas dans la liste. C’est un modèle tiers et votre forfait est Free ou Plus.
• Les règles sont ignorées. Vérifiez que AGENTS.md ou CLAUDE.md se trouve à la racine du projet, ou que la règle de .cursor/rules s’applique aux fichiers modifiés.
• La CI reste bloquée sur une demande d’approbation. Ajoutez --trust, utilisez CURSOR_API_KEY et passez --approve-mcps si des serveurs MCP sont configurés.

Faire tourner Cursor CLI à côté d’autres CLI

Si votre équipe vit déjà dans Cursor, Cursor CLI est un bon choix : les mêmes modèles, règles et serveurs MCP dans l’éditeur et dans le terminal. Si vous voulez des points d’extension poussés dans le terminal, comme les hooks, les skills et les plugins, Claude Code est plus solide sur ce terrain. Et si vous envisagez de quitter Cursor, Meilleures alternatives à Cursor passe les options en revue honnêtement.

Beaucoup finissent par faire tourner Cursor CLI à côté de Claude Code, Codex ou Gemini CLI, chacun sur sa propre tâche. Dans de simples terminaux, cela veut dire un onglet par agent et des worktrees -w pour les séparer. AgentVera est une application de bureau qui fait tourner ces CLI côte à côte dans de vrais terminaux, avec vos propres installations et connexions. La prise en charge de Cursor fonctionne ainsi :

• Chaque agent a sa propre conversation. Une conversation vide est créée pour chaque nouvel agent Cursor (cursor-agent create-chat) et l’agent y revient toujours ; plusieurs agents Cursor travaillent donc sur le même projet sans se gêner. L’éditeur Cursor n’a pas besoin d’être ouvert.
• Votre connexion, vos modèles. C’est la connexion propre à Cursor CLI qui est utilisée ; si le modèle est laissé vide, celui des réglages Cursor s’applique.
• Des règles plutôt qu’un prompt de rôle. Cursor CLI n’a pas d’option pour des instructions supplémentaires, donc le champ Rôle de l’agent n’atteint pas Cursor. Mettez les instructions durables dans AGENTS.md ou dans des fichiers de règles.
• MCP depuis un seul endroit. Les serveurs MCP ajoutés dans AgentVera et le navigateur d’AgentVera sont ajoutés comme un plugin local et approuvés pour l’exécution.
• Grille, comptes et serveurs. Faites tourner Cursor dans la grille de l’Espace de travail à côté d’autres agents, avec une revue de code automatique à la fin de chaque tour. Dans Réglages → Comptes, vous pouvez placer plusieurs comptes Cursor dans un ordre de secours, et un agent Cursor peut aussi tourner sur un serveur SSH enregistré.

Pour essayer, téléchargez AgentVera.

En résumé

Pour utiliser Cursor CLI, installez-la, lancez agent login puis agent dans un projet. Passez en Plan avec Shift+Tab avant les gros changements, utilisez agent -p --force dans les scripts, et gardez vos règles dans AGENTS.md ou .cursor/rules et vos outils dans mcp.json. C’est votre forfait Cursor qui fixe jusqu’où va votre usage : choisissez vos modèles en pensant au quota hebdomadaire.