Skip to content

t1k:unity:editor:cli

FieldValue
Moduleeditor
Version3.50.7
Effortmedium
Tools—

Keywords: t1k unity, unity cli, unity doctor, unity eval, unity facade, unity recompile, unity test

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

SituationUse
Static file edit (field, ref, new asset, .meta, rename), any batch of them, Editor closedt1k-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 runtimet1k unity <verb> (this skill); no verb for the job: t1k unity eval
DOTS world, entities, systems, SubScenes, graphics, physicst1k 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 neededt1k unity run --command <id> (headless one-shot; only list_component_types / list_subscenes mean anything)
TestsEditor 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 simulationNo 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.

VerbDoesLocks
statusEditor reachability plus CLI, pin, pipeline and package health (exit 14 if no Editor)no
doctorRead-only health report with error.fix per problem; works with no Editorno
setup [--no-install]Installs the pinned unity CLI if missing, the pinned pipeline package, and the embedded editor packageyes
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 testno
recompile [--strict] [--timeout S]Refresh, compile, poll until done; data.errors[] as file/line/messageyes
refresh [--compile]AssetDatabase refresh, waits for the Editor to settleyes
console [--level error|warning|log] [--since N] [--limit N] [--grep RX]Tail the Editor consoleno
eval '<C#>' or eval --file f.csEvaluate C# in the Editorno
menu '<Menu/Path>'Invoke a menu itemyes
play enter|exit|statusToggle Play mode and wait for the Editor to settleenter/exit
dots <action> [--flag v]One of 30 DOTS actions, references/dots-actions.mdmutating actions only
instance [list|current]Which Editor is bound to this project (binding is by working directory; there is no select)no
commandsList every command the CLI and package exposeno
run --command <id>Headless one-shot; refuses when an Editor already has the projectyes

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.

ExitMeaningRetry
0ok-
1verb failed (raw tail in error.details)no
2usage: bad verb or flagno, fix the call
3Unity auth failureno, needs a human
4setup required (CLI, pipeline package or editor package missing)no, run error.fix
6operation failed: compile errors, test run did not finish, DOTS command errortest once; others no
7Editor unreachable after the facade’s own retryyes, later; check state first
8tests ran and some failedNEVER
10project lock busy: a sibling session drives this Editoryes, later; never reach around it
11blocked by T1K safety policy (Quit, Exit, Reimport All, denied eval pattern)no
12installed unity is not the pinned versionno, references/setup-and-pin.md
13no Unity project at or above cwdno
14no Editor open for this project (or still booting)yes, after opening it
15dotnet-test only: .NET SDK missing or older than 8.0no, install it (error.fix)
16dotnet-test only: zero engine-free tests discovered or run (red, not green)no, see references/dotnet-test.md
130 / 143signal 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.

The Editor is single-threaded for reloads, Play transitions, test runs and imports, and shared by every session on the machine.

  1. Mutating verbs take <root>/Temp/t1k-unity.lock. Exit 10 means someone else is mid-run: wait, never bypass.
  2. A source edit during a test run triggers a recompile and kills the run. Edit nothing under Assets/ or Packages/ while a test or Play session is live; a write there by ANY agent also tears down the DOTS world mid-Play.
  3. Never kill, quit or restart the Editor, never run Reimport All (rules/unity-forbidden-operations.md; the facade enforces forbiddenMenus and evalDeny with exit 11).
  4. Never issue a second reload while one is in flight (status:ready first); a reload on a reload crashes the Editor.

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

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.