/unity-pipeline

name: unity-pipeline
description: Use when automating a running Unity Editor from the terminal via UnityCLI — entering play mode, running builds or tests, executing editor commands for scenes, GameObjects, prefabs, assets, materials, or settings, adding or removing UPM packages in the running Editor, polling build/recompile/bake status — or when `unity command` or `unity status` reports no connected Editor or a missing Pipeline package, or the Editor hangs or shows a modal dialog.

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](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](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](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

| Convention | Meaning | |---|---| | `--confirm true` | Destructive commands (delete_asset, set_player_settings, package_add/remove, clears/bakes) refuse to run without it | | `--dry_run true` | Preview what a mutating command would do, without doing it | | Async + status polling | Long operations return immediately; poll their status command: `build`→`build_status`, `recompile`→`recompile_status`, `run_tests`→`test_status`, bakes→`*_bake_status`, `switch_build_target`→`switch_build_target_status`, packages→`package_status` | | Authoring root | File/asset-creating commands resolve and confine bare paths under a base folder inside `Assets/`; `get_authoring_root` / `set_authoring_root --root Assets` for full project access | | Recompile before use | `create_script` produces a type only after `recompile` completes — poll `recompile_status`, then `attach_script`. Files written by anything **other** than pipeline commands (shell, external tools) stay invisible to the AssetDatabase until `eval AssetDatabase.Refresh()` ([references/eval-recipes.md](references/eval-recipes.md)); `write_text_file` imports what it writes itself | | Main-thre