Driving the Unity Editor via UnityCLI

The Unity Pipeline package (com.unity.pipeline) runs a local HTTP server inside the Editor; unity command executes commands against it live — no relaunch, no batch mode. The exposed surface is full authoring (scenes, GameObjects, prefabs, materials, animation, script creation, packages, tests, builds) — the same command set MCP-based Unity integrations wrap, reachable without an MCP bridge. Prerequisite basics (PATH, --json, auth): see skill unity-cli-core.

Argument syntax — the #1 source of silent failures

The only working form is --flag value with snake_case names:

unity command set_transform --gameobject Player --position "[1,2,3]"

Every other form — key=value, positional, -- key=value, kebab-case (--save-path) — is dropped silently: the command reports success and runs with defaults. Verified failure mode: a click command "succeeds" while clicking at (0,0); a path=... argument becomes a literally-named folder. Missing required parameters do fail loudly (400) — only unknown/malformed forms vanish.

Two mandatory habits:

1. Verify the echo. Every response carries data.parameters — the arguments the server actually received. After any mutating or surprising call, check your arguments are in there. An empty parameters: {} when you passed arguments means they were dropped.
2. Verify the schema on doubt. Argument names are not uniform across commands (delete_asset --asset, but open_scene --path). references/editor-commands.md lists the core commands with arguments; on a mismatch, the live truth is unity --json command (full JSON schemas, per-project).

Prerequisites — check, don't install

Live control needs BOTH: UnityCLI on the machine AND the Unity Pipeline package (com.unity.pipeline) inside the target project. The CLI alone can install/open editors but cannot talk to a running Editor.

1. unity status — is an Editor running? GUI editors only: an editor launched with -batchmode serves commands but never appears here — probe it with unity command --project-path <path> instead.
2. unity pipeline list — does the project show Pipeline: Installed?

If the package is missing, stop and ask the user — do not run the install to unblock yourself. unity pipeline install edits the project's Packages/manifest.json and triggers a recompile: a project change that lands in version control. Propose the exact command (unity pipeline install --project-path <path>; requires unity auth login) and continue only after approval. Same rule for unity pipeline upgrade. unity pipeline list-versions shows available versions.

Discover, then execute

unity status                     # connected Editors: port, project, version, PID, state
unity command                    # list commands the Editor exposes (or: unity list)
unity command <name> --param value ...

• The command list is dynamic and incomplete. It depends on package version, project code, and installed packages — and ten RuntimeOnly commands (simulate_pointer, simulate_key, runtime_status, capture_runtime_element, set_timescale, set_target_framerate, quit, log, hotreload_status, cleanup_hotreload), intended for Player connections (--runtime), are filtered out of the editor listing yet execute fine against the editor (capture_runtime_element only exists on Unity 6000.7+). Their schemas exist only in references/editor-commands.md (section "RuntimeOnly commands") — the CLI cannot show them. Absence from the list proves nothing; a genuinely unknown name fails with exit code 6 and prints the available list.
• Projects can define their own commands: a static method with [CliCommand]/[CliArg] attributes auto-registers after compilation, schema included (references/eval-recipes.md).
• Multiple Editors open → disambiguate with --project-path <path> (env UNITY_PROJECT_PATH).
• Slow operations → raise --timeout <seconds> (default 30).
• --json wraps results as {success, command, data: {parameters, result}}.

Play-mode state is verified with editor_status (its playMode field) — editor_play/editor_stop only mutate.

Conventions the commands follow

Scene changes lose data silently

open_scene (and API-level EditorSceneManager.OpenScene) discards unsaved changes without any prompt. Protocol before replacing scenes: list_open_scenes → any isDirty scene → save_all, or explicitly decide to discard; if the dirty work isn't yours, ask. Details and editor shutdown/recovery: references/lifecycle-recovery.md.

Hangs and modal dialogs

A modal dialog blocks the Editor main thread: commands time out while unity status still reports ready (heartbeat needs no main thread). Diagnosis table, dialog inventory, prevention, clean-shutdown (save_all + eval EditorApplication.Exit(0)), and crash-recovery procedure: references/lifecycle-recovery.md.

Verification and capture

• State read while the Editor is playing measures whatever Update wrote last frame — for stable assertions, read with play mode stopped.
• capture_game_view renders a camera to PNG (base64 inline by default, --save_path for a file); capture_scene_view renders the Scene View; screenshot --view game|scene captures the actual view to a file. UI on a Screen Space Overlay canvas is not part of any camera's render — camera-based capture misses it.
• simulate_pointer / simulate_key drive a virtual Input System device (hidden from the listing — schemas in references/editor-commands.md). Passing arguments in any form other than --x 10 --y 20 silently clicks at (0,0) — the argument-drop trap above. If gameplay code still doesn't react (e.g. it polls a specific device), queue state on the real device via eval (references/eval-recipes.md).

Tests

Against a running Editor: unity command run_tests --mode all|editor|playmode (async with --async_tests true, poll test_status). Headless unity test uses different mode names: --mode EditMode|PlayMode. The two are not interchangeable.

Headless (no running Editor)

These spawn an editor in batch mode instead of connecting to one:

unity build . --target StandaloneWindows64 --execute-method Builder.PerformBuild -o ./out
unity test . --mode EditMode --filter "MyNamespace" --output results.xml --timeout 1800
unity run . -- -executeMethod Tool.Run -quit      # raw editor args after --
unity run . --command my_command -- --arg value   # registered command, one-shot: boots, runs, exits

• unity build requires --execute-method — Unity has no built-in command-line build.
• --allow-install downloads and installs the project's editor version if missing — multi-gigabyte; don't pass it without the user's OK.
• unity test writes an NUnit XML report; set --timeout or a hung run never exits.
• unity run --command mixes the editor log into stdout — parse with --format ndjson.
• Against a running Editor, prefer unity command build / unity command run_tests (async, editor stays open).

Resident headless editor (agent / SSH build box)

For many commands against one project, a fresh batch boot per command is wasteful. Launch the editor binary with -batchmode and no -quit — it loads the project, stays resident, and serves the Pipeline API like a GUI editor (~sub-second round-trips, no domain reload per call):

"<editor-binary>" -batchmode -projectPath <project> -logFile editor.log &
# PowerShell: Start-Process "<editor-binary>" -ArgumentList '-batchmode','-projectPath','<project>','-logFile','editor.log'
unity command --project-path <project>       # reachability probe + command list

• Such an editor is invisible to unity status and unity editors running (its lockfile heartbeat differs from a GUI editor's) — always target it via --project-path and probe with unity command/unity list, never status.
• A bare unity run <project> (no --command) is NOT a way to get one: batch runs to completion and exits.
• Any resident editor — batch or GUI — holds a license seat until it exits; one-shot unity run --command releases it on exit.
• Binary paths per install: unity editors -i (the location field). Launching directly also sidesteps unity open EBUSY failures (references/lifecycle-recovery.md).

Common mistakes