Unity CLI: Installing the Unity CLI

Setting Up Unity’s Beta Terminal Tool on Windows, macOS, and Linux

Important: Unity CLI is currently a beta product. Its installation process, commands, file locations, and behavior may change before the final release. Unity CLI can also perform operations that modify or damage Unity projects. Back up important projects and place them under version control before using the CLI against them. The complete beta and project-safety notice appears at the end of this article.

Introduction

Unity CLI is distributed as a standalone command-line application for Windows, macOS, and Linux. Unlike the older Unity Hub command-line interface, the new CLI does not require the complete Unity Hub desktop application to be installed.

After installation, the CLI is launched with a single command:

unity

From that one entry point, developers can manage Unity Editor installations, platform modules, projects, authentication, licensing, builds, tests, diagnostics, and connections to running Unity Editors.

Unity CLI is also designed for automation. The same installation can be used from an interactive terminal, a PowerShell script, a Bash script, a continuous integration worker, or an external development agent.

At the time this article was prepared, Unity CLI remained a beta product. Unity’s official installation commands therefore select the beta release channel explicitly. Unity also warns that the locally installed unity --help output may be more current than the online command reference.

This article provides a complete installation guide for:

• Windows using PowerShell
• macOS using Terminal and Zsh
• Linux using Bash or another compatible shell
• Intel and Arm64 processors
• Interactive developer workstations
• Headless or continuous integration machines

You will also learn how to:

• Check your operating-system architecture
• Review the official installer before running it
• Verify that Unity CLI was added to PATH
• Inspect the installed version and command list
• Run the built-in diagnostic tool
• Update the CLI
• Preview an update’s changelog
• Install a specific published version
• Roll back a recent CLI update
• Remove Unity CLI
• Resolve common installation and shell problems

This article installs only the Unity CLI application. Installing Unity Editors and platform modules will be covered separately in Topic Group 3.

What the Installation Adds

Unity CLI is delivered as a self-contained binary. Unity says it does not require the Unity Hub desktop application or a collection of additional runtime dependencies after installation. The official installer downloads the correct build for the host operating system and processor architecture, installs the binary, and adds its location to the user’s PATH.

The PATH environment variable contains a list of directories that the operating system searches when a user enters a command.

When you type:

unity --version

the shell searches each directory listed in PATH until it finds the Unity CLI executable.

If the installation succeeds but the current terminal has not loaded the updated PATH, the shell may report that the unity command cannot be found. Unity’s documentation recommends reopening the terminal or adding the installation directory to PATH.

The Unity CLI executable is separate from:

• The Unity Hub application
• A Unity Editor executable
• The UGS CLI
• Unity Version Control commands
• Third-party applications that may also use the word unity

This distinction becomes important when confirming which executable the shell is actually running.

Supported Platforms and Architectures

The first public Unity CLI beta provided binaries for:

• Windows x64
• Windows Arm64
• macOS Intel
• macOS Apple silicon
• Linux x64
• Linux Arm64

Unity describes the CLI as one self-contained executable for each supported operating-system and architecture combination.

Before installation, identify the architecture of the computer.

Check the Architecture on Windows

Open PowerShell and run:

$env:PROCESSOR_ARCHITECTURE

Common results include:

AMD64

or:

ARM64

You can request additional operating-system information with:

Get-ComputerInfo |
    Select-Object WindowsProductName, WindowsVersion, OsArchitecture

Check the Architecture on macOS

Open Terminal and run:

uname -m

An Apple silicon Mac normally returns:

arm64

An Intel Mac normally returns:

x86_64

You can also open the Apple menu and select About This Mac to identify the processor or Apple chip.

Check the Architecture on Linux

Open a terminal and run:

uname -m

Common results include:

x86_64

or:

aarch64

The installer should select the appropriate binary automatically. Recording the architecture remains useful when reporting an installation problem.

Before Running the Installer

The official installation commands download a script from Unity’s content-delivery network and execute it immediately.

On Windows, the command uses:

Invoke-RestMethod

and:

Invoke-Expression

On macOS and Linux, the command pipes the downloaded script directly into Bash.

This one-line approach is convenient, but it also means the downloaded script is executed before the user reads it.

Before running any remotely downloaded installer:

1. Confirm that the address uses Unity’s official domain.
2. Confirm that the command came from current Unity documentation.
3. Check that the command has not been altered while copying it.
4. Consider downloading and reviewing the script before executing it.
5. Follow your employer’s software-installation and security policies.
6. Avoid running an unfamiliar installer with elevated privileges unless elevation is explicitly required and understood.

The official scripts currently come from:

https://public-cdn.cloud.unity3d.com/

Unity’s release notes state that the CLI’s platform binaries use SHA-256 checksums for verifiable downloads.

The official blog also says that conventional package-manager support, including systems such as Homebrew, WinGet, and APT, is planned but was not yet the primary documented installation route when this article was prepared.

Installing Unity CLI on Windows

Unity instructs Windows users to perform the installation from PowerShell.

PowerShell is available through several interfaces, including:

• Windows PowerShell
• PowerShell 7
• Windows Terminal with a PowerShell profile
• The PowerShell terminal inside some development tools

Use a normal user PowerShell session first. Do not automatically launch an elevated Administrator session unless your system configuration or organization requires one.

Open PowerShell

Open the Start menu and search for:

PowerShell

Alternatively, open Windows Terminal and select a PowerShell profile.

Confirm that PowerShell is operating:

$PSVersionTable.PSVersion

Run the Official Windows Installer

Unity’s official Windows installation command is:

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

In this command:

• $env:UNITY_CLI_CHANNEL='beta' selects the beta release channel.
• irm is a PowerShell alias for Invoke-RestMethod.
• The URL identifies Unity’s official PowerShell installer.
• iex is an alias for Invoke-Expression.
• The downloaded script is passed directly into PowerShell for execution.

The command can be written without aliases:

$env:UNITY_CLI_CHANNEL = 'beta'

Invoke-RestMethod `
    -Uri 'https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1' |
    Invoke-Expression

Both forms perform the same general operation. The expanded form is easier for readers unfamiliar with PowerShell aliases.

Unity publishes the Windows command in its official Unity CLI announcement and documentation.

Download and Inspect the Windows Installer First

A more cautious process downloads the script to a file before running it.

Create a temporary location:

$installerPath = Join-Path $env:TEMP 'unity-cli-install.ps1'

Download the script:

Invoke-RestMethod `
    -Uri 'https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1' `
    -OutFile $installerPath

Display the script:

Get-Content $installerPath

Open it in Notepad:

notepad $installerPath

After reviewing the contents and confirming the source, select the beta channel and run the script:

$env:UNITY_CLI_CHANNEL = 'beta'
& $installerPath

Delete the temporary installer when finished:

Remove-Item $installerPath

Your organization’s PowerShell execution policy may prevent a downloaded .ps1 file from running directly. Do not weaken a company-managed security policy merely to complete the installation. Use an approved installation process or consult the system administrator.

Verify the Windows Installation

After the installer finishes, run:

unity --version

The command should display the installed Unity CLI version.

Do not assume that the version shown in an online article is the version the beta installer will provide. The beta channel can move faster than the web documentation.

Next, inspect the available commands:

unity --help

Unity says the local help output is the authoritative command list for the installed release.

Locate the executable PowerShell is using:

Get-Command unity

For more detail:

Get-Command unity |
    Format-List Name, CommandType, Source, Version

Run Unity CLI’s diagnostics:

unity doctor

Finally, view the changelog bundled with the installed CLI:

unity changelog

If Windows Cannot Find the Command

If PowerShell reports:

The term 'unity' is not recognized...

close PowerShell and open a new session.

The installer may have updated the user-level PATH, but the PowerShell process that was already open may still contain the old environment.

Check the current PATH:

$env:Path -split ';'

Check whether PowerShell can locate the executable:

Get-Command unity -ErrorAction SilentlyContinue

You can also search for executable files named unity:

Get-ChildItem `
    -Path $env:LOCALAPPDATA, $env:USERPROFILE `
    -Filter 'unity*.exe' `
    -Recurse `
    -ErrorAction SilentlyContinue

Avoid manually adding a guessed directory to PATH. First identify the actual location created by the official installer.

Check for a Name Collision on Windows

A computer may already have another executable, function, alias, or script named unity.

Run:

Get-Command unity -All

If several results appear, PowerShell normally executes the first matching command according to its command-precedence rules.

Confirm that the selected executable is the new Unity CLI:

unity --version
unity --help

A traditional Unity Editor executable is usually launched through a complete path such as:

C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe

The new CLI should display its command groups rather than immediately launching the Unity Editor.

Installing Unity CLI on macOS

macOS installation uses Terminal and an official Bash installer.

Modern versions of macOS use Zsh as the default interactive shell, but the Unity installation command explicitly executes the downloaded script with Bash.

Open Terminal

Open:

Applications > Utilities > Terminal

Check the current shell:

echo "$SHELL"

Check the processor architecture:

uname -m

Confirm That curl and Bash Are Available

Run:

curl --version

Then:

bash --version

Both tools are normally available on macOS.

Run the Official macOS Installer

Unity’s official macOS command is:

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

The curl options mean:

• -f causes curl to fail on HTTP errors.
• -s uses silent mode.
• -S displays an error when silent mode encounters a failure.
• -L follows redirects.

The downloaded installer is passed into Bash while the environment variable:

UNITY_CLI_CHANNEL=beta

selects the beta release channel.

Unity publishes this command in both the official announcement and the installation documentation.

Download and Inspect the macOS Installer First

Download the script to a temporary file:

installer_path="/tmp/unity-cli-install.sh"

curl -fsSL \
    https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh \
    -o "$installer_path"

Review it:

less "$installer_path"

You can also open it in a text editor:

open -a TextEdit "$installer_path"

After confirming the contents and source, run:

UNITY_CLI_CHANNEL=beta bash "$installer_path"

Remove the temporary file:

rm "$installer_path"

Verify the macOS Installation

Run:

unity --version

Then:

unity --help

Locate the command:

command -v unity

Display every matching command found in the current shell configuration:

type -a unity

Run diagnostics:

unity doctor

Display the installed changelog:

unity changelog

If macOS Cannot Find the Command

Close Terminal and open it again.

If the problem remains, display the directories in PATH:

echo "$PATH" | tr ':' '\n'

Check whether the shell can locate the executable:

command -v unity

Inspect common Zsh startup files:

ls -la ~/.zshrc ~/.zprofile ~/.profile 2>/dev/null

Do not add a directory to these files until you have identified the actual installation directory.

After correcting PATH, reload the appropriate shell configuration or open a new Terminal window.

For example:

source ~/.zshrc

Use that command only when .zshrc is the file you actually changed.

Apple Silicon and Intel Macs

The installer is intended to detect whether the Mac uses Apple silicon or an Intel processor.

Confirm the architecture before reporting a problem:

uname -m

Unity’s issue tracker has documented installation behavior separately across Intel and Apple silicon systems during the beta period. Because beta installer defects may be opened and closed quickly, consult the issue tracker and installed changelog when an architecture-specific failure occurs.

Installing Unity CLI on Linux

Linux installation uses the same shell command as macOS.

The Unity CLI binary is self-contained after installation, but the installer requires basic command-line tools such as curl and Bash.

Open a Terminal

Check the processor architecture:

uname -m

Check the distribution:

cat /etc/os-release

Check for curl:

curl --version

Check for Bash:

bash --version

Install curl When Necessary

On Ubuntu or Debian-based systems:

sudo apt update
sudo apt install curl

On Fedora:

sudo dnf install curl

On distributions using another package manager, install the distribution’s curl package according to its documentation.

Run the Official Linux Installer

Run:

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

The command downloads Unity’s official shell installer and tells it to use the beta channel. Unity documents the same installer for both macOS and Linux.

Download and Inspect the Linux Installer First

Download the script:

installer_path="/tmp/unity-cli-install.sh"

curl -fsSL \
    https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh \
    -o "$installer_path"

Review it:

less "$installer_path"

Run it after inspection:

UNITY_CLI_CHANNEL=beta bash "$installer_path"

Remove the temporary file:

rm "$installer_path"

Verify the Linux Installation

Run:

unity --version

Then:

unity --help

Locate the binary:

command -v unity

Display all matches:

type -a unity

Run diagnostics:

unity doctor

Inspect the bundled release history:

unity changelog

If Linux Cannot Find the Command

Close the terminal and open a new session.

Display the current search path:

echo "$PATH" | tr ':' '\n'

Check startup files:

ls -la \
    ~/.bashrc \
    ~/.bash_profile \
    ~/.profile \
    ~/.zshrc \
    2>/dev/null

Different distributions and shells load different combinations of startup files.

Identify the actual installed executable before changing PATH:

find "$HOME" \
    -type f \
    -name 'unity' \
    -perm -u+x \
    2>/dev/null

Do not use a system-wide location or sudo merely to avoid configuring the user’s shell. Follow the installation model and security requirements of the machine.

Linux Authentication Storage

The first Unity CLI beta stored authentication tokens through the operating system’s secure credential system:

• Keychain on macOS
• Credential Manager on Windows
• libsecret on Linux

A Linux installation may therefore require an operational secret-service environment when the user later signs in. The CLI itself may install and run before interactive authentication is configured.

If unity auth login later encounters credential-storage errors, check that the Linux desktop or headless environment provides the required secret service.

Verifying the Installation on Every Platform

A successful installation should pass several checks.

Check 1: Display the Version

unity --version

Record the complete result.

Do not shorten it to only the major version. Beta identifiers are important when diagnosing differences among releases.

Check 2: Display the Help

unity --help

This confirms that:

• The executable starts
• The shell is finding the correct program
• The CLI can display its command list
• The current terminal supports the output

Unity specifically identifies the installed help as the authoritative source for the commands and flags available in that release.

Check 3: Display the Changelog

unity changelog

This command displays release information included with the installed CLI.

The online release notes and the installed binary may not always update simultaneously. Record both the installed version and the installed changelog before relying on a newly introduced command.

Check 4: Run Diagnostics

unity doctor

The diagnostic command can report information about the CLI environment, installation, authentication, configuration, Editors, and logs. Later beta releases added a dedicated cli-log.json file and integrated it with unity doctor, unity logs, and bug-reporting workflows.

Check 5: Confirm the Selected Executable

Windows:

Get-Command unity -All

macOS or Linux:

type -a unity

This detects command-name collisions.

Check 6: Test Structured Output

unity editors --installed --format json

A machine without installed Unity Editors may return an empty result. That does not mean the CLI installation failed.

The important checks are:

• The command starts
• The output is structured
• The process completes without an installation error

Check 7: Record the Environment

Windows:

Get-ComputerInfo |
    Select-Object WindowsProductName, WindowsVersion, OsArchitecture

$PSVersionTable.PSVersion
unity --version

macOS:

sw_vers
uname -m
echo "$SHELL"
unity --version

Linux:

cat /etc/os-release
uname -m
echo "$SHELL"
unity --version

This information belongs in a bug report or article Tested-Version block.

Understanding the Beta Channel

The official installation commands currently include:

UNITY_CLI_CHANNEL=beta

This tells the installer to retrieve a beta release rather than a future stable channel.

The channel matters because:

• Beta releases may update frequently.
• Commands can be added or renamed.
• Output formats may change.
• Installation behavior may change.
• Bugs may appear or be fixed between installations.
• Two developers installing on different dates may receive different versions.

Never write:

Installed the beta version

without also recording:

unity --version

A reproducible report should contain the complete installed version.

Updating Unity CLI

Unity CLI contains a self-update command:

unity upgrade

Unity says this replaces the current binary with the latest release available through the appropriate update channel.

Before updating, record the current version:

unity --version

Review the installed changelog:

unity changelog

Then preview available update information:

unity upgrade --changelog

Unity added --changelog so users can review release notes before installing an update.

After reviewing the changes, run:

unity upgrade

Verify the result:

unity --version
unity --help
unity doctor

Installing or Updating to a Specific CLI Version

Unity CLI supports selecting a specific published CLI version:

unity upgrade --target <version>

For example:

unity upgrade --target 0.1.0-beta.7

The target version must be available through Unity’s release channel.

Unity added this option so users can choose a published release instead of automatically installing the newest version in the channel.

Get Lem Apperson’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Pinning a version is particularly useful for:

• Continuous integration
• Classroom computers
• Team-wide development environments
• Reproducible technical articles
• Testing a reported bug
• Avoiding unexpected command changes

Do not copy the example version blindly. Use a version you have verified is available and appropriate for the workflow.

Rolling Back an Update

Later beta releases added:

unity upgrade --rollback

This restores the previously installed CLI version.

A typical recovery sequence is:

unity --version
unity upgrade --rollback
unity --version
unity doctor

Rollback should not replace proper version management.

It may not solve:

• Configuration changes made by the newer release
• Project changes made while using the newer release
• Authentication changes
• Editor installations or removals
• Pipeline package changes
• External script changes

Before updating Unity CLI in a production environment:

1. Record the current version.
2. Review the changelog.
3. Test the update outside production.
4. Preserve logs.
5. Confirm that critical commands still behave as expected.
6. Keep project and automation scripts under version control.

Automatic Update Checks

Unity’s release notes state that later beta versions perform update checks in the background without blocking command execution.

An update check does not necessarily mean the installed CLI will replace itself automatically.

The explicit command remains:

unity upgrade

For production automation, avoid silently changing the CLI during an unrelated build. Update the CLI through a separate, reviewed maintenance step.

Removing Unity CLI

Later beta releases introduced:

unity self-uninstall

Unity says this removes the CLI binary, environment files, and stored credentials. The older unity implode command was deprecated in favor of unity self-uninstall.

Before removal, record:

unity --version
unity doctor

Then run:

unity self-uninstall

In a non-interactive environment, the operation may require confirmation through:

unity self-uninstall --yes

The removal command applies to CLI installations created through the official installer.

Removing Unity CLI does not necessarily remove:

• Unity Hub
• Installed Unity Editors
• Unity projects
• Project assets
• Unity Pipeline packages inside projects
• Build outputs
• External shell scripts
• CI configuration

After removal, open a new terminal and check:

Windows:

Get-Command unity -ErrorAction SilentlyContinue

macOS or Linux:

command -v unity

If another program named unity remains, the shell may now resolve that program instead.

Installing Unity CLI on a Headless Machine

Unity CLI is designed for machines that do not run Unity Hub, including headless continuous integration workers.

The installation commands remain the same:

Windows CI Worker

$env:UNITY_CLI_CHANNEL = 'beta'

Invoke-RestMethod `
    -Uri 'https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1' |
    Invoke-Expression

macOS or Linux CI Worker

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

A headless workflow should also:

• Pin or record the installed version
• Use non-interactive commands
• Preserve unity doctor output
• Store credentials through the CI platform’s secret manager
• Avoid updating the CLI during an ordinary build
• Cache downloads only when the cache can be invalidated safely
• Test the installation in a disposable runner first

A simple Linux or macOS verification step might be:

set -euo pipefail

unity --version
unity --help > unity-help.txt
unity doctor --format json > unity-doctor.json

A PowerShell equivalent might be:

$ErrorActionPreference = 'Stop'

unity --version
if ($LASTEXITCODE -ne 0) {
    throw "Unity CLI version check failed."
}
unity doctor --format json |
    Set-Content 'unity-doctor.json'
if ($LASTEXITCODE -ne 0) {
    throw "Unity CLI diagnostics failed."
}

Detailed CI configuration belongs to a later automation article.

The CLI Does Not Install an Editor Automatically

Installing Unity CLI does not necessarily install a Unity Editor.

After installing the CLI, this command may return no installed Editors:

unity editors --installed

That is a valid state.

Unity CLI and a Unity Editor are separate installations:

Unity CLI
The command-line management application

Unity Editor
The application used to create and run Unity projects

To install the newest long-term support Editor:

unity install lts

To install a specific Editor:

unity install 6000.3.7f1

To include modules:

unity install 6000.3.7f1 \
    -m android webgl

Unity’s command reference documents version aliases, architecture selection, modules, child modules, changesets, installation paths, and other options.

Editor installation will be examined in Topic Group 3 because it introduces additional decisions about versions, modules, download sizes, paths, architectures, and build dependencies.

Signing In Is a Separate Step

Installing Unity CLI does not automatically sign the user into a Unity account.

Check authentication status:

unity auth status

Begin browser-based sign-in:

unity auth login

Unity says the CLI stores the resulting session so later commands can use it without requiring another sign-in.

Sign-in is not required for every read-only local command, but it is required for operations that depend on Unity services, licensing, or account information.

Authentication and licensing will receive their own articles.

Common Installation Problems

The unity Command Is Not Found

Symptoms:

unity: command not found

or:

The term 'unity' is not recognized

Actions:

1. Close the terminal.
2. Open a new terminal.
3. Run the command-location tool for the platform.
4. Inspect PATH.
5. Confirm that the installer completed without an error.
6. Run the installer again only after understanding the original failure.

Windows:

Get-Command unity -All
$env:Path -split ';'

macOS or Linux:

type -a unity
echo "$PATH" | tr ':' '\n'

The Wrong unity Command Runs

A different program may already use the name unity.

Windows:

Get-Command unity -All

macOS or Linux:

type -a unity

Run:

unity --help

The new CLI should display its command groups. A traditional Unity Editor executable behaves differently.

The Installer Cannot Download the Binary

Possible causes include:

• No internet connection
• Corporate proxy configuration
• Firewall restrictions
• DNS failure
• Temporary Unity content-delivery outage
• TLS or certificate problems
• Security software blocking the download
• Unsupported architecture
• Interrupted transfer

Test access to the official script without executing it.

Windows:

Invoke-WebRequest `
    -Uri 'https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1' `
    -Method Head

macOS or Linux:

curl -I \
    https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh

Later Unity CLI betas added support for HTTP, HTTPS, SOCKS, authenticated, and PAC proxies. That support helps CLI operations after installation, but the initial installer must still reach Unity’s download host.

PowerShell Blocks the Downloaded Script

A downloaded .ps1 file may be affected by PowerShell execution policy or corporate application-control rules.

Do not disable a managed security policy without authorization.

Options include:

• Use Unity’s documented direct pipeline command.
• Ask an administrator to review and deploy the script.
• Use an approved software-deployment system.
• Verify the downloaded script and digital-signature expectations.
• Install through a future officially supported package manager when available.

macOS Reports a Security or Permission Error

Confirm:

uname -m
command -v unity
ls -la "$(command -v unity)"

Avoid changing ownership or permissions broadly.

If Gatekeeper, endpoint security, or managed-device policy blocks the executable, follow the organization’s approval process rather than overriding security controls.

Linux Authentication Fails After Installation

The CLI may install successfully but later fail to store credentials.

Check:

• Whether libsecret is installed
• Whether a secret-service daemon is available
• Whether the session has access to the desktop keyring
• Whether the machine is headless
• Whether service-account authentication is more appropriate

Run:

unity doctor
unity auth status

Preserve the diagnostic output before making changes.

The Online Documentation Does Not Match the Installed CLI

Run:

unity --version
unity --help
unity changelog

Unity explicitly says the local help is authoritative for the installed release.

Record the discrepancy rather than assuming the command is broken.

unity upgrade Causes a Problem

Record:

unity --version
unity doctor

Then consider:

unity upgrade --rollback

After rollback:

unity --version
unity --help
unity doctor

Report the failure through Unity’s bug-reporting process when it is reproducible.

Reporting an Installation Problem

A useful report should include:

• Operating system and exact version
• Processor architecture
• Shell and shell version
• Installation command used
• Whether the official installer was modified
• Complete Unity CLI version
• Complete error message
• Exit code
• unity doctor output, when available
• Proxy or firewall context
• Whether Unity Hub is installed
• Whether another executable named unity exists
• Whether reopening the terminal changed the result

Windows environment information:

Get-ComputerInfo |
    Select-Object WindowsProductName, WindowsVersion, OsArchitecture

$PSVersionTable.PSVersion
Get-Command unity -All
unity --version
unity doctor

macOS environment information:

sw_vers
uname -m
echo "$SHELL"
type -a unity
unity --version
unity doctor

Linux environment information:

cat /etc/os-release
uname -m
echo "$SHELL"
type -a unity
unity --version
unity doctor

Review diagnostic files before sharing them publicly. Remove credentials, private paths, repository addresses, user names, tokens, and other sensitive information.

Recommended Installation Checklist

Before installation:

• Confirm the operating system.
• Confirm the processor architecture.
• Open the appropriate shell.
• Confirm internet access.
• Confirm that the installer URL uses Unity’s official domain.
• Review organizational installation policies.
• Back up important Unity projects.
• Commit and push current project work.

During installation:

• Select the beta channel.
• Review the installer when practical.
• Avoid unnecessary administrative elevation.
• Preserve the complete installation error if the script fails.

After installation:

• Open a new terminal.
• Run unity --version.
• Run unity --help.
• Run unity changelog.
• Run unity doctor.
• Confirm which executable the shell resolves.
• Record the operating system, architecture, shell, and CLI version.
• Test only read-oriented commands first.
• Do not immediately run project-upgrade or live-evaluation commands.

Wrap-Up

Unity CLI can be installed independently of Unity Hub on Windows, macOS, and Linux.

Windows uses an official PowerShell installer:

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

macOS and Linux use an official Bash installer:

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

Both commands select the beta channel explicitly.

After installation, verify the result with:

unity --version
unity --help
unity changelog
unity doctor

The local unity --help output should be treated as the authoritative command reference for the installed beta.

Unity CLI can update itself:

unity upgrade

It can preview update notes:

unity upgrade --changelog

It can target a specific published CLI release:

unity upgrade --target <version>

It can restore the previously installed version:

unity upgrade --rollback

It can remove itself:

unity self-uninstall

Installing the CLI does not automatically install a Unity Editor, activate a license, sign in to an account, or install the Pipeline package. Those are separate steps that will be covered in later articles.

The most important practice is to record the actual installed version. Unity CLI is changing quickly, and two installations performed on different dates may not produce identical commands or behavior.

The next step is to divide this master installation article into shorter articles covering preparation, Windows, macOS, Linux, updates, and troubleshooting.

Further Reading

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

Introduction to the Unity Command-Line Interface
https://docs.unity.com/en-us/unity-cli/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 Hub and Unity CLI Overview
https://docs.unity.com/en-us/hub/cli-overview

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

Unity Issue Tracker
https://issuetracker.unity3d.com/

Unity Discussions
https://discussions.unity.com/

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

Inspect Remote Installation Scripts

The official Unity CLI installation commands download and immediately execute remote scripts.

Before running any remote installer:

1. Confirm that the URL belongs to Unity.
2. Compare the command with current official documentation.
3. Download and inspect the script when practical.
4. Do not execute a modified or untrusted copy.
5. Avoid unnecessary administrator or root privileges.
6. Follow organizational software-installation policies.
7. Preserve the installer and logs when diagnosing a failure.

A valid official domain does not eliminate every risk. DNS, network proxies, compromised accounts, altered documentation, or accidental command changes can still affect software installation.

Protect Authentication and Licensing Information

Unity CLI may store account sessions, service-account information, licensing data, and local configuration.

Do not expose:

• Service-account IDs and secrets
• OAuth tokens
• License serial numbers
• Offline activation files
• Floating-license credentials
• Keystores
• Signing passwords
• Private repository credentials

Do not include protected information in screenshots, public bug reports, source repositories, terminal transcripts, or article examples.

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
• Rolling back the Unity CLI version

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, installation scripts, or AI-controlled operations will behave consistently across Unity versions, operating systems, projects, networks, or future releases.

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