Unity CLI: What Is Unity CLI?

A First Look at Unity’s Terminal-Native Workflow for Developers, Automation, and AI Agents

Important: Unity CLI is currently a beta product, and some operations can modify or damage a Unity project. Before using any commands shown in this article, make sure your project is properly backed up and under version control. The complete beta and project-safety notice appears at the end of this article.

Introduction

Unity development has traditionally centered on two graphical applications. Unity Hub manages Editor installations, modules, licenses, and projects, while the Unity Editor provides the visual environment in which developers create scenes, write scripts, import assets, configure builds, and test their games.

Command-line tools have always existed around that workflow, but they have generally been divided among several different systems. Developers could run Unity Hub in a headless mode, launch a specific Unity Editor executable with command-line arguments, write shell scripts around batch-mode builds, or use the separate Unity Gaming Services command-line interface to configure cloud services.

Unity CLI introduces a more unified approach.

Announced in connection with Unite Seoul 2026, Unity CLI is a new standalone command-line application that gives developers a terminal-native way to manage Unity Editors, modules, projects, authentication, builds, tests, licensing, and automation. It can also connect to a running Unity Editor or development build through the experimental Unity Pipeline package. Unity describes the combination as an execution surface for scripts, continuous integration systems, custom tools, and AI agents. (Unity)

This means Unity CLI is not merely a shorter way to open the Unity Editor. It represents a broader attempt to make Unity controllable from tools outside the Editor.

A developer could use Unity CLI to install the correct Editor version on a new computer. A continuous integration server could use it to prepare a build machine, authenticate, run tests, and produce a build. A studio could expose project-specific commands that validate scenes or inspect assets. An AI agent could potentially discover those commands, inspect a running project, make a controlled change, and verify the result.

In this introductory article, you will learn:

• What Unity CLI is
• Why Unity created a new command-line tool
• How its three major layers fit together
• What kinds of Unity tasks it can perform
• How it differs from Unity Hub, the older Hub CLI, Editor command-line arguments, and the UGS CLI
• Why structured output matters for automation and AI systems
• What Unity CLI may mean for future Unity development workflows
• Why its beta status requires additional care

This article provides a broad overview rather than a complete installation guide. Installation, project management, builds, tests, custom commands, live C# evaluation, and AI-agent integration will each receive more detailed treatment later in this series.

A New Command-Line Entry Point for Unity

The term CLI stands for command-line interface. A command-line interface lets a user interact with an application by typing commands into a terminal rather than selecting controls in a graphical interface.

On Windows, this generally means working in PowerShell or Windows Terminal. On macOS, developers commonly use Terminal with Zsh. On Linux, Bash and other shells are common.

After Unity CLI is installed and added to the operating system’s PATH, its commands begin with the word unity.

For example:

unity --help

This asks Unity CLI to display its top-level help information.

The command is intentionally simple. Instead of invoking a long path to Unity Hub or a particular Unity Editor executable, the user works through a single unity command.

Unity describes Unity CLI as a self-contained binary. It can be installed and run without installing the Unity Hub desktop application, making it appropriate for developer workstations, scripts, headless build machines, and continuous integration environments. The first public beta provided binaries for Windows, macOS, and Linux on both x64 and Arm64 architectures. (Unity Documentation)

The CLI can also update itself:

unity upgrade

Its installed version can be inspected with:

unity --version

Those commands may appear modest, but the important change is organizational. Unity now has a dedicated command-line product rather than requiring developers to treat the graphical Unity Hub or the Unity Editor executable as the primary entry point for every automated workflow.

Why Unity Created A New CLI

Modern development work increasingly happens outside graphical applications.

Builds run on remote servers. Tests execute automatically when code is pushed to a repository. Teams provision development machines through scripts. Docker containers and cloud workers may not have graphical desktops. AI coding tools work most effectively when they can call commands and receive structured results.

The older Unity Hub headless interface could install Editors and modules, but it remained part of the larger Unity Hub desktop application. Unity says the new native CLI starts more quickly than the old Hub headless path, which matters when a script or automated agent makes many calls during a single job. (Unity)

Unity CLI is designed specifically for automation. It separates successful output from errors, supports machine-readable formats, offers non-interactive operation, and returns exit codes that scripts can evaluate. It also supports service-account authentication for unattended systems. (Unity)

Those features make the tool useful in several different situations:

• A developer wants to create or open projects without navigating Unity Hub.
• A studio wants every build machine configured identically.
• An educator needs to prepare multiple classroom computers.
• A continuous integration server needs to install the required Editor and modules.
• A test system needs to run Edit Mode or Play Mode tests.
• A custom tool needs to communicate with a running Editor.
• An AI agent needs a predictable way to observe and operate a project.

Unity CLI does not eliminate every graphical workflow. Unity Hub and the Unity Editor remain useful applications. The CLI instead provides another route into the same development environment — one designed for repeatable commands rather than manual interaction.

Understanding The Three Layers

A useful way to understand Unity CLI is to divide it into three layers:

1. The standalone Unity CLI
2. The Unity Pipeline package
3. Live C# evaluation

Unity uses similar language in its announcement, describing the CLI as the layer that manages Unity, the Pipeline package as the layer that drives it, and eval as the layer that reaches inside it. (Unity)

Each layer adds a different level of access.

Layer One: The Standalone Unity CLI

The first layer is the unity executable installed on the computer.

This layer handles tasks that can be performed from outside a running Unity project. These include installing Editor versions, adding modules, managing project records, opening projects, authenticating, checking licenses, running builds, executing tests, and diagnosing the local environment.

A few representative commands include:

unity editors
unity projects
unity auth status
unity license status
unity doctor

These examples illustrate the command structure:

unity <command> <subcommand> <options>

The exact commands available depend on the installed beta version. Unity warns that the locally installed help output should be treated as the authoritative command list because new commands and options may appear before the online reference has been updated. (Unity Documentation)

You can inspect the top-level command list with:

unity --help

You can inspect a specific command with:

unity editors --help

For commands with additional subcommands, help can be requested at a deeper level:

unity editors add --help

This pattern is worth learning early because Unity CLI is evolving quickly.

Layer Two: The Unity Pipeline Package

Managing installations and project files from outside the Editor is only part of the system.

The second layer is the experimental com.unity.pipeline package. When installed in a Unity project, this package allows Unity CLI to communicate with a running Unity Editor through a local HTTP API.

Unity describes the Pipeline package as a way to automate builds, tests, development workflows, and project-specific commands. It requires Unity 6.0 or later. (Unity Documentation)

The package can be installed with:

unity pipeline install

A developer can then inspect connected projects and Pipeline status:

unity pipeline list

When a compatible Unity Editor is running, the following command asks it to report the commands it exposes:

unity command

If several Editor instances are open, a specific project can be selected:

unity command --project-path="/path/to/MyProject"

The crucial distinction is that the Pipeline command list is not necessarily fixed.

A Unity project can define its own commands in C#. A studio might expose commands such as:

validate-scenes
find-missing-references
build-addressables
inspect-prefabs
capture-game-view
run-smoke-test

Those operations would be specific to the needs of that project or team.

Unity’s introductory example exposes a static C# method by applying the [CliCommand] attribute:

using Unity.Pipeline.Commands;
using UnityEngine;

public static class ProjectCommands
{
    [CliCommand(
        "greet",
        "Log a greeting and return its length")]
    public static int Greet(
        [CliArg(
            "name",
            "The person to greet",
            Required = true)]
        string name)
    {
        Debug.Log($"Hello, {name}!");
        return name.Length;
    }
}

The command can then be invoked from the terminal:

unity command greet --name World

The Pipeline package discovers attributed commands automatically rather than requiring every method to be added to a separate central registry. (Unity)

This is an important extension point. Instead of asking external tools to manipulate project files directly, a team can provide carefully designed commands that perform approved Unity operations.

Layer Three: Live C# Evaluation

Custom Pipeline commands are useful when a developer knows in advance which operations should be available.

There will also be situations in which a developer, diagnostic script, or agent needs to ask a question that was not anticipated when the project commands were written. For those cases, Unity CLI includes live C# evaluation.

Unity’s announcement demonstrates commands such as:

unity command eval "return Application.version;"

Another example checks whether the Editor is currently in Play Mode:

unity command eval \
    "return UnityEditor.EditorApplication.isPlaying;"

A longer C# script can be placed in a file:

unity command eval_file "Scripts/InspectScene.cs"

Unity says the code is compiled with Roslyn and executed on the Unity main thread. Because it runs inside the connected Unity instance, it can reach the Unity APIs available to the project. Unity also says this evaluation does not require the normal project-level recompilation and domain reload cycle. Access is protected by a security token because arbitrary C# execution is extremely powerful. (Unity)

The beta release notes also describe a shorter form:

unity eval '<expression>'

This is an example of why version-specific help is important. Command names and shortcuts may shift during the beta, and different official pages may show different forms while the tool is evolving. (Unity Documentation)

Live evaluation could be used for inspection:

return Object.FindObjectsByType<Rigidbody>(
    FindObjectsSortMode.None).Length;

It could also be used to change a project or running scene. That makes eval one of the most useful—and potentially most dangerous—parts of Unity CLI.

A later article in this series will examine eval in detail, including safe inspection techniques, security tokens, Editor targeting, runtime targeting, and the reasons narrowly defined custom commands may be preferable to unrestricted C# execution.

What Unity CLI Can Manage

The initial Unity CLI documentation emphasizes Editor installation, modules, project opening, and authentication. The beta release notes reveal a broader and rapidly expanding command set.

As of the most recently documented beta release available while this article was prepared, Unity CLI includes capabilities in the following areas. (Unity Documentation)

Area -> Representative Capabilities

Editor Management
- Install, list, register, locate, select, update, and remove Unity Editors

Module Management
- Discover and install Android, iOS, WebGL, and other platform modules

Project Management
- Create, register, open, clone, pin, export, import, inspect, and upgrade projects

Templates
- List official templates and create reusable custom project templates

Authentication
- Sign in interactively or use service-account credentials

Licensing
- Inspect, activate, return, and diagnose Personal, serial, offline, and floating licenses

Source Control
- Clone projects and link GitHub, GitLab, or Unity Version Control repositories

Unity Cloud
- Inspect organizations and link local projects to Unity Cloud projects

Builds
- Run automated builds and configure platform-specific options

Testing
- Run Edit Mode and Play Mode tests and generate NUnit reports

Diagnostics
- Inspect environment settings, logs, proxies, authentication, and installation state

Pipeline Commands
- Execute built-in or custom commands inside a connected Editor

Live Evaluation
- Compile and execute C# against a connected Editor or development Player

Extensibility
- Discover additional executables named with the unity-<name> convention

Not every user will need every command.

A solo developer may primarily use Editor installation, project opening, diagnostics, and simple build commands. A larger studio may focus on source-control integration, service accounts, testing, build pipelines, and custom commands. An AI-tool developer may concentrate on structured output, Pipeline discovery, eval, and MCP compatibility.

The breadth of the command set is one reason Unity CLI should be viewed as a development platform rather than a simple installer.

Managing Editors And Modules

One of the most immediately understandable uses of Unity CLI is Editor management.

A developer can install the latest long-term support release with a version alias:

unity install lts

A specific Editor can be installed by using its complete version:

unity install 6000.3.7f1

Modules can be requested during installation:

unity install lts -m android ios webgl

Modules can also be added to an existing compatible Editor:

unity install-modules \
    -e 6000.3.7f1 \
    -m android ios

Unity’s documentation notes that module installation applies to Editors installed through Unity Hub or Unity CLI. A manually installed Editor may need to be reinstalled or properly registered before the CLI can manage its modules. (Unity Documentation)

Installed Editors can be listed with:

unity editors --installed

The exact shorthand and output may vary by beta. Before relying on a command in an automated script, inspect its current options:

unity editors --help

These installation workflows will be the focus of later articles covering Windows, macOS, and Linux.

Managing Projects

Unity CLI can also manage projects.

A project can be opened by path:

unity open ./MyProject

The open keyword can be omitted when the first argument is a project path:

unity ./MyProject

Unity CLI reads the project’s configuration and attempts to open it with the appropriate Editor version. (Unity Documentation)

Later beta releases added project creation, cloning, source-control linking, custom templates, project upgrades, and module requirement checks.

Representative examples include:

unity projects new MyGame \
    --template <template-id> \
    --editor-version <editor-version>

unity projects clone <repository>

unity projects upgrade ./MyGame \
    --to <editor-version>

These commands demonstrate why project backups are essential. An installation-listing command is largely observational. A project-upgrade command may rewrite serialized project data, update settings, or trigger package and API migrations.

Project management will receive its own article because these operations deserve more preparation than a simple copy-and-paste command.

Running Builds And Tests

Unity CLI includes higher-level commands for builds and tests.

A build may begin with:

unity build

Tests may be run with:

unity test ./MyProject

The test command supports Edit Mode and Play Mode execution through the Unity Test Framework. It can also generate NUnit XML output for use in continuous integration systems:

unity test ./MyProject \
    --mode editmode \
    --output test-results.xml

Unity CLI beta 0.1.0-beta.7 added a dedicated exit code for the case in which test execution completes but one or more tests fail. That distinction lets an automated system tell the difference between a test failure and a failure to run the test process itself. (Unity Documentation)

Build functionality includes versioning and platform-specific options. The release notes describe Git-derived build versions, dirty-working-tree checks, Android signing options, APK and Android App Bundle output, target SDK configuration, and symbol generation. (Unity Documentation)

The implementation details will be covered later in this series. At the introductory level, the important point is that Unity CLI is not limited to installing Editors. It is becoming a common front end for complete automation workflows.

Built For Structured Automation

A command-line tool becomes much more useful when its output is predictable.

Text designed for a person can be difficult for another program to interpret. Decorative headings, changing table widths, progress animations, and localized messages may look attractive in a terminal but create problems for scripts.

Unity CLI supports human-readable output as well as structured formats.

For example:

unity editors --format json

The same information can be requested as tab-separated values:

unity editors --format tsv

Long-running operations can use newline-delimited JSON:

unity build --format ndjson

Standard JSON is appropriate when a command returns one completed result. NDJSON is useful when a process needs to stream a sequence of progress events while work continues.

Unity’s beta release notes describe a standardized JSON envelope containing fields such as:

{
  "success": true,
  "command": "editors",
  "data": [],
  "errors": [],
  "warnings": []
}

The exact contents of data depend on the command, but the consistent outer structure makes results easier for scripts and external tools to process. (Unity Documentation)

Unity also separates normal results from errors:

• Successful results are written to stdout.
• Errors are written to stderr.
• Exit codes communicate whether the command succeeded or failed.

Unity’s announcement gives a basic contract of 0 for success, 1 for an error, and 130 for cancellation. Later releases add more specific exit codes for authentication, networking, usage errors, conflicts, and failed test results. (Unity)

A simple Bash or Zsh script can respond to an exit code:

unity test ./MyProject

if [ $? -ne 0 ]; then
    echo "Unity tests did not succeed."
    exit 1
fi

A PowerShell script can perform a similar check on Windows:

unity test .\MyProject

if ($LASTEXITCODE -ne 0) {
    Write-Error "Unity tests did not succeed."
    exit $LASTEXITCODE
}

Production scripts should generally do more than these introductory examples. They should preserve logs, distinguish different exit codes, validate expected files, and avoid continuing after an unsafe failure.

The larger idea is that the same qualities that make Unity CLI suitable for continuous integration also make it suitable for AI agents. Both need clear commands, structured results, and dependable error reporting.

Interactive And Non-Interactive Workflows

A person using Unity CLI in a terminal may be able to answer prompts.

For example, an installation command could ask the user to confirm a license agreement, select an architecture, or choose from available versions.

A continuous integration worker cannot reliably respond to those questions. It needs a non-interactive mode in which every required decision has been specified in advance.

Unity CLI includes global options and environment variables for unattended operation. Depending on the command and beta version, these can include options such as:

--non-interactive
--yes
--quiet
--no-banner

An unattended installation may also accept license agreements through command options:

unity install <version> \
    -m android \
    --accept-eula \
    --yes

Service-account credentials can be supplied through environment variables so a headless machine does not require a person to complete a browser login. Unity’s release notes name the following variables:

UNITY_SERVICE_ACCOUNT_ID
UNITY_SERVICE_ACCOUNT_SECRET

These values should be stored through the secret-management system provided by the continuous integration platform. They should not be committed to a public repository or written directly into an ordinary script.

Unity CLI And Unity Hub

Unity CLI and Unity Hub overlap, but they are not the same product.

Unity Hub is a graphical desktop application. It gives users visual controls for installing Editors, adding modules, viewing projects, managing licenses, and starting the Editor.

Unity CLI is a standalone terminal application. It can perform many related operations without launching the Hub interface.

Unity’s documentation describes Unity CLI as the recommended tool for new scripts, automation, and CI pipelines. The older Hub CLI is deprecated beginning with Unity Hub 3.18.0 and receives minimal support. (Unity Documentation)

The older Hub command-line workflow required the Unity Hub executable to be launched in headless mode. A command often began with a long application path followed by special headless arguments.

Conceptually, the older approach resembled:

<Unity Hub executable> -- --headless <operation>

The newer approach is:

unity <operation>

For example:

unity install lts

This does not mean Unity Hub becomes useless.

Many developers will continue to prefer the visual project list and installation controls. Unity CLI may coexist with Unity Hub on the same workstation. Some beta releases have added shared authentication and configuration behavior between the two tools. (Unity Documentation)

The practical distinction is based on workflow:

• Use Unity Hub when a person wants a graphical interface.
• Use Unity CLI when a person, script, server, or agent needs a repeatable command.

Unity CLI Is Not The Traditional Editor Command Line

Unity developers have long been able to launch the Unity Editor executable with command-line arguments.

A traditional Windows command may resemble:

& "C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" `
    -batchmode `
    -projectPath "C:\Projects\MyGame" `
    -quit

On macOS, a comparable command points to the executable inside the Unity application bundle:

"/Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity" \
    -batchmode \
    -projectPath "/Projects/MyGame" \
    -quit

On Linux, the command points to the installed Editor executable:

/path/to/Unity \
    -batchmode \
    -projectPath "/projects/MyGame" \
    -quit

These commands launch a particular Unity Editor and pass arguments directly to that Editor process. They remain useful for batch mode, custom execute methods, log configuration, graphics settings, and specialized startup behavior. Unity’s Editor documentation continues to describe launching Editor and Player applications with command-line arguments. (Unity Documentation)

Unity CLI operates at a higher level.

Instead of requiring a script to know the complete executable path, Unity CLI can resolve an installed Editor version, inspect a project, open the correct Editor, run a build, or invoke Pipeline commands.

The two systems may work together. Unity CLI does not necessarily make every traditional Editor argument obsolete. Some advanced workflows may still pass arguments through to the Editor.

Unity CLI Is Not The UGS CLI

Unity also has a separate command-line product called the Unity Gaming Services CLI, commonly called the UGS CLI.

The UGS CLI manages configuration for services such as Cloud Code, Economy, Remote Config, and other Unity Gaming Services. It is designed as an automatable alternative to performing those operations through the Unity Dashboard. (Unity Documentation)

The distinction can be summarized as follows:

ToolPrimary PurposeUnity CLIManage Editors, projects, builds, tests, licensing, Pipeline commands, and connected Unity instancesUnity Hub CLIOlder headless interface contained within Unity Hub; now deprecatedUnity Editor ArgumentsConfigure and control a particular Editor or Player process at startupUGS CLIManage and deploy Unity Gaming Services configurationUnity Pipeline PackageLet Unity CLI communicate with a running Editor or development Player

Because several products include the letters “CLI,” technical articles should name the exact tool being discussed.

In this series, Unity CLI refers to the new standalone unity binary unless another tool is explicitly identified.

Cross-Platform Development

Unity CLI is intended for Windows, macOS, and Linux.

The commands generally use the same unity syntax on all three systems:

unity --help
unity --version
unity editors

The surrounding shell syntax may differ.

Windows PowerShell

PowerShell uses its own environment-variable syntax:

$env:UNITY_FORMAT = "json"
unity editors

Paths commonly use backslashes:

unity open "C:\UnityProjects\MyGame"

PowerShell can also use forward slashes in many circumstances, but Windows examples should avoid assuming that Bash syntax will work unchanged.

macOS Terminal

Modern macOS installations commonly use Zsh:

export UNITY_FORMAT=json
unity editors

A project path might resemble:

unity open "/Users/lem/UnityProjects/MyGame"

Linux Terminal

Linux examples commonly use Bash:

export UNITY_FORMAT=json
unity editors

A project path might resemble:

unity open "/home/lem/UnityProjects/MyGame"

The Unity CLI command is largely consistent, but installation permissions, shell configuration, secure credential storage, executable locations, and available build modules can differ among operating systems.

Unity’s first beta release used the macOS Keychain, Windows Credential Manager, and libsecret on Linux for secure authentication-token storage. (Unity Documentation)

Later articles will provide platform-specific instructions where those differences matter.

Connecting To A Running Editor

The Pipeline package changes Unity CLI from a project-management utility into an Editor-control system.

Without Pipeline, Unity CLI can install an Editor, inspect projects, open a project, and invoke high-level automated operations.

With Pipeline, a running Editor can receive requests and report the commands it exposes.

The basic discovery command is:

unity command

This is significant because the Editor becomes partially self-describing.

An external script does not necessarily need a permanently hardcoded list of project operations. It can ask the project which commands are currently available.

A project might report something conceptually similar to:

greet
validate-scenes
find-missing-scripts
capture-game-view
run-project-smoke-test

A developer could then call one of those commands:

unity command validate-scenes

The result could be returned in a structured form suitable for a terminal, build pipeline, dashboard, or agent.

This creates a boundary between external automation and internal Unity APIs. The external caller requests a named operation. The Unity project decides how that operation is implemented.

Connecting To Development Builds

The Pipeline package can also be included in a development Player build.

Unity says a running development build can expose commands through a local interface. Unity CLI can target that Player to read logs, inspect runtime status, modify game state, or support automated testing. The runtime interface is described as localhost-only, disabled by default, and intended for development and quality-assurance builds rather than production releases. (Unity)

A runtime-targeting command may resemble:

unity command \
    --runtime <player-executable-name>

This opens several interesting possibilities:

• Automated playtesting
• Runtime smoke tests
• Live state inspection
• Development-build diagnostics
• Verification after a build is launched
• Reproduction of difficult gameplay defects

A test system could theoretically build a game, launch it, connect to the running Player, trigger a controlled scenario, inspect the result, and report whether the expected behavior occurred.

That is more advanced than traditional compile-and-build automation because the system can continue observing the application after it starts running.

Unity CLI And AI Agents

Unity’s announcement places considerable emphasis on AI-assisted development.

Get Lem Apperson’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

An AI coding assistant can already generate C# scripts or suggest changes. The difficult part has often been everything that follows:

• Opening the correct project
• Waiting for Unity to compile
• Reading errors
• Running tests
• Entering Play Mode
• Inspecting the scene
• Confirming whether a change worked
• Repeating the process after a failure

Unity CLI and the Pipeline package provide an execution layer through which an agent can perform some of those tasks.

Unity describes an observe-act-verify loop:

1. Observe the project.
2. Decide what action to take.
3. Execute a command or C# expression.
4. Read the result.
5. Verify whether the problem was resolved.
6. Continue if necessary.

The announcement demonstrates an agent receiving a report that a player sometimes falls through the floor. The agent inspects the live scene, discovers a collider disabled at runtime, re-enables it, returns to Play Mode, and checks the result. (Unity)

The important technical features are not unique to AI:

• Structured output
• Predictable exit codes
• Command discovery
• Project-specific commands
• Live Editor access
• Runtime access
• Fast C# evaluation

Those are also valuable to ordinary automation scripts and continuous integration systems.

AI agents are simply another kind of external caller.

Bring Your Own Agent

Unity says the CLI is intended to work with a range of existing assistants and models, including Claude, Codex, Copilot, and local models. The agent provides the reasoning layer. Unity CLI and Pipeline provide the execution layer. (Unity Discussions)

This distinction matters.

Unity CLI is not itself a large language model. It does not independently understand a project requirement or invent a game mechanic.

Instead, it exposes operations that another system can call.

The relationship can be represented like this:

Developer Request
       |
       v
AI Agent Or Automation Script
       |
       v
Unity CLI
       |
       v
Unity Pipeline Package
       |
       v
Unity Editor Or Development Player
       |
       v
Project Code And Unity APIs

A human-written script may call the same commands as an AI agent. The difference is how the caller chooses what to do next.

Unity CLI And MCP

MCP stands for Model Context Protocol. It is a protocol used to expose tools and contextual information to compatible AI agents.

Unity has said that the existing Unity MCP remains supported and that Unity CLI includes an MCP mode for developers using MCP-based agents. Unity representatives have directed users to:

unity mcp --help

Unity has also said that the CLI-based MCP implementation is built on the new Pipeline package. According to Unity’s official discussion, this newer approach is intended to improve performance, Editor-focus handling, domain-reload handling, and communication with multiple Editor instances. (Unity Discussions)

MCP is not required for every Unity CLI workflow.

A developer can call Unity CLI commands directly from:

• A terminal
• A Bash script
• A Zsh script
• PowerShell
• Python
• A continuous integration system
• A custom desktop application
• An AI tool capable of running shell commands

MCP provides a standardized agent-tool connection, but the underlying CLI remains useful without it.

Later in this series, the MCP and agent article will compare direct command execution with MCP-based tool exposure.

Why Custom Commands Matter

Live C# evaluation attracts attention because it can reach a large portion of Unity’s API surface. However, unrestricted access is not always the best design for a production workflow.

A custom command creates a controlled contract.

Consider a hypothetical command:

unity command validate-release-scenes

Internally, that command might:

1. Load the scenes included in the release build.
2. Search for missing scripts.
3. Check required lighting settings.
4. Verify that no development-only GameObjects are enabled.
5. Return a structured report.
6. Avoid changing any project content.

The caller does not need to understand how those checks work. It only needs to know the command name, arguments, and return structure.

A studio could expose a small set of approved operations:

inspect-project
validate-scenes
run-tests
create-development-build
capture-screenshot

It could withhold more dangerous operations from ordinary automation.

This approach provides several advantages:

• The command behavior can be reviewed in source control.
• Input arguments can be validated.
• Errors can be handled consistently.
• The command can be tested independently.
• The command can restrict what an external caller is allowed to modify.
• The same command can be used by people, scripts, CI systems, and AI agents.

Custom commands will receive a dedicated article later in the series.

An Introductory Command Tour

This article does not provide the full installation process, but it is useful to recognize several basic commands.

After installing Unity CLI, begin with:

unity --version

This displays the installed CLI version.

Next, inspect the authoritative help:

unity --help

View the release history associated with the installed tool:

unity changelog

Check the local environment:

unity doctor

List Editors:

unity editors

Check authentication:

unity auth status

Check licensing:

unity license status

Inspect registered projects:

unity projects

When using structured output, request JSON:

unity editors --format json

When Pipeline is installed and a compatible Editor is running, inspect available commands:

unity command

Before using any unfamiliar operation, read its help:

unity <command> --help

For example:

unity projects upgrade --help

Reading help before executing a project-changing command should become a normal part of the workflow.

What Unity CLI Does Not Yet Guarantee

Unity CLI is experimental.

Unity’s documentation states that features and documentation may change in upcoming releases. It also warns that Unity CLI may not yet contain every feature available in the Unity Hub interface. (Unity Documentation)

During a beta period, developers should expect:

• Command names to change
• Options to be renamed
• Output structures to evolve
• New commands to appear
• Existing commands to be removed or reorganized
• Documentation to lag behind the installed release
• Platform-specific bugs
• Differences among beta versions
• Incomplete integration with some Unity workflows

The release history illustrates the pace of change. Between the first public beta in April 2026 and beta.7 in June 2026, Unity added diagnostics, custom templates, builds, tests, Pipeline commands, eval, licensing, source-control integration, Cloud integration, proxy support, service accounts, new output formats, and expanded project management. (Unity Documentation)

Code examples written for one beta may not remain correct indefinitely.

For that reason, every article in this series will identify the CLI, Editor, Pipeline, operating-system, and shell versions used during testing. Readers should compare those versions with their own environments.

The Potential For Project Damage

A terminal command can be executed more quickly than the same operation can be reviewed visually.

That efficiency creates risk.

Unity CLI can run project upgrades, alter source-control associations, install packages, start builds, invoke custom project code, and execute C# inside a running Unity Editor. Depending on the command, it may affect:

• Project settings
• Package dependencies
• Assets
• Scenes
• Prefabs
• Build profiles
• Source-control configuration
• Generated files
• Editor installations
• Platform modules
• Licenses
• Runtime state

A command does not need to be intentionally destructive to create an unwanted result.

For example, upgrading a project to a newer Editor may update serialized data. An evaluated C# expression may save a changed scene. A custom command may modify assets. An AI agent may interpret an instruction too broadly.

All important projects should be committed and pushed to a remote repository before Unity CLI experiments begin.

The safest environment is:

Disposable Project Copy
        Or
Clean Experimental Branch
        Plus
Verified Remote Backup

The full safety notice appears at the end of this article and will be included at the end of every article in the series.

Who Should Pay Attention To Unity CLI

Unity CLI may be useful to several different groups.

Solo Developers

A solo developer can use the CLI to reproduce a development environment, inspect installed Editors, automate tests, and reduce repeated setup tasks.

Teams And Studios

A team can standardize Editor versions, required modules, project setup, build processes, test execution, and validation commands.

Build And Release Engineers

Build engineers can integrate structured Unity operations into continuous integration and delivery systems without depending on graphical interaction.

Tool Developers

Tool developers can expose project-specific operations to external applications or create terminal-based utilities around Unity workflows.

Educators

Educators can automate classroom setup, verify installed versions, distribute project templates, and check whether student machines have the required modules.

Quality-Assurance Teams

QA systems can run automated tests, launch development builds, inspect runtime status, gather logs, and trigger controlled test scenarios.

AI-Workflow Developers

Developers experimenting with Claude, Codex, Copilot, local models, or other agents can give those systems a structured path into Unity.

The value of Unity CLI will differ among these groups, but they share one requirement: Unity operations need to be repeatable, observable, and scriptable.

A Practical Mental Model

When first encountering Unity CLI, it may help to remember this simplified model:

Unity CLI
Manages the Unity environment.

Unity Pipeline
Connects the CLI to a running Editor or development Player.
Custom Commands
Expose planned project-specific operations.
Eval
Executes unplanned C# inspection or actions.
MCP
Connects compatible AI agents to the available tools.

Another useful summary is:

Install And Configure
        |
        v
Open And Manage
        |
        v
Build And Test
        |
        v
Connect To The Editor
        |
        v
Inspect And Control
        |
        v
Automate And Verify

The first public beta already reaches across this entire sequence, although individual parts remain experimental and are likely to evolve.

Where This Series Goes Next

This introductory article has focused on what Unity CLI is and how its major parts fit together.

The remaining articles in the series will move from concepts to practical workflows:

1. Installing Unity CLI on Windows, macOS, and Linux
2. Managing Unity Editors and platform modules
3. Creating, cloning, opening, and upgrading projects
4. Writing dependable Unity CLI automation scripts
5. Running builds, tests, authentication, and licensing workflows
6. Connecting Unity CLI to a running Unity Editor
7. Creating project-specific CLI commands in C#
8. Using live C# evaluation safely
9. Connecting AI agents and MCP-based tools to Unity

Each article will use small, focused examples. Potentially destructive operations will be performed only after preparing version control and a recoverable test environment.

Wrap-Up

Unity CLI is Unity’s new standalone terminal interface for managing and automating Unity development. It can install Editors, add modules, manage projects, authenticate users and services, inspect licenses, run builds, execute tests, and produce structured output for scripts and continuous integration systems.

The experimental Unity Pipeline package extends the CLI into a running Unity Editor or development Player. Projects can expose custom C# methods as named commands, allowing external tools to perform operations designed specifically for that project.

Live C# evaluation extends the system further by allowing code to be compiled and executed inside a connected Unity instance without the normal project-level compilation and domain-reload cycle. This creates a fast feedback loop, but it also introduces substantial risk if commands are not reviewed and projects are not backed up.

Unity CLI is also designed as an execution layer for AI-assisted development. Agents can discover available commands, call project-specific tools, inspect structured results, and potentially verify their own work. MCP compatibility provides another route for connecting compatible agents, while ordinary scripts can call the same operations directly.

The central lesson is that Unity CLI is not simply a replacement for a few Unity Hub commands. It is an emerging automation interface that spans installation, project management, testing, builds, Editor control, runtime access, custom tooling, and agent workflows.

It is also beta software. The capabilities are promising, but the commands, documentation, and behavior remain subject to change. Developers should begin with disposable projects, clean experimental branches, and verified backups.

The next article will cover installing Unity CLI on Windows, macOS, and Linux, verifying the installation, inspecting its help system, updating or rolling back the CLI, and diagnosing common environment problems.

Further Reading

Meet The Unity CLI: Manage Unity From Your Terminal
https://unity.com/blog/meet-the-unity-cli

Unity Command-Line Interface Documentation
https://docs.unity.com/en-us/unity-cli

Use The Unity Command-Line Interface
https://docs.unity.com/en-us/unity-cli/use-unity-cli

Unity CLI Command Reference
https://docs.unity.com/en-us/unity-cli/unity-cli-reference

Unity CLI Release Notes
https://docs.unity.com/en-us/unity-cli/release-notes

Unity Pipeline Package
https://docs.unity.com/en-us/unity-production-pipeline/local-tools-cli/unity-pipeline-package

Unity Hub And Unity CLI Overview
https://docs.unity.com/en-us/hub/cli-overview

Unity Gaming Services CLI
https://docs.unity.com/en-us/services/ugs-cli-introduction

Unity Editor Command-Line Arguments
https://docs.unity3d.com/Manual/CommandLineArguments.html

Unity CLI Announcement Discussion
https://discussions.unity.com/t/announcing-the-unity-cli-a-new-way-to-connect-your-tools-and-agents/1731104

Unity CLI Beta And Project-Safety Notice

Unity CLI is currently a beta product. Its commands, options, package requirements, installation procedures, output formats, and behavior may change before the final release. Examples in this article were prepared for the versions identified in the Tested-Version block, but they may not behave identically with earlier or later releases.

Before using a command, review the documentation for the version you have installed. You should also examine the command’s locally installed help information:

unity --help
unity <command> --help

The locally installed help output may be more current than online articles or documentation.

Unity CLI Can Modify Or Damage A Project

Unity CLI is capable of making changes to Unity projects, Editor installations, packages, project settings, scenes, assets, source-control configuration, build settings, licensing information, and other development files.

Some operations may overwrite files, remove files, upgrade serialized project data, alter package dependencies, change settings, regenerate assets, or leave a project in a state that cannot easily be reversed.

The risk becomes greater when using:

• Project upgrade commands
• Package installation or removal
• Automated build scripts
• Custom Pipeline commands
• Live C# evaluation
• Commands that modify scenes or assets
• Development Player control
• AI agents that can select and execute commands
• Experimental or undocumented options

A command does not need to contain words such as delete, remove, or overwrite to cause a damaging or irreversible change.

Back Up The Project Before Proceeding

Before running Unity CLI against an important project, place the project under version control using Git, Unity Version Control, or another reliable version-control system.

For Git-based projects, use a remote hosting service such as GitHub, GitLab, or Bitbucket rather than relying only on the local repository stored on your computer.

Before beginning:

1. Save all open scenes and project files.
2. Close or pause other programs that may be modifying the project.
3. Review the project’s source-control status.
4. Commit all current changes.
5. Push the commit to a remote repository.
6. Confirm that the remote repository contains the latest commit.
7. Create a separate branch for Unity CLI experiments.
8. Test unfamiliar commands on a copy of the project when practical.

A typical Git workflow might resemble:

git status
git add .
git commit -m "Backup before Unity CLI testing"
git push
git switch -c unity-cli-testing

The exact commands may differ depending on your source-control system and existing branch structure.

Version Control Is Not A Complete Backup

Git and similar systems protect only the files they are configured to track.

They may not protect:

• Uncommitted work
• Ignored files
• Files excluded by .gitignore
• Local credentials
• Keystores and signing files
• Large files not correctly configured for Git LFS
• Files stored outside the project repository
• Locally installed Editor modules
• Machine-specific configuration
• External tools or generated output
• Changes made to Unity installations or licenses

Review .gitignore before relying on the repository as your only backup. Make sure important project files have not been excluded accidentally.

For project upgrades, package migrations, large asset changes, or experimental automation, consider keeping a separate compressed or external backup in addition to source control.

Use A Clean Working State

Do not begin potentially destructive operations while the project contains unrelated, uncommitted changes.

A clean working state makes it easier to identify what Unity CLI changed:

git status

After running a command, inspect the project again:

git status
git diff

Review all changes before committing them. Do not assume that a successful exit code means every resulting project change is desirable.

Use Experimental Branches

Run Unity CLI tests on a dedicated branch whenever possible:

git switch -c unity-cli-experiment

Commit changes in small stages so individual operations can be inspected and reversed.

Avoid combining a project upgrade, package migration, scene modification, automated refactor, and build-configuration change in a single unreviewed operation.

Be Especially Cautious With Live C# Evaluation

Unity CLI’s live C# evaluation features may execute code inside a connected Unity Editor or development Player.

Depending on the APIs used, evaluated code may be able to:

• Change open scenes
• Create or delete GameObjects
• Modify components
• Save assets
• Delete assets
• Change project settings
• Enter or exit Play Mode
• Write files
• Move or rename project content
• Trigger imports
• Modify runtime state

Evaluate only code that you understand. Prefer narrowly defined custom commands over unrestricted evaluation for repeated or shared workflows.

Be Especially Cautious With AI Agents

An AI agent may interpret a request differently from what the user intended. It may also select multiple commands, generate C# code, repeat a failed operation, or make changes beyond the immediate problem it was asked to solve.

Before allowing an AI agent to operate on a Unity project:

1. Use a disposable project, project copy, or experimental branch.
2. Limit the commands the agent can access.
3. Prefer read-only inspection commands where possible.
4. Require confirmation before destructive actions.
5. Review generated code before execution.
6. Inspect all resulting file and project changes.
7. Run tests before accepting or merging the work.
8. Do not expose passwords, tokens, signing credentials, or private keys.

Do not give an automated tool unrestricted access to an important production project until its behavior has been tested and understood.

Restore The Project When Necessary

When a Unity CLI operation produces unwanted tracked-file changes, stop and inspect the repository before taking further action.

Depending on the situation, recovery may involve:

• Reverting selected files
• Resetting the experimental branch
• Returning to the previous branch
• Restoring from a remote commit
• Replacing the project with a separate backup
• Reinstalling an affected Editor or module

Do not run additional corrective commands blindly. Additional automation can make the original problem harder to diagnose.

Proceed At Your Own Risk

The commands and examples in this article are provided for educational purposes. Test them in a controlled environment before incorporating them into a production workflow.

The author and publisher cannot guarantee that beta software, experimental packages, third-party integrations, generated commands, or AI-controlled operations will behave consistently across Unity versions, operating systems, projects, or future releases.

Always maintain verified backups and review every operation before applying it to important work.