t1k:unity:editor:cli
| Field | Value |
|---|---|
| Module | editor |
| Version | 3.50.7 |
| Effort | medium |
| Tools | — |
Keywords: t1k unity, unity cli, unity doctor, unity eval, unity facade, unity recompile, unity test
How to invoke
Section titled “How to invoke”/t1k:unity:editor:cli[verb] [args] [--lock-wait N] [--format json]t1k unity: the one interface to the Unity Editor
Section titled “t1k unity: the one interface to the Unity Editor”t1k unity <verb> runs scripts/t1k-unity.cjs, a thin facade over the official unity CLI plus the unity-cli-tools package that setup embeds in the project. Run it from anywhere inside a Unity project (the root is the nearest ancestor holding ProjectSettings/ProjectVersion.txt, else the single project found up to two levels below; UNITY_PROJECT_PATH is ignored). Other unity subcommands (the CLI’s mcp subcommands, the CLI’s close subcommand) are never used: the facade is the interface, and it deliberately has no kill verb.
Which path? (decision table)
Section titled “Which path? (decision table)”| Situation | Use |
|---|---|
Static file edit (field, ref, new asset, .meta, rename), any batch of them, Editor closed | t1k-unity-blind-edit-assets. It refuses while Temp/UnityLockfile shows a live Editor: close the Editor or use the live path for that edit. |
| Editor open: console, compile, Play mode, menu, tests, GameObject work, anything runtime | t1k unity <verb> (this skill); no verb for the job: t1k unity eval |
| DOTS world, entities, systems, SubScenes, graphics, physics | t1k unity dots <action> (Play mode needed for runtime state). The embedded package is REQUIRED in a DOTS project: doctor fails without it, run t1k unity setup (references/setup-and-pin.md) |
| Editor closed and only a DOTS query is needed | t1k unity run --command <id> (headless one-shot; only list_component_types / list_subscenes mean anything) |
| Tests | Editor open: t1k unity test runs the live Test Runner; Editor closed: the same verb launches batch mode (gated, one Unity process at a time). Quick pre-check of the engine-free subset first: t1k unity dotnet-test (no Editor, seconds) |
| Profiler, screenshots, input simulation | No CLI command yet: say so, take the manual or blind-edit path |
Launching Unity yourself defaults to headless (-batchmode -nographics); open a window only for rendering or frame events: rules/unity-headless-by-default.md, flags in references/headless-vs-windowed.md.
Write ALL source changes first, then ONE t1k unity recompile (or refresh --compile): see rules/ai-velocity-batch-compile-unity.md.
All verbs accept --format json (the only format) and --lock-wait N (seconds to queue for the project lock, default 120). Flags and examples: references/verbs-detail.md.
| Verb | Does | Locks |
|---|---|---|
status | Editor reachability plus CLI, pin, pipeline and package health (exit 14 if no Editor) | no |
doctor | Read-only health report with error.fix per problem; works with no Editor | no |
setup [--no-install] | Installs the pinned unity CLI if missing, the pinned pipeline package, and the embedded editor package | yes |
test [--mode edit|play] [--filter X] [--assembly A] [--timeout S] [--allow-empty] | Counts, failing test names, path taken (live-editor or batch); exit 8 is never downgraded; 0 tests run is exit 1 no-tests-run unless --allow-empty; a run the Editor REFUSED is exit 1 test-run-refused carrying the pipeline’s own message (see below) | yes |
dotnet-test [--assembly A] [--filter X] [--timeout S] [--tfm netN.0] [--classify-only] [--strict-closure] | Fast PRE-CHECK: links only source-clean files and runs the engine-free EditMode tests under plain dotnet test -m:1, no Editor (seconds vs about a minute). Engine-bound tests are NOT run (data.unityRunRequired: true); never a substitute for test | no |
recompile [--strict] [--timeout S] | Refresh, compile, poll until done; data.errors[] as file/line/message | yes |
refresh [--compile] | AssetDatabase refresh, waits for the Editor to settle | yes |
console [--level error|warning|log] [--since N] [--limit N] [--grep RX] | Tail the Editor console | no |
eval '<C#>' or eval --file f.cs | Evaluate C# in the Editor | no |
menu '<Menu/Path>' | Invoke a menu item | yes |
play enter|exit|status | Toggle Play mode and wait for the Editor to settle | enter/exit |
dots <action> [--flag v] | One of 30 DOTS actions, references/dots-actions.md | mutating actions only |
instance [list|current] | Which Editor is bound to this project (binding is by working directory; there is no select) | no |
commands | List every command the CLI and package expose | no |
run --command <id> | Headless one-shot; refuses when an Editor already has the project | yes |
Reading the envelope
Section titled “Reading the envelope”stdout is exactly ONE JSON object, human text goes to stderr: {schema, ok, verb, exit, data | error{code,message,fix,hint,details}, meta}. Branch on ok and exit, never on stderr. error.fix is the remedy to run (often a t1k unity ... line); act on it before improvising. meta carries retried (the facade already re-issued the call once), unityExit, lock, gate, durationMs, pin, projectRoot, ignoredEnv.
Exit codes and the retry rule
Section titled “Exit codes and the retry rule”| Exit | Meaning | Retry |
|---|---|---|
| 0 | ok | - |
| 1 | verb failed (raw tail in error.details) | no |
| 2 | usage: bad verb or flag | no, fix the call |
| 3 | Unity auth failure | no, needs a human |
| 4 | setup required (CLI, pipeline package or editor package missing) | no, run error.fix |
| 6 | operation failed: compile errors, test run did not finish, DOTS command error | test once; others no |
| 7 | Editor unreachable after the facade’s own retry | yes, later; check state first |
| 8 | tests ran and some failed | NEVER |
| 10 | project lock busy: a sibling session drives this Editor | yes, later; never reach around it |
| 11 | blocked by T1K safety policy (Quit, Exit, Reimport All, denied eval pattern) | no |
| 12 | installed unity is not the pinned version | no, references/setup-and-pin.md |
| 13 | no Unity project at or above cwd | no |
| 14 | no Editor open for this project (or still booting) | yes, after opening it |
| 15 | dotnet-test only: .NET SDK missing or older than 8.0 | no, install it (error.fix) |
| 16 | dotnet-test only: zero engine-free tests discovered or run (red, not green) | no, see references/dotnet-test.md |
| 130 / 143 | signal passthrough | - |
Full table: scripts/lib/exit-codes.cjs. A timed-out call may have executed anyway: check state (console, files) before re-issuing a mutating verb.
Editor mutex: obligations that stay
Section titled “Editor mutex: obligations that stay”The Editor is single-threaded for reloads, Play transitions, test runs and imports, and shared by every session on the machine.
- Mutating verbs take
<root>/Temp/t1k-unity.lock. Exit 10 means someone else is mid-run: wait, never bypass. - A source edit during a test run triggers a recompile and kills the run. Edit nothing under
Assets/orPackages/while a test or Play session is live; a write there by ANY agent also tears down the DOTS world mid-Play. - Never kill, quit or restart the Editor, never run Reimport All (
rules/unity-forbidden-operations.md; the facade enforcesforbiddenMenusandevalDenywith exit 11). - Never issue a second reload while one is in flight (
status:readyfirst); a reload on a reload crashes the Editor.
Play mode and domain reload
Section titled “Play mode and domain reload”The eval token and port survive Play mode and recompiles. A call landing in the ~5 s Play-entry reload window fails with a network error the unity CLI does not retry: the facade polls editor_status until ready, re-issues once and sets meta.retried. After play enter DOTS runtime state exists; in Edit mode dots list_worlds returns 0 worlds. Exit 7 with error.code: editor-busy-or-modal means a modal dialog blocks the Editor: ask the user to dismiss it.
PlayMode tests cannot run synchronously (live path). The Pipeline run_tests command refuses a synchronous PlayMode request by design — entering Play mode triggers a domain reload that drops the in-flight HTTP request — and reports the refusal as a returned value over HTTP 200: {Success:false, Error:"<why>", Summary:<all zeros>, Results:[]}. The facade surfaces that as exit 1 test-run-refused with the pipeline’s own sentence in error.message, never as no-tests-run (“0 tests”). Do not read a refusal as an empty suite. Use the batch path (close the Editor and run t1k unity test --mode play, which runs the CLI’s own PlayMode runner) for a real PlayMode result. --assembly scopes the live run as --filter_type assembly; it cannot be combined with --filter.
References
Section titled “References”references/verbs-detail.md: flags, behaviours, what is not carried over from the old tool surface.references/dotnet-test.md: the engine-free fast pre-check: decision rule, exit codes, JSON fields, what is NOT covered.references/dots-actions.md: the 30 DOTS actions (generated, drift-tested).references/setup-and-pin.md: install, pin, package stamp, opt-out.references/headless-vs-windowed.md: task-to-mode table with the batch flags.references/incident-history.md: compile, cache, log and diagnosis traps, dated incidents.
Executed by
Section titled “Executed by”Runs inline in the main session (or an inline sub-agent Bash call): each verb is a deterministic script invocation, not a reasoning or orchestration task. No sub-agent fan-out.