A beginner’s guide to Unity CLI and the Pipeline package

Nous avons récemment lancé le Unity CLI, et les retours ont été extrêmement positifs avec de plus en plus de cas d'utilisation inspirants qui apparaissent. Cependant, si vous, comme beaucoup d'autres, trouvez les outils en ligne de commande un peu intimidants, vous vous sentez plus comme un designer que comme un programmeur, ou si vous n'avez simplement pas eu le temps d'expérimenter avec, ce guide est conçu pour vous.

Qu'est-ce que le CLI Unity ?

L'une des plus grandes forces de l'éditeur Unity est le GUI, qui facilite la gestion visuelle de projets complexes. Inspecter un prefab, modifier les valeurs des matériaux, exécuter des tests, cuire l'éclairage ou traquer des erreurs de console ne sont qu'à quelques clics de souris dans l'Éditeur. Ce flux de travail a servi les utilisateurs pendant près de deux décennies, il est devenu le goulot d'étranglement pour les tâches répétitives, l'automatisation et les flux de travail pilotés par l'IA (agentiques). Un agent IA peut naviguer dans les clics et les interfaces visuelles uniquement, mais cela nécessite une couche d'interprétation visuelle supplémentaire et non native qui ralentit le processus et ajoute une surcharge inutile, ce qui consomme rapidement des jetons.

C'est là qu'interviennent le nouveau CLI Unity et le package Unity Pipeline expérimental.

L'interface en ligne de commande Unity est, comme son nom l'indique, une interface en ligne de commande pour gérer Unity. Parce qu'il n'a pas d'interface utilisateur graphique, il est exceptionnellement bien adapté à l'automatisation et aux flux de travail agentiques. Il fonctionne comme un binaire autonome (application) qui inclut ce dont il a besoin pour fonctionner, gérer et interagir avec Unity. En d'autres termes, vous pouvez exécuter des commandes depuis le terminal qui communiquent directement avec Unity, remplaçant ainsi la couche de clics de souris et les flux de travail entiers dans le Hub ou l'Éditeur.

Remarque : De nouvelles fonctionnalités et améliorations sont ajoutées fréquemment. Au moment de la rédaction, la version 1.0.0-beta.6 de Unity CLI combinée avec 0.5.0-exp.1 du package com.unity.pipeline et Unity 6000.6.0b9 est la configuration la plus à jour. Si vous rencontrez des problèmes, consultez la documentation de l'Unity CLI : https://docs.unity.com/en-us/unity-cli/use-unity-cli

Comment le CLI Unity et le package Pipeline fonctionnent ensemble

Alors que le binaire CLI Unity autonome gère votre configuration d'environnement (comme l'installation des éditeurs, des modules et la gestion des licences), la vraie valeur réside lorsque vous l'associez au package Unity Pipeline (com.unity.pipeline).

Ce package Unity Pipeline transforme essentiellement votre Éditeur en cours d'exécution en un serveur HTTP local. Parce que l'Éditeur reste ouvert en arrière-plan, vos scènes chargées et votre base de données d'actifs restent "chaudes" dans la mémoire du système. En gardant tout préchargé, vous contournez entièrement la lourdeur frustrante au démarrage du moteur à partir d'un état froid. Votre terminal (ou un agent IA) peut maintenant piloter l'Éditeur instantanément pour exécuter des tests, charger des scènes ou modifier des GameObjects.

Le système gère également le goulot d'étranglement notoire du rechargement de domaine. Avant le package Pipeline, chaque fois que vous ou votre agent IA apportiez des modifications directes à un script C# sur le disque, vous deviez attendre que Unity reconstruise le projet et recharge le domaine. Certaines actions nécessiteraient même que vous vous concentriez ou cliquiez sur quelque chose dans l'Éditeur avant qu'elles ne puissent se poursuivre.

Mais le serveur local du package Pipeline gère ce processus de compilation entièrement de manière asynchrone. La connexion reste stable et active tout au long de la compilation, garantissant que votre session de terminal ne se déconnecte ni n'expire pendant que l'Éditeur se recharge en arrière-plan.

Les choses vont encore plus vite lorsque vous exécutez du code dynamiquement via la commande eval. Ici, le package Pipeline dans l'Éditeur agit comme un traducteur instantané, compilant votre extrait C# à la volée et le plaçant directement sur le thread principal de Unity. Parce que cette exécution dynamique est entièrement autonome, elle contourne complètement le processus de recompilation à l'échelle du projet et de rechargement du domaine. Vous sautez complètement l'attente fastidieuse et obtenez vos résultats en millisecondes.

Cela signifie que vos scripts d'automatisation robustes ne planteront pas ni ne perdront leur connexion simplement parce qu'une compilation de projet massive se déroule en arrière-plan, tandis que vos commandes rapides dans le terminal s'exécutent toujours avec un délai quasi nul. Vous obtenez stabilité et vitesse dans le même outil.

Passage de MCP à l'interface de ligne de commande Unity

Vous vous demandez peut-être : « Qu'en est-il du serveur officiel du protocole de contexte Unity (MCP) ? » Pourquoi ne devrais-je pas simplement utiliser ou m'en tenir à ça ?

La réponse courte est que nous ne retirons pas le support MCP. Cependant, l'interface de ligne de commande Unity et le package Pipeline gèrent tous les mêmes cas d'utilisation que le MCP et plus encore, mais ils le font beaucoup mieux et plus rapidement.

La réponse plus longue revient à l'architecture. Les configurations MCP traditionnelles nécessitent un harnais client actif (comme Claude Desktop ou Cursor) pour agir comme traducteur entre votre agent IA et Unity. Mais les agents modernes, natifs du terminal, comme Claude Code, sont déjà incroyablement bons pour exécuter directement des commandes shell standard. En utilisant des entrées CLI directes comme unity command ou unity eval, vous contournez complètement la surcharge de configuration et de maintenance d'un serveur MCP. Votre agent peut parler directement à Unity via un serveur HTTP local unifié et ultra-rapide. Cela signifie que vous écrivez des configurations plus propres, passez moins de temps à déboguer les sockets de connexion et pouvez laisser votre IA fonctionner avec la vitesse pure et native du terminal.

De plus, le legacy MCP server fonctionnait directement à l'intérieur du processus Éditeur en tant que paquet C#. Cela signifiait que le pont de connexion lui-même était lié au thread principal et à l'espace mémoire de Unity. Dès que vous compiliez du code ou déclenchiez un rechargement de domaine, Unity vidait sa mémoire, ce qui provoquait fréquemment la déconnexion du socket, le lancement d'exceptions null ou le blocage de l'agent en milieu de boucle.

Le package actuel com.unity.pipeline est également un package C# fonctionnant à l'intérieur de l'Éditeur, mais il expose un serveur HTTP et une API REST (pas un pont de socket), ce qui explique pourquoi il est plus résilient aux rechargements de domaine. Parce que ce serveur local gère les commandes de manière asynchrone, votre connexion terminale reste complètement stable et active même pendant les compilations lourdes et les rechargements de domaine.

En résumé, en passant à l'interface de ligne de commande Unity, vous évitez complètement les déconnexions et le gaspillage de jetons. Enfin, l'interface en ligne de commande propose également un mode MCP si vous avez un cas d'utilisation spécifique pour lequel vous souhaitez utiliser MCP.

Installation du paquet CLI et Pipeline

L'installation des paquets CLI et Pipeline est effectuée automatiquement avec Unity Hub dans les dernières versions. Au moment de la rédaction, il existe plusieurs façons d'installer Unity CLI, alors assurez-vous de vous référer à la documentation pour la source de vérité la plus récente.

Si vous ne l'avez pas déjà installé pour une raison quelconque, le moyen le plus simple est d'utiliser des commandes de terminal pour le processus d'installation. Vous pouvez regarder la vidéo ou suivre les instructions ci-dessous.

Pour installer l'Unity CLI, tout ce que vous avez à faire est d'exécuter les commandes suivantes depuis votre terminal, en fonction de la plateforme sur laquelle vous êtes :

# macOS ou Linux

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

# Windows

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

L'étape suivante consiste à installer le package Unity Pipeline :

pipeline unity install

Une fois que les deux sont installés, vous pouvez vérifier s'ils fonctionnent.

Vérification des installations

Pour confirmer votre installation, exécutez simplement la commande suivante :

statut Unity

Il devrait retourner quelque chose comme ceci :

Unity Editor (port 7800): readyProject: /Users/thomaskr/Github/UnityProjects/MyAwesomeProjectVersion: 6000.6.0b7PID: 85009

Si vous voyez l'état ready à côté de la première ligne, cela signifie que l'Éditeur est en direct et accessible. Il confirme également sur quel port se trouve l'Éditeur, le chemin du Projet, la Version de l'Éditeur et un identifiant de processus (PID).

Ensuite, pour vous assurer que votre accès a été authentifié, exécutez la commande suivante :

connexion auth unity

Ceci ouvrira votre navigateur pour la connexion OAuth à votre compte Unity. Une fois que vous vous authentifiez, l'interface en ligne de commande stocke vos informations d'identification dans le trousseau système afin que les commandes futures nécessitant une authentification (comme unity projects list, unity build, unity license, unity cloud) fonctionnent automatiquement sans nouvelle invite.

Exécuter quelques commandes de base

Avec les paquets CLI et Pipeline installés, il est temps d'essayer quelques commandes supplémentaires. Commençons par la commande unity --help, qui vous donne un aperçu rapide de tout ce que vous pouvez faire.

unity --help

La commande unity --help vous donne une liste de toutes les commandes de base disponibles avec l'aperçu et les options disponibles pour chacune.

Le nombre d'options peut sembler un peu accablant au début, mais la syntaxe de l'interface en ligne de commande suit un modèle très logique et cohérent.

Utilisons une commande que nous venons d'utiliser comme exemple, mais cette fois avec une option :

unity auth login --non-interactive

De gauche à droite :

• unity active le CLI de Unity et est donc la commande principale.
• auth login sont les sous-commandes. Vous pouvez les considérer comme des verbes qui indiquent au programme principal exactement quelle action entreprendre. Ici, auth dirige l'interface en ligne de commande vers le système d'Authentication, et login lui dit de vous connecter.
• --non-interactiveest l'option. Considérez les options comme similaires aux paramètres. Ce sont des modificateurs qui indiquent au commandement comment se comporter. Dans ce cas, il indique à l'interface en ligne de commande de vous connecter directement via le terminal plutôt que d'ouvrir une fenêtre de navigateur visuel. Les options sont parfois également appelées « drapeaux » lorsqu'elles sont utilisées dans le contexte d'options marche/arrêt.

Il existe également un raccourci en une seule lettre conçu pour un frappe rapide dans votre flux de travail quotidien du terminal.

En revenant à notre option d'aide (--help), au lieu d'exécuter unity --help, vous pouvez également utiliser simplement unity -h, ce qui vous donne la même réponse dans les deux cas.

unity --help # Version avec long flag (lisibilité améliorée) unity -h # Version avec court flag (plus rapide au quotidien)

Les drapeaux courts utilisent le tiret simple (-) et sont conçus comme un raccourci, tandis que les drapeaux longs utilisent le double tiret (--) et sont les descriptions complètes équivalentes conçues pour la lisibilité.

La commande -- help est l'outil le plus important de votre boîte à outils ; vous pouvez l'ajouter à n'importe quel niveau d'une commande imbriquée pour obtenir une documentation rapide. Voici quelques exemples pour la commande d'Authentication que nous venons de couvrir :

# Aide aux commandes d'authentification

unity auth --help

# Aide pour la commande de connexion spécifiquement

unity auth login --help

Chaque écran d'aide affichera instantanément exactement ce que fait la commande, quelles options sont disponibles et quels arguments elle attend. En cas de doute, demandez simplement à la commande elle-même !

Essayons les commandes releases comme un autre exemple :

Unity releases

Ceci me donne un bon aperçu de chaque version disponible pour Unity au moment de la rédaction.

Ajoutons maintenant l'option --help:

versions de unity --help

La commande unity releases --help vous donne une explication de toutes les différentes options que vous pouvez ajouter pour affiner votre recherche de versions Unity.

Par exemple, au moment de la rédaction, nous sommes sur une version bêta d'Unity 6.6b7 et souhaitons installer la dernière version bêta. Nous pouvons utiliser la commande de base unity install , qui nous donnera une interface visuelle simple, où nous pourrons choisir la version que nous voulons.

installer Unity

Choisissons la version b9, qui démarrera l'installateur en arrière-plan (et qui prendra quelques minutes à se terminer).

Plutôt que d'utiliser l'assistant d'installation, vous pouvez également utiliser la commande --help pour obtenir un aperçu de toutes les commandes :

unity install --help

Ceci vous donne un aperçu qui ressemble à ceci :

Dans la liste, vous pouvez voir que vous êtes en mesure de passer la version d'Unity que vous souhaitez installer en tant qu'argument. Cela signifie que si vous aviez une version spécifique que je voulais installer, vous pourriez faire cela en une seule commande en utilisant :

#Remplacez simplement la version par celle que vous souhaitez utiliser

unity install 6000.5.9f1

Pendant ce temps, notre nouvelle version de l'Éditeur a été installée, nous devons donc maintenant mettre à jour le projet. Pour faire cela, ajoutez la version spécifique dans laquelle vous souhaitez ouvrir le projet. Ce serait la même chose que si vous alliez dans le Hub et choisissiez une autre version d'éditeur pour ouvrir par projet en déclenchant la mise à niveau du projet.

unity open --version 6000.6.0b9

Comme nous l'avons abordé précédemment, le package Pipeline ouvre une boîte à outils massive contenant presque tout ce que vous pouvez faire dans l'éditeur Unity (et avec de nouvelles commandes ajoutées constamment à mesure que la version bêta mûrit).

Si vous voulez voir quelles commandes sont disponibles dans votre projet actuel, exécutez :

liste unity

Cette commande vous donne un tableau de haut niveau montrant le nom, le groupe et une courte description pour chaque commande. C'est excellent comme point de départ pour parcourir rapidement les centaines de commandes intégrées telles que eval,add_animator_layer,build, et find_assets.

Lorsque vous devez savoir exactement comment formater vos entrées. Vous pouvez exécuter :

commande unity

L'exécuter sans arguments vous donne le « plan » détaillé des commandes Unity avec la documentation pour chaque commande enregistrée, y compris les options (les drapeaux exacts et les types de données que la commande attend).

Les deux commandes parlent au même processus Éditeur connecté, mais elles renvoient des niveaux de détail différents. Au début de la création de scripts d'automatisation personnalisés ou de la configuration de flux de travail agentiques qui pilotent Unity en arrière-plan, commande unity deviendra rapidement votre outil de référence le plus consulté pour structurer des appels propres et automatisés.

Enfin, terminons en examinant la commande eval et comment exécuter un test simple Debug.Log( “Hello World”) dans notre console Unity. eval est une commande du package Pipeline (et sans doute la plus excitante des plus de 140 commandes intégrées) qui compile et exécute dynamiquement du code C# dans le processus de l'Éditeur. Essayez d'exécuter la commande suivante :

unity command eval --code 'Debug.Log("hello from unity cli");'

Ceci vous donne le résultat suivant où le JSON renvoie avec "success": true s'il a fonctionné.

Dans l'Éditeur, vous pouvez maintenant vérifier que cela a bien fonctionné dans la fenêtre Console .

Décomposons la commande :

unity command eval --code 'Debug.Log("hello from unity cli");'

De gauche à droite :

1. unity exécute l'outil CLI Unity.
2. command est la sous-commande qui lui indique de "parler à un Éditeur connecté".
3. eval est un sous-sous-commande qui signifie "évaluer (exécuter) du code pour moi".
4. --code est une option (ou un drapeau) qui signifie "voici le code à exécuter".
5. 'Debug.Log("hello from unity cli");' est la valeur pour --code; le code réel à exécuter.

Connecter le LLM

Se familiariser avec quelques commandes de base peut aider à accélérer une partie de la maintenance de vos installations Unity, mais c'est lorsque vous commencez à automatiser et à intégrer vos flux de travail agentiques que cela brille vraiment.

Avec Unity CLI et le package Pipeline, vous pouvez connecter l'agent de votre choix. Signifiant que vous utilisiez Claude, Codex, Copilot ou des modèles locaux, etc., l'interface en ligne de commande est conçue pour s'intégrer à votre configuration existante et préférée et devrait se connecter sans nécessiter de configuration supplémentaire.

Ouvrez simplement un terminal, naviguez (en utilisant cd) directement dans le répertoire de votre projet Unity et démarrez l'agent en entrant « claude » (ou la commande de votre agent). Vous pouvez confirmer que vous êtes connecté en demandant simplement à l'agent quelque chose dans le genre suivant :

Exécutez "unity command" dans un bash et dites-moi ce qu'il peut faire, puis testez une simple commande "eval"

Connecter le LLM en utilisant MCP

Unity a déprécié le serveur MCP en édition dans le package com.unity.ai.assistant. Il a été remplacé par le serveur MCP intégré de l'interface de ligne de commande Unity (unity mcp), alimenté par le package Unity Pipeline. Il utilise le même protocole, donc les clients se connectent sans problème. Le mode MCP reste entièrement pris en charge pour les agents qui ne peuvent pas exécuter des commandes shell arbitraires ou qui ont des difficultés avec la composition en ligne de commande.

Pour utiliser MCP, exécutez la commande suivante :

unity mcp configure

Cette commande injecte automatiquement la configuration directement dans les paramètres de votre agent. Pour tester si votre LLM est connecté, effectuez une petite requête de test demandant à votre outil LLM d'exécuter quelque chose de similaire à ce qui suit :

Je veux que vous créiez un cube de 2 × 2 × 2 au centre de la scène que j'ai actuellement ouverte. Puis créez un script qui le fait tourner continuellement autour des trois axes à 45 degrés par seconde.

Voici ce que Claude Code a répondu :

Une fois terminé, il devrait passer en mode Lecture et exécuter la scène afin que vous puissiez vérifier que le cube tourne correctement.

Étendre avec vos propres commandes personnalisées

La suite intégrée de l'interface en ligne de commande couvre toutes les bases comme basculer en mode Lecture, recompiler et exécuter des tests unitaires. Cependant, la véritable force de cette architecture réside dans son extensibilité. Vous pouvez facilement écrire des commandes personnalisées pour fournir à vos agents IA un contexte sur mesure spécifique au projet et des outils uniques créés spécialement pour votre jeu.

Créer une commande personnalisée est très simple. Tout ce que vous avez à faire est d'écrire une méthode C# statique standard et de la décorer avec les attributs [CliCommand] et [CliArg].

Le package Pipeline découvre automatiquement ces attributs pendant la compilation, ce qui signifie qu'il ne nécessite aucune configuration manuelle ni fichiers d'enregistrement. Lorsque vous exécutez unity command sans arguments, l'interface en ligne de commande liste dynamiquement toutes les commandes personnalisées disponibles aux côtés des commandes intégrées.

Remarque : L'attribut [CliCommand] rend les commandes découvrables et invocables via l'interface de ligne de commande. Pour une exécution paramétrée, vous appelez la méthode directement en utilisant unity command eval avec la syntaxe C#, plutôt que de passer des drapeaux de style CLI.

Regardons un rapide commande personnalisée "Hello World" en action.

Créez un nouveau script C# nommé HelloWorldCommand.cs. Assurez-vous que la classe et la méthode sont statiques, et incluez l'espace de noms Unity.Pipeline.Commands> :

using UnityEngine;

using Unity.Pipeline.Commands;

public static class HelloWorldCommand

{

[CliCommand("hello-world", "Une simple commande bonjour monde")]

public static void SayHello()

{

Debug.Log("Bonjour, le monde!") Ceci est une commande CLI personnalisée.");

}

}

Pour exécuter votre nouvelle commande, lancez votre terminal et exécutez la commande suivante :

commande unity hello-world

Le terminal devrait ressembler à ceci

Et votre journal de console devrait ressembler à ceci :

Vous pouvez également étendre la fonctionnalité si vous avez besoin de passer des paramètres en utilisant l'attribut [CliArg] .

using UnityEngine;

using Unity.Pipeline.Commands;

public static class HelloWorldCommand

{

[CliCommand("hello-world", "Une simple commande bonjour monde")]

public static void SayHello(

[CliArg("name", "Qui saluer")] string name)

{

Debug.Log($"Bonjour, {name}!" Ceci est une commande CLI personnalisée.");

}

}

Pour exécuter votre nouvelle commande, lancez votre terminal et exécutez :

unity command hello-world --name "thomas"

Installation du plugin Unity Agent

Unity propose également un plugin de développement de jeux officiel, qui au moment de la rédaction est disponible pour Claude Code, Codex et Grok. Il expédie des compétences sélectionnées pour le développement de jeux et l'optimisation des performances. Une fois installées, les compétences se chargent automatiquement lorsque vous travaillez sur un projet Unity dans l'un des précédents. Pour l'installer pour Claude, exécutez simplement cette commande :

claude plugin marketplace ajouter Unity-Technologies/unity-agent-plugin

github.com/Unity-Technologies/unity-agent-plugin

Un autre conseil rapide si vous êtes un utilisateur de Claude Code et que vous commencez un nouveau projet est d'exécuter la phase d'initialisation qui configure Claude avec un contexte de base sur votre projet en créant un fichier claude.md. C'est un fichier markdown qui se trouve à la racine de votre dossier Project que Claude Code lit au début de chaque session.

/init # Exécuter cette commande à l'intérieur de Claude Code

De cette façon, vous pouvez l'utiliser pour informer Claude de votre pile technologique préférée, comme par exemple si vous préférez uGUI à UI Toolkit pour l'interface utilisateur, le nouveau Input System à l'ancien Input Manager, etc. Il pourrait également être utilisé pour les décisions d'architecture telles que l'utilisation d'un modèle de localisateur de services plutôt que des singletons, le MVP pour la conception de votre interface utilisateur, etc.

Alors que Claude construit également une mémoire automatique au fur et à mesure qu'il travaille, en sauvegardant les apprentissages entre les sessions sans que vous ayez à écrire quoi que ce soit, le fichier Claude.md aide à guider la direction générale du projet spécifique.

Au fur et à mesure que vous progressez dans le processus, vous pouvez envisager d'ajouter plus d'instructions personnalisées telles que votre guide de style de code. J'ai écrit un article sur le fonctionnement de cela pour les instructions personnalisées dans l'assistant IA, mais les principes sont exactement les mêmes pour Claude Code si vous souhaitez en savoir plus.

La prochaine étape

Nous espérons que cette introduction vous a été utile pour vous aider à démarrer. Si vous êtes intéressé par l'optimisation plus poussée de votre flux de travail agentique, consultez l'article sur la configuration de instructions personnalisées pour votre LLM, y compris la définition d'un guide de style de code Unity C# Unity C# code style guide.

Regardez la vidéo ici :

Interface en ligne de commande (CLI) de Unity