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

Unity Technologies launched the Unity CLI, a self-contained command-line binary for managing Unity, alongside the experimental Unity Pipeline package (com.unity.pipeline), according to a beginner's guide by Unity Technologies' Thomas Krogh-Jacobsen. The most up-to-date configuration at the time of writing is Unity CLI 1.0.0-beta.6 with com.unity.pipeline 0.5.0-exp.1 and Unity 6000.6.0b9, a combination Unity says is suited to automation and AI-driven agentic workflows. The Pipeline package turns the running Editor into a local HTTP server, keeping scenes and the asset database warm in memory and handling domain reload asynchronously so terminal sessions do not drop during compilation.

A beginner’s guide to Unity CLI and the Pipeline package Thomas Krogh-Jacobsen - Unity Technologies We recently launched the Unity CLI https://unity.com/blog/meet-the-unity-cli , and the feedback has been overwhelmingly positive with more and more inspiring use cases popping up. However, if you, like many others, find command-line tools a bit intimidating, feel more like a designer than a programmer, or simply haven’t had the time to experiment with it yet, this guide is designed for you. What is the Unity CLI? One of the Unity's Editor’s greatest strengths is the GUI, which makes it easy to visually manage complex projects. Inspecting a prefab, tweaking material values, running tests, baking lighting, or tracking down console errors are all just a few mouse clicks away in the Editor. This workflow has served users for almost two decades, it has become the bottleneck for repetitive tasks, automation, and AI-driven agentic workflows. An AI agent can navigate clicks and visual-only interfaces, but this requires an extra, non-native layer of visual interpretation that slows down the process and adds unneeded overhead, which quickly consumes tokens. This is where the new Unity CLI and the experimental Unity Pipeline package come in. The Unity CLI is, as its name suggests, a Command Line Interface for managing Unity. Because it has no graphical user interface, it’s exceptionally well-suited for automation and agentic workflows. It works as a self-contained binary application that includes what it needs to run, manage, and interface with Unity. In other words, you can run commands from the terminal that talks straight to Unity, replacing the layer of mouse clicks and entire workflows in the Hub or Editor. Note: New features and improvements are being added frequently. At the time of writing, the1.0.0-beta.6 version of Unity CLI combined with 0.5.0-exp.1 of the com.unity.pipeline package and Unity 6000.6.0b9 is the most up to date configuration. If you run into issues, check out the Unity CLI documentation: https://docs.unity.com/en-us/unity-cli/use-unity-cli https://docs.unity.com/en-us/unity-cli/use-unity-cli How the Unity CLI and Pipeline package work together While the standalone Unity CLI binary handles your environment setup like installing editors, modules, and managing licenses , the real value comes when you pair it with the Unity Pipeline package com.unity.pipeline . This Unity Pipeline package essentially turns your running Editor into a local HTTP server. Because the Editor stays open in the background, your loaded scenes and asset database remain "warm" in system memory. By keeping everything pre-loaded, you entirely bypass the frustrating startup overhead of booting the engine from a cold state. Your terminal or an AI agent can now drive the Editor instantly to run tests, load scenes, or modify GameObjects. The system also handles the notorious domain reload bottleneck. Before the Pipeline package, whenever you or your AI agent made direct changes to a C script on disk, you had to wait for Unity to rebuild the project and reload the domain. Some actions would even require you to focus or click something in the Editor before it could proceed. But the Pipeline package's local server handles that compilation process completely asynchronously. The connection remains stable and active throughout the compile, ensuring your terminal session never drops or times out while the Editor reloads in the background. Things get even faster when you execute code dynamically via the eval command. Here, the Pipeline package in the Editor acts like an instant translator, compiling your C snippet on the fly and slipping it directly onto Unity's main thread. Because this dynamic execution is entirely self-contained, it completely bypasses the project-wide recompile and domain reload process. You skip the tedious waiting entirely and get your results back in milliseconds. This means your heavy-duty automation scripts won't crash or lose their connection just because a massive project compile is happening in the background, while your quick terminal commands still fire with near-zero lag. You get stability and speed in the exact same tool. Moving from MCP to the Unity CLI You might be wondering, “What about the official Unity Model Context Protocol MCP server? Why shouldn't I just use or stick with that?” The short answer is that we’re not dropping the MCP support. However, the Unity CLI and Pipeline package handle all the same use cases as the MCP and more, but do them far better and faster. The longer answer comes down to architecture. Traditional MCP setups require an active client harness like Claude Desktop or Cursor to act as a translator between your AI agent and Unity. But modern, terminal-native agents like Claude Code are already incredibly good at running standard shell commands directly. By using direct CLI inputs like unity command or unity eval , you completely bypass the overhead of configuring and maintaining an MCP server. Your agent gets to talk straight to Unity over a unified, ultra-fast local HTTP server. This means you write cleaner configurations, spend less time debugging connection sockets, and can let your AI operate with pure, native terminal speed. Additionally, the legacy MCP server https://docs.unity.com/en-us/unity-cli/replace-mcp-server-unity-cli ran directly inside the Editor process as a C package. This meant the connection bridge itself was bound to Unity's main thread and memory space. The second you compiled code or triggered a domain reload, Unity flushed its memory, which frequently caused the connection socket to drop, throw null exceptions, or stall the agent mid-loop. The current com.unity.pipeline package is also a C package running inside the Editor, but it exposes an HTTP server and REST API not a socket bridge , which is why it's more resilient to domain reloads. Because this local server handles commands asynchronously, your terminal connection remains completely stable and active even during heavy compiles and domain reloads. In summary, by moving to the Unity CLI, you completely avoid dropped connections and wasted tokens. Finally, the CLI also offers an MCP mode if you have a specific use case you want to use MCP for. Installing the CLI and Pipeline package Installing the CLI and Pipeline packages is done automatically with the Unity Hub in the latest versions. At the time of writing, there are several ways to install Unity CLI, so make sure you refer to the documentation https://docs.unity.com/en-us/unity-cli/use-unity-cli for the latest source of truth. If you for some reason do not have it installed already, the simplest way is to use terminal commands for the installation process. You can watch the video or follow the instructions below. To install the Unity CLI, all you need to do is run the following commands from your terminal, depending on what platform you’re on: macOS or 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 The next step is to install the Unity Pipeline package: unity pipeline install Once both are installed, you can double check if they’re up and running. Verifying the installations To confirm your installation, simply run the following command: unity status It should return something like this: Unity Editor port 7800 : readyProject: /Users/thomaskr/Github/UnityProjects/MyAwesomeProjectVersion: 6000.6.0b7PID: 85009 If you see the ready state next to the first line, it means that the Editor is live and reachable. It also confirms what port the Editor is on, the Project path, Editor Version, and a process identifier PID . Next, to ensure your access has been authenticated, run the following command: unity auth login This will open your browser for OAuth sign-in to your Unity account. Once you authenticate, the CLI stores your credentials in the system keyring so future commands that need auth like unity projects list, unity build, unity license, unity cloud work automatically without re-prompting. Running a few basic commands With the CLI and Pipeline package installed, it's time to try a few more commands. Let’s start with the unity --help command, which gives you a quick overview of everything you can do. unity --help The unity --help command gives you a list of all the basic commands available with the overview and options available for each. The number of options might feel a bit overwhelming at first, but the CLI syntax follows a very logical, consistent pattern. Let's use a command we just used as an example, but this time with an option: unity auth login --non-interactive Starting left to right: - unity activates Unity CLI and is thus the main command. - auth login are the subcommands. You can think of them as verbs that tell the main program exactly what action to take. Here, auth directs the CLI to the authentication system, and login tells it to sign you in. - --non-interactive is the option. Think of options as similar to parameters. They’re modifiers that tell the command how to behave. In this case, it tells the CLI to log you in directly via the terminal rather than opening a visual browser window. Options are also sometimes referred to as “flags” when used in the context of on/off options. There’s also a single-letter shortcut designed for fast typing in your daily terminal workflow. Coming back to our help option --help , instead of running unity --help you can also just use unity -h , which both give you the same answer. unity --help Long flag version improved readbility unity -h Short flag version faster in day to day The short flags use the single dash - and are designed as a shortcut, while the long flags use the double dash -- and are the equivalent full-word descriptions designed for readability. The -- help command is the single most important tool in your toolkit; you can append it to literally any level of a nested command to get quick documentation. Here are a few examples for the authentication command we just covered: Help for authentication commands unity auth --help Help for the login command specifically unity auth login --help Every single help screen will instantly output exactly what the command does, what options are available, and what arguments it expects. When in doubt, just ask the command itself Let’s try the releases commands as another example: unity releases This gives me this nice overview of every version available for Unity at the time of writing. Now let’s add the --help option: unity releases --help The unity releases --help command gives you an explanation of all the various options you can add in order to narrow down your search for Unity versions. As an example, at the time of writing, we’re on a beta version of Unity 6.6b7 and want to install the latest beta. We can use the basic unity install command, which will give us a simple visual interface, where we can pick the version we want. unity install Let’s pick the b9 version, which will start the installer running in the background and will take a few minutes to complete . Rather than using the installation wizard, you could also just use the --help command to get an overview of all the commands: unity install --help This gives you an overview that looks like this: From the list, you can see that you’re able to pass the version of Unity you want to install as an argument. This means that if you had a specific version I wanted to install, you could do this in a single command using: Simply replace the version with the one you want to use unity install 6000.5.9f1 Meanwhile, our new version of the Editor has now been installed, so now we need to upgrade the project. To do this, add the specific version you want to open the project in. This would be the same as if you went into the Hub and chose another Editor version to open by project in triggering the upgrade project. unity open --version 6000.6.0b9 As we touched on earlier, the Pipeline package opens up a massive toolbox containing nearly everything you can do inside the Unity Editor and with new commands constantly being added as the beta matures . If you want to see what commands are available in your current project, run: unity list This command gives you a high-level table showing the name, group, and a short description for each command. It works great as a starting point to quickly browse through the hundreds of built-in commands such as eval , , add animator layer , and build find assets . When you need to know exactly how to format your inputs. You can run: unity command Running this with no arguments gives you the detailed “blueprint” of the Unity commands with documentation for every single registered command including options the exact flags and data types the command expects . Both commands talk to the same connected Editor process, but they return different levels of detail. As you begin building custom automation scripts or setting up agentic workflows that drive Unity under the hood, unity command will quickly become your most-referenced lookup tool for structuring clean, automated calls. Finally let’s wrap up by looking at the eval command and how to run a simple Debug.Log “Hello World” eval is a Pipeline package command and arguably the most exciting out of the 140+ built-in commands that dynamically compiles and executes C code in the Editor process. Try running the following command: unity command eval --code 'Debug.Log "hello from unity cli" ;' This gives you the following result where the JSON returns with "success": true if it worked. In the Editor, you can now verify this has indeed worked in the Console window. Let's break down the command: unity command eval --code 'Debug.Log "hello from unity cli" ;' Reading left to right: 1. unity runs the Unity CLI tool. 2. command is the subcommand that instructs it to "talk to a connected Editor". 3. eval is a sub-subcommand that says "evaluate run some code for me". 4. --code is an option or flag that says "here comes the code to run". 5. 'Debug.Log "hello from unity cli" ;' is the value for --code ; the actual code to execute. Connecting the LLM Familiarizing yourself with a few basic commands can help speed up some of the housekeeping with your Unity installs, but where it really shines is when you start automating and integrating your agentic workflows. With Unity CLI and the Pipeline package, you’re able to connect your agent of choice. Meaning whether you’re using Claude, Codex, Copilot, or local models etc., the CLI is designed to integrate with your existing, preferred setup and should connect without requiring any extra setup. Simply open a terminal, navigate using cd directly into your Unity project directory and start the agent by entering “claude” or your agent's command . You can confirm you’re connected by simply asking the agent something along the following lines: Run "unity command" in a bash and tell me what it can do, and then test a simple "eval" command Connecting the LLM using MCP Unity has deprecated the in-Editor MCP server https://docs.unity.com/en-us/unity-cli/replace-mcp-server-unity-cli in the com.unity.ai.assistant package. It’s been replaced by the Unity CLI’s built-in MCP server unity mcp , powered by the Unity Pipeline package. It uses the same protocol, so clients connect seamlessly. MCP mode remains fully supported for agents that can’t run arbitrary shell commands or struggle with command-line composition. To use MCP, run the following command: unity mcp configure This command automatically injects the configuration directly into your agent’s settings. To test if you LLM is connected, perform a small test prompting your LLM tool to run something similar to the following: I want you to create a 2 × 2 × 2 cube at the center of the scene I currently got open. Then create a script that makes it continuously rotate around all three axes at 45 degrees per second. Here is what Claude Code did responded: Once done, it should enter Play mode and run the scene so you can verify that the cube is rotating correctly. Extend with your own custom commands The CLI's built-in suite covers all the basics like toggling Play mode, recompiling, and running unit tests. However, the real power of this architecture lies in its extensibility. You can easily write custom commands to provide your AI agents with tailored, project-specific context and unique tools built just for your game. Creating a custom command is very straightforward. All you need to do is write a standard static C method and decorate it with the CliCommand and CliArg attributes. The Pipeline package automatically discovers these attributes during compilation, meaning it requires zero manual configuration or registration files. When you run unity command with no arguments, the CLI dynamically lists all available custom commands alongside the built-ins. Note: The CliCommand attribute makes commands discoverable and invocable via the CLI. For parameterized execution, you call the method directly using unity command eval with C syntax, rather than passing CLI-style flags. Let's look at a quick "Hello World" custom command in action. Create a new C script named HelloWorldCommand.cs . Make sure the class and method are static, and include the Unity.Pipeline.Commands namespace: using UnityEngine; using Unity.Pipeline.Commands; public static class HelloWorldCommand { CliCommand "hello-world", "A simple hello world command" public static void SayHello { Debug.Log "Hello, World This is a custom CLI command." ; } } To run your new command, fire up your terminal and execute the following command: unity command hello-world The terminal should look something like this And your console log should like this: You could also expand the feature if you need to pass parameters using the CliArg attribute. using UnityEngine; using Unity.Pipeline.Commands; public static class HelloWorldCommand { CliCommand "hello-world", "A simple hello world command" public static void SayHello CliArg "name", "Who to greet" string name { Debug.Log $"Hello, {name} This is a custom CLI command." ; } } To run your new command, fire up your terminal and execute: unity command hello-world --name "thomas" Installing the Unity Agent plugin Unity also offers an official game development plugin https://github.com/Unity-Technologies/unity-agent-plugin , which at the time of writing is available for Claude Code, Codex, and Grok. It ships curated skills for game development and performance optimization. Once installed, the skills load automatically when you work on a Unity project in any of the above. To install it for Claude, simply run this command: claude plugin marketplace add Unity-Technologies/unity-agent-plugin github.com/Unity-Technologies/unity-agent-plugin Another quick tip if you are a Claude Code user and starting a new project is to run the initialization phase which sets up Claude with basic context about your project by creating a claude.md https://claude.md file. It’s a markdown file that lives in the root of your Project folder that Claude Code reads at the start of every session. /init Run this command inside Claude Code That way you can use it to let Claude know about your preferred tech stack, like perhaps you prefer uGUI over UI Toolkit as UI, the newer Input System over the older Input Manager etc. It could also be used for architecture decisions like using a service locator pattern over singletons, MVP for your UI design etc. While Claude also builds auto memory as it works, saving learnings across sessions without you writing anything, the Claude.md file helps guide the overall direction of the specific project. As you progress through the process, you can consider adding more custom instructions such as your code style guide. I wrote an article https://discussions.unity.com/t/create-your-own-custom-instructions-for-unity-ai/1731678/2 about how this works for the custom instructions in the AI assistant, but the principles are exactly the same for Claude Code if you’re interested in learning more. What’s next We hope this was a helpful introduction to help you get started. If you’re interested in optimizing your agentic workflow further, check out the article on setting up custom instructions https://discussions.unity.com/t/create-your-own-custom-instructions-for-unity-ai/1731678 for your LLM including defining a Unity C code style guide https://github.com/krogh-jacobsen/unity-code-style-guide . Check out the video here: