How to Use Unity CLI - First Agent Safe Editor Session 2026

If you are searching unity cli, you do not need another Unite Seoul recap. You need a Monday path: install a unity binary, open a throwaway project, drive the Editor from the terminal, and decide keep or hold before any AI agent gets eval rights on a shipping branch.

On July 20, 2026, Unity published Meet the Unity CLI—a standalone terminal binary for Editors, modules, projects, and auth—plus the experimental com.unity.pipeline package that lets scripts and agents talk to a running Editor (and even a development Player). Discussions framed the same shift a few days earlier: terminal-native tooling for the agents you already pay for, with MCP Mode as a bridge—not a forced rewrite.Unity Discussions Unity Docs

Who this is for: beginners who only ever used Hub clicks, working Unity 6 indies wiring CI or Cursor/Claude agents, and studio leads who need governance language for “agent can run C# in our Editor.”
Time: 90–150 minutes for a first agent-safe session on a branch.
Honest limit: the CLI and Pipeline package are experimental; cloud Unity Production Pipeline is a separate closed beta (rolling access, GA aimed at November 2026). Tonight is local CLI + Pipeline—not a promise that your whole studio is approved for the cloud dashboard.

Non-repetition: This is not the Unity MCP with Cursor safe bridge (IDE ↔ Editor MCP tools). It is not the Unity 7 roadmap keep/hold (Q1 2027 product story). It is not Antigravity CLI migration (coding-agent product CLI). Same discipline family—different binary.

Why this matters now

1. Terminal is where agents and CI already live. Unity’s own blog positions the CLI as the execution surface under AI assistants: structured JSON/TSV, exit codes, service-account auth, and a live eval loop without domain reload theater.Meet the Unity CLI
2. MCP did not disappear—CLI is the recommended terminal path. Official Discussions guidance: existing Unity MCP stays supported; CLI + Pipeline is the more robust, extensible direction, with MCP Mode for teams that already invested in MCP clients.Discussions
3. SERP is announcement-heavy. Blog posts and docs explain install; they do not ship an indie U1–U6 keep/hold with token policy, CI notes, and explicit separation from Unity 7 marketing. That gap is what this URL closes.

Parent demand stays huge under the unity keyword family (Semrush-class snapshots on unity.com stay six figures monthly). Community GitHub repos named “unity-cli” already proved people wanted terminal Editor control before the official binary shipped—stars in the hundreds on agent-oriented forks. The Jul 20 launch is the official capture of that intent.

What Unity CLI is (and is not)

Docs are blunt: the Unity CLI is experimental, and controlling a running Editor requires installing and setting up the Pipeline package—not only the binary.Use the Unity CLI Unity CLI overview

Prerequisites

Confirm every line before you paste install scripts into a machine that also holds signing certs.

• [ ] Windows PowerShell, macOS Terminal, or Linux shell you control (not a shared kiosk).
• [ ] Unity 6.0 LTS or newer project on a branch or throwaway clone (Pipeline targets 6.0+ for Editor drive).
• [ ] Disk space for at least one Editor install if this machine is Hub-free (CI agents especially).
• [ ] Named session owner who will write the receipt at the end.
• [ ] Written eval policy: off until U1–U4 pass; token stored outside chat history.
• [ ] Optional: an AI coding agent (Cursor, Claude Code, Codex) you will allowlist later—not required for the first human-driven smoke.

If you only want “Hub installs Editors forever,” you can skip this evening. If you want agents or headless CI to observe → act → verify without copy-pasting console text, continue.

Beginner path - first evening without an agent

Step 1 - Install the Unity CLI binary

Official install (beta channel) from Unity’s blog and docs:

macOS / Linux

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

Windows (PowerShell)

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

Then reopen the terminal (or refresh PATH) and run:

unity --version
unity --help

If unity is not found, add the install directory to PATH before you declare the tool broken. The binary is self-contained—CI workers do not need the Hub desktop UI.Use the Unity CLI

Common mistake: running the install script, then testing in a terminal that still has an old PATH. Fix the shell session first.

Step 2 - Sign in once (interactive machines)

unity auth login
unity auth status

Browser login stores a session for later commands. On headless CI, do not pretend this step works—use service-account env auth (dev path below). For tonight’s laptop smoke, interactive login is enough.

Step 3 - List Editors and open a throwaway project

unity editors --format json
unity open ./MyThrowawayProject

You can also pass a path without the open keyword when the first argument is a path (unity ./MyThrowawayProject).Use the Unity CLI

Beginner checkpoint: Editor opens the branched project. If Hub still works and CLI open fails, note the error string—do not “fix” it by pointing CLI at main production.

Step 4 - Optional Editor install without Hub UI

Useful on a clean CI image or a second machine:

unity install lts
# or pin a version your project already uses:
unity install 6000.2.10f1 -m android ios webgl --accept-eula --yes

Module IDs and aliases live in the Unity CLI reference. Prefer pinning the same Editor string as ProjectSettings/ProjectVersion.txt before you invent a second toolchain.

Step 5 - Install the Pipeline package into the project

With auth + project ready:

unity pipeline install
unity pipeline list

This adds com.unity.pipeline so a running Editor can receive commands from the CLI on your machine. Unity documents this as experimental and local—expect the surface to evolve.Meet the Unity CLI

Beginner checkpoint: package present; Editor open; you have not run eval yet.

Developer path - drive the Editor safely

Structured output and exit codes (CI-ready habits)

Every command can emit machine-readable output:

unity editors --format json
unity editors --format tsv

Exit-code contract from Unity’s blog: 0 success, 1 error, 130 cancelled. Errors go to stderr; results to stdout. Train agents and shell scripts on that contract instead of scraping colored Hub logs.Meet the Unity CLI

List and run commands against a connected Editor

With Pipeline installed and Editor open:

unity command
unity command <command-name>

unity command with no arguments asks the connected Editor what it exposes—self-describing for humans and agents. That is the difference between a hardcoded tool list and a discoverable surface.

Custom [CliCommand] tools (project-owned API)

Unity’s blog sample pattern (attribute-based discovery—no separate registration step):

using Unity.Pipeline.Commands;
using UnityEngine;

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

Then from the terminal:

unity command greet --name World

Governance rule: treat every custom command like an MCP write tool. Document write scope in one sentence. Decide enable first / owner-only / keep off before any agent may call it. Prefer read-only commands (list-scenes, console-tail) on night one.

eval - power with a token gate

unity command eval "return Application.version;"
unity command eval "return UnityEditor.EditorApplication.isPlaying;"
unity command eval_file "path/to/script.cs"

eval compiles with Roslyn on the Editor main thread—milliseconds instead of “edit → domain reload → relaunch.” That is exactly why agents love it, and exactly why you gate it. Unity’s blog is explicit: eval is behind a security token; do not paste that token into a public chat, a ticket, or an agent transcript that gets committed.Meet the Unity CLI

Runtime Player note: development builds can expose a localhost-only runtime API (--runtime style flows in Unity’s materials). Keep it off by default, never in production players, and never on a shared QA device without a wipe policy. Indie rule: if you cannot explain who holds the token, eval stays off.

CI / service-account auth (working-dev branch)

For unattended agents:

• Prefer service-account credentials via environment variables (Unity’s blog calls this out for headless build agents—no browser).
• Use --accept-eula --yes style non-interactive flags on installs.
• Run unity doctor when env/credential/config fails before blaming the agent.
• Pin Editor version strings in the workflow YAML; do not use floating lts on release pipelines until you accept surprise upgrades.

Store secrets in the CI secret store. Never in .env committed next to [CliCommand] samples.

MCP Mode vs Unity MCP (Cursor) - pick one evening path

Unity staff on Discussions: existing Unity MCP is not required to use CLI MCP helpers—unity mcp --help after CLI install—and CLI MCP is described as a superior implementation on Pipeline.Discussions thread

If your team’s only muscle memory is Cursor tools, finish the MCP safe session first, then add CLI for CI. If your muscle memory is GitHub Actions and shell, start here and treat MCP Mode as optional.

Keep / hold vs Unity 7 marketing

Unite Seoul also launched the Unity 7 story (beta December 2026, full release Q1 2027) with CLI/MCP as ecosystem pillars.Unity 7 indie keep/hold

CLI availability today is not the same as Unity 7 shipping next year. Do not let roadmap slides cancel a working 6.6 CI job.

Gates U1–U6 (agent-safe latch)

Latch unity_cli_ok only when all six pass. Store a receipt file (example name) unity_cli_safe_session_receipt_v1.json next to your other build receipts.

If any gate fails, hold agent write access. Humans can still use Hub.

Example receipt fields (studio-friendly)

{
  "receipt": "unity_cli_safe_session_receipt_v1",
  "project": "MyThrowawayProject",
  "branch": "spike/unity-cli-evening",
  "cli_version": "<paste unity --version>",
  "editor_version": "6000.x.yf1",
  "pipeline_package": true,
  "eval_enabled": false,
  "gates": { "U1": true, "U2": true, "U3": true, "U4": true, "U5": true, "U6": true },
  "owner": "session-owner-name",
  "notes": "Read-only command smoke only; eval held."
}

Do not invent pass results. If U5 is incomplete, leave eval_enabled false and say so in standup.

Failure modes and quick fixes

Community threads already show agent wrappers inventing filesystem errors that raw PowerShell does not hit—debug the wrapper before filing Unity bugs.Discussions

Company / diligence notes

• Ownership: one person owns CLI version pins and token rotation; one person owns agent allowlists.
• Cost/ROI: CLI and MCP are positioned free at announcement time—budget still exists for engineer hours, CI minutes, and Unity AI subscription if you keep the separate MCP Server path.
• Security: localhost-only runtime hooks, token-gated eval, no production Player exposure. Treat eval like remote code execution with a shorter fuse.
• Audit: keep receipts with gate booleans; partners care more about that than a Unite keynote clip.
• AI policy: if your studio bans generative AI in creative work, you can still use CLI for non-AI automation (Jenkins, install scripts)—Unity staff explicitly heard that ask on Discussions. Document the boundary.

How this fits a micro-studio week

Monday (90 min): U1–U4 on a throwaway branch; no agent.
Tuesday: Add one [CliCommand] that lists scenes or prints Application.version.
Wednesday: Wire CI install + unity editors --format json on a build agent image.
Thursday: Optional MCP Mode or Cursor MCP path—pick one, do not dual-enable write tools everywhere.
Friday: Review keep/hold; decide whether Production Pipeline cloud beta is worth an apply form.

Pair install automation with your existing Unity 6.6 LTS upgrade safety sprint so CLI pins match the Editor you actually certify.

Common mistakes (beginner + mid-level)

1. Pointing agents at main on night one — always U2 first.
2. Confusing Production Pipeline cloud beta with local Pipeline package — different products, different access.
3. Assuming Unity 7 is required — CLI ships against current Unity 6 workflows.
4. Enabling eval before a token vault — U5 is not optional theater.
5. Copying Hub --headless scripts blindly — migrate deliberately.
6. Treating CLI as a replacement for art review — producers may still need cloud Pipeline later; local smoke is not a browser build gallery.
7. Letting the agent invent CliCommands in chat without code review — attributes land in your repo; review like any gameplay C#.
8. Skipping structured JSON — scraping human console text reintroduces the problem CLI solved.

Key takeaways

1. Unity CLI is a standalone unity binary for Editors, modules, projects, auth, and automation—available now, experimental, free at announcement.
2. com.unity.pipeline turns a running Editor (and optionally a dev Player) into a programmable target for scripts and agents.
3. Start with install → auth → open throwaway → pipeline install → read-only commands—not with eval.
4. eval is token-gated remote-ish power—treat it like RCE lite; vault the token.
5. MCP Mode ≠ abandon Unity MCP—use CLI for terminal/CI; use the MCP Cursor guide for IDE bridges.
6. Unity 7 slides do not delay Unity 6 CI—see the Unity 7 keep/hold.
7. Latch unity_cli_ok only when U1–U6 pass with a written receipt.
8. Cloud Production Pipeline closed beta is optional for solo evenings—do not block local smoke on an apply form.
9. Custom [CliCommand] APIs need the same allowlist discipline as MCP write tools.
10. Prefer structured JSON/TSV + exit codes so agents and CI share one contract.

FAQ

What is the Unity CLI?

A standalone command-line binary that installs and manages Unity Editors and modules, opens projects, handles auth, and—with the Pipeline package—drives a running Editor from the terminal for scripts, CI, and AI agents.Docs Blog

How do I install Unity CLI on Windows or Mac?

Use Unity’s beta-channel install script (install.ps1 on Windows PowerShell, install.sh on macOS/Linux), then verify with unity --version. Refresh PATH if the command is missing.Use the Unity CLI

Is Unity CLI free?

Unity’s announcement positions the CLI and related MCP tooling as free to remove barriers; always re-check current licensing pages before a partner contract, and remember engineer time is still a cost.Discussions pricing note

Do I need Unity 7 to use the Unity CLI?

No. The CLI and Pipeline package target current Unity 6.x workflows. Unity 7 is a separate 2026–2027 product roadmap.Unity 7 playbook

How is Unity CLI different from Unity MCP?

CLI is terminal-native automation (installs, CI, Pipeline commands, eval). Unity MCP is an MCP server for IDE agents inside the Editor via the AI Assistant package. CLI offers MCP Mode for compatibility; you can use either or both with clear allowlists.MCP guide

Is unity command eval safe for AI agents?

Only after U1–U6, with a vaulted token, on a non-production branch, and with a human-owned allowlist. Unscoped eval on main is an incident waiting to happen.Meet the Unity CLI

What is Unity Production Pipeline vs com.unity.pipeline?

com.unity.pipeline is the local package that lets the CLI talk to a running Editor. Unity Production Pipeline is the broader cloud/services beta (dashboard, team workflows) with rolling admission and later GA messaging—apply separately; do not conflate the two.RuntimeWire coverage Get started docs

Can beginners finish a safe first session in one evening?

Yes if scope is install + open throwaway + Pipeline + one read-only command + a written receipt. No if you try to rebuild all CI and enable eval for three agents the same night.

Related reading

• Unity MCP with Cursor - First Safe Editor Bridge Session 2026
• Unity 7 Roadmap - What Indies Should Decide After Unite Seoul 2026
• Unity Fast Enter Play Mode in 6.6 - CoreCLR Prep Playbook for Indies 2026
• Unity 6.6 LTS Upgrade Safety Sprint - Small Teams 2026
• Antigravity CLI migration - what changed for game developers 2026
• Unity AI Assistant Ask Plan Agent modes - first safe session

Official sources

• Meet the Unity CLI
• Unity CLI docs
• Use the Unity CLI
• Announcing the Unity CLI (Discussions)
• RuntimeWire - Unity CLI for AI agents