From 4922272dc0872bbdaae5c1ab07594e0666b25876 Mon Sep 17 00:00:00 2001 From: "pre-shared-workflows-auth[bot]" <168739156+pre-shared-workflows-auth[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:17:16 +0000 Subject: [PATCH] chore: publish 2 skills (new-unity-project, unity-cli) --- skills/new-unity-project/SECURITY.md | 8 +- skills/new-unity-project/SKILL.md | 358 ++++------ .../new-unity-project/references/checklist.md | 23 + .../references/common-mistakes.md | 19 + .../references/join-and-terms.md | 33 + .../references/packages-and-identity.md | 44 ++ .../new-unity-project/references/publish.md | 41 ++ .../references/sign-in-details.md | 21 + .../references/skill-setup.md | 5 +- .../references/visual-baseline.md | 93 +++ skills/unity-cli/SKILL.md | 609 ++---------------- .../unity-cli/{ => references}/CHANGELOG.md | 133 ++-- .../references/auth-license-cloud.md | 8 +- skills/unity-cli/references/build-run-test.md | 14 +- .../unity-cli/references/cloud-automation.md | 6 +- skills/unity-cli/references/collaboration.md | 8 +- .../unity-cli/references/common-workflows.md | 462 +++++++++++++ skills/unity-cli/references/config-hub.md | 10 +- .../references/diagnostics-maintenance.md | 18 +- skills/unity-cli/references/docs-workflow.md | 10 +- .../unity-cli/references/editors-install.md | 6 +- skills/unity-cli/references/exit-codes.md | 53 ++ .../unity-cli/references/global-flags-env.md | 89 +++ .../references/integration-advanced.md | 24 +- skills/unity-cli/references/notes.md | 30 + .../references/playmode-verification-loop.md | 6 +- .../references/projects-templates.md | 8 +- .../unity-cli/references/version-control.md | 6 +- skills/unity-cli/references/worktrees.md | 3 + 29 files changed, 1232 insertions(+), 916 deletions(-) create mode 100644 skills/new-unity-project/references/checklist.md create mode 100644 skills/new-unity-project/references/common-mistakes.md create mode 100644 skills/new-unity-project/references/join-and-terms.md create mode 100644 skills/new-unity-project/references/packages-and-identity.md create mode 100644 skills/new-unity-project/references/publish.md create mode 100644 skills/new-unity-project/references/sign-in-details.md create mode 100644 skills/new-unity-project/references/visual-baseline.md rename skills/unity-cli/{ => references}/CHANGELOG.md (79%) create mode 100644 skills/unity-cli/references/common-workflows.md create mode 100644 skills/unity-cli/references/exit-codes.md create mode 100644 skills/unity-cli/references/global-flags-env.md create mode 100644 skills/unity-cli/references/notes.md create mode 100644 skills/unity-cli/references/worktrees.md diff --git a/skills/new-unity-project/SECURITY.md b/skills/new-unity-project/SECURITY.md index 5c94292..f3ac986 100644 --- a/skills/new-unity-project/SECURITY.md +++ b/skills/new-unity-project/SECURITY.md @@ -2,15 +2,17 @@ This skill has the agent install Unity Editors and packages, create a cloud-linked project, run C# inside the user's Editor (the visual baseline), write one small bootstrap script into the project, -and append one line to the project's CLAUDE.md or AGENTS.md. Automated skill scanners flag several -of these as powerful capabilities. They are intentional, and limited by the safeguards below. +append one line to the project's CLAUDE.md or AGENTS.md, and — only on the user's yes — upload a +WebGL build to Unity Play as a public listing. Automated skill scanners flag several of these as +powerful capabilities. They are intentional, and limited by the safeguards below. ## Accepted risks | Risk | Capability | Why it is accepted | |---|---|---| | `SEC_POWER_CAP` | Runs C# in the user's Editor | It only reaches the Editor the user already has open, on their own machine, as that user; the commands sit behind the Pipeline capability gate. No code fetched from a remote source is run — the agent runs C# it writes from this skill's and its delegated skills' own recipes. | -| `SEC_FILE_WRITE` | Writes one bootstrap script (Step 6) and appends one line to CLAUDE.md/AGENTS.md (Step 9) | Both writes land inside the project the skill just created and both are surfaced before they run: in paved mode as notice with an opt-out on the assumptions manifest ("say the word to change any of these"), in guided mode as per-step asks that are true consent. Both are reversible on a word, and the scope section caps the skill at exactly one bootstrap script. | +| `SEC_FILE_WRITE` | Writes one bootstrap script (Step 6) and appends one line to CLAUDE.md/AGENTS.md (Step 11) | Both writes land inside the project the skill just created and both are surfaced before they run: in paved mode as notice with an opt-out on the assumptions manifest ("say the word to change any of these"), in guided mode as per-step asks that are true consent. Both are reversible on a word, and the scope section caps the skill at exactly one bootstrap script. | +| `SEC_PUBLISH` | Uploads a WebGL build to Unity Play as a public listing on the user's account (Step 10) | Publishing is a human gate that is never consumed: the agent asks once after Step 9's commit, says plainly that a yes uploads the scene as it currently stands publicly (Step 9's playable loop on the paved path, the raw template on a `--bare` run), and waits. The upload runs only through the CLI's own publishing command on the signed-in account — network egress of the build and nothing else — and its confirmation flag is passed only because the user just answered that same question. An editing URL in the result is handed over as the author's page to finish, never presented as a playable link, and an accepted upload is never retried (a retry would create a second public listing); a timeout or unclear outcome is reported as uncertain and checked on the user's listings page, never retried blind. | | `SEC_INSTALL` | Installs Editors, modules, packages, and (with the user's yes) agent skills | Installs go through the Unity CLI's own commands and the PackageManager API — never `curl \| sh`, never hand-edited manifests. Skill installs always ask first (Before Step 1). Versions and the package list are declared before installing. | | `SEC_CLOUD` | Creates a cloud-linked Unity project with diagnostics per the CLI's defaults | The link is `projects create`'s own default behavior, narrated to the user from the create result. Sign-in is a human gate: it runs only after the user's yes, and the user completes it in the browser. `--bare` and the link opt-outs are honored on the user's word. | diff --git a/skills/new-unity-project/SKILL.md b/skills/new-unity-project/SKILL.md index e533f96..986398a 100644 --- a/skills/new-unity-project/SKILL.md +++ b/skills/new-unity-project/SKILL.md @@ -9,7 +9,7 @@ allowed-tools: # New Unity Project -A flow from an idea to a running, version-controlled Unity project. This skill owns the **flow** — +A flow from an idea to a running, version-controlled Unity project that plays. This skill owns the **flow** — mode, defaults, ordering, background installs, handoffs. **Delegates to (read these for the actual commands — don't reinvent them):** @@ -22,6 +22,14 @@ mode, defaults, ordering, background installs, handoffs. - **`implement-in-app-purchases`**, **`levelplay-unity-integration`**, **`build-live-game`** — monetization / backend *integration* (invoked at the end). +**Before you go forward with a step or a diagnosis, open and read its pages**: the delegated +skill and the `references/` file the step names. Name the files you read in your reply, because +your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version. +Prefer fetching a doc page directly (for example `WebFetch`) over searching (for example +`WebSearch`), and only search without an exact URL. Replace `` before fetching: +- **docs.unity3d.com**: the Unity version, eg `6000.6` +- **Package on docs.unity3d.com**: the package version, eg `4.2`; check it if unsure. These sites have no `.md` variant + ## Mode: paved by default, guided on request Run **paved** unless the user asks for the interview — in words ("ask me questions", "guide me") @@ -30,9 +38,9 @@ or by pushing back on the manifest; mode is decided once per session. The paved the create launches · **proceed**, asking only on pushback or an unruled fork · **never consume a human gate** — sign-in, license activation and publishing each need the user's yes, asked as a question you wait on (see Sign-in and license). A **bare/minimal** ask gets -`--bare`, skips the floors, and states the cost (identity, saves, ranks unwired). Bare runs Steps -1–4, installs only the packages the user named in Step 5, skips Steps 6 and 7, then commits (Step 8) -and hands off monetization (Step 9) without the forward baton. +`--bare`, skips the floors, and states the cost (identity, saves, ranks unwired; no playable loop). +Bare runs Steps 1–5 (only the packages the user named), skips 6, 7, 9 and 10's publish ask +(the report names the route for later), commits (Step 8), and hands off (Step 11) without the baton. In **guided** mode, ask only the current step's questions and wait. The paved additions (identity, floors, baton) are asked at their steps there, never assumed. @@ -54,19 +62,7 @@ accepted, and an agent can't see or click that dialog. When sign-in and license and no license question goes out, still ask about the terms with your first question; the create can start before the answer, but `unity terms accept` and the first `unity open` wait for it. -- Never tell the user to sign in or activate a license themselves, and never hand them commands to - run. You run them, after they say yes. -- On yes, sign in only where the choice needs an account: Personal and an existing subscription - activate the signed-in user's licenses, and a cloud-linked project needs one too. Run - `unity auth login` then (it opens the browser; the user only completes the sign-in page, so tell - them that page is coming), in the background or with its output unfiltered, and pass on the - sign-in link it prints in case the browser doesn't open: a pipe through `tail` holds the link - back until sign-in ends. Then `unity license activate --personal --accept-eula` for Personal. - Serial and floating activation need no account: `unity license activate --floating`, or the - serial through `UNITY_LICENSE_SERIAL` and a bare `unity license activate`, so it stays off argv. -- Declining stops the run before the create only when nothing can license the Editor. A user who - declines sign-in but has, or activates, a serial or floating license still gets a local project: - create with `--no-cloud` and say the cloud link and player accounts are off. +You run every sign-in and activation command yourself, after the user's yes, and never hand them commands to run. Personal and subscription seats need `unity auth login`; serial and floating do not. Exact commands and the declined-sign-in path: [references/sign-in-details.md](references/sign-in-details.md). ## The Defaults table @@ -80,7 +76,7 @@ Every row reverses on a word; change a row only with a run-earned receipt. | Monetization | None at creation; noted for later | | Version control | Local git + Unity .gitignore | | Player identity | Anonymous accounts — create's when its result shows them, else wired in Step 6 | -| Craft floors | Always on, via the `craft-game-floors` skill: look, camera, lighting, feedback, audio, shell, live floor, done gate | +| Craft floors | Always on, via the `craft-game-floors` skill: look, camera, lighting, character motion, a playable loop (the minimum), feedback, audio, shell, live floor, done gate | Cloud link and diagnostics are **not** a row: create applies its own defaults — narrate them from the result, don't re-decide. @@ -94,21 +90,19 @@ create will do (the URP template per `--template 3d|2d`, never a guessed id): > anonymous player accounts (create's, else one bootstrap script) · · > cloud-linked with diagnostics (create's defaults, narrated from the result) · floor packages > (Cinemachine; identity + live services when cloud-linked) · craft floors on via `craft-game-floors` · -> a one-line handoff note for the project's CLAUDE.md, written only on your yes. +> at least one playable loop (, or the user's stated shape), scored by its +> done gate · a one-line handoff note for the project's CLAUDE.md, written only on your yes. > Say the word to change any of these; otherwise I'm proceeding. -One block, every assumption present, each reversible, nothing implied; Step 3 reconciles the -result against it. +Step 3 reconciles the result against it. ## Before Step 1: check the delegated skills are loaded Look for `unity-cli`, `unity-package-management`, `urp-postprocessing`, `ui`, `build-live-game` and `craft-game-floors` in your client's skills. If any is missing, say which and what it does, and offer the install routes in [references/skill-setup.md](references/skill-setup.md), in the same question as sign-in and -license when that one goes out — never install without a yes. Don't -stall: a decline gets the fallback at its step, gap named in the report. `unity skill show` prints -`unity-cli` without installing; without `unity-package-management`, Step 5 can't run — say so -before Step 2. +license — never install without a yes. A decline gets the fallback at its step, gap named in the +report; without `unity-package-management`, Step 5 can't run, so say so before Step 2. ## The flow — and where the parallelism is @@ -118,22 +112,19 @@ installs the Editor + modules (minutes), then creates the project; keep talking 3. **(joins)** reconcile the result against the manifest. 4. **Source control.** 5. **Packages.** 6. **Player identity, then the craft floors** — confirm create's identity or wire it; load `craft-game-floors`. 7. **Visual baseline** on the craft skill's art bible. 8. **Save & first commit.** -9. **Hand off** + the forward baton. - -The multi-minute Editor install overlaps the user's answers, so setup feels instant. +9. **First playable loop** + the done gate. 10. **Publish** — asked, never assumed. +11. **Hand off** + the forward baton. ## Step 1 — Concept -**Paved:** the prompt is the spec — parse genre, dimension (2D/3D), look, scope, and name into a -2–4 line brief; fill gaps from the Defaults table; no read-back. +**Paved:** the prompt is the spec — parse genre, core loop, dimension (2D/3D), look, scope, and name +into a 2–4 line brief; fill gaps from the Defaults table (no loop named → pick one from the genre and +put it in the manifest); no read-back. -**Guided:** ask with your client's multiple-choice tool (`AskUserQuestion` in Claude Code, -`ask_user` in Copilot CLI, `askQuestions` in VS Code); without one, plain text. -Cover **genre / core loop** · **dimension & look** (2D or 3D; pixel, low-poly, stylized, -realistic) · **gameplay** (the one-sentence "what the player does moment to moment") · **scope** -(prototype vs. multi-scene; single- or multiplayer). Settle a **project name**, write the brief, -read it back. The brief drives the template (Step 2), packages (Step 5) and the baseline (Step 7): -note the palette / mood words and pixel-art looks. +**Guided:** ask with your client's multiple-choice tool (plain text without one): **genre / core +loop** · **dimension & look** · **gameplay** (what the player does moment to moment) · **scope**. +Settle a **project name**, write the brief, read it back. Note the palette and mood words, +pixel-art looks and the loop's verb: they drive Steps 2, 5, 7 and 9. ## Step 2 — Platforms & monetization, then start installing @@ -141,17 +132,22 @@ Two decisions (paved: filled from the Defaults table, then **print the manifest* - **Target platforms**: Desktop, Mobile (iOS/Android), WebGL, Console — they map to Editor **modules** (`--module`) and argue for leaner packages on mobile/WebGL. -- **Monetization**: none / premium / IAP / ads / mix — this only decides the Step 9 handoff. +- **Monetization**: none / premium / IAP / ads / mix — this only decides the Step 11 handoff. Default to an explicit `--editor-version latest` unless the user names a version — without the flag, create prefers a stored default or an older installed Editor. For a cloud-linked create, pick the organization first: `unity cloud orgs --format json`. When `data.activeOrganizationId` is null and `data.organizations` holds exactly one org, pass that org's `id` as -`--cloud-org `; without it create links nothing (`CLOUD_LINK_FAILED`, no organization -configured) and skips player accounts, Remote Config and Cloud Save. With several orgs and no -default, ask the user which one before starting the create (the list needs sign-in, so this comes -after it). +`--cloud-org `; without it create links nothing and skips player accounts, Remote Config and +Cloud Save. With several orgs and no default, ask the user which one before the create. + +| Error code | Cause | Resolution | +|---|---|---| +| `CLOUD_LINK_FAILED` (no organization configured) | create had no org to link | pass `--cloud-org ` from `unity cloud orgs`; ask when several | +| `PIPELINE_EDITOR_UNSUPPORTED` | Editor 6000.5.0 to 6000.5.2 can't run the Pipeline package | ask to update to 6000.5.3f1 or later ([visual-baseline.md](references/visual-baseline.md)) | +| `PROJECT_UPGRADE_REQUIRED` | `unity open` refuses a move to 6000.7 or later | `unity projects upgrade "" --to --yes` | +| `CLOUD_CHOICE_REQUIRED` | upgrading a project the user kept unlinked | add `--no-cloud` to that upgrade | Confirm prerequisites, then **start the create as a background task** (`unity-cli` has module names and auth / license setup): @@ -169,37 +165,19 @@ unity projects create "" --output-dir --editor-version latest \ The command waits for the install, then creates the project, so its one result covers both. If you have nothing left to ask, it's fine to just wait. -**Template:** `--template 3d` / `2d` resolve to the version's URP templates -(`com.unity.template.urp-blank`, `com.unity.template.universal-2d`), the default for every game. -Built-in templates (`com.unity.template.3d`/`.2d` as full ids) are deprecated from 6.5, removed in -6.7 — pass one only when the user explicitly asks for Built-in. +**Template:** `--template 3d` / `2d` resolve to the URP templates. Pass a Built-in template id only +when the user asks for Built-in (deprecated from 6.5, removed in 6.7). ## Step 3 — Join: project ready, result reconciled -Wait for the background create and read its JSON result: `data.path` is the project, -`data.version` the Editor, `data.editorInstalled` whether this run installed it. - -**Paved: reconcile the result against the manifest**, narrating divergence — the cloud-link -soft-fail included (`cloudLinked: false`, warnings, project intact; Step 6 keys off it). A 403 on -the link is often the saved default org refusing new projects — retry -`unity projects link cloud --cloud-org ` before concluding -no-identity. A result carrying a `steps` field reconciles step-by-step from it. - -`--module` only applies when the run installs the Editor: on `data.editorInstalled: false`, add -the platform modules with `unity install-modules -e -m --accept-eula` -(skips what's already there). If create failed, surface the error (`unity-cli` troubleshooting) -and stop — a failed install creates no project, and nothing downstream works without an Editor. - -**Once create succeeded, accept the Editor Software Terms before any open, and only after the -user's yes.** If the terms question is still unanswered, wait for the answer before running -anything. If the user declined, don't run `unity terms accept`: stop before the first open and say -the Editor won't start past its terms dialog. On a yes, run -`unity terms accept --architecture --yes` with no Editor running -(a running Editor can overwrite the answer). It reports `alreadyAccepted: true` and writes nothing -when they are already recorded. Do the same for any Editor the run moves to later, such as the -6000.5.3+ update in Step 7. If `unity status --until-ready` after an open reports -no instance while the Editor process is running, check `unity terms status --architecture `: a -`not-accepted` Editor is sitting on that dialog, which only the user can click. +Wait for the background create and read its JSON result: `data.path` is the project, `data.version` +the Editor, `data.editorInstalled` whether this run installed it. If create failed, surface the error +and stop, because nothing downstream works without an Editor. + +Then follow [references/join-and-terms.md](references/join-and-terms.md): reconcile the result +against the manifest (paved), add modules when `editorInstalled` is false, and run +`unity terms accept` only after the user's yes and before any `unity open`, because an unaccepted +Editor stops on a dialog an agent cannot click. ## Step 4 — Source control @@ -213,116 +191,39 @@ commit is Step 8. Exact flags: the `unity-cli` workflow. ## Step 5 — Packages Map the brief to a package list and install via **`unity-package-management`** (**never** -hand-edit `manifest.json`): `package add` once the Editor is open with `com.unity.pipeline` -(Step 7); its C# installer script when packages must land pre-open (the `-quit` gotcha applies). -That skill has the genre/platform/monetization → package mapping. A `--bare` run installs only the -packages the user named, through the C# installer script (bare has no `com.unity.pipeline`, so -`package add` can't run; never `unity pipeline install` to get it, which undoes the bare ask), and -stops there. Otherwise paved -adds the floors' needs: Cinemachine for any gameplay camera (2D rigs included); -`com.unity.services.authentication` when Step 6 wires identity; and the live floor's services set -on cloud-linked projects — in this pass, not at shell time. Cloud save and remote config come from -create: when its `steps` report `cloudSave` and `remoteConfig` as `done` or `present`, skip them and -add only what is left (leaderboards). The template already provides the -render pipeline — never add `com.unity.render-pipelines.universal` on a Built-in template -(materials go pink) or vice versa. Read the list back before installing (paved: print it now); -verify `manifest.json` after. +hand-edit `manifest.json`); a `--bare` run installs only the packages the user named. Paved adds the +floors' needs (Cinemachine, authentication when Step 6 wires identity, the live floor's services on +cloud-linked projects) and skips what create already reports. Never add a render-pipeline package +atop the template. Read the list back (paved: print it), then verify `manifest.json`. Install +routes, the bare path and the services rules: [packages-and-identity.md](references/packages-and-identity.md). ## Step 6 — Player identity, then the craft floors -**Identity — the create result is the switch** (a `--bare` run skips this whole step: bare -projects still cloud-link unless `--no-cloud`, and the unwired cost was stated at Mode time): -identity addressed in the result → confirm it in the reconciliation and **skip**, never wire auth -twice. No identity and the project cloud-linked → -wire it: services init plus anonymous sign-in kicked off at bootstrap in **one small bootstrap -script**, never blocked on (mechanics: **`build-live-game`**, auth section — checked in Before -Step 1; missing and declined → skip the wiring, gap named); each service dependency is a named -plan line, declining removes only that line. Cloud link failed or skipped → -skip with the cost stated (saves and ranks stay local) — never wire services init against a -project with no cloud id. Invisible to players, upgradeable later — the root the live floor -builds on. - -**A `--bare` run skips the floors too** (the Mode section's stated cost). Otherwise **load the -`craft-game-floors` skill** (checked in Before Step 1) and follow its floors through the -build — art bible first, then camera, lighting, feedback, audio, shell, live floor, its done gate. -Its values supersede the inline fallbacks below whenever present, version skew included. Missing -and declined → fallbacks, gap named in the report. +A `--bare` run skips this step. **Identity:** the create result is the switch. Identity in the +result → confirm it and skip; none and cloud-linked → wire anonymous sign-in in one small bootstrap +script (`build-live-game`); link failed or skipped → skip, cost stated. Then **load +`craft-game-floors`** and follow its floors through the build; its values supersede the inline +fallbacks. Missing and declined → fallbacks, gap named. Full rules: +[packages-and-identity.md](references/packages-and-identity.md). ## Step 7 — Visual baseline -A fresh template renders correctly but looks like a default; left there, agents reach for `OnGUI` -and guess shader names. Apply this floor **before** any gameplay work. A `--bare` run skips this -whole step (no Pipeline install, no baseline): go to Step 8, which opens the project. - -**On Unity 6000.5.0 to 6000.5.2, stop here.** The Pipeline package can't start its server on those -Editors (create reports `PIPELINE_EDITOR_UNSUPPORTED`), so nothing below can connect, and reopening -won't help. Create also left the package out on those Editors. Ask the user to update to -6000.5.3f1 or later, then continue below with the project still closed: the Pipeline install comes -first, then `unity terms accept --architecture --yes` (Step 3; the -architecture of the Editor you'll open), then the open names the updated Editor, `unity open "" --editor-version -` — a plain `unity open` reopens with the project's saved 6000.5.x Editor. If the -update is 6000.7 or later, `unity open` refuses that move (`PROJECT_UPGRADE_REQUIRED`): run -`unity projects upgrade "" --to --yes` instead. It asks -nothing: add `--no-cloud` when the user declined the cloud link at create, since an unlinked -project otherwise exits `CLOUD_CHOICE_REQUIRED`, and no cloud flag when create linked it. - -**First, `unity pipeline install --project-path ""`, before opening the -Editor.** Running C# in the Editor and `unity command capture screenshot` below both need the -project's `com.unity.pipeline` package. Create adds it by default on newer CLIs (this install then -changes nothing); older CLIs leave the project without it, and Step 5's `-batchmode` installer -never touches it. Install-before-open is the supported order; without the package, everything below fails to -connect (it mimics `unity-cli`'s Safe Mode failure). The failure codes -(`PIPELINE_MANIFEST_WRITE_FAILED`, a stuck `STATUS_PIPELINE_LOAD_PENDING`) and the stuck-Editor -recovery are tabled in [references/skill-setup.md](references/skill-setup.md). - -**Then** `unity open ""`, wait until `unity status` reports the Editor ready, and -apply each item below by running C# in it — **`unity-cli` owns those commands**; don't re-derive -them here. - -Once the Editor is ready, read the `unity-pipeline` guide if your skills don't list it — -locations and mirroring routes: [references/skill-setup.md](references/skill-setup.md). - -**Items 1, 2, 5 and 6 assume a URP template**, the Step 2 default. If the user explicitly chose -Built-in, don't run them as written — `UniversalAdditionalCameraData`, `Light2D`, the -`urp-postprocessing` volume framework and `Universal Render Pipeline/*` shaders don't exist there; -post-processing means the legacy Post Processing Stack, the shader names are `Standard` / -`Unlit/Color`, and items 3–4 apply as written. Don't reach for `migrate-birp-to-urp` — the user -asked for Built-in. - -1. **Post-processing.** Global Volume — `craft-game-floors`'s scene-lighting values when loaded (they - supersede these); fallback: Tonemapping (ACES), Bloom intensity 0.5–1 @ threshold 0.9, Vignette - ≈ 0.25; set `renderPostProcessing = true` on the main camera's `UniversalAdditionalCameraData`. - **REQUIRED SUB-SKILL:** `urp-postprocessing` — its templates create the volume and check HDR and - the layer mask; if it isn't loaded, do both yourself from these values. -2. **Camera and light.** 2D → orthographic, solid background from the brief's palette, a `Light2D` - of type Global if the template scene has none (Sprite-Lit shaders render black without one). - 3D → perspective, main-light shadows on; `craft-game-floors`'s lighting pass replaces the template's - default light story when loaded, else keep the template's directional light and skybox. -3. **Quality tier.** Read `QualitySettings.names` first — tier names differ per template — then - `QualitySettings.SetQualityLevel` to the one matching the primary target: the highest tier for - desktop, the lowest for mobile/WebGL. Leave color space Linear and the Input System as the - template set them. -4. **UI stack.** HUD and menus use a uGUI Canvas + TextMeshPro or UI Toolkit — **never `OnGUI`**. - **REQUIRED SUB-SKILL:** `ui` picks between them for the project. If it isn't loaded, choose - between them from the brief and say which you chose, and why, in your final report. -5. **Materials and shaders.** Under URP use `Universal Render Pipeline/Lit`, `…/Unlit`, - `…/2D/Sprite-Lit-Default` or `…/2D/Sprite-Unlit-Default`. `Standard` and `Unlit/Color` render - pink or washed out under URP. Prefer `GraphicsSettings.currentRenderPipeline.defaultMaterial` - / `.default2DMaterial` over `Shader.Find`, and treat a `null` from `Shader.Find` as an error. - `currentRenderPipeline`, not `defaultRenderPipeline`: a quality tier can carry its own pipeline - asset, and item 3 above just set the tier. -6. **Pixel art only.** Point filter mode on sprites and a Pixel Perfect Camera — see - `2d-pixel-perfect`. If missing, do both yourself and note the skill-setup install route in the - report. - -Save the scene, then confirm both of these — **not with `unity logs`**, which reads the CLI's own -log and reports clean whatever the scene looks like: - -- No render-pipeline or shader errors Editor-side. Read the Editor console through `unity-cli`, - or read `Editor.log` directly — that skill's "Recovering from Safe Mode" section has the - per-platform paths. -- `unity command capture screenshot --output-path baseline.png` looks lit and tonemapped rather than flat - gray. +A fresh template renders correctly but looks like a default, and agents then reach for `OnGUI` +and guess shader names. Apply the baseline **before** any gameplay work. A `--bare` run skips this +step: go to Step 8. + +1. **Read [references/visual-baseline.md](references/visual-baseline.md) first.** It holds the + Editor-version stop (6000.5.0 to 6000.5.2 cannot run the Pipeline package), the order of + `unity pipeline install` before `unity open`, and the six items, because the details differ per + render pipeline and a wrong guess renders pink or flat. +2. Install the Pipeline package, open the project, and wait until `unity status` reports it ready. +3. Apply post-processing, camera and light, quality tier, UI stack, materials and shaders (and + pixel-art settings for pixel art). `unity-cli` owns the commands; use `craft-game-floors` values when it is loaded. +4. Save the scene, then check by file and API, never a screenshot: the Editor console has no + render-pipeline or shader errors (`unity command console status`; never `unity logs`, the CLI's + own log), and `script eval` reads back the camera post-processing flag, the Volume profile and the + quality tier. On a failure, reread [visual-baseline.md](references/visual-baseline.md), fix + that setting and check again. ## Step 8 — Save & first commit @@ -341,71 +242,76 @@ only if not — headless/CI uses the "Import & save headlessly" method in - **Unity Version Control (UVCS):** check in through the workspace from Step 4 — no `git` step; generated folders stay excluded by the ignore rules. -If Step 7 mirrored skills into the project, ask whether to include them. If Step 4 linked -**without** `--no-initial-commit`, the CLI already committed the bare project — add a follow-up -commit rather than double-committing. +If Step 7 mirrored skills into the project, ask whether to include them. A Step 4 link without +`--no-initial-commit` already committed the bare project: add a follow-up commit. + +## Step 9 — First playable loop + +A `--bare` run skips this step. Otherwise the Step 8 commit is the restore point; build on it with +`craft-game-floors`'s floors in its order: the gameplay camera, placeholder assets, character motion +(floor 6), then **at least one playable loop** (floor 7): one verb, one visible goal, one pressure, +a win or lose state, and a restart, or the shape the user stated (a sandbox has no lose state). Close the +loop first, then build as far as the prompt reaches, one system per pass. Then the feel, audio, shell and live floors, and +its **done gate** last, scored on the running build. Commit with the Step 4 VCS, `.meta` files +included. `craft-game-floors` missing and declined → build the loop from the +shape above, skip the gate, gap named in the report. + +## Step 10 — Publish + +**Publishing is a human gate**: after Step 9's commit, ask once whether to upload to Unity Play, +say plainly what a yes uploads, and wait. It is public and on the user's account, so never assume it. -## Step 9 — Hand off +On a yes, follow [references/publish.md](references/publish.md): confirm the CLI has a publishing +command, build WebGL through a build profile, upload, and read `urlKind` from the JSON result. +Never retry an upload that may have been accepted, because that creates a second public listing. +A declined publish is a one-line note in the report with the route to run later, never a nag. + +## Step 11 — Hand off Based on Step 2 monetization, invoke the matching skill for the actual integration: - IAP → **implement-in-app-purchases** - Ads → **levelplay-unity-integration** - Accounts / cloud save / economy / remote config / leaderboards → **build-live-game** -If the matching skill isn't loaded, point the next steps at the skill-setup install route rather -than integrating from memory. +If it isn't loaded, point at the skill-setup install route; never integrate from memory. **Offer the forward baton** (declared on the manifest; not on a `--bare` run): one idempotent line for the project's `CLAUDE.md` or `AGENTS.md` — "When building gameplay, feel, audio, shell, or live features, load the `craft-game-floors` skill; if it isn't installed, ask the user whether to run `unity skill install ` (ask: never run it without a yes)." That file steers every later agent session in the project, so **ask before writing it**, even in paved mode, and show the line. -On a yes, append it and commit the note — appended after Step 8, it otherwise never reaches clones. -On a no, put the line in the report for the user to add. Later sessions reach the floors through -it without this skill re-triggering. - -Report the project path, Editor version, pipeline and template, packages, the manifest with its -reconciliation, identity state, the baseline applied, any missing skill, `craft-game-floors`'s done gate -as the build's finish line, and next steps. - -## Scope — what this skill does NOT do - -- **No gameplay scaffolding.** A running, wired project with a visual floor; the game is the next - conversation (with `craft-game-floors`). One exception: Step 6's single bootstrap script. -- **No command reference.** Syntax lives in `unity-cli` / `unity-package-management`. -- **No re-deciding create's defaults** — narrate them from the result. The Defaults table is this - file's only opinions; the guided interview survives untouched. - -## Checklist - -- [ ] Delegated skills checked before Step 1 (incl. `craft-game-floors`): a missing one offered, or named - in the report -- [ ] Mode decided once; in paved, the manifest printed before the create launches -- [ ] Brief captured; platforms + monetization recorded -- [ ] Background create with `--install-editor` + modules, URP template (`--template 3d`/`2d`) - unless Built-in was requested; `--bare` only on the user's ask; result reconciled -- [ ] Source control attached (Step 4), or local git + Unity `.gitignore` -- [ ] Packages via `package add` (or the C# script pre-open); `manifest.json` verified; no - render-pipeline package atop the template -- [ ] Identity confirmed from the result or wired in Step 6 (stated cost on a failed link) -- [ ] `craft-game-floors` loaded (or its absence named); `unity-pipeline` read once the Editor was ready -- [ ] Baseline applied: Volume + camera post on, quality tier, UI stack (no `OnGUI`), URP shaders, - capture checked (skipped on `--bare`; on 6000.5.0–6000.5.2, Editor updated first) -- [ ] `.meta` files exist; first commit made; `Library/` excluded -- [ ] Forward baton offered and written only on a yes (none on `--bare`); handoff done if applicable +On a yes, append it and commit the note — appended after the last commit, it otherwise never +reaches clones. On a no, put the line in the report for the user to add. + +**Final check before the report.** Confirm the project has zero console errors with +`unity command console status` (on a `--bare` run without `com.unity.pipeline`, read `Editor.log` +instead; never install Pipeline for this), and stop there unless the user asked for proof or you suspect a +specific fault. To chase one, enter Play mode once and read state with `unity command script eval` +instead of adding logging, and take no screenshots. If a fix doesn't work, go back and reread the +step's delegated skill and `references/` file before trying again. + +## Final report + +Summarize what you did: project path, Editor version, pipeline and template, the manifest with its +reconciliation, identity state, the baseline, what the loop built, `craft-game-floors`'s done gate +scores, and the Unity Play link and kind (or Step 10's note). Disclose every side effect: packages +installed, terms accepted, sign-in, and files written such as the `CLAUDE.md` line. Then list the +user's follow-ups, any missing skill included. + +## Guardrails + +- **Do only what's asked. Don't change unrelated assets or files. Avoid long explanations.** Create one project and make only the changes the steps name, because the user will open this folder as their own. +- **Never leave verification code in the user's script. Never build logging or detection they didn't ask for.** +- **Restore point first.** Step 8's commit is the project's restore point. Make it before any gameplay work, and never rewrite or force-push it, so the user can return to a clean template. +- **Ask before anything public or global**: signing in, installing agent skills, writing to `CLAUDE.md` or `AGENTS.md`, and publishing, because each is hard to undo or affects more than this project. +- **Never run destructive commands** (`rm -rf`, `git reset --hard`, clearing the user's console) in the user's project. +- **End with the Final report**, listing what was and was not done and anything skipped, so nothing is silent. + +## Scope + +No command reference (syntax lives in `unity-cli` / `unity-package-management`), and no +re-deciding create's defaults: narrate them from the result. ## Common mistakes -- **Blocking on the create** instead of backgrounding it: with `--install-editor` it waits for the - whole Editor install. -- **Acting before the manifest prints** (paved), or burying an assumption outside it — if it isn't - in the manifest, it isn't assumed. -- **Wiring auth twice** — if create's result shows identity, Step 6's wiring is a skip. -- **Hand-editing `manifest.json`** instead of the package commands or the skill's script. -- **Doing a required sub-skill's job from memory** when it isn't loaded, without telling the user - or offering the install. -- **Committing `Library/`/`Temp/`/`obj/`/`Build/`**, or scripts without their `.meta` files. -- **Missing Editor modules** — a mobile target needs `android`/`ios`; WebGL needs `webgl`. -- **Picking `com.unity.template.2d` / `.3d` by name** — Built-in templates; use `--template 3d`/`2d`. -- **Skipping the visual baseline** — flat template defaults, `OnGUI` HUDs, and - `Shader.Find("Standard")` under URP. +Before you report, tick [references/checklist.md](references/checklist.md) and skim [references/common-mistakes.md](references/common-mistakes.md): backgrounding the create, hand-editing `manifest.json`, committing `Library/`, skipping the baseline, and publishing without a yes. diff --git a/skills/new-unity-project/references/checklist.md b/skills/new-unity-project/references/checklist.md new file mode 100644 index 0000000..d7f33be --- /dev/null +++ b/skills/new-unity-project/references/checklist.md @@ -0,0 +1,23 @@ +# Checklist — new-unity-project reference + +Tick every line before the Final report. + +- [ ] Delegated skills checked before Step 1 (incl. `craft-game-floors`): a missing one offered, or named + in the report +- [ ] Mode decided once; in paved, the manifest printed before the create launches +- [ ] Brief captured; platforms + monetization recorded +- [ ] Background create with `--install-editor` + modules, URP template (`--template 3d`/`2d`) + unless Built-in was requested; `--bare` only on the user's ask; result reconciled +- [ ] Source control attached (Step 4), or local git + Unity `.gitignore` +- [ ] Packages via `package add` (or the C# script pre-open); `manifest.json` verified; no + render-pipeline package atop the template +- [ ] Identity confirmed from the result or wired in Step 6 (stated cost on a failed link) +- [ ] `craft-game-floors` loaded (or its absence named); `unity-pipeline` read once the Editor was ready +- [ ] Baseline applied: Volume + camera post on, quality tier, UI stack (no `OnGUI`), URP shaders, + settings read back with `script eval` (skipped on `--bare`; on 6000.5.0–6000.5.2, Editor updated first) +- [ ] `.meta` files exist; first commit made; `Library/` excluded +- [ ] At least one playable loop closed (floor 7, or the user's stated shape), the done gate run on + the build, and the build committed (skipped on `--bare`) +- [ ] Publish asked once after the Step 9 commit, never assumed; on a yes, the Unity Play link in + the report (the gap named on CLI versions without `publish`) +- [ ] Forward baton offered and written only on a yes (none on `--bare`); handoff done if applicable diff --git a/skills/new-unity-project/references/common-mistakes.md b/skills/new-unity-project/references/common-mistakes.md new file mode 100644 index 0000000..d552047 --- /dev/null +++ b/skills/new-unity-project/references/common-mistakes.md @@ -0,0 +1,19 @@ +# Common mistakes — new-unity-project reference + +- **Blocking on the create** instead of backgrounding it: with `--install-editor` it waits for the + whole Editor install. +- **Acting before the manifest prints** (paved), or burying an assumption outside it — if it isn't + in the manifest, it isn't assumed. +- **Wiring auth twice** — if create's result shows identity, Step 6's wiring is a skip. +- **Hand-editing `manifest.json`** instead of the package commands or the skill's script. +- **Doing a required sub-skill's job from memory** when it isn't loaded, without telling the user + or offering the install. +- **Committing `Library/`/`Temp/`/`obj/`/`Build/`**, or scripts without their `.meta` files. +- **Missing Editor modules** — a mobile target needs `android`/`ios`; WebGL needs `webgl`. +- **Picking `com.unity.template.2d` / `.3d` by name** — Built-in templates; use `--template 3d`/`2d`. +- **Skipping the visual baseline** — flat template defaults, `OnGUI` HUDs, and + `Shader.Find("Standard")` under URP. +- **Stopping at the baseline** — a project that renders but doesn't play leaves the done gate + nothing to score. The opposite slip: piling on content before the first loop closes. +- **Publishing on an assumption, or not asking at all** — the link is the flow's last leg, and + it's a human gate in both directions: never uploaded without a yes, never silently dropped. diff --git a/skills/new-unity-project/references/join-and-terms.md b/skills/new-unity-project/references/join-and-terms.md new file mode 100644 index 0000000..cb2e924 --- /dev/null +++ b/skills/new-unity-project/references/join-and-terms.md @@ -0,0 +1,33 @@ +# Step 3: join the create, reconcile, accept terms — new-unity-project reference + +### Contents + +- Read the create result and reconcile it with the manifest +- Install modules when the Editor was already present +- Accept the Editor Software Terms + +Wait for the background create and read its JSON result: `data.path` is the project, +`data.version` the Editor, `data.editorInstalled` whether this run installed it. + +**Paved: reconcile the result against the manifest**, narrating divergence — the cloud-link +soft-fail included (`cloudLinked: false`, warnings, project intact; Step 6 keys off it). A 403 on +the link is often the saved default org refusing new projects — retry +`unity projects link cloud --cloud-org ` before concluding +no-identity. A result carrying a `steps` field reconciles step-by-step from it. + +`--module` only applies when the run installs the Editor: on `data.editorInstalled: false`, add +the platform modules with `unity install-modules -e -m --accept-eula` +(skips what's already there). If create failed, surface the error (`unity-cli` troubleshooting) +and stop — a failed install creates no project, and nothing downstream works without an Editor. + +**Once create succeeded, accept the Editor Software Terms before any open, and only after the +user's yes.** If the terms question is still unanswered, wait for the answer before running +anything. If the user declined, don't run `unity terms accept`: stop before the first open and say +the Editor won't start past its terms dialog. On a yes, run +`unity terms accept --architecture --yes` with no Editor running +(a running Editor can overwrite the answer). It reports `alreadyAccepted: true` and writes nothing +when they are already recorded. Do the same for any Editor the run moves to later, such as the +6000.5.3+ update in Step 7. If `unity status --until-ready` after an open reports +no instance while the Editor process is running, check `unity terms status --architecture `: a +`not-accepted` Editor is sitting on that dialog, which only the user can click. + diff --git a/skills/new-unity-project/references/packages-and-identity.md b/skills/new-unity-project/references/packages-and-identity.md new file mode 100644 index 0000000..bb76734 --- /dev/null +++ b/skills/new-unity-project/references/packages-and-identity.md @@ -0,0 +1,44 @@ +# Packages and player identity (Steps 5 and 6) — new-unity-project reference + +The detail behind the main skill file's Steps 5 and 6. Read it before either step. + +## Step 5 — Packages + +Map the brief to a package list and install via **`unity-package-management`** (**never** +hand-edit `manifest.json`): `package add` once the Editor is open with `com.unity.pipeline` +(Step 7); its C# installer script when packages must land pre-open (the `-quit` gotcha applies). +That skill has the genre/platform/monetization → package mapping. A `--bare` run installs only the +packages the user named, through the C# installer script (bare has no `com.unity.pipeline`, so +`package add` can't run; never `unity pipeline install` to get it, which undoes the bare ask), and +stops there. Otherwise paved +adds the floors' needs: Cinemachine for any gameplay camera (2D rigs included); +`com.unity.services.authentication` when Step 6 wires identity; and the live floor's services set +on cloud-linked projects — in this pass, not at shell time. Cloud save and remote config come from +create: when its `steps` report `cloudSave` and `remoteConfig` as `done` or `present`, skip them and +add only what is left (leaderboards). The template already provides the +render pipeline — never add `com.unity.render-pipelines.universal` on a Built-in template +(materials go pink) or vice versa. Read the list back before installing (paved: print it now); +verify `manifest.json` after. + +## Step 6 — Player identity, then the craft floors + +**Identity — the create result is the switch** (a `--bare` run skips this whole step: bare +projects still cloud-link unless `--no-cloud`, and the unwired cost was stated at Mode time): +identity addressed in the result → confirm it in the reconciliation and **skip**, never wire auth +twice. No identity and the project cloud-linked → +wire it: services init plus anonymous sign-in kicked off at bootstrap in **one small bootstrap +script**, never blocked on (mechanics: **`build-live-game`**, auth section — checked in Before +Step 1; missing and declined → skip the wiring, gap named); each service dependency is a named +plan line, declining removes only that line. Cloud link failed or skipped → +skip with the cost stated (saves and ranks stay local) — never wire services init against a +project with no cloud id. Invisible to players, upgradeable later — the root the live floor +builds on. + +**A `--bare` run skips the floors too** (the Mode section's stated cost). Otherwise **load the +`craft-game-floors` skill** (checked in Before Step 1) and follow its floors through the +build — art bible and lighting with the baseline (Step 7), then camera, character motion, the +playable loop, feedback, audio, shell, live floor, and its done gate (Step 9). +Its values supersede the skill's own fallbacks (`visual-baseline.md` items 1 to 6 and the main +skill file's Step 9 loop) whenever present, version skew included. Missing +and declined → fallbacks, gap named in the report. + diff --git a/skills/new-unity-project/references/publish.md b/skills/new-unity-project/references/publish.md new file mode 100644 index 0000000..77aa18a --- /dev/null +++ b/skills/new-unity-project/references/publish.md @@ -0,0 +1,41 @@ +# Publish to Unity Play (Step 10) — new-unity-project reference + +### Contents + +- The human gate +- Confirm the CLI offers publishing +- Build WebGL +- Upload and read the result + +The flow's last leg is a link someone can play, because a project that exists only on this machine +hands the user nothing to show. **Publishing is a human gate** (the Mode contract): after Step 9's +commit, ask once whether to upload the project to Unity Play, and wait — the upload is +public-facing and runs on the user's account, so it is never assumed, in paved mode included. Say +plainly what a yes uploads at this point — describe the scene as it actually stands: on the paved +path that is Step 9's playable loop as its done gate scored it, on a `--bare` run the raw +template (not yet a game, so that listing is only a pipeline receipt). On a yes, in order: + +1. **Confirm the CLI offers it**: run `unity --help` and look for a publishing command group. + Most installed CLIs have none yet — then say so, point the user at the WebGL Publisher package + as the manual route, with `` the package version, eg `4.2` (check it if unsure; the site has no `.md` variant) + (https://docs.unity3d.com/Packages/com.unity.connect.share@/manual/index.html), record the + gap in the report, and never drive the Editor UI to publish on the user's behalf. +2. **A WebGL build is the input.** WebGL has no built-in command-line build, so it takes a build + profile: `unity build --create-profile WebGL` once, then `unity build --profile "Assets/Settings/Build + Profiles/WebGL.asset" --output-path ` (the `webgl` module must be installed — Step 2's + modules, else `unity install-modules`). +3. **Upload through that publishing group's own command** — read its `--help` first; it takes the + build directory, zips and uploads it on the signed-in account, and asks its own confirmation, + which is the same human gate the user just answered, so pass the confirmation flag its help + names. Read the result with `--format json`: `url` is the listing and `urlKind` says what kind — + `listing-edit` is the author's editing page, not a playable link, so hand it to the user as + "finish the listing here" and present a playable URL only once they have. The command's errors + are self-contained (sign-in, a non-WebGL folder, the size limit) and name the fix: run the + named fix and retry only when the failure clearly came before the upload was accepted — after + acceptance, every invocation uploads again and creates a second listing, so report the accepted + upload for inspection instead of retrying. A timeout or dropped connection is neither: the + upload may have been accepted anyway, so do not retry — report the outcome as uncertain and ask + the user to check their Unity Play listings before any second attempt. + +A declined publish is a one-line note in the report with the route to run later, never a nag. + diff --git a/skills/new-unity-project/references/sign-in-details.md b/skills/new-unity-project/references/sign-in-details.md new file mode 100644 index 0000000..f4be3d6 --- /dev/null +++ b/skills/new-unity-project/references/sign-in-details.md @@ -0,0 +1,21 @@ +# Sign-in and license details — new-unity-project reference + +### Contents + +- Rules for signing in and activating +- Declining + +- Never tell the user to sign in or activate a license themselves, and never hand them commands to + run. You run them, after they say yes. +- On yes, sign in only where the choice needs an account: Personal and an existing subscription + activate the signed-in user's licenses, and a cloud-linked project needs one too. Run + `unity auth login` then (it opens the browser; the user only completes the sign-in page, so tell + them that page is coming), in the background or with its output unfiltered, and pass on the + sign-in link it prints in case the browser doesn't open: a pipe through `tail` holds the link + back until sign-in ends. Then `unity license activate --personal --accept-eula` for Personal. + Serial and floating activation need no account: `unity license activate --floating`, or the + serial through `UNITY_LICENSE_SERIAL` and a bare `unity license activate`, so it stays off argv. +- Declining stops the run before the create only when nothing can license the Editor. A user who + declines sign-in but has, or activates, a serial or floating license still gets a local project: + create with `--no-cloud` and say the cloud link and player accounts are off. + diff --git a/skills/new-unity-project/references/skill-setup.md b/skills/new-unity-project/references/skill-setup.md index ae8a564..9500b52 100644 --- a/skills/new-unity-project/references/skill-setup.md +++ b/skills/new-unity-project/references/skill-setup.md @@ -39,8 +39,9 @@ the installer put it and read the skill file from there. It is the Pipeline package's own guide, and no client loads it from the package folder. If it is missing from your skills, read its skill file directly. It sits under `.claude/skills/unity-pipeline/` in the package: `Packages/com.unity.pipeline/` if the project embeds -the package, otherwise the `Library/PackageCache/com.unity.pipeline@*` folder. List -`Library/PackageCache` for the exact name, since the suffix is often a hash, not the version. +the package, otherwise `/Library/PackageCache/com.unity.pipeline@*/`. List +`Library/PackageCache` for the exact name, since the suffix is often a hash, not the version. Read +only `.md` files, and only from that one package folder. To have your client load it in later sessions, `unity skill install --local` can mirror it, but only for a client with a project scope (`unity skill install --list` shows which, and Claude diff --git a/skills/new-unity-project/references/visual-baseline.md b/skills/new-unity-project/references/visual-baseline.md new file mode 100644 index 0000000..99c120a --- /dev/null +++ b/skills/new-unity-project/references/visual-baseline.md @@ -0,0 +1,93 @@ +# Visual baseline (Step 7) — new-unity-project reference + +Relative links in this file resolve to the skill directory's `references/` folder. + +### Contents + +- The Editor-version stop on 6000.5.0 to 6000.5.2 +- Pipeline install before the first open +- The six baseline items +- Confirming the result + +A fresh template renders correctly but looks like a default; left there, agents reach for `OnGUI` +and guess shader names. Apply this floor **before** any gameplay work. A `--bare` run skips this +whole step (no Pipeline install, no baseline): go to Step 8, which opens the project. + +**On Unity 6000.5.0 to 6000.5.2, stop here.** The Pipeline package can't start its server on those +Editors (create reports `PIPELINE_EDITOR_UNSUPPORTED`), so nothing below can connect, and reopening +won't help. Create also left the package out on those Editors. Ask the user to update to +6000.5.3f1 or later, then continue below with the project still closed: the Pipeline install comes +first, then `unity terms accept --architecture --yes` (Step 3; the +architecture of the Editor you'll open), then the open names the updated Editor, `unity open "" --editor-version +` — a plain `unity open` reopens with the project's saved 6000.5.x Editor. If the +update is 6000.7 or later, `unity open` refuses that move (`PROJECT_UPGRADE_REQUIRED`): run +`unity projects upgrade "" --to --yes` instead. It asks +nothing: add `--no-cloud` when the user declined the cloud link at create, since an unlinked +project otherwise exits `CLOUD_CHOICE_REQUIRED`, and no cloud flag when create linked it. + +**First, `unity pipeline install --project-path ""`, before opening the +Editor.** Running C# in the Editor, which every check below uses, needs the +project's `com.unity.pipeline` package. Create adds it by default on newer CLIs (this install then +changes nothing); older CLIs leave the project without it, and Step 5's `-batchmode` installer +never touches it. Install-before-open is the supported order; without the package, everything below fails to +connect (it mimics `unity-cli`'s Safe Mode failure). The failure codes +(`PIPELINE_MANIFEST_WRITE_FAILED`, a stuck `STATUS_PIPELINE_LOAD_PENDING`) and the stuck-Editor +recovery are tabled in [skill-setup.md](skill-setup.md). + +**Then** `unity open ""`, wait until `unity status` reports the Editor ready, and +apply each item below by running C# in it — **`unity-cli` owns those commands**; don't re-derive +them here. + +Once the Editor is ready, read the `unity-pipeline` guide if your skills don't list it — +locations and mirroring routes: [skill-setup.md](skill-setup.md). + +**Items 1, 2, 5 and 6 assume a URP template**, the Step 2 default. If the user explicitly chose +Built-in, don't run them as written — `UniversalAdditionalCameraData`, `Light2D`, the +`urp-postprocessing` volume framework and `Universal Render Pipeline/*` shaders don't exist there; +post-processing means the legacy Post Processing Stack, the shader names are `Standard` / +`Unlit/Color`, and items 3–4 apply as written. Don't reach for `migrate-birp-to-urp` — the user +asked for Built-in. + +1. **Post-processing.** Global Volume — `craft-game-floors`'s scene-lighting values when loaded (they + supersede these); fallback: Tonemapping (ACES), Bloom intensity 0.5–1 @ threshold 0.9, Vignette + ≈ 0.25; set `renderPostProcessing = true` on the main camera's `UniversalAdditionalCameraData`. + **REQUIRED SUB-SKILL:** `urp-postprocessing` — its templates create the volume and check HDR and + the layer mask; if it isn't loaded, do both yourself from these values. +2. **Camera and light.** 2D → orthographic, solid background from the brief's palette, a `Light2D` + of type Global if the template scene has none (Sprite-Lit shaders render black without one). + 3D → perspective, main-light shadows on; `craft-game-floors`'s lighting pass replaces the template's + default light story when loaded, else keep the template's directional light and skybox. +3. **Quality tier.** Read `QualitySettings.names` first — tier names differ per template — then + `QualitySettings.SetQualityLevel` to the one matching the primary target: the highest tier for + desktop, the lowest for mobile/WebGL. Leave color space Linear and the Input System as the + template set them. +4. **UI stack.** HUD and menus use a uGUI Canvas + TextMeshPro or UI Toolkit — **never `OnGUI`**. + **REQUIRED SUB-SKILL:** `ui` picks between them for the project. If it isn't loaded, choose + between them from the brief and say which you chose, and why, in your final report. +5. **Materials and shaders.** Under URP use `Universal Render Pipeline/Lit`, `…/Unlit`, + `…/2D/Sprite-Lit-Default` or `…/2D/Sprite-Unlit-Default`. `Standard` and `Unlit/Color` render + pink or washed out under URP. Prefer `GraphicsSettings.currentRenderPipeline.defaultMaterial` + / `.default2DMaterial` over `Shader.Find`, and treat a `null` from `Shader.Find` as an error. + `currentRenderPipeline`, not `defaultRenderPipeline`: a quality tier can carry its own pipeline + asset, and item 3 above just set the tier. +6. **Pixel art only.** Point filter mode on sprites and a Pixel Perfect Camera — see + `2d-pixel-perfect`. If missing, do both yourself and note the skill-setup install route in the + report. + +Save the scene, then confirm both of these — **not with `unity logs`**, which reads the CLI's own +log and reports clean whatever the scene looks like: + +- No render-pipeline or shader errors Editor-side. Read the Editor console through `unity-cli`, + or read `Editor.log` directly — that skill's "Recovering from Safe Mode" section has the + per-platform paths. +- The settings took, read back with `unity command script eval` rather than a screenshot: the main + camera's `UniversalAdditionalCameraData.renderPostProcessing` is `true`, a global `Volume` with a + non-null profile is in the scene, `QualitySettings.GetQualityLevel()` is the tier you set, and + `GraphicsSettings.currentRenderPipeline` is not `null`. On Built-in, check only that a + `PostProcessVolume` with a profile is in the scene, that the main camera has a + `PostProcessLayer` whose layer mask includes the volume's layer, and that the quality tier took; + `currentRenderPipeline` is `null` there by design. + +If either check fails, reread the matching item above, fix that setting, save, and check again. +Report a check that still fails after one fix instead of moving on to gameplay. + diff --git a/skills/unity-cli/SKILL.md b/skills/unity-cli/SKILL.md index 46fd7ce..d605b9b 100644 --- a/skills/unity-cli/SKILL.md +++ b/skills/unity-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: unity-cli -description: Controls Unity Editors and projects from the command line, including a running Editor. Use to install or manage Editors, licenses, or projects, set up version control, build, test, edit scenes, run C#, look up the scripting API or manual for the project's Unity version, or run any unity command. +description: Controls Unity Editors and projects from the command line, including a running Editor. Make sure to use this skill when the user asks to install or manage Editors, licenses, or projects, set up version control, build, test, edit scenes, run C#, look up the scripting API or manual for the project's Unity version, or run any unity command. allowed-tools: - Bash --- @@ -14,6 +14,19 @@ being wrong. Check with `unity self-update --check --format json`. **When you can run shell commands, use `unity command` and the rest of this CLI, not the Unity MCP server.** The CLI reaches more than the server's tools. MCP is for clients that have no shell. +Fetch a doc page directly (for example `WebFetch`) rather than searching (`WebSearch`). Replace `` first: the Unity version, eg `6000.3`, for docs.unity3d.com, or the package version, eg `1.2`, for a package page. These sites serve `.html` only, with no `.md` variant. Error codes, causes and fixes: [common-workflows.md](references/common-workflows.md#error-codes-cause-and-fix). + +**Before you go forward with a workflow or diagnosis, open and read its page**: the reference file for the command group ([Commands](#commands)) or the recipe in [common-workflows.md](references/common-workflows.md). Name the files you read in your reply. Your training knowledge about Unity and this CLI might be out of date, incorrect, or for the wrong Unity version. + +## Workflow + +1. Check the CLI is installed and current ([Install the CLI](#install-the-cli-if-not-already-installed)). +2. Find the command ([search, don't grep help](#find-a-command-search-dont-grep-help)) and read its reference page. +3. If you will drive an Editor, run `unity command console status` first and keep its cursor. +4. Run the command, or drive the Editor with `unity command`. +5. Check the project has zero console errors with `unity command console status`, and read any with `console get -- --since --level error`. Stop there unless the user asked for proof or you suspect a specific fault. To chase a fault in a change to runtime behaviour, enter Play mode once and read state with `unity command script eval` instead of adding logging, and take no screenshots. +6. If the fix doesn't work, go back and reread the reference page for that command group before trying again. + ## Find a command: search, don't grep help **Never filter `unity --help` or a group's help with `grep`.** Help is long, and a grep over it drops the match or the context around it. Use the CLI's own search: @@ -23,9 +36,9 @@ unity commands --grep license # built-in commands, plugins and t unity command --query screenshot # the same search ``` -`unity commands --grep ` and `unity command --query ` are one search. It covers the CLI's built-in commands, the plugin catalog (installed or not) and the Pipeline commands of the live connected Editor, best match first. Plain words each match in any order; regex characters make it a regular expression. Each row says how to run it (`invoke`): `unity projects link cloud`, `unity command create_gameobject`, `unity ` for an installed plugin, or `unity plugin install ` for one not yet installed. In `--format json` each row also carries `kind` (`command`, `plugin`, `pipeline`), `path`, `description` and `matchedOn` (`name`, `description` or `option`), so act on `invoke` rather than parsing the table. +`unity commands --grep ` and `unity command --query ` are one search. It covers the CLI's built-in commands, the plugin catalog (installed or not) and the Pipeline commands of the live connected Editor, best match first. Plain words each match in any order; regex characters make it a regular expression (Rust `regex` syntax, case-insensitive; no lookaround or backreferences, which are refused with a usage error). Each row says how to run it (`invoke`): `unity projects link cloud`, `unity command create_gameobject`, `unity ` for an installed plugin, or `unity plugin install ` for one not yet installed. In `--format json` each row also carries `kind` (`command`, `plugin`, `pipeline`), `path`, `description` and `matchedOn` (`name`, `description` or `option`), so act on `invoke` rather than parsing the table. -- **Search before you work around the CLI or tell the user it can't help.** A request that names a Unity service, store or product feature (finding Asset Store assets, generating a texture, a cloud build) may be served by a catalog plugin that isn't installed yet, and nothing else on the machine will say so. Search with the request's own words (`unity commands --grep "asset store"`). A row whose `invoke` is `unity plugin install ` is that plugin: tell the user, and ask before installing it ([Use a catalog plugin](#use-a-catalog-plugin-for-a-task-the-built-in-commands-dont-cover)). +- **Search before you work around the CLI or tell the user it can't help.** A request that names a Unity service, store or product feature (finding Asset Store assets, generating a texture, a cloud build) may be served by a catalog plugin that isn't installed yet, and nothing else on the machine will say so. Search with the request's own words (`unity commands --grep "asset store"`). A row whose `invoke` is `unity plugin install ` is that plugin: tell the user, and ask before installing it ([Use a catalog plugin](references/common-workflows.md#use-a-catalog-plugin-for-a-task-the-built-in-commands-dont-cover)). - Use `unity command --query ` to search a specific Editor (`--project-path `) or a Player (`--runtime `, e.g. `unity command --query screenshot --runtime MyGame`). - `commands --grep` waits at most 3 seconds for the Editor; `command --query` waits for it. When the Editor was not searched, a last line says why (no Editor, no answer in time, several Editors) and what to run. Wait for the Editor first with `unity status --until-ready --project-path `: before it connects, no Pipeline row is not proof nothing exists. @@ -65,13 +78,13 @@ unity command editor.playmode start --project-path /path/to/MyProject To pin one Editor when several share a project (worktrees, duplicate projects, Multiplayer Play Mode players), `unity command`, `list`, `job` and `mcp` also take `--port `, `--pid ` or `--instance ` (the MPPM instance name or `vpId`); a pin that matches no running Editor exits 12 with `EDITOR_NOT_RUNNING`. A `unity status` instance's `project` field is what `--project-path` takes. For `unity command`/`list`/`job`/`mcp`, matching no running project fails with `AMBIGUOUS_EDITOR` and lists the candidates. [Details](references/integration-advanced.md#targeting-one-of-several-running-editors). -**Working in several worktrees or agent sessions? One Editor per worktree.** Make each worktree with `unity vcs git worktree add --output-dir `, so you choose where it lands. `--output-dir` is optional: `--format json` reports the real worktree and project paths, and only the human output masks the account name in a home-directory path. The Unity project is `` when it sits at the repository root, and `/` when it doesn't. Open that project's own Editor with `unity open `. Then pin every call that reaches the Editor to that project: pass `--project-path `, or prefix the call with the variable, as in `UNITY_PROJECT_PATH= unity command editor status`. Most agent tools run each command in a fresh shell, so an `export` or a bare assignment in one call never reaches the next one. Every command that takes `--project-path` reads the variable when you pass no path, and so does `unity open`. Only `close`, `projects unlink cloud`, `mcp configure` and `ci init` don't read it: pass the path to those. Without the variable, a bare `unity open` opens the project of the current directory, which is still your source checkout. Target that Editor by the same full path every time, including `unity status --until-ready --project-path `. A path that exists matches only that project, while a bare name also matches a sibling whose path contains it. Never drive an Editor whose project is not your own checkout (or one of its Multiplayer Play Mode clones). An Editor open on a sibling worktree answers every command just like yours. A command sent there edits that checkout's scenes, and its Play mode, recompiles and imports run against that checkout's code. If your own Editor isn't open, open it. If it has gone away, tell the user rather than borrowing the one that is running. +**Several worktrees or agent sessions? One Editor per worktree.** Pin every Editor call to your own project with `--project-path ` or `UNITY_PROJECT_PATH`, and never drive an Editor open on a sibling checkout, because it edits that checkout. Full recipe: [worktrees.md](references/worktrees.md). Requires the project's `com.unity.pipeline` package (Unity 6.0+) — add it once with `unity pipeline install`. Full details — launching a batch-mode Editor to drive, `unity command` tool discovery, and authoring custom `[CliCommand]` tools — are in [integration-advanced.md](references/integration-advanced.md). The package also ships a deeper `unity-pipeline` agent skill, invisible to clients inside `Library/PackageCache` — in a project with the package, run `unity skill install --local` once to mirror it beside this skill. -> **Can't connect / commands time out? Check for Safe Mode first.** When a project has C# compile errors, the Editor boots into **Safe Mode**, where the Pipeline package doesn't load, so `unity command` and `unity recompile` can't connect at all (`unity status` doesn't connect for this: it reads the Editor's log and reports Safe Mode). Note what that means for `unity recompile` specifically: it reports errors you introduce into an Editor that is **already running**, but an Editor that *started* with broken code never loads the package, so there is nothing to ask and it exits `12` rather than reporting the errors. Don't fall back to blind file-editing: run `unity status` (it reports Safe Mode and lists the compile errors, `safeMode.compileErrors` under `--format json`), then fix the errors: the Editor leaves Safe Mode once they compile. Full recovery loop in [integration-advanced.md → Recovering from Safe Mode](references/integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors). +> **Can't connect / commands time out? Check for Safe Mode first.** C# compile errors boot the Editor into **Safe Mode**, where the Pipeline package doesn't load, so `unity command` and `unity recompile` can't connect (`unity recompile` exits `12`). Run `unity status`: it reports Safe Mode and lists the compile errors (`safeMode.compileErrors` under `--format json`). Fix them and the Editor leaves Safe Mode. Full loop: [integration-advanced.md → Recovering from Safe Mode](references/integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors). > **Running as a sandboxed coding agent and `unity status` reports no instances?** A restrictive sandbox can hide an Editor that is genuinely running from this CLI's view of it — don't treat that alone as proof the Editor is down. Full detail in [integration-advanced.md → Sandboxed agent tooling can hide a running Editor](references/integration-advanced.md#sandboxed-agent-tooling-can-hide-a-running-editor). @@ -111,81 +124,11 @@ After installing, open a new shell so `unity` is on PATH, then verify with `unit ## Global flags -These work on every command: - -| Flag | Description | -|---|---| -| `--format ` | Output format: `human` (default), `json`, `tsv`, `ndjson`, `github`. Also via `UNITY_FORMAT` env var. | -| `--json` | Global shorthand for `--format json`, accepted on every command (e.g. `unity status --json`, `unity doctor --json`). Passing it with a different `--format` (e.g. `--json --format tsv`) is a usage error (exit 2); `--json` overrides `UNITY_FORMAT`. | -| `--no-banner` | Suppress the branded header — use in scripts | -| `--no-header` | Leave the header row out of `tsv` tables. The header row is the column names, which are the same keys the `json` rows use (`version`, `upgradeTo`, ...). An empty `tsv` result is the header row alone, so with `--no-header` it is no output at all. | -| `--no-pager` | Turn off paging. Governs both pagers: the external one over the long listings (`unity command`, `releases`, `editors`, `changelog`, `logs`) and the interactive one in `unity projects`. Also via `UNITY_NO_PAGER` (presence-based — any value, including `0`, disables it). | -| `--non-interactive` | Disable all interactive prompts — use in CI | -| `--quiet` | Hide notices, warnings and progress in human and tsv output. Errors, the exit code and the `tsv` rows stay, so a script that pipes with `--quiet` still gets its data. json output never changes, and ndjson output does not either, except that a few listings still drop their rows (see [Notes](#notes)). | -| `--verbose` | Print full error details (stack trace + cause chain) on failure. Also via `UNITY_VERBOSE`. | -| `--proxy ` | HTTP/HTTPS/SOCKS/PAC proxy URL for this invocation. Also via `UNITY_PROXY`. Takes precedence over standard `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` env vars and the persisted `proxy.json` setting. | -| `--proxy-disable` | Disable proxy for this invocation, ignoring all sources (env vars, persisted config, system settings). | -| `--log-proxy` | Log one redacted entry per outbound request to `proxy-request.json` — for reproducing proxy issues. Also via `UNITY_LOG_PROXY=1` or the `proxyRequestLogging` setting. | -| `--no-log-proxy` | Opt a single invocation out of proxy request logging when it's enabled globally. | -| `--color ` | Control colored output for this invocation, overriding `NO_COLOR`/`FORCE_COLOR` and TTY auto-detection. Governs every ANSI-emitting surface (help, tables, spinners, errors), not just `human` output. | -| `--no-color` | Shorthand for `--color never`. Whichever of `--color`/`--no-color` appears last on the line wins. | - -**Always use `--format json` when you need to parse output programmatically.** If you read `tsv` instead, select columns by header name, not position: a command's `tsv` columns keep their names and order, and a flag that adds information (such as `editors --long`) only appends columns at the end. Failures in `tsv` go to stderr, so stdout holds only data. A single-record answer (`unity env`, `unity config proxy`, `unity doctor`, `unity editors default`, `unity install-path` and the like) is a `keyvalue` table instead, one row per field keyed by its `json` path (`values.editor`, `tools.0.id`), so `unity install-path` piped prints the path on its `path` row, not bare; `unity cache key` alone still prints the bare key. - -**Every listing has one JSON shape.** Read the rows from `.data.items[]`. Beside them, `.data.total` is the full count (`null` when the service doesn't report one), `.data.nextPage` (pass it to the command's `--page`, `--skip` or `--offset`, whichever it takes: `--offset` for `collab annotations count --grouped`) or `.data.nextCursor` (pass it to `--next` or `--cursor`) is `null` on the last page, and `.data.partial` is `true` when the listing stopped before it finished. Under `--format ndjson` the rows stream one per line and the last line, `type: "result"`, carries `count` and the same paging fields. Some listings still carry their older keys too (`instances`, `entries`, `results`); prefer `items`. - -`--accelerator ` and `--no-accelerator` are **not** root globals — they are accepted only on `run`, `test` and `build`, and only after the command name. See [build-run-test.md](references/build-run-test.md). - -**`unity projects` is the only command that pages IN-PROCESS.** It shows 10 projects per screen and waits for a keypress between screens, and only when stdout is a terminal. Paging is off for redirected stdout, under every machine format (`json`, `ndjson`, `tsv`, `github`), and under `--all`, `--watch`, or `--no-pager` / `UNITY_NO_PAGER`. - -**The long listings page through an external pager, like `git log`.** `unity command` (the bare listing), `unity releases`, `unity editors`, `unity changelog`, and `unity logs` pipe human output through `less -RFX` on a terminal; `-F` quits by itself when the output fits one screen. `$UNITY_PAGER` then `$PAGER` override the choice and run through a shell, so `PAGER="less -S"` works; a blank value is ignored rather than treated as an opt-out. Like `projects`'s pager this one is **`human`-only**, and it never engages for redirected stdout, any machine format (`json`, `tsv`, `ndjson`, `github`), `--quiet`, `TERM=dumb`, the streaming modes (`editors --watch`, `logs --follow`), a named `unity command `, or inside `unity shell`. A broken pager costs the paging, not the output: a `$PAGER` naming something that is not there is resolved before anything spawns (a warning on stderr names it, and on Windows a bare name also finds `.com` programs such as `more`), and one that spawns and then dies has its output reprinted to the terminal, decided from the pager's exit status (a clean exit is a normal `q` and discards; a failure status reprints). A pager that exits 0 without reading (`PAGER=true`) is indistinguishable from `q`, so its output is lost. One that merely *waits* is not broken; the CLI waits with it. - -A branded Unity header (logo, wordmark, CLI version) renders on the landing surfaces — bare `unity`, `unity --help` / `-h`, and `unity help`. It's shown only on a TTY, prints at most once, and degrades to compact, uncolored text on narrow terminals, without Unicode, or under `NO_COLOR`. Piped output is unaffected. Use `--no-banner` to suppress it in scripts. Bare `unity` prints usage and exits 0. The header's accent is brand blue (`#0F70CB` on a light background, `#6EB8FF` on a dark one), in 24-bit color where the terminal supports it and the nearest 256-color entry otherwise. The background comes from `UNITY_THEME`, then `COLORFGBG`, then, on the header only, a terminal query. The query runs only where the terminal can answer (Windows Terminal, VS Code, or a Unix terminal with `TERM` set), and waits at most 100 ms; no reply means dark. Git Bash is never queried. Subcommand help and the command listing never query the terminal: they use `UNITY_THEME`, then `COLORFGBG`, then dark. Where the header cannot query, set `UNITY_THEME=light` or `UNITY_THEME=dark` to choose the background yourself. +Every command accepts `--format json|ndjson|tsv`, `--non-interactive`, `--proxy` and more. Confirmation flags such as `--yes` are command-specific, not global: check the command's own help. Use `--format json` whenever you parse output. Full list: [global-flags-env.md](references/global-flags-env.md#global-flags). ## Environment variables -All CLI env vars use the `UNITY_` prefix. A CLI flag always overrides the corresponding env var. - -| Variable | Mirrors flag | Description | -|---|---|---| -| `UNITY_FORMAT` | `--format` | Output format (`human`, `json`, `tsv`, `ndjson`, `github`). `HUB_FORMAT` is a deprecated alias. | -| `UNITY_EDITOR_VERSION` | `--editor-version` | Editor version (e.g. `2023.3.0f1`, `latest`, `lts`). Read by every command that takes `--editor-version`, `build` included; `build` prints a notice when the variable chose its Editor. Not read by the `pipeline cloud-build` filters. | -| `UNITY_ARCHITECTURE` | `--architecture` | Chip architecture (`x86_64`, `arm64`). `build` names it in the same notice. | -| `UNITY_PROJECT_PATH` | `--project-path` | Project path when none is passed. Read by every command that takes `--project-path` (the Editor-connecting commands, `recompile`, `pipeline`, `collaboration`, `assets`, `auth default`, `templates create`/`pack`, `projects link`, `projects unlink vcs` and the `vcs` commands that act on a project) and by `open`. A path argument or `--project-path` wins over it. Not read by `close` (and `projects close`), `projects unlink cloud`, `mcp configure` or `ci init`. | -| `UNITY_QUIET` | `--quiet` | Suppress non-essential output. | -| `UNITY_VERBOSE` | `--verbose` | Show full error details on failure. | -| `UNITY_NON_INTERACTIVE` | `--non-interactive` | Disable interactive prompts. | -| `UNITY_NO_BANNER` | `--no-banner` | Suppress the branded banner. | -| `UNITY_THEME` | — | `light` or `dark` (any case): the terminal background the branded header assumes, so its accent reads on it. Wins over `COLORFGBG` and the header's terminal query, and is the fallback where that query cannot run (Git Bash, a legacy console, or `TERM` unset). Help and the command listing rely on it and `COLORFGBG`, never on a query. Any other value is ignored. | -| `UNITY_NO_PAGER` | `--no-pager` | Turn off paging — both the external pager over the long listings and `unity projects`'s interactive one. Presence-based: any value counts, including `0`. | -| `UNITY_PAGER` | — | The pager to use for the long listings, overriding `$PAGER` and the `less -RFX` default. Runs through a shell, so flags work (`less -S`). A blank value is ignored, not an opt-out. | -| `PAGER` | — | Same as `UNITY_PAGER`, consulted only when that is unset or blank. | -| `LESS` / `LV` / `LESSCHARSET` / `MORE` | — | Passed to the pager only when you have not set them, defaulting to `FRX`, `-c`, `utf-8`, and `FRX`. `LESSCHARSET` keeps multi-byte glyphs readable where the locale does not declare UTF-8; `MORE` exists because `more` on macOS/BSD is `less` under another name and reads `$MORE`, so without it `PAGER=more` waits for a keypress even for one line. | -| `UNITY_RUN_TIMEOUT` | `--timeout` | Timeout for `unity run` in seconds. | -| `UNITY_TEST_TIMEOUT` | `--timeout` | Timeout for `unity test` in seconds. | -| `UNITY_CLOUD_ORG` | `--cloud-org` | Active Unity Cloud organization id or name for a single call. | -| `UNITY_CLOUD_PROJECT` | `--cloud-project` | Cloud project ID or name (a service account needs the ID); used by Cloud Build inventory. Pipeline Automation inventory is organization-scoped. | -| `UNITY_NO_CLOUD` | `--no-cloud` | Decline the Unity Cloud link on `projects create` and `projects upgrade`. Presence-based: any value counts, including `0`. On `projects create` and `projects upgrade`, an explicit `--cloud`, `--cloud-project`, `--cloud-org` or `--coppa` wins over it. `projects create --vcs uvcs` is refused with it set unless one of those flags overrides it. | -| `UNITY_SERVICE_ACCOUNT_ID` | — | Service account client ID for non-interactive (CI) auth. | -| `UNITY_SERVICE_ACCOUNT_SECRET` | — | Service account client secret for non-interactive (CI) auth. | -| `UNITY_PROXY` | `--proxy` | HTTP/HTTPS/SOCKS/PAC proxy URL. Takes precedence over `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` and the persisted `proxy.json` setting. | -| `UNITY_NO_UPDATE_CHECK` | — | Disable the background "update available" check (see `unity config update-check`). | -| `UNITY_CLI_ROLLBACK_KEEP` | — | How many previous CLI versions `unity self-update` keeps for `--rollback`, from 1 to 10 (default 3). | -| `UNITY_NO_AGENT_HINTS` | — | Stop suggesting Unity's agent plugin or skill when an AI agent runs `unity`: Claude Code's install prompt, the `unity setup codex` / `grok` / `antigravity` / `copilot` tip, and the `unity skill install` tip (an `AGENT_PLUGIN_AVAILABLE` entry in the envelope's `notifications` under `--format json`), plus the once-a-day `unity skill sync` notice when installed Unity skills are older than the CLI's pin (`AGENT_SKILLS_OUTDATED`). Presence-based: any value counts. A tip asks you to get the user's approval before running its command. | -| `UNITY_NO_CRASH_REPORT` | — | Disable anonymous crash/error reporting (Sentry) entirely. The Hub's "Send crash reports" setting, when off, also disables it. | -| `UNITY_NO_CLI_INVOKED_TELEMETRY` | — | Stop the anonymous once-per-run `cli telemetry` usage ping. Presence-based: any value counts. | -| `DO_NOT_TRACK` | — | The cross-tool [Console Do Not Track](https://consoledonottrack.com) setting. Any value but empty, `0` or `false` stops the `cli telemetry` usage ping and the upload of opt-in usage data. Licensing records are not affected. | -| `UGS_CLI_TELEMETRY_DISABLED` | — | The UGS CLI's telemetry switch, honored exactly like `DO_NOT_TRACK`. Any value but empty, `0` or `false` stops the `cli telemetry` usage ping and the upload of opt-in usage data. Licensing records are not affected. | -| `UNITY_LOG_PROXY` | `--log-proxy` | Log one redacted entry per outbound request to `proxy-request.json`. Truthy values: `1`, `true`. | -| `UNITY_ACCELERATOR` | `--accelerator` | Unity Accelerator endpoint (`host:port`). Outranks the persisted `accelerator.json`; `--accelerator` outranks it. | -| `UNITY_NO_ELEVATE` | `--no-elevate` | Windows: skip the elevated (UAC) install helper for `install` / `install-modules`, so the install service runs unelevated. The Editor's NSIS installer still asks for elevation on demand if Windows requires it for your account — an administrator token always does; a standard user never does. | -| `UNITY_INSTALL_RETRIES` | `--retries` (`install-modules` only) | Number of times `install` and `install-modules` retry an editor or module download whose transfer or validation fails. `0` disables retries; `unity install` has no `--retries` flag, so set the variable there. | -| `UNITY_NO_AUTH_BROKER` | — | Skip the resident auth broker and read credentials directly from the OS keyring. By default every command that needs a token goes through a broker that starts on demand and exits after two idle minutes (see [auth-license-cloud.md](references/auth-license-cloud.md)). | -| `UNITY_CLI_HOME` | — | Install root for the install script and `unity self-install`, on every platform including Windows: the binary lands in `/bin` instead of the default location. | -| `UNITY_NO_EDITOR_IDENTITY_SERVER` | — | Disable the background identity helper that `unity open` starts to answer the Editor’s sign-in lookups when no Hub is running (see [projects-templates.md](references/projects-templates.md)). Presence-based. | -| `UNITY_EXPERIMENTAL_FEX_EMU` | none | Linux arm64 only, experimental and unsupported: run the x86_64 Editor under FEX-Emu. `1`, `true` or `yes` turns it on, and it takes effect only when FEX-Emu and an x86_64 RootFS are installed (`unity doctor` checks). C# script compilation is known to crash under FEX-Emu. See [editors-install.md](references/editors-install.md). | - -**CI service account auth:** Set both `UNITY_SERVICE_ACCOUNT_ID` and `UNITY_SERVICE_ACCOUNT_SECRET` to skip the browser OAuth flow — this keeps the secret out of the process argument list and shell history. These map to the `--client-id` / `--secret-from-stdin` inputs of `unity auth login`, but reading the credentials from the environment isn't a full login: it doesn't run the interactive flow or persist credentials to the keyring. +The CLI reads `UNITY_*` variables for credentials, proxies, paths and CI behavior. Full list: [global-flags-env.md](references/global-flags-env.md#environment-variables). ## Getting help @@ -197,59 +140,24 @@ Not sure which command? [Search, don't grep help](#find-a-command-search-dont-gr ## Exit codes -Branch on the exit code, then on `errors[0].code` in the json or ndjson envelope. **Retry** says -whether running the same command again, unchanged, can succeed. A command that starts work -(`pipeline cloud-build builds start`, `pipeline automation pipelines trigger`) would start it -again, so once its request may have been sent, never re-run it: follow what it started instead. -`unity commands --json` carries this table as `exitCodes`, with the error codes that pick each -exit. `6` covers every failure no more specific code names, including a `unity command` result -that reports `success: false` or a failed `status`; a missing project, an Editor that -isn't running, an unknown Editor command and a timeout have their own codes (`11` to `14`). A -request that gets no answer (offline, a failed DNS lookup, a refused connection, a dead proxy) -exits `7`; a timeout is `14`, and a reset connection or an unreadable body is -`6`. A TLS or certificate failure is `ERR_NETWORK` too, so retrying a `7` does not always help, -and a request already sent may have reached the server: retry only a command that is safe to -repeat. - - -| Code | Name | Retry | Meaning | -|---|---|---|---| -| 0 | `SUCCESS` | no | The command succeeded. | -| 1 | `ERROR` | no | An unexpected or unsupported state. | -| 2 | `BAD_ARGS` | no | A usage error: an unknown command or option, or a bad value. | -| 3 | `AUTH_ERROR` | no | Not signed in, the session expired, or permission was denied. | -| 4 | `NEEDS_CONFIG` | no | Setup is missing: a required tool, setting or link. | -| 6 | `COMMAND_FAILED` | no | The command failed, or its result reported a failure, and no more specific code names why. | -| 7 | `NETWORK_UNREACHABLE` | yes | A required service could not be reached. | -| 8 | `TESTS_FAILED` | no | The tests ran, and some failed. | -| 9 | `INSTALL_LOCKED` | yes | Another process holds the install lock. | -| 10 | `READY_TIMEOUT` | yes | The Editor did not become ready in time. | -| 11 | `NOT_FOUND` | no | What the command names does not exist: a project, a release, a module. | -| 12 | `EDITOR_UNREACHABLE` | yes | No running Editor answered: none is running, none matches, or it refused the connection. | -| 13 | `REMOTE_COMMAND_FAILED` | no | The Editor answered, but it has no command by that name. | -| 14 | `TIMEOUT` | yes | An operation ran out of time: an Editor request, an HTTP request, a batch run. | -| 15 | `RUN_FAILED` | no | A build or job the command waited on finished unsuccessfully. | -| 16 | `JOB_SUSPENDED` | yes | A job the command watched waits on a person to resume or approve it. | -| 17 | `UNAVAILABLE` | yes | The target answered but can't do this now: it is busy. | -| 18 | `AWAITING_INPUT` | yes | The target answered but waits on a person first: a dialog to dismiss, a prompt to answer. | -| 130 | `INTERRUPTED` | yes | Interrupted by Ctrl-C (SIGINT). | -| 141 | `OUTPUT_CLOSED` | no | The reader of stdout closed the pipe. | -| 143 | `TERMINATED` | yes | Terminated by SIGTERM. | - - -`8` is `unity test` only: the tests ran and some failed. A run that never completed exits `6` -and a timed-out one `14`, so CI can retry those and never blindly re-run a failing test. `9`: -earlier items of the same install may already be in place (`data.completedUids`). `10` is -`unity open --until-ready` only; the Editor is still running. `17` is an Editor that is loading, -compiling, reloading or in Safe Mode: retry later. `18` is a modal dialog blocking it: list and -answer it with `unity command editor dialog`, then retry. +`0` is success; any other code is a failure with a stable meaning (for example `7` for a network failure, `12` when no running Editor answers, `11` for a missing project, release or module). Branch on the code, not on message text. The table is in [exit-codes.md](references/exit-codes.md). + +## Guardrails + +- **Do only what's asked. Don't change unrelated assets or files. Avoid long explanations.** Editors, licenses and projects are the user's own. +- **Never leave verification code in the user's script. Never build logging or detection they didn't ask for.** +- **Ask before** installing or uninstalling an Editor, activating or returning a license, signing in or out, publishing, or running a command that deletes or overwrites project files, because these are slow or hard to undo. +- **Make a restore point before changing a project**: confirm a clean commit (`git status`) or a Unity Version Control checkin, and tell the user how to return to it. +- **Never run `console clear`**: it also deletes the user's own entries. Read only your own entries, from a cursor you saved before your first Editor operation. +- **Finish with the console check in [Workflow](#workflow) step 5** and a short report: what you ran, what changed, what failed or was skipped, and the next step. ## Commands The full per-command reference — syntax, flags, and examples — lives in grouped files under [`references/`](references/). **Read the file for the command group you need**; all the global flags, environment variables, and exit codes above apply throughout. Every command also supports -`-h` / `--help` (see [Getting help](#getting-help)). +`-h` / `--help` (see [Getting help](#getting-help)). What changed in this skill between CLI +releases: [CHANGELOG.md](references/CHANGELOG.md). | Commands | Reference file | |---|---| @@ -266,432 +174,15 @@ flags, environment variables, and exit codes above apply throughout. Every comma ## Common workflows -### Inspect and run cloud builds and Pipeline Automation jobs - -Read [cloud-automation.md](references/cloud-automation.md) for every command in -both groups, context/authentication, per-command filters and sorting, -output fields, pagination (including the leaves that refuse `--page`/`--limit` -rather than ignoring them), errors, and redaction. `pipeline cloud-build` works with Build Automation; -`pipeline automation` works with Pipeline Automation. Neither needs a running Editor -or the local Pipeline package. Use numeric organization IDs for service accounts. -The inventory commands are read-only. The commands that act on work start and -cancel builds, download artifacts, trigger pipelines, and follow or act on jobs; -`builds cancel`, `jobs terminate` and `jobs reject` ask first unless `--yes` is -given, and none of them change configuration. - -JSON/NDJSON return full API-shaped results under `data`, as Collab does; NDJSON -has one terminal result, without item frames. Preserve native fields and free-form -metadata, subject to the reference's bounded secret protections and public-API -redaction assumption. Table projections remain separate. Explicit local build -targets retain `_local`; missing targets aren't local. These conventions apply -to follow-up cloud-automation work too. - -### Edit a scene, GameObject, or asset — `unity status` first - -**Before editing any scene, GameObject, prefab, or asset, run `unity status` to detect a connected Editor.** If one is reachable, drive it with live commands instead of touching project files — the Editor applies changes to the *actual active scene* and keeps its in-memory state in sync. - -```bash -unity status # is an Editor connected? (look for state "ready") -unity command # discover the scene/GameObject commands THIS Editor exposes -# then drive it with the commands it lists — for example, if your Editor exposes them: -unity command gameobject create # act on the live, active scene -unity command scene save # persist the active scene -``` - -Commands are grouped and invoked as `unity command `. Their names are defined by the Editor, so run `unity command` to see the exact set — don't assume a name. - -> **Never hand-edit `.unity`, `.prefab`, or `.asset` YAML while a live Editor is reachable.** Raw-file edits are: -> - **error-prone** — fileIDs and GUIDs are assigned by hand and easy to get wrong; -> - **invisible** to the running Editor until a reimport, so the change silently fails to take effect; and -> - **prone to hitting the wrong file** — e.g. writing to `SampleScene.unity` while the Editor's active scene is actually `Demo2.unity`, producing valid-looking YAML that changes nothing the user sees. - -**Rule out two false negatives before concluding no Editor is reachable — both look identical to a genuinely closed Editor, and both are easy to get wrong under time pressure:** - -- **Safe Mode.** If an Editor *is* running for this project but `unity command` won't connect, it may be stuck in **Safe Mode** from a compile error rather than genuinely absent. Run `unity status`: if it reports Safe Mode (`STATUS_SAFE_MODE`, with the compile errors), editing the C# source to fix the compile errors *is* the correct move, not a fallback. See [integration-advanced.md → Recovering from Safe Mode](references/integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors). -- **A sandboxed agent shell.** If your own shell commands run inside a restrictive sandbox — the normal case for a coding agent like this one — the sandbox can hide a genuinely running Editor from `unity status` the same way. This applies to **every** scene/GameObject/prefab/asset task that reaches this preflight, not only ones that obviously need a live Editor: a task you could otherwise finish without any CLI involvement (e.g. generating an asset through ordinary Editor APIs) can still get funneled into "no Editor" here and derailed. Don't treat "no instances" as proof the Editor is down, and don't quietly improvise a third path — like driving a separate batch-mode Editor process to approximate what a live connection would have done — as a substitute for a disclosed file edit. Say plainly that your sandbox may be blocking your view of a real Editor, and ask whether one is actually open before falling back. Full detail: [integration-advanced.md → Sandboxed agent tooling can hide a running Editor](references/integration-advanced.md#sandboxed-agent-tooling-can-hide-a-running-editor). - -Only fall back to editing files directly once you've ruled out both of the above — and say so explicitly ("no live Editor detected, editing the file directly"). - -### Use a catalog plugin for a task the built-in commands don't cover - -The CLI ships a catalog of Unity plugins, installed on demand. **Before approximating a request -some other way, or saying the CLI can't do it, check whether a catalog plugin covers it.** A plugin -is Unity's own tool for its class of request, and using it is almost always the better answer. -`unity plugins` always lists the full catalog, installed or not, and the command search -([Find a command](#find-a-command-search-dont-grep-help)) matches each plugin's name and description. -The steps below use the Unity AI Generators plugin (`ai`), which covers "generate a -texture/sprite/image/3D model for my project", as the example. Every catalog plugin works the same -way. - -1. **Find the plugin and check whether it's installed.** - ```bash - unity commands --grep "" --format json - unity plugins --format json - ``` - Find the entry whose `id` is the plugin's (`"ai"` here) and read its `installed` field - (`true` / `false`). - -2. **Not installed? Tell the user, then ask, never install silently.** Say plainly that Unity - ships an AI Generators plugin that covers this, and wait for a yes before running: - ```bash - unity plugin install ai - ``` - A refusal is a normal answer: fall back to whatever you would otherwise have done, and don't - ask again in the same conversation. - - `unity plugin install --local` writes the plugin's agent skill into the current project - (`/.claude/skills/...` and the other project-local client folders) instead of each AI - client's user-wide folder. It applies only to clients that already have Unity's skill in that - project, and Claude Desktop is skipped because its skills are user-wide only. `unity plugin - upgrade` never adds a copy: it updates the plugin's skill only where it is already installed, - user-wide or in the current project. Run it from that project to refresh its copy. - - `ai` is alpha, and during alpha it's gated to Unity staff on Unity's internal network. An - ordinary user's `unity plugin install ai` can fail with a **sign-in** message (Unity AI - Generators is limited to Unity staff, so sign in with a Unity staff account) or, once - past that, a plain **download failure** if the network it needs isn't reachable from where - you're running. Neither is a bug in the request: report the message and fall back, the same as - any other refusal. - - `unity plugin install` and `unity plugin upgrade` install the newest build the catalog offers - you, whatever its channel. When that build is a prerelease (`beta`, or `alpha`/`nightly` for - Unity staff), a warning says so before the download, in the envelope's `warnings` under - `--format json`. Pass it on to the user: a prerelease may change or break between versions. - - A plugin whose registry entry carries license terms shows them and waits for an answer - before anything downloads. `unity plugin install ` and `unity plugin upgrade ` ask on - a terminal. A run that cannot ask (`--non-interactive`, CI, piped input) fails with the - error code `PLUGIN_EULA_REQUIRED` and downloads nothing, and a "no" fails with - `PLUGIN_EULA_DECLINED`. Pass `--accept-eula` only after the user has read the terms and - agreed: it is their acceptance, never yours to give. An accepted version is remembered, so an - upgrade asks again only when the terms changed. `--dry-run` on either command prints the terms - and what would change, asks nothing, records nothing and downloads nothing. In - `--format json`, a row for a plugin with terms carries `eula` (`required`, `accepted` or - `declined`); a plugin with no terms has no such field. A `--dry-run` row also carries `dryRun: true` and an `eulaNotice` object (`version`, `url`, - `label`, `message`, `links`) with the terms to read. `--quiet` never hides the terms. A notice - the registry carries but the CLI cannot read refuses the install under `PLUGIN_EULA_REQUIRED`. - - A plugin can need other plugins. `unity plugin install ` installs the ones it requires - first, each with its own license step, and reports each as its own row. If one of them cannot - install, the plugin itself is not installed, and its row names the one that stopped it. - `unity plugin remove ` refuses a plugin another installed plugin requires: remove the - other one first. `unity plugin --json` lists each entry's `dependencies` (`id`, `optional`). - -3. **Pick up its agent skill in the same session.** A catalog plugin can ship its own agent skill - inside its payload (`ai` does), and installing the plugin does not, by itself, make that skill - visible to you; it has to be mirrored the same way this skill itself is: - ```bash - unity skill install # e.g. claude-code, first time this session - unity skill refresh # already mirrored earlier? re-render it fresh - ``` - `unity plugin install`'s own last line already tells you which one applies: it points at - `unity skill install` right after installing a copy that ships a skill, and at - `unity skill refresh` once one is already mirrored but the plugin's copy just changed. Confirm - where it landed with `unity skills --format json` (look for the row whose `skill` field - names the plugin's own skill, e.g. `unity-ai`, and read its `path`), then read that file before - driving the plugin's commands. Don't guess its command surface from this skill, which only - documents `unity` itself. - -**A command invoked before any of this** (`unity ai …` typed straight, or suggested from memory) -**fails with a clear, actionable message** naming the exact install command (`unity plugin install -ai`), in both human and machine (`--format json` / `--format ndjson`) output, under the stable -error code `TOOL_NOT_INSTALLED`. Read that message rather than guessing why the command did -nothing; the same shape (`TOOL_UNSUPPORTED_PLATFORM`, `TOOL_RUNTIME_NOT_INSTALLED`) covers the -two other reasons a catalog tool can't run. - -### Bootstrap a new project from scratch - -> For a **guided** end-to-end experience — concept questions, installing the Editor in the -> background while you plan, package selection, and monetization handoff — use the -> **`new-unity-project`** skill. This section is the raw CLI recipe that skill builds on; use it -> directly when you just want the commands. - -Take an idea to a running, version-controlled project using only the CLI. Decide the **target -platforms first** — they determine which Editor modules you install in step 2. You can add -modules later (`unity install-modules`), but a project can't build for a platform until that -platform's module is installed, so it's simplest to decide up front. - -```bash -# 1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md). -unity --version -unity auth status --format json # if signed out: unity auth login -unity license status --format json # if none active: unity license activate - -# 2. Pick and install an Editor with the modules your target platforms need. -# Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream -# release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as -# evaluation-only, never for a project you intend to ship. A deadline argues for LTS. -# (lts / latest aliases work almost everywhere a version is accepted — `templates` is the -# exception; see step 3.) -unity releases --stream lts --limit 5 --format json -unity install lts --module android --module ios --yes --accept-eula # add --module webgl, etc. -unity editors --installed --format json # confirm it landed - -# 3. List the real template ids this Editor offers — don't guess them — and pick by RENDER -# PIPELINE, not just by 2D/3D. Default to the URP templates: -# 3D → com.unity.template.urp-blank ("Universal 3D") -# 2D → com.unity.template.universal-2d ("Universal 2D": URP + the 2D packages) -# com.unity.template.3d and com.unity.template.2d are the Built-in Render Pipeline templates -# (displayName "… (Built-In Render Pipeline)"): deprecated from Unity 6.5, gone in 6.7. Use -# them only when the user explicitly asks for Built-in. Confirm the pick with the JSON -# `renderPipeline` field — it is blank for universal-2d on current releases, so match that -# one by id. -# `templates` resolves the lts / latest aliases through the release catalog, as `install` -# does, but the version you just installed (read it from `editors --installed`) is the one -# whose templates you want. -unity templates --editor-version <6000.x.y> --type core --format json - -# 4. Create the project. The first positional arg is the NAME; --output-dir sets the parent directory. -# All options supplied, so it won't prompt; add --non-interactive in CI. -# (To publish it to a remote in the same step, use the source-control forms below instead.) -unity projects create "MyGame" --output-dir ~/UnityProjects \ - --editor-version lts --template com.unity.template.urp-blank - -# 5. Add the Pipeline package BEFORE the first open. `unity command`, `unity status` and -# `unity command script eval` all need it, and templates don't include it. The Editor reads -# Packages/manifest.json when it loads the project, so installing first means the package -# is live from the first open. -unity pipeline install --project-path ~/UnityProjects/MyGame - -# 6. Open the project and wait until its Editor is ready to take commands. Pass the project's -# full path: a path that exists matches that project's Editor only, so an Editor open on a -# sibling checkout such as ~/UnityProjects/MyGame-lighting can't end the wait. -cd ~/UnityProjects/MyGame -unity open . -unity status --until-ready --project-path ~/UnityProjects/MyGame --format json -``` - -**Then build the scene in the live Editor, not in batch mode.** Create GameObjects, wire -components, and set asset references with `unity command script eval` (or the Editor's own `unity command` -tools) against the running Editor, and read the result back the same way. Each step can be -checked before the next one. A script run through `unity run -- -executeMethod` is the -**fallback** for when no Editor can stay open (CI, a headless build box). It can't see what it -produced: a reference saved as null, such as a `UIDocument` with no `PanelSettings`, still -reports success. If you do use batch mode, open the result in a live Editor and inspect it before -calling the work done. How to get an Editor to drive: -[integration-advanced.md → Getting an Editor to drive](references/integration-advanced.md#getting-an-editor-to-drive). - -**Source control — let the user choose.** The CLI publishes the new project to a fresh remote in -one step for any provider. **Always pass tokens on stdin** (`--git-token-from-stdin`) so secrets never -land in shell history or the process list. Pick based on the project — don't default to one: - -- **Git — GitHub / GitLab** (`--vcs github` / `--vcs gitlab`). Ubiquitous. For asset-heavy games - add **Git LFS** (`--git-lfs`) so large binaries don't bloat history. -- **Unity Version Control — UVCS** (`--vcs uvcs`). Unity's own VCS, built for large binary game - assets: it handles them natively (**no LFS needed**) and supports file locking — often the - better fit for art-heavy projects or larger teams. Auth uses your Unity sign-in; `--vcs-region` - selects the region. - -```bash -# Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you -# want to add packages/assets BEFORE the first commit (see the new-unity-project flow). -unity projects create "MyGame" --output-dir ~/UnityProjects \ - --editor-version lts --template com.unity.template.urp-blank \ - --vcs github --git-namespace my-org --git-repo my-game \ - --git-visibility private --git-default-branch main --git-token-from-stdin --git-lfs - -# Unity Version Control (UVCS) — handles binaries natively, so no LFS: -unity projects create "MyGame" --output-dir ~/UnityProjects \ - --editor-version lts --template com.unity.template.urp-blank \ - --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region -``` - -Feed the token to `--git-token-from-stdin` from a secret store, never a literal — e.g. -`… --git-token-from-stdin <<<"$GIT_TOKEN"` where `$GIT_TOKEN` comes from your CI/secret manager -(UVCS uses your Unity sign-in, so no token is needed). +Step-by-step recipes live in [common-workflows.md](references/common-workflows.md). Read it before you attempt one of these: -**Working with a UVCS workspace day to day: a few wrapped reads, everything else straight through -to `cm`.** The split is deliberate and worth teaching, because guessing wrong wastes a user's time: - -- **`unity vcs uvcs `** wraps the reads that **join `cm`'s data to your project** — - `locks` (who holds a lock, *and which locks cover files you have already changed*), - `changesets`, and `review`. Those joins are the thing `cm` cannot do for you, and they come in a - stable envelope, so prefer them whenever something *parses* the output. -- **`unity uvcs `** forwards the whole command line to `cm` verbatim, `--help` and - `--format` included. That is the supported route, not a workaround: `cm` owns and versions this - vocabulary, so wrapping it would pin a paraphrase that goes stale. Reach for it for **partial - checkout**, **shelves**, and **taking or releasing a lock**, and when a human reads the output. - -```bash -unity vcs uvcs locks # who holds what, and what collides with your changes -unity uvcs lock list # the raw listing, cm's own flags and output -unity uvcs partial update /Assets/Levels # cm's own vocabulary, unchanged -unity uvcs shelve -c "wip: lighting pass" -``` - -Every verb, flag and trap: [version-control.md](references/version-control.md). - -`unity cm ` is the same passthrough under cm's own name. Both need the `cm` client; install -it with `unity plugin install plastic` if a command says it is missing. - -**Beyond setup, the `vcs` group covers the whole day-2 loop** — `status`, `sync`, `switch`, -`merge-setup`, `conflicts` / `explain` / `resolve`, `diff`, `blame`, `summarize`, `affected`, -`hooks`, `doctor`, `providers` — and the Unity semantics are the reason to reach for it over raw -`git`. Full reference, with the flags and the traps: -[version-control.md](references/version-control.md). - -**Git tokens belong to the user's credential manager, not the CLI.** When no token flag or env var -is given, the CLI asks `git credential fill` and uses whatever the configured helper returns; it -stores nothing it is passed or told. Don't suggest the CLI can save a Git token, and don't reach for -a token flag when the user already has a working credential helper. If they want a different token -per organization, that is `git config --global credential.useHttpPath true` plus a multi-account -helper such as [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager). -The CLI passes the full repo URL so the helper can discriminate, but it never installs or -reconfigures a helper. `UNITY_GITHUB_TOKEN` / `UNITY_GITLAB_TOKEN` are one token per provider, so a -CI job spanning several orgs should pass `--git-token-from-stdin` per invocation instead. See -[references/projects-templates.md](references/projects-templates.md) for the full -source-control flag set. For a purely local Git repository instead, initialize git with a -Unity-appropriate ignore so the multi-GB `Library/` and other generated folders are never committed: - -```bash -cd ~/UnityProjects/MyGame -git init -b main -# Download (do not pipe to a shell) a maintained Unity .gitignore: -curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore - -# Asset-heavy game? Keep large binaries out of git history with Git LFS: -git lfs install -git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png" # adjust to your asset types -git add .gitattributes - -git add -A -git status # sanity-check: Library/ Temp/ obj/ Build/ must NOT be staged -git commit -m "Initial Unity project: MyGame" -git ls-files | grep -c '^Library/' # must print 0 -``` - -**What the CLI does and doesn't cover.** The CLI handles editor, project, and source control. -It has no top-level package command. To add UPM (Unity Package Manager) packages beyond the -template, use the **`unity-package-management`** skill: it runs the Pipeline `package add` -command through `unity command`, with a batch-mode C# script as the fallback. For monetization/backend, hand off to the dedicated skills: `implement-in-app-purchases` -(IAP), `levelplay-unity-integration` (ads), or `build-live-game` (accounts, cloud save, -economy, remote config, leaderboards). Once steps 5 and 6 above are done, work in the open -Editor. - -**Installed the Pipeline package while the Editor was already open?** The Editor picks up the -manifest change only when it next refreshes. Until then `unity status` reports -`STATUS_PIPELINE_LOAD_PENDING` (or `STATUS_NO_INSTANCES` on CLI releases before that code -existed). An Editor that is still opening or importing reports the same code until it finishes, -so wait for that first (`unity status --until-ready`). The CLI can't trigger the refresh itself: -if the Editor has finished opening, ask the user to switch to the Unity Editor window, then -re-run `unity status --until-ready`. Installing before the first open (step 5) avoids this -entirely. - -### Find and install a missing editor - -```bash -# 1. Check what's installed -unity editors --installed --format json - -# 2. Browse available LTS versions -unity releases --lts --limit 5 --format json - -# 3. Install -unity install 6000.0.47f1 --yes --accept-eula -``` - -### Open a project with the correct editor - -```bash -# 1. Check the project's required editor version -unity projects info /path/to/MyProject --format json -# Look at "editorVersion" in the result - -# 2. Confirm that editor is installed -unity editors --installed --format json - -# 3. Open (warns if the editor version is missing) -unity open /path/to/MyProject -``` - -### CI: activate a license, then build - -```bash -# 1. Activate a license without signing in; a service account cannot activate one. -# A perpetual or legacy serial: store it as the CI secret UNITY_LICENSE_SERIAL -# (the name `unity ci init` generates) and pass it to the step, e.g. in GitHub -# Actions `env: { UNITY_LICENSE_SERIAL: ${{ secrets.UNITY_LICENSE_SERIAL }} }`. -# A serial tied to a subscription needs a signed-in user, so for those seats use -# --floating, or the offline --generate-request / --file path (see "Headless / -# fleet license activation" in references/auth-license-cloud.md). -unity license activate # reads UNITY_LICENSE_SERIAL from the step env, so the serial stays off argv; or: unity license activate --floating - -# 2. Only if the job also runs cloud commands: export UNITY_SERVICE_ACCOUNT_ID and -# UNITY_SERVICE_ACCOUNT_SECRET from the CI secret store. Every later command reads -# them directly, with no `unity auth login` and nothing written to a credential -# store (which a headless runner may not have). - -# 3. Build -unity build /path/to/MyProject \ - --editor-version 6000.0.47f1 \ - --target StandaloneLinux64 \ - --execute-method Builder.PerformBuild \ - --allow-install -echo "Exit code: $?" - -# 4. Return the license when done (serial or assigned seats) -unity license return --yes -``` - -### CI: batch-mode build - -Prefer the dedicated `unity build` command (handles batch mode, logging, and CI flags): - -```bash -unity build /path/to/MyProject \ - --editor-version 6000.0.47f1 \ - --target StandaloneLinux64 \ - --execute-method Builder.PerformBuild \ - --allow-install -echo "Exit code: $?" -``` - -Or use `unity run` (batch mode is automatic — never pass `-batchmode`/`-quit`): - -```bash -unity run /path/to/MyProject \ - --editor-version 6000.0.47f1 \ - --allow-install \ - -- -executeMethod Builder.PerformBuild -logFile build.log -echo "Exit code: $?" -``` - -Writing scripts for a player build? Keep each `MonoBehaviour` alone in a `.cs` file named after its class. Several in one file can run fine in the Editor and Play Mode, yet the built player crashes at startup saying a scene file such as `level0` is corrupted. See [build-run-test.md](references/build-run-test.md#build). - -### CI: run tests and publish results - -```bash -unity test /path/to/MyProject \ - --editor-version 6000.0.47f1 \ - --mode EditMode \ - --report-format junit \ - --output ./test-results.xml \ - --allow-install \ - --timeout 600 -case $? in - 0) echo "All tests passed" ;; - 8) echo "Tests failed — report to developers, do not retry" ;; - *) echo "Run did not complete — infrastructure failure, safe to retry" ;; -esac -``` - -Exit `8` means the run finished and reported failing tests; any other non-zero code means it never produced a verdict. Under `--format json` the same split is `errors[0].code`: `TESTS_FAILED` versus `TEST_RUN_ERROR` / `TEST_TIMED_OUT`. - -`--report-format junit` makes `--output` a JUnit-schema report, which GitHub Actions and GitLab ingest as native test results with no converter step. It is written even when tests fail. Drop the flag for the NUnit3 default, or use `--report-format nunit,junit` to get both from one run. Add `--coverage` to collect coverage via the Unity Code Coverage package — it warns and carries on if the project doesn't have the package. See [build-run-test.md](references/build-run-test.md). - -**Iterating on a change, not gating a pipeline?** Run the cheapest test that can fail for the change. Try EditMode first. Use `--filter`, `--affected` or `--rerun-failed` while you work. Run the full suite on the final code, once per mode, before you hand the work back. Never re-run a suite on code that has not changed, unless the run exited `6` with no verdict. Keep the NUnit default for these runs, because `--affected` and `--rerun-failed` cannot read the JUnit-only report the CI example above writes. [build-run-test.md](references/build-run-test.md#run-the-cheapest-test-that-proves-the-change) has the rule, and which report each flag reads and writes. `unity test` refuses a project that is open in an Editor: don't close the user's Editor to make room, and don't start a test run while they are in Play Mode. - -### Debug the CLI - -```bash -# Check auth + installed editors + recent errors in one command -unity doctor --format json - -# Follow live logs during an install -unity logs --follow --level info -``` - ---- +- inspect and run cloud builds and Pipeline Automation jobs +- edit a scene, GameObject, or asset (`unity status` first) +- use a catalog plugin for a task the built-in commands don't cover +- bootstrap a new project from scratch, and set up source control +- find and install a missing Editor, open a project with the right Editor +- CI: activate a license, build, run tests and publish results +- debug the CLI ## Notifications @@ -735,21 +226,5 @@ yourself.** Surface the notification and the command, and let the user decide. ## Notes -- `--non-interactive` and `--yes` together suppress all prompts — use both in CI. -- A short flag means one thing on every command: `-y` is `--yes` wherever `--yes` exists, `-a` is `--architecture`, `-e` is `--editor-path`, `-f` is `--force`, `-i` is `--installed`, `-l` is `--list`, `-m` is `--module`, `-o` is `--output` and `-r` is `--releases`. Every other option takes its long name: `unity projects` and `unity projects size` spell "every project" `--all`, `logs` and `projects logs` spell `--follow`, `projects import` spells `--input`, `build` and `run` spell `--log-file`, `projects` spells `--modified`, `templates location` spells `--reset`, and `foundry get` spells `--out`. An old spelling the CLI still accepts (`-a`, `-m`, `-i`, `-l`, `-r`, `-f` or `-o` on those, `--project` on `status`, `--template-version`, `--hub-version`, `--package-version`, `--list-components`, `--install-dir`, `--childModules`, `--wait-timeout`, `--git-token-stdin`, `--group_by` on `command`, `--local-space` on `collaboration annotations`, `--project-id` and `--organization-id` on `collaboration`, `-v` on `projects`, `--since` on `releases` and `vcs git migrate-lfs`, `--project` on `assets export`, `assets import` and `auth default`, `--path` on `build run`, `--project-path` on `projects clone`, `--skip` on `releases` and `cloud projects`, `--out` on `collaboration annotations export`, `collaboration attachments download` and `collaboration thumbnail download`) prints a warning naming the spelling to use; so does `--verbose` on `editors` and `projects`, which still shows every column but now spells it `--long`; in `--format json` it is in the envelope's `warnings`. Use the new spelling, so the warning never lands in a log you parse. -- `--timeout` takes a whole number of seconds written as digits (`--timeout 600`) on every command, and so do `UNITY_BUILD_TIMEOUT`, `UNITY_RUN_TIMEOUT` and `UNITY_TEST_TIMEOUT`. A unit, fraction or exponent (`30s`, `5m`, `1.5`, `1e3`) is a usage error (exit `2`), so convert minutes to seconds yourself. -- `--format json` always produces machine-readable output; prefer it over parsing human text. Error envelopes are pretty-printed with the same 2-space indent as success envelopes. The envelope's `command` is the full command path (`projects list`, `cloud org list`), the same in json and ndjson and on success and failure; it is `""` when no command matched, such as an unknown one. -- **`success` is `true` exactly when the exit code is `0`.** A status command whose answer is no (`unity auth status` signed out, `unity license status` with no license, `unity status` with no ready Editor) is a failure: `success: false`, an `errors[0].code` naming the answer, and its report still in `data`. A listing that finds nothing (`unity editors running` with no Editor) succeeds with an empty list. -- **A streamed named command has no CLI envelope.** When the project's `com.unity.pipeline` formats a named command's output itself (see `references/integration-advanced.md`), `unity command --format json` (or `--json`) prints the command's own result, one JSON value per line, with no `success`, `errors` or `data` wrapper, so its rows are not under `.data.items[]`. Branch on the exit code, which is the command's own, not one from the exit-code table above: `0` means it succeeded and any other code that it did not, such as `1` for a failed command, `102` when the Editor was busy and refused it (retry), or `106` when it was cancelled. A cancel that follows your Ctrl-C or a SIGTERM to the CLI exits `130` or `143` instead. With an older `com.unity.pipeline` the envelope and every rule in this list apply. -- **Read failures from stdout, not stderr.** A failed command still writes a complete document to stdout: under `--format json` an envelope with `success: false` and a populated `errors` array (`errors[0].code` is the stable token to branch on); under `--format ndjson` the usual terminal `{"type":"result","success":false,…}` frame. **Every ndjson stream ends with exactly one terminal `{"type":"result"}` frame, on success too**, so a stream without one was truncated. Table-shaped listings (`unity editors`, `unity editors upgrade --check`, `unity templates`, `unity releases`, `unity projects`, `unity contexts`, `unity auth accounts`, `unity modules`, `unity command`, `unity skills`, `unity logs`, `unity cloud orgs`, `unity cloud projects` and the like) write one row per line first, each starting with `"type":"row"` so you can tell a row from a `progress` or `result` frame, then a terminal frame whose `data` is `{count, total, nextPage|nextCursor, partial}` (some listings keep older keys there too). A `unity templates` row keeps its own `type` (the template type) with no `"row"` marker. A single-record answer (`unity version`, `unity language`, `unity env`, `unity doctor`, `unity config proxy`, `unity cache info`, `unity context current`, `unity editors default`, `unity install-path`, `unity diagnose update` and the like) is that frame alone, its `data` the same as `--format json`. `--quiet` never changes json output. It never changes ndjson output either, except that `unity editors upgrade`, `unity build --list-targets` and `unity build --list-profiles` still drop their rows under `--quiet` (the terminal frame stays), a known bug; leave `--quiet` off when you need those rows. A warning in either format appears only in `warnings`, never on stderr. A `--watch` or `--follow` stream, which only ends on Ctrl-C, writes its rows and no terminal frame. **Branch on `success`, never on `data`** — `data` is usually `null` on a failure, but not always: a partial `unity editors add` failure carries a row per path, and an ambiguous `unity auth switch` carries `data.candidates` for you to disambiguate with. Check `success` and the exit code — never treat empty stdout as a failure signal, and do not parse stderr, which carries only human diagnostics in these formats. If stdout is empty on a non-zero exit, that is a known bug in that command rather than a shape you should code against. -- **Never merge stderr into stdout when you parse (`2>&1`, or a tool that captures both as one stream).** Stdout alone is a complete, valid document under `--format json` and `--format ndjson`, but stderr carries human diagnostics. Merged in, those lines trail the JSON, and a parser fails with `Extra data` or a decoder needs `raw_decode`. Capture the two streams separately (`unity … --format json 2>err.txt >out.json`) and parse stdout only, or discard stderr with `2>/dev/null` (`2>NUL` on Windows cmd). No agent install hint goes to stderr under these formats: the tips ride the envelope's `notifications`, and Claude Code's `` tag is printed under every format but these two. -- `unity [path]` is a shorthand for `unity open [path] --editor-version `. Works with `lts`, `latest`, or a full version string like `6000.0.47f1`. -- The CLI supports kubectl-style plugins: any `unity-` binary on PATH is callable as `unity `. -- Terminal output is hardened against control-character / escape-sequence injection from server-provided values (project titles, editor versions, module names) — C0 controls and non-SGR escape sequences are stripped from table/list/tree output, and now also from Commander usage errors, the `unity bug` log-archive warning, and `unity projects add`/`remove` machine (tsv) output, while SGR color/style codes are preserved. -- The CLI reports anonymous crashes and errors via Sentry to help fix bugs (no IP address or hostname; home-directory paths and token-like values scrubbed before send), aligned with the Unity Hub. Opting in to analytics additionally attaches an anonymized machine id; opted-out users stay fully anonymous. Set `UNITY_NO_CRASH_REPORT`, or turn off "Send crash reports" in the Hub's settings, to disable reporting entirely. Separately again, every run sends one anonymous `cli telemetry` usage ping even when nobody answered the consent prompt; turning analytics off (in the CLI, or in the Hub while signed in), `DO_NOT_TRACK`, `UGS_CLI_TELEMETRY_DISABLED`, or `UNITY_NO_CLI_INVOKED_TELEMETRY` stops it — see [diagnostics-maintenance.md](references/diagnostics-maintenance.md#analytics--usagetelemetry-consent). -- `unity --version` prints the version you have. `unity self-update --check --format json` says whether a newer one exists on your installed channel (a beta follows betas). `unity self-update --check --channel stable --format json` checks for a stable release, for example when moving off a beta once GA ships. -- **Always use the latest version of the Unity CLI unless you are told to use a specific version.** A newer CLI regularly adds commands and output fields these docs describe, so an outdated one fails in ways that read like the docs being wrong. -- Since `0.1.0-beta.8` the CLI checks in the background for a newer version and prints an unobtrusive "update available" notice (interactive sessions only; never delays a command). Turn it off with `unity config update-check off` or the `UNITY_NO_UPDATE_CHECK` env var. -- The same check also covers plugins the CLI installed (`unity plugin install`): when one has a newer version, a notice names it and suggests `unity plugin upgrade`, at most once a day. The same two switches turn it off. -- **Under `--format json` and `--format ndjson` that same notice reaches you as a `notifications` array on the envelope** — see [Notifications](#notifications) below. Over MCP it arrives once per session, as prose in the server's `initialize` `instructions`. -- Outbound HTTP from every CLI command honors the resolved proxy (see `unity config proxy`). An invalid `--proxy` value (malformed URL or unsupported scheme) fails with a usage error (exit 2) instead of being silently ignored. Inspect what the CLI actually resolved with `unity env --format json` or `unity doctor --format json` — both surface the active proxy URL, its source, and auth source. +Short-flag rules, prompt suppression for CI, and other cross-cutting details: [notes.md](references/notes.md). Read it when a flag or prompt behaves unexpectedly. + diff --git a/skills/unity-cli/CHANGELOG.md b/skills/unity-cli/references/CHANGELOG.md similarity index 79% rename from skills/unity-cli/CHANGELOG.md rename to skills/unity-cli/references/CHANGELOG.md index 7bd52f1..3689072 100644 --- a/skills/unity-cli/CHANGELOG.md +++ b/skills/unity-cli/references/CHANGELOG.md @@ -10,16 +10,23 @@ usually tracked alongside the CLI change itself, not here. The `[Unreleased]` se the narrow exception: a surface documented ahead of its CLI release. It folds into that release's own dated section once the CLI actually ships it. +## Contents + +- [Unreleased](#unreleased): skill changes documented ahead of their CLI release. +- One `CLI ` section per CLI release below it, newest first, each dated with that release. + ## [Unreleased] ### Added - **Insecure credential storage**: `auth-license-cloud.md` documents `unity auth login --insecure-storage`, the opt-in that keeps a sign-in in a plain file when no system credential store works, and says the CLI no longer falls back to that file without it. Pending the CLI release that adds it. +- **MCP filter and groups**: `integration-advanced.md` says that with `--tool-groups`, a `--tools` or `--exclude-tools` entry also matches a group by its dotted or tool name (`--tools editor_playmode`), and that an `--exclude-tools` entry matching `unity-cli-status` hides it. Pending the CLI release that adds groups. - **MCP group filter**: `integration-advanced.md` documents `unity mcp --exclude-tool-groups `, which hides whole Editor command groups and refuses a call to any of their commands, and says an `--exclude-tools` list keeps working with groups. Pending the CLI release that adds it. - **MCP annotation filter**: `integration-advanced.md` documents `unity mcp --exclude-annotations `, which hides the Editor commands whose MCP annotations include `read-only`, `destructive`, `idempotent` or `open-world`, and refuses a call to one. Pending the CLI release that adds it. ### Changed +- **Slimmer main page and guardrails**: The main skill file keeps the search, Editor-driving and command-map content and moves global flags, environment variables, exit codes, common workflows, notes and the worktree recipe into `references/`. It adds a Guardrails section (ask first, restore point, no `console clear`, final console check and report). - **`recompile` exits 12 with no Editor**: `build-run-test.md` says `unity recompile` exits `12` (`EDITOR_UNREACHABLE`), not `7`, when no Editor answers, including while the Editor reloads after a fix. Treat `12` as worth retrying. `errors[0].code` is still `EDITOR_NOT_RUNNING`. Pending the CLI release that changes the exit code. - **`close` on a path that isn't a project fails**: `projects-templates.md` says `unity close` and `unity projects close` exit `11` with `PROJECTS_CLOSE_NOT_A_PROJECT` for a path with no `Assets` or `ProjectSettings` folder, where they used to succeed with `not_open`. Pending the CLI release that changes it. - **Don't clear the user's console**: `playmode-verification-loop.md` tells agents never to run `console clear`, which also deletes the user's own entries, and to read only their own entries with `console get --since ` from the cursor `console status` returns. @@ -27,6 +34,10 @@ release's own dated section once the CLI actually ships it. - **Kebab-case Pipeline command parameters**: `integration-advanced.md`, `playmode-verification-loop.md`, the `runtime-verify` skill and the `new-unity-project` skill spell Editor command parameters the way the Pipeline package now accepts them: `--enabled` (was `--enable`), `--output-path` for every capture command (was `--save_path` and `--output`), `--wait-id`, `--async-tests`, `--include-inline-image`, `--max-resolution`, and `find-type` and `on-met.capture` inside `job wait`. The Pipeline rejects the old spellings with `INVALID_COMMAND_ARGS`. Pending the `com.unity.pipeline` release that renames them. +## CLI `1.0.1` (2026-11-16) + +Aligned to the CLI's `1.0.1` release. Cut automatically by the release that published it, from the skill as it stood in that release — so this entry covers the documentation changes that had already landed by then. Anything worth calling out individually is added here in a follow-up pass. + ## CLI `1.0.0` (2026-11-12) Aligned to the CLI's `1.0.0` release. Cut automatically by the release that published it, from the skill as it stood in that release — so this entry covers the documentation changes that had already landed by then. Anything worth calling out individually is added here in a follow-up pass. @@ -44,7 +55,7 @@ Aligned to the CLI's `1.0.0-beta.16` release. Everything below was documented ah - **`skill install --all`**: `integration-advanced.md` documents installing the Unity skills into every agent client on the machine, which clients it maps each plugin agent to, that it runs no agent CLI and needs no git, its per-client lines, exit codes and json records, and that the install scripts run it. - **Administrator prompt needs a terminal**: `editors-install.md` says `uninstall`, `editors prune --remove` and `editors upgrade --replace` open the administrator password dialog for a folder this user can't delete only on a terminal, after one line saying why, and otherwise stop before removing anything with exit 2 and `UNINSTALL_ELEVATION_NEEDS_TERMINAL`. - **`projects upgrade` on an open project**: `projects-templates.md` says the upgrade exits `6` with "already open in a running Editor" and launches nothing when an Editor already holds the project, and to ask the user to close it first. -- **Setting up a Build Automation build target**: `SKILL.md` and `cloud-automation.md` document `pipeline cloud-build targets create`, `update` and `auditlog` (one option per field, or `--file` with a JSON target, `-` for stdin), `connections` and `connections create`, `scm check-url`, `credentials upload` and `org free-tier`, the order to run them in, and that passwords and tokens come from stdin or an environment variable, never an argument. +- **Setting up a Build Automation build target**: The main skill file and `cloud-automation.md` document `pipeline cloud-build targets create`, `update` and `auditlog` (one option per field, or `--file` with a JSON target, `-` for stdin), `connections` and `connections create`, `scm check-url`, `credentials upload` and `org free-tier`, the order to run them in, and that passwords and tokens come from stdin or an environment variable, never an argument. - **Streamed `unity command` output**: `integration-advanced.md` says a newer Editor formats and streams a named command's output, in the format `--plain` or `--json` picks, narrowed by `--fields`, that piped stdin and Ctrl-C reach the command, and that the CLI exits with the command's code. - **`unity auth broker ensure`**: `auth-license-cloud.md` documents starting the sign-in service for a plugin, its five states, exit codes and error codes. - **Remote Config kill switch and Cloud Save slot in `projects create`**: `projects-templates.md` says a create that links the project to Unity Cloud sets `liveops_enabled` to `true` on the server (add-only, never in a `.rc` file, and only by creating the `settings` config: an existing one is never written and the `notAdded` flag asks for the key to be added in the dashboard), adds `com.unity.remote-config` and `Assets/LiveOps/`, adds `com.unity.services.cloudsave` and `Assets/PlayerSave/` with one save slot, and that `--bare`, `--no-cloud` and a failed link leave both out. The `steps` report gains `remoteConfig` and `cloudSave`. @@ -52,7 +63,7 @@ Aligned to the CLI's `1.0.0-beta.16` release. Everything below was documented ah ### Fixed - **Commit ids in `projects clone --ref`**: `projects-templates.md` says a git `--ref` is a branch, a tag, or a commit id, full or abbreviated, that is checked out after the clone. -- **`--output` names a file, `--output-dir` a directory**: `build-run-test.md` writes `unity build -o, --output` and says `--output-path` still works. `collaboration.md` writes `-o, --output` for `annotations export`, `attachments download` and `thumbnail download`. `SKILL.md`, `projects-templates.md`, `version-control.md` and the `new-unity-project` skill write `--output-dir` for `projects create` and `clone`, `templates create` and `vcs git worktree add`, and say `clone --output-dir` is the exact destination, not a parent. The old spellings still work, with a deprecation warning. Pending the change shipping in a CLI release. +- **`--output` names a file, `--output-dir` a directory**: `build-run-test.md` writes `unity build -o, --output` and says `--output-path` still works. `collaboration.md` writes `-o, --output` for `annotations export`, `attachments download` and `thumbnail download`. The main skill file, `projects-templates.md`, `version-control.md` and the `new-unity-project` skill write `--output-dir` for `projects create` and `clone`, `templates create` and `vcs git worktree add`, and say `clone --output-dir` is the exact destination, not a parent. The old spellings still work, with a deprecation warning. Pending the change shipping in a CLI release. - **`skill install --all`**: `integration-advanced.md` documents installing the Unity skills into every agent client on the machine, which clients it maps each plugin agent to, that it runs no agent CLI and needs no git, its per-client lines, exit codes and json records, and that the install scripts run it. Pending the change shipping in a CLI release. - **Plugin areas in `unity bug`**: `diagnostics-maintenance.md` documents `--area ugs|plastic|ai|transform`, that a plugin area attaches that plugin's own logs, and the `Installed plugins:` line every report carries. Pending the change shipping in a CLI release. - **`unity setup qwen`**: `integration-advanced.md` documents installing Unity's agent plugin into Qwen Code, the `qwen` commands it runs, where it reads an existing install, the enable step that turns a disabled one back on, and the not-found and install-failed error codes. `SECURITY.md` extends the plugin-install fence to it. Pending the change shipping in a CLI release. @@ -63,7 +74,7 @@ Aligned to the CLI's `1.0.0-beta.16` release. Everything below was documented ah - **Pipeline on Unity 6000.5.0 to 6000.5.2**: `projects-templates.md` says `projects create` leaves the Pipeline package out on those Editors, which can't start its server, and raises `PIPELINE_EDITOR_UNSUPPORTED` (a stderr warning outside json and ndjson) saying to update to 6000.5.3f1 or later. `integration-advanced.md` says `STATUS_PIPELINE_LOAD_PENDING` on those Editors names the cause. Pending the change shipping in a CLI release. - **Administrator prompt needs a terminal**: `editors-install.md` says `uninstall`, `editors prune --remove` and `editors upgrade --replace` open the administrator password dialog for a folder this user can't delete only on a terminal, after one line saying why, and otherwise stop before removing anything with exit 2 and `UNINSTALL_ELEVATION_NEEDS_TERMINAL`. Pending the change shipping in a CLI release. - **`projects upgrade` on an open project**: `projects-templates.md` says the upgrade exits `6` with "already open in a running Editor" and launches nothing when an Editor already holds the project, and to ask the user to close it first. Pending the change shipping in a CLI release. -- **Setting up a Build Automation build target**: `SKILL.md` and `cloud-automation.md` document `pipeline cloud-build targets create`, `update` and `auditlog` (one option per field, or `--file` with a JSON target, `-` for stdin), `connections` and `connections create`, `scm check-url`, `credentials upload` and `org free-tier`, the order to run them in, and that passwords and tokens come from stdin or an environment variable, never an argument. Pending the change shipping in a CLI release. +- **Setting up a Build Automation build target**: The main skill file and `cloud-automation.md` document `pipeline cloud-build targets create`, `update` and `auditlog` (one option per field, or `--file` with a JSON target, `-` for stdin), `connections` and `connections create`, `scm check-url`, `credentials upload` and `org free-tier`, the order to run them in, and that passwords and tokens come from stdin or an environment variable, never an argument. Pending the change shipping in a CLI release. - **Streamed `unity command` output**: `integration-advanced.md` says a newer Editor formats and streams a named command's output, in the format `--plain` or `--json` picks, narrowed by `--fields`, that piped stdin and Ctrl-C reach the command, and that the CLI exits with the command's code. Pending the change shipping in a CLI release. - **`unity auth broker ensure`**: `auth-license-cloud.md` documents starting the sign-in service for a plugin, its five states, exit codes and error codes. Pending the change shipping in a CLI release. - **Remote Config kill switch and Cloud Save slot in `projects create`**: `projects-templates.md` says a create that links the project to Unity Cloud sets `liveops_enabled` to `true` on the server (add-only, never in a `.rc` file, and only by creating the `settings` config: an existing one is never written and the `notAdded` flag asks for the key to be added in the dashboard), adds `com.unity.remote-config` and `Assets/LiveOps/`, adds `com.unity.services.cloudsave` and `Assets/PlayerSave/` with one save slot, and that `--bare`, `--no-cloud` and a failed link leave both out. The `steps` report gains `remoteConfig` and `cloudSave`. Pending the change shipping in a CLI release. @@ -86,42 +97,42 @@ Aligned to the CLI's `1.0.0-beta.15` release. Everything below was documented ah - **`projects create` prerequisites**: `projects-templates.md` says create checks a license, and with the Unity Cloud link the sign-in, the network and the organization choice, before it does anything, and names the notification codes and exit codes. - **`unity projects audit`**: `projects-templates.md` documents opening Project Auditor in the running Editor on a workflow page (`--workflow upgrade|optimization|urp|coreclr`), ready for the user to run the analysis, after installing or updating its packages, plus `--report`, `--timeout`, the result data and the exit codes. - **`unity auth token`**: `auth-license-cloud.md` documents printing an access token for scripts and other tools, alone on stdout, its refresh of an expired session, the service-account bearer, `--json`'s expiry and auth mode, the exit codes, and that `--audience` and `--scope` are refused for now. -- **Running cloud builds and Pipeline Automation jobs**: `SKILL.md` and `cloud-automation.md` document `pipeline cloud-build builds` `steps`, `failures`, `artifacts`, `log`, `download`, `start` and `cancel`, and `pipeline automation pipelines trigger` and `jobs` `watch`, `logs`, `terminate`, `resume`, `approve` and `reject`. A waited run that fails exits `15` (`RUN_FAILED`), and a job waiting on a person exits `16` (`JOB_SUSPENDED`). They say never to re-run `builds start` or `pipelines trigger` after a failure, since that starts the work again. +- **Running cloud builds and Pipeline Automation jobs**: The main skill file and `cloud-automation.md` document `pipeline cloud-build builds` `steps`, `failures`, `artifacts`, `log`, `download`, `start` and `cancel`, and `pipeline automation pipelines trigger` and `jobs` `watch`, `logs`, `terminate`, `resume`, `approve` and `reject`. A waited run that fails exits `15` (`RUN_FAILED`), and a job waiting on a person exits `16` (`JOB_SUSPENDED`). They say never to re-run `builds start` or `pipelines trigger` after a failure, since that starts the work again. - **`projects create --install-editor`**: `projects-templates.md` says `--install-editor` installs a missing Editor version, waits, then creates the project, that `--module` and `--accept-eula` go to that install, that a failed install creates nothing, and that `data.editorInstalled` reports it. The `ENGINE_NOT_INSTALLED` remediation is now the create command with `--install-editor`. - **Anonymous player sign-in in `projects create`**: `projects-templates.md` says a create that links the project to Unity Cloud adds `com.unity.services.authentication` and `Assets/PlayerAuthentication/` (`PlayerAuthentication.cs` and its own assembly definition), that `PlayerAuthentication.SignedIn` is what to await, that nothing is configured server-side, and that `--bare`, `--no-cloud` and a failed link leave it out. The `steps` report gains `playerAuth`. -- **`unity setup copilot`**: `integration-advanced.md` documents installing Unity's agent plugin into GitHub Copilot CLI, the two `copilot plugin` commands it runs, `COPILOT_HOME`, the already-registered marketplace it accepts, and the `COPILOT_NOT_FOUND` / `COPILOT_PLUGIN_INSTALL_FAILED` error codes. `SECURITY.md` extends the plugin-install fence to it, and `SKILL.md`'s `UNITY_NO_AGENT_HINTS` row names the Copilot CLI tip. +- **`unity setup copilot`**: `integration-advanced.md` documents installing Unity's agent plugin into GitHub Copilot CLI, the two `copilot plugin` commands it runs, `COPILOT_HOME`, the already-registered marketplace it accepts, and the `COPILOT_NOT_FOUND` / `COPILOT_PLUGIN_INSTALL_FAILED` error codes. `SECURITY.md` extends the plugin-install fence to it, and the main skill file's `UNITY_NO_AGENT_HINTS` row names the Copilot CLI tip. ### Changed -- **Analytics on by default, no first-run prompt**: `diagnostics-maintenance.md` says the CLI never asks, that a user who never chose is opted in and told once by a stderr notice, and that an earlier choice, the Hub's setting and `DO_NOT_TRACK` are kept. The notice and `analytics status` now link the privacy policy, and `status` no longer prints the ping hint. `SKILL.md` drops `UNITY_NO_CONSENT_PROMPT` and the banner above the prompt. Pending the change shipping in a CLI release. +- **Analytics on by default, no first-run prompt**: `diagnostics-maintenance.md` says the CLI never asks, that a user who never chose is opted in and told once by a stderr notice, and that an earlier choice, the Hub's setting and `DO_NOT_TRACK` are kept. The notice and `analytics status` now link the privacy policy, and `status` no longer prints the ping hint. The main skill file drops `UNITY_NO_CONSENT_PROMPT` and the banner above the prompt. Pending the change shipping in a CLI release. - **Local package docs in `docs --package`**: `diagnostics-maintenance.md` and `docs-workflow.md` say `unity docs --package` opens the project's own `Documentation~` page when it has one, offline, that `--online` skips it and `--url` still prints the online manual, and that JSON reports `resolvedBy: local`, `source: local` and `path`. Pending the change shipping in a CLI release. -- **Busy and dialog-blocked Editors**: `SKILL.md` lists exit `17` (`UNAVAILABLE`) for an Editor that is loading, compiling, reloading or in Safe Mode, and `18` (`AWAITING_INPUT`) for one a modal dialog blocks, with what to do for each. Pending the change shipping in a CLI release. +- **Busy and dialog-blocked Editors**: The main skill file lists exit `17` (`UNAVAILABLE`) for an Editor that is loading, compiling, reloading or in Safe Mode, and `18` (`AWAITING_INPUT`) for one a modal dialog blocks, with what to do for each. Pending the change shipping in a CLI release. - **`plugin install` and `plugin upgrade` install a plugin's skill**: `integration-advanced.md` says they write the skill a plugin ships into every AI client that already has the Unity skill, and leave other clients alone. Pending the change shipping in a CLI release. - **`job wait` timeout parameter**: `playmode-verification-loop.md` uses `--timeout` (seconds, default 30, clamped 0 to 600) for `unity command job wait`, the name `com.unity.pipeline` 0.9.1-exp.1 uses in place of `--timeout_s`, and notes that it needs the `--` fence like `script eval`'s `timeout`. Pending the change shipping in a CLI release. - **`plugin install` and `plugin upgrade` install a plugin's skill**: `integration-advanced.md` says they write the skill a plugin ships into every AI client that already has the Unity skill, and leave other clients alone. - **`job wait` timeout parameter**: `playmode-verification-loop.md` uses `--timeout` (seconds, default 30, clamped 0 to 600) for `unity command job wait`, the name `com.unity.pipeline` 0.9.1-exp.1 uses in place of `--timeout_s`, and notes that it needs the `--` fence like `script eval`'s `timeout`. -- **Parse stdout alone**: `SKILL.md` says never to merge stderr into stdout (`2>&1`) when parsing `--format json` or `ndjson`, since stderr carries human diagnostics and the Claude Code install hint line, which trail the JSON and break a parser. It says to capture the streams separately or discard stderr. +- **Parse stdout alone**: The main skill file says never to merge stderr into stdout (`2>&1`) when parsing `--format json` or `ndjson`, since stderr carries human diagnostics and the Claude Code install hint line, which trail the JSON and break a parser. It says to capture the streams separately or discard stderr. - **`unity setup all`**: `integration-advanced.md` documents setting up every detected coding agent in one run, its per-client json `data` (`warnings`, the `skipped` outcome), the MCP retry and project-only notes, the state `notifications`, and its exit code. -- **`--offset` pages by offset**: `projects-templates.md` writes `releases --offset ` and `auth-license-cloud.md` shows `cloud project list --search --limit --offset `. `SKILL.md` lists `--skip` on `releases` and `cloud project list` among the old spellings that warn. -- **The rest of the Pipeline group-and-name rename**: `SECURITY.md` and `integration-advanced.md` name `unity command script eval` where they still said `eval`, `SKILL.md` and `integration-advanced.md` say commands run as `unity command `, and `integration-advanced.md`'s custom-command section explains `[CliCommand(name, description)]` (the `global` group) against `[CliCommand(group, name, description)]`, and names the `Tags` property, with `Tags = new[] { "runtime" }` marking a Player-only command, in place of `RuntimeOnly`. +- **`--offset` pages by offset**: `projects-templates.md` writes `releases --offset ` and `auth-license-cloud.md` shows `cloud project list --search --limit --offset `. The main skill file lists `--skip` on `releases` and `cloud project list` among the old spellings that warn. +- **The rest of the Pipeline group-and-name rename**: `SECURITY.md` and `integration-advanced.md` name `unity command script eval` where they still said `eval`, the main skill file and `integration-advanced.md` say commands run as `unity command `, and `integration-advanced.md`'s custom-command section explains `[CliCommand(name, description)]` (the `global` group) against `[CliCommand(group, name, description)]`, and names the `Tags` property, with `Tags = new[] { "runtime" }` marking a Player-only command, in place of `RuntimeOnly`. - **MCP tool names**: `integration-advanced.md` says each `unity mcp` tool is named by its full command name with spaces and dots written as `_` (`script_eval`, `settings_player_get`), that an older package's flat names (`eval`, `run_tests`) stay its tool names, and that `--tools` and `--exclude-tools` match that name too. - **Offline docs**: `docs-workflow.md` adds reading a page with `docs --content` and working offline with `docs cache add`, `list` and `clear`, and drops the "not available yet" list. `diagnostics-maintenance.md` documents `docs cache` and the `cache` source of `--content`. -- **Old spellings are listed once**: the references no longer repeat that a deprecated option spelling still works and warns; `SKILL.md`'s Notes list is the one place, and it now names `--project` on `assets export`, `assets import` and `auth default`, `--path` on `build run` and `--project-path` on `projects clone`. `SECURITY.md` names `build run --build-path`. -- **Machine formats never page `unity projects`**: `SKILL.md` drops the note that `--format tsv` and `--format github` on a terminal fell through to the paged human table; every machine format now turns that paging off. -- **Reference files open with a contents list**: each long reference file lists its sections at the top, and each one with relative links says they resolve from its `references/` folder. `SKILL.md` drops two time-sensitive phrasings, per the skills repo's mechanical checks (R1, R2, B11). -- **CI secrets stay off argv**: `SKILL.md`, `auth-license-cloud.md` and `diagnostics-maintenance.md` activate a serial with a bare `unity license activate` and `UNITY_LICENSE_SERIAL` in the step environment, and `build-run-test.md` documents `UNITY_ANDROID_KEYSTORE_PASSWORD` and `UNITY_ANDROID_KEY_ALIAS_PASSWORD` (the Editor still takes the passwords on its command line). +- **Old spellings are listed once**: the references no longer repeat that a deprecated option spelling still works and warns; the main skill file's Notes list is the one place, and it now names `--project` on `assets export`, `assets import` and `auth default`, `--path` on `build run` and `--project-path` on `projects clone`. `SECURITY.md` names `build run --build-path`. +- **Machine formats never page `unity projects`**: The main skill file drops the note that `--format tsv` and `--format github` on a terminal fell through to the paged human table; every machine format now turns that paging off. +- **Reference files open with a contents list**: each long reference file lists its sections at the top, and each one with relative links says they resolve from its `references/` folder. The main skill file drops two time-sensitive phrasings, per the skills repo's mechanical checks (R1, R2, B11). +- **CI secrets stay off argv**: The main skill file, `auth-license-cloud.md` and `diagnostics-maintenance.md` activate a serial with a bare `unity license activate` and `UNITY_LICENSE_SERIAL` in the step environment, and `build-run-test.md` documents `UNITY_ANDROID_KEYSTORE_PASSWORD` and `UNITY_ANDROID_KEY_ALIAS_PASSWORD` (the Editor still takes the passwords on its command line). - **A plugin-provided `unity-cli` skips only itself**: `integration-advanced.md` says that when a client plugin already provides the `unity-cli` skill, `unity skill install` still installs the skills an installed plugin or the project's package ships. - **`unity skill install` also writes `new-unity-project`**: `integration-advanced.md` says a default install writes it beside `unity-cli`, documents `--skill ` and the per-skill `--list` status, and says the plugin-provided skip also covers it when the providing plugin carries it, with its own `plugin-provided` record. -- **Listing is the bare plural noun**: `SKILL.md` and the references write `unity projects`, `unity templates`, `unity config`, `unity editors`, `unity modules `, `unity editors modules `, `unity plugins`, `unity skills`, `unity contexts`, `unity licenses` and `unity license servers` where they wrote the `list` leaf, which the CLI no longer accepts. +- **Listing is the bare plural noun**: The main skill file and the references write `unity projects`, `unity templates`, `unity config`, `unity editors`, `unity modules `, `unity editors modules `, `unity plugins`, `unity skills`, `unity contexts`, `unity licenses` and `unity license servers` where they wrote the `list` leaf, which the CLI no longer accepts. - **Whether a package is signed**: `projects-templates.md` says `assets inspect` and `assets import` report `signed` under `--format json` / `ndjson` (inspect also prints a `Signed:` line), that an unsigned import warns and `--require-signed` refuses it with `ASSET_PACKAGE_UNSIGNED` (exit `6`), and that the CLI checks only that a signature is present, never that it is valid. -- **`--editor-version` everywhere, and `-e` means `--editor-path`**: `projects-templates.md`, `SKILL.md`, `editors-install.md`, `cloud-automation.md`, `build-run-test.md` and `version-control.md` write `templates --editor-version`, `install-modules --editor-version` and `pipeline cloud-build ... --editor-version`, say `-e` is `--editor-path` (now on `vcs merge-setup` and `vcs resolve` too), that `templates` resolves `lts` and `latest`, that `UNITY_EDITOR_VERSION` is read by every command with `--editor-version` but the Cloud Build filters, and that `build` reads it and `UNITY_ARCHITECTURE` with a notice. The old `--editor`, `-e` and `--unity-version` spellings still work with a deprecation warning. -- **One meaning per short flag, part two**: `SKILL.md` lists every short flag with its one meaning, and says `--follow`, `--input`, `--log-file`, `--modified`, `--reset`, `--output-path` and `--out` have no short flag. `build-run-test.md` and `projects-templates.md` write `--log-file` and `--modified` in full. +- **`--editor-version` everywhere, and `-e` means `--editor-path`**: `projects-templates.md`, the main skill file, `editors-install.md`, `cloud-automation.md`, `build-run-test.md` and `version-control.md` write `templates --editor-version`, `install-modules --editor-version` and `pipeline cloud-build ... --editor-version`, say `-e` is `--editor-path` (now on `vcs merge-setup` and `vcs resolve` too), that `templates` resolves `lts` and `latest`, that `UNITY_EDITOR_VERSION` is read by every command with `--editor-version` but the Cloud Build filters, and that `build` reads it and `UNITY_ARCHITECTURE` with a notice. The old `--editor`, `-e` and `--unity-version` spellings still work with a deprecation warning. +- **One meaning per short flag, part two**: The main skill file lists every short flag with its one meaning, and says `--follow`, `--input`, `--log-file`, `--modified`, `--reset`, `--output-path` and `--out` have no short flag. `build-run-test.md` and `projects-templates.md` write `--log-file` and `--modified` in full. - **Which Editor version create uses**: `projects-templates.md` says `projects create` takes `--editor-version`, else the stored default, else the newest installed Editor, else the latest release when none is installed. It says `latest` and `lts` name releases rather than installed Editors, and that a version with no installed Editor fails with `ENGINE_NOT_INSTALLED`. It also says a json or ndjson run notes a newer official release with an `ENGINE_UPDATE_AVAILABLE` notification. -- **Every listing has one JSON shape**: `SKILL.md` says to read a listing's rows from `.data.items[]`, with `total`, `nextPage` or `nextCursor`, and `partial` beside them, and the ndjson `result` line carrying `count` and the same paging. `cloud-automation.md`, `integration-advanced.md` and `projects-templates.md` read `items` and page with `nextPage`. +- **Every listing has one JSON shape**: The main skill file says to read a listing's rows from `.data.items[]`, with `total`, `nextPage` or `nextCursor`, and `partial` beside them, and the ndjson `result` line carrying `count` and the same paging. `cloud-automation.md`, `integration-advanced.md` and `projects-templates.md` read `items` and page with `nextPage`. ### Removed -- **`projects new`**: `projects-templates.md` drops its section, and `SKILL.md` and the unattended-create advice no longer point at it. Use `unity projects create --no-cloud`, with `--path`, `--editor-version` and `--template` for a run that never prompts. +- **`projects new`**: `projects-templates.md` drops its section, and the main skill file and the unattended-create advice no longer point at it. Use `unity projects create --no-cloud`, with `--path`, `--editor-version` and `--template` for a run that never prompts. ### Fixed @@ -137,26 +148,26 @@ Aligned to the CLI's `1.0.0-beta.14` release. Everything below was documented ah ### Added -- **Agent install hints**: `SKILL.md` lists `UNITY_NO_AGENT_HINTS`, which turns off the suggestion to install Unity's agent plugin or skill, and names the `AGENT_PLUGIN_AVAILABLE` envelope notification. +- **Agent install hints**: The main skill file lists `UNITY_NO_AGENT_HINTS`, which turns off the suggestion to install Unity's agent plugin or skill, and names the `AGENT_PLUGIN_AVAILABLE` envelope notification. - **`unity setup antigravity`**: `integration-advanced.md` documents installing Unity's agent plugin into Antigravity, the `agy` command it runs, where it reads an existing install, and the not-found and install-failed error codes. `SECURITY.md` extends the plugin-install fence to it. - **Docs workflow for agents**: a new `docs-workflow.md` reference gives the order an agent follows to read the right Unity documentation: find a page with `docs toc`, resolve and cite its address with `docs --url`, and match the Editor version with `--editor-version`. It covers the daily page-index cache and the offline behavior, uses 2D examples, and lists reading page content in the terminal, offline content and package docs as not yet available. - **Accepting the Unity Editor Software Terms with `unity terms`**: `editors-install.md` documents `unity terms accept ` (it shows the terms link and the Editor's own copy, then asks; `--yes` for unattended setup, and the `TERMS_ACCEPT_NEEDS_CONFIRMATION` refusal without a terminal) and `unity terms status`. `projects-templates.md` now says current Editors ignore `-acceptSoftwareTermsForThisRunOnly` and points at `terms accept`, which an agent runs with `--yes` only when the user has agreed to the terms. - **Reading and following the Editor console with `unity logs --console`**: `diagnostics-maintenance.md` documents `--console`, `--console --follow` and `--project-path` on `unity logs`, the entry fields (Burst and compiler errors carry a `diagnostic` with their code, file and line), how `--level` maps onto the console's levels, and how the follower handles a script reload, an Editor restart and evicted entries. -- **Safe Mode in `unity status`**: the Safe Mode recovery in `integration-advanced.md` and the Safe Mode notes in `SKILL.md` now start from `unity status`, which reports an Editor in Safe Mode (`STATUS_SAFE_MODE`) and lists its compile errors (`safeMode.compileErrors` under `--format json`). Reading `Editor.log` by hand is the fallback when it can't. +- **Safe Mode in `unity status`**: the Safe Mode recovery in `integration-advanced.md` and the Safe Mode notes in the main skill file now start from `unity status`, which reports an Editor in Safe Mode (`STATUS_SAFE_MODE`) and lists its compile errors (`safeMode.compileErrors` under `--format json`). Reading `Editor.log` by hand is the fallback when it can't. - **Using the Hub's sign-in**: `auth-license-cloud.md` says a signed-out CLI on a terminal asks "Use , signed in to Unity Hub? (y/N)" from `unity auth` and `unity auth login`, that yes switches only the CLI's own account, and that `--json`, `--non-interactive` and runs without a terminal never switch but report `adoptable` and the `unity auth switch ` command, which an agent should show the user rather than run unasked. - **Named dialog codes on `unity open --until-ready`**: `projects-templates.md` says the Safe Mode prompt, the Auto Graphics API Notice and the Software Terms dialog are reported as `OPEN_BLOCKED_BY_DIALOG_SAFE_MODE`, `_GRAPHICS_API` and `_SOFTWARE_TERMS`, with the same remedies `unity status` gives (and the Safe Mode compile errors), and that all keep the `OPEN_BLOCKED_BY_DIALOG` prefix. `integration-advanced.md`'s Safe Mode recovery names the `open` code too. -- **Search first, never grep help**: `SKILL.md` now leads with a "Find a command" section telling agents to use `unity commands --grep` (built-in commands and plugins) and `unity command --query` (Pipeline commands of the connected Editor or a running Player) instead of filtering `unity --help` with `grep`, and says which covers what until a unified search ships. Needs a `sync-cli-skill` publish. +- **Search first, never grep help**: The main skill file now leads with a "Find a command" section telling agents to use `unity commands --grep` (built-in commands and plugins) and `unity command --query` (Pipeline commands of the connected Editor or a running Player) instead of filtering `unity --help` with `grep`, and says which covers what until a unified search ships. Needs a `sync-cli-skill` publish. - **`--operating-system` on `releases` and `install --dry-run`**: `editors-install.md` documents listing another OS's releases and previewing another OS's install, the `CROSS_OS_INSTALL_UNSUPPORTED` and `INVALID_OPERATING_SYSTEM` refusals, and that `--list-modules`, `modules list` and `editors --releases` stay on the host's OS. -- **Word search and ranking in `commands --grep`**: `SKILL.md` and `integration-advanced.md` say plain words match in any order and rank by command name, parent path, description, then options, while a pattern with a regex character stays a regular expression in tree order. +- **Word search and ranking in `commands --grep`**: The main skill file and `integration-advanced.md` say plain words match in any order and rank by command name, parent path, description, then options, while a pattern with a regex character stays a regular expression in tree order. - **See-also between `cloud project` and `projects link cloud`**: `auth-license-cloud.md` notes that linking a local folder to a cloud project is `unity projects link cloud `, and that the two help pages now point at each other. -- **What each command search skips**: `SKILL.md` says `unity commands --grep` never searches Pipeline commands and that each search names the source it skipped (`data.hint`); `integration-advanced.md` documents `unity command --query` with no connected Editor (exit 0, a pointer at `commands --grep` with its match count) and on an empty result. +- **What each command search skips**: The main skill file says `unity commands --grep` never searches Pipeline commands and that each search names the source it skipped (`data.hint`); `integration-advanced.md` documents `unity command --query` with no connected Editor (exit 0, a pointer at `commands --grep` with its match count) and on an empty result. - **Search pointer in help and errors**: "Getting help" says `unity --help` and the unknown-command error end with "Not sure which command? `unity commands --grep `". - **The Unity Editor Software Terms dialog**: `projects-templates.md` says a first windowed open can stop at it despite `-acceptSoftwareTermsForThisRunOnly`, that `unity status` reports it as `STATUS_BLOCKED_BY_DIALOG_SOFTWARE_TERMS`, and that only the user accepts it. It also says `unity open` passes the flag only on a headless open, and `--args` cannot remove it. - **The Auto Graphics API Notice**: `projects-templates.md` says `unity status` reports the Windows notice an upgraded project shows as `STATUS_BLOCKED_BY_DIALOG_GRAPHICS_API`, and that the user answers it with Confirm. - **The "Enter Safe Mode?" prompt**: `integration-advanced.md`'s Safe Mode recovery now covers the prompt a windowed Editor stops on before Safe Mode, which `unity pipeline list` can't see. `unity status` reports it as `STATUS_BLOCKED_BY_DIALOG_SAFE_MODE` with the first compile errors. The section says no launch flag answers it, that the user answers it (Quit, or Enter Safe Mode), and that an agent stops only an Editor it started, by PID. - **Headless / fleet license activation**: `auth-license-cloud.md` has a recipe for machines with no browser: `--serial` for perpetual and legacy Pro/Plus serials, `--generate-request` then `--file` for air-gapped machines (with the licensing client staged before the machine goes offline), `--floating`, and `license return` on decommission. It states that there is no username/password option and that a service account cannot activate a license. Verified: `--serial` needs no sign-in on either engine. - **Hub accounts in `auth list`**: "Separate sign-in from Hub" explains that an account signed in to in the Hub appears in `unity auth list` without the CLI being signed in to it, and that `unity auth switch` activates it when its sign-in is readable, or `unity auth login` signs it in when not. -- **`UNITY_NO_CLOUD` and where the default project applies**: `SKILL.md`'s env table and `projects-templates.md` document `UNITY_NO_CLOUD` beside `--no-cloud` (presence-based, yields to an explicit cloud flag). `auth-license-cloud.md` says the saved default feeds the service commands and `projects link cloud` but not `projects create`, and that `cloud project current` prints the default rather than the folder's project. +- **`UNITY_NO_CLOUD` and where the default project applies**: The main skill file's env table and `projects-templates.md` document `UNITY_NO_CLOUD` beside `--no-cloud` (presence-based, yields to an explicit cloud flag). `auth-license-cloud.md` says the saved default feeds the service commands and `projects link cloud` but not `projects create`, and that `cloud project current` prints the default rather than the folder's project. - **`--accept-upgrades` on `unity open` and `unity projects open`**: `projects-templates.md` documents the opt-in that passes `-skipUpgradeDialogs` to the Editor, what it says yes to (the project upgrade and the API Updater's script rewrite, with no backup prompt), why it is never a default, and `unity projects upgrade` as the deliberate path. - **`--download-directory` (`-d`, alias `--install-dir`) on `unity install` and `unity install-modules`**: `editors-install.md` documents installing a self-contained Editor into a named folder without registering it or changing the install path, the `data.path` result field, the per-folder already-installed check and lock (a `-d` naming the Hub's own install folder locks like a normal install), the `--resume` refusal, and adding modules there later. - **`--bare` and the `steps` result field on `unity projects create`**: `projects-templates.md` documents creating a project without the default project scaffolding while keeping the cloud link and `--vcs`, the `--with-pipeline` refusal (`BARE_ARGS_CONFLICT`), and the per-step report with its statuses and reason codes. @@ -167,43 +178,43 @@ Aligned to the CLI's `1.0.0-beta.14` release. Everything below was documented ah - **Play Mode loop turns auto-tick back off**: `playmode-verification-loop.md` step 8 and the command summary turn `editor set_auto_tick` off after `editor.playmode stop`, next to the Run In Background revert, unless the agent will keep driving the Editor. - **`setup claude` installs from the official marketplace**: `integration-advanced.md` and `SECURITY.md` say `unity setup claude` runs `claude plugin marketplace add anthropics/claude-plugins-official` and `claude plugin install unity@claude-plugins-official`, and that an earlier `unity@unity-agent-plugin` install is reported as installed. - **`unity mcp` desktop capture is opt-in**: `integration-advanced.md` says `capture_game_view` and `capture_scene_view` return an error when the Editor can't be captured, and fall back to a screenshot of every display only when `UNITY_MCP_DESKTOP_FALLBACK=1` is set for the server. -- **Search rows say what matched**: `SKILL.md` and `integration-advanced.md` say each `commands --grep` and `command --query` row carries `path` and `matchedOn` (`name`, `description` or `option`) beside `kind`, `description` and `invoke`, that an installed plugin's `invoke` is `unity `, and that tsv appends `path` and `matchedOn` as its last columns. -- **A timeout is whole seconds**: `SKILL.md` says every `--timeout`, and `UNITY_BUILD_TIMEOUT`, `UNITY_RUN_TIMEOUT` and `UNITY_TEST_TIMEOUT`, take a whole number of seconds written as digits, and that `30s`, `5m`, `1.5` or `1e3` is a usage error (exit 2). -- **`--timeout` bounds the wait for another install**: `editors-install.md` writes `unity install`, `unity install-modules` and `unity projects require` with `--timeout `, the spelling every other command uses, and says the old `--wait-timeout` still works with a deprecation warning. `SKILL.md` lists `--wait-timeout` among the old spellings that warn. -- **`--since` means a revision**: `version-control.md` writes `vcs git migrate-lfs --after ` and `projects-templates.md` writes `releases --from-year `, and the common-traps entry says `--since` takes a revision on `vcs summarize`, `vcs affected` and `test`. `SKILL.md` lists `--since` on `releases` and `vcs git migrate-lfs` among the old spellings that warn. -- **`collaboration` uses `--cloud-org` and `--cloud-project`**: `collaboration.md` writes `--cloud-project ` and `--cloud-org ` everywhere it wrote `--project-id` and `--organization-id`, says both take an id only and that the old spellings still work and warn, and says the organization of `jira server`, `jira project add`/`delete`/`update` and `jira issues list` falls back to `UNITY_CLOUD_ORG` and then the stored default organization, while `jira configs` reads only the scope typed, and that an empty or whitespace-only flag or variable counts as not set. `SKILL.md` lists the two old spellings among those that warn. -- **One command search**: `SKILL.md` says `unity commands --grep` and `unity command --query` are now one search over built-in commands, plugins and the connected Editor's Pipeline commands, and that each row says how to run it. `integration-advanced.md` documents the `pipeline` kind, the `invoke` field, the line that says why the Editor was not searched, and that `--query` beside another listing flag is still the Editor's own filter. `playmode-verification-loop.md` and the `runtime-verify` skill read a command's schema with `--query --detail full`. -- **Old option spellings warn**: `SKILL.md` says an old spelling the CLI still accepts (`projects list -a`, `status --project`, `--template-version`, `--hub-version`, `--package-version`, `--list-components`, `--install-dir`, `--childModules`) prints a deprecation warning naming the new one, in the envelope's `warnings` under `--format json`. `config-hub.md`, `editors-install.md`, `integration-advanced.md` and `projects-templates.md` call those spellings deprecated rather than hidden aliases, and `integration-advanced.md` filters `status` with `--project-path`. -- **One spelling per option**: `SKILL.md`, `projects-templates.md`, `version-control.md` and the `new-unity-project` skill pipe Git tokens to `--git-token-from-stdin`; `collaboration.md` writes the annotation anchor `--local`, as on spatial attachments; `integration-advanced.md` writes `command --group-by` and drops the note not to correct `--group_by`; `editors-install.md` shows every column with `editors --long`. `SKILL.md` lists the old spellings among the deprecated ones that warn, and says `--verbose` on `editors` and `projects list` still shows every column but warns. +- **Search rows say what matched**: The main skill file and `integration-advanced.md` say each `commands --grep` and `command --query` row carries `path` and `matchedOn` (`name`, `description` or `option`) beside `kind`, `description` and `invoke`, that an installed plugin's `invoke` is `unity `, and that tsv appends `path` and `matchedOn` as its last columns. +- **A timeout is whole seconds**: The main skill file says every `--timeout`, and `UNITY_BUILD_TIMEOUT`, `UNITY_RUN_TIMEOUT` and `UNITY_TEST_TIMEOUT`, take a whole number of seconds written as digits, and that `30s`, `5m`, `1.5` or `1e3` is a usage error (exit 2). +- **`--timeout` bounds the wait for another install**: `editors-install.md` writes `unity install`, `unity install-modules` and `unity projects require` with `--timeout `, the spelling every other command uses, and says the old `--wait-timeout` still works with a deprecation warning. The main skill file lists `--wait-timeout` among the old spellings that warn. +- **`--since` means a revision**: `version-control.md` writes `vcs git migrate-lfs --after ` and `projects-templates.md` writes `releases --from-year `, and the common-traps entry says `--since` takes a revision on `vcs summarize`, `vcs affected` and `test`. The main skill file lists `--since` on `releases` and `vcs git migrate-lfs` among the old spellings that warn. +- **`collaboration` uses `--cloud-org` and `--cloud-project`**: `collaboration.md` writes `--cloud-project ` and `--cloud-org ` everywhere it wrote `--project-id` and `--organization-id`, says both take an id only and that the old spellings still work and warn, and says the organization of `jira server`, `jira project add`/`delete`/`update` and `jira issues list` falls back to `UNITY_CLOUD_ORG` and then the stored default organization, while `jira configs` reads only the scope typed, and that an empty or whitespace-only flag or variable counts as not set. The main skill file lists the two old spellings among those that warn. +- **One command search**: The main skill file says `unity commands --grep` and `unity command --query` are now one search over built-in commands, plugins and the connected Editor's Pipeline commands, and that each row says how to run it. `integration-advanced.md` documents the `pipeline` kind, the `invoke` field, the line that says why the Editor was not searched, and that `--query` beside another listing flag is still the Editor's own filter. `playmode-verification-loop.md` and the `runtime-verify` skill read a command's schema with `--query --detail full`. +- **Old option spellings warn**: The main skill file says an old spelling the CLI still accepts (`projects list -a`, `status --project`, `--template-version`, `--hub-version`, `--package-version`, `--list-components`, `--install-dir`, `--childModules`) prints a deprecation warning naming the new one, in the envelope's `warnings` under `--format json`. `config-hub.md`, `editors-install.md`, `integration-advanced.md` and `projects-templates.md` call those spellings deprecated rather than hidden aliases, and `integration-advanced.md` filters `status` with `--project-path`. +- **One spelling per option**: The main skill file, `projects-templates.md`, `version-control.md` and the `new-unity-project` skill pipe Git tokens to `--git-token-from-stdin`; `collaboration.md` writes the annotation anchor `--local`, as on spatial attachments; `integration-advanced.md` writes `command --group-by` and drops the note not to correct `--group_by`; `editors-install.md` shows every column with `editors --long`. The main skill file lists the old spellings among the deprecated ones that warn, and says `--verbose` on `editors` and `projects list` still shows every column but warns. - **URP is the default template**: `projects-templates.md` says `projects create` without `--template` uses the Editor version's own `com.unity.template.urp-blank`, that `--template 3d` and `--template 2d` name the version's URP templates, that create never falls back to a Built-in Render Pipeline template, and that a version without it fails with `TEMPLATE_NOT_FOUND` and lists what it offers in `data.offered`. -- **Peer code-signature check**: `SKILL.md` no longer lists a development-only setting that weakens the peer code-signature check, and `auth-license-cloud.md` no longer documents it. `auth-license-cloud.md` says that the auth broker and the Editor identity helper refuse an unsigned or non-Unity-signed peer on macOS and Windows, and that an Editor built from source isn't supported for automatic sign-in. Earlier entries below are reworded to match. +- **Peer code-signature check**: The main skill file no longer lists a development-only setting that weakens the peer code-signature check, and `auth-license-cloud.md` no longer documents it. `auth-license-cloud.md` says that the auth broker and the Editor identity helper refuse an unsigned or non-Unity-signed peer on macOS and Windows, and that an Editor built from source isn't supported for automatic sign-in. Earlier entries below are reworded to match. - **`auth login` progress on stderr**: `auth-license-cloud.md` says the `--format json` `auth_url=` progress frame goes to stderr, so stdout is the envelope alone. -- **One meaning per short flag**: `SKILL.md` says `-y` is `--yes` on every command that has `--yes` (now including `bug mcp`, `mcp configure`, `skill install` and `skill refresh`), and `-a` is `--architecture` everywhere, so `projects list` and `projects size` are written with `--all`. -- **Failures never reach stderr as JSON**: `SKILL.md` no longer says some commands still print `{"error": "…"}` to stderr, and lists `unity cloud org list` and `unity cloud project list` among the table listings that end in a `{"count": N}` frame. +- **One meaning per short flag**: The main skill file says `-y` is `--yes` on every command that has `--yes` (now including `bug mcp`, `mcp configure`, `skill install` and `skill refresh`), and `-a` is `--architecture` everywhere, so `projects list` and `projects size` are written with `--all`. +- **Failures never reach stderr as JSON**: The main skill file no longer says some commands still print `{"error": "…"}` to stderr, and lists `unity cloud org list` and `unity cloud project list` among the table listings that end in a `{"count": N}` frame. - **`unity mcp` says why it lists no Editor tools**: `integration-advanced.md` says that until an Editor is reachable, the tool list holds one `unity-cli-status` tool whose description gives the reason, and that calling it checks again. - **`skill install` writes one JSON document**: `integration-advanced.md` says `--format json` writes one envelope whose `data` holds a record per skill considered. - **`skill install` says when it skips**: `integration-advanced.md` says a non-interactive `unity skill install` without `--yes` skips an outdated copy, or a skill a plugin already provides, still exits `0`, and marks the skipped skill's JSON result with `skipped: true` and a `skipReason`. -- **More ndjson answers end in their frame**: `SKILL.md` no longer lists `unity pipeline list` or `unity changelog` among the commands whose ndjson stream lacks a terminal `{"type":"result"}` frame. +- **More ndjson answers end in their frame**: The main skill file no longer lists `unity pipeline list` or `unity changelog` among the commands whose ndjson stream lacks a terminal `{"type":"result"}` frame. - **`editors upgrade` leaves the IDE modules behind**: `editors-install.md` says the upgrade no longer carries Visual Studio Code or Visual Studio over to the new editor, and that `-m visualstudiocode` installs it anyway. - **`--version` names a command's own subject below the root**: `unity --version` and `unity -V` still print the CLI version, but subcommands no longer inherit them. `config-hub.md`, `integration-advanced.md` and `projects-templates.md` now use `hub install --version`, `pipeline install --version` and `templates create|pack|edit --version`, and say the old `--hub-version`, `--package-version` and `--template-version` spellings still work. -- **Single-record ndjson answers end in their frame**: `SKILL.md` says `unity version`, `unity language`, `unity config proxy`, `unity cache info` and other single-record answers write one `{"type":"result"}` frame whose `data` matches `--format json`, and that `unity env` writes its rows and then that frame, so it no longer lists `unity env` or `unity version` among the commands that lack one. +- **Single-record ndjson answers end in their frame**: The main skill file says `unity version`, `unity language`, `unity config proxy`, `unity cache info` and other single-record answers write one `{"type":"result"}` frame whose `data` matches `--format json`, and that `unity env` writes its rows and then that frame, so it no longer lists `unity env` or `unity version` among the commands that lack one. - **`status` and `editors running` rows use the shared key names**: `integration-advanced.md` says `unity status` rows name the project as `projectPath` and the Editor as `editorVersion`, with `project` and `version` deprecated, and `editors-install.md` says `unity editors running` rows carry `editorVersion`, with `unityVersion` deprecated. -- **Pin each Editor call to its worktree's project.** `SKILL.md`'s one-Editor-per-worktree paragraph told agents to set `UNITY_PROJECT_PATH` once for the session. Most agent tools run each command in a fresh shell, so the variable never reached later calls, which then targeted the source checkout's Editor. It now says to pass `--project-path` on every call that reaches the Editor, or to prefix each call with the variable, and shows the prefixed form. `integration-advanced.md`'s target-resolution note says the same. -- **Play Mode checks on a locked or unattended desktop.** `playmode-verification-loop.md` now says a locked Windows session can stop Play Mode from advancing, even with Run In Background on. Stepping it by hand works: pause the Editor, then call `Step()` through `script eval`. That is only for a session the agent started, so the loop now opens by reading the Editor's play state. `capture game_view --source screen` needs an unlocked desktop (reported on Windows, where a locked session returned a solid cyan image). `--source camera` works when the machine may be locked, except for a Screen Space - Overlay canvas, which no camera draws. `SKILL.md`'s Play Mode note names the locked case. -- **No hard-coded "latest" version or release stage**: `SKILL.md`'s Notes no longer name a CLI version as the latest, or say the CLI is currently in beta. It points at `unity --version` and `unity self-update --check --format json`, so the installed skill can't call itself a release behind. +- **Pin each Editor call to its worktree's project.** The main skill file's one-Editor-per-worktree paragraph told agents to set `UNITY_PROJECT_PATH` once for the session. Most agent tools run each command in a fresh shell, so the variable never reached later calls, which then targeted the source checkout's Editor. It now says to pass `--project-path` on every call that reaches the Editor, or to prefix each call with the variable, and shows the prefixed form. `integration-advanced.md`'s target-resolution note says the same. +- **Play Mode checks on a locked or unattended desktop.** `playmode-verification-loop.md` now says a locked Windows session can stop Play Mode from advancing, even with Run In Background on. Stepping it by hand works: pause the Editor, then call `Step()` through `script eval`. That is only for a session the agent started, so the loop now opens by reading the Editor's play state. `capture game_view --source screen` needs an unlocked desktop (reported on Windows, where a locked session returned a solid cyan image). `--source camera` works when the machine may be locked, except for a Screen Space - Overlay canvas, which no camera draws. The main skill file's Play Mode note names the locked case. +- **No hard-coded "latest" version or release stage**: The main skill file's Notes no longer name a CLI version as the latest, or say the CLI is currently in beta. It points at `unity --version` and `unity self-update --check --format json`, so the installed skill can't call itself a release behind. - **`unity status` and modal dialogs**: `integration-advanced.md` says a dialog-frozen Editor reads `starting`, that an Editor busy running another command still reads `ready`, and documents `STATUS_BLOCKED_BY_DIALOG` and the row's `blockedBy` (Unity 6000.7 or later names the dialog; an older Editor's row is plain `starting`). It listed four failure codes and no `blockedBy`. - **The Pipeline package is part of every `unity projects create`**: `projects-templates.md` documents that create adds `com.unity.pipeline` unless `--bare`, that `--with-pipeline` is now a no-op, the quiet `UNSUPPORTED_VERSION` skip before Unity 6, and drops the agent-session hint; `integration-advanced.md` no longer points at `--with-pipeline`. -- `SKILL.md`'s "CI: activate a license, then build" workflow no longer signs in a service account and then runs the default activation, which a service account is refused. It activates with `--serial` (or `--floating`), runs no `unity auth login` (service-account environment variables cover cloud commands without a credential store), and says `license return` covers serial and assigned seats. The CI step reads `UNITY_LICENSE_SERIAL`, the secret `unity ci init` generates, and scopes `--serial` to perpetual or legacy serials. `auth-license-cloud.md` no longer says `unity auth logout` has a confirmation prompt for `--yes` to skip, no longer says `unity auth revoke` stops an application from using your sign-in (it records it in a local list the auth broker does not consult yet), and no longer says `--serial` works offline: it needs no sign-in, but it does reach the licensing server. -- **One `MonoBehaviour` per file for a player build.** `build-run-test.md`'s Build section and `SKILL.md`'s batch-mode build section now tell agents to keep each `MonoBehaviour` they write alone in a `.cs` file named after its class. The symptom of getting it wrong is a built player that crashes at startup saying a scene file such as `level0` is corrupted. That error points at scene data, and the Editor and Play Mode can run without a warning. -- **`vcs git worktree` paths**: `SKILL.md` no longer says the output masks paths, and `version-control.md` says `--format json` carries the real paths while human output masks them. `--into` stays as optional advice. -- **Run the cheapest test that proves a change, and never test during the user's Play Mode.** `build-run-test.md` now carries a short rule for `unity test`: EditMode before PlayMode, `--filter`, `--affected` or `--rerun-failed` while iterating, the full suite on the final code before handing work back, and no re-run on code that has not changed. It says which report each of those runs reads and writes, so a narrow run never replaces the full-suite record. It also says `unity test` refuses a project that is open in an Editor. Closing the user's Editor to make room, or starting a test run while they are in Play Mode, is not the answer. `SKILL.md`'s test section points at it, so the flags no longer read as CI-only. -- **Editors built from source**: `SKILL.md` and `auth-license-cloud.md` no longer suggest a signature-check setting for an Editor built from source: the Editor identity helper signs in only Unity-signed Editors on macOS and Windows. -- **`projects` description**: `SKILL.md`'s command table quotes the new `unity projects` help line, "Create, open, upgrade, and link local Unity projects (Unity Cloud, GitHub/GitLab)", and says linking a folder to Unity Cloud is `projects link cloud`, not `cloud`. -- **Pipeline commands are named by group and name.** `SKILL.md`, `integration-advanced.md` and `playmode-verification-loop.md` run them as `unity command editor status`, `unity command editor.playmode start`, `unity command script eval` and so on, where they used the flat names (`editor_status`, `editor_play`, `eval`). `integration-advanced.md` explains the form, and that a package from before command groups is retried under its old names with a one-time warning to run `unity pipeline upgrade`. +- the main skill file's "CI: activate a license, then build" workflow no longer signs in a service account and then runs the default activation, which a service account is refused. It activates with `--serial` (or `--floating`), runs no `unity auth login` (service-account environment variables cover cloud commands without a credential store), and says `license return` covers serial and assigned seats. The CI step reads `UNITY_LICENSE_SERIAL`, the secret `unity ci init` generates, and scopes `--serial` to perpetual or legacy serials. `auth-license-cloud.md` no longer says `unity auth logout` has a confirmation prompt for `--yes` to skip, no longer says `unity auth revoke` stops an application from using your sign-in (it records it in a local list the auth broker does not consult yet), and no longer says `--serial` works offline: it needs no sign-in, but it does reach the licensing server. +- **One `MonoBehaviour` per file for a player build.** `build-run-test.md`'s Build section and the main skill file's batch-mode build section now tell agents to keep each `MonoBehaviour` they write alone in a `.cs` file named after its class. The symptom of getting it wrong is a built player that crashes at startup saying a scene file such as `level0` is corrupted. That error points at scene data, and the Editor and Play Mode can run without a warning. +- **`vcs git worktree` paths**: The main skill file no longer says the output masks paths, and `version-control.md` says `--format json` carries the real paths while human output masks them. `--into` stays as optional advice. +- **Run the cheapest test that proves a change, and never test during the user's Play Mode.** `build-run-test.md` now carries a short rule for `unity test`: EditMode before PlayMode, `--filter`, `--affected` or `--rerun-failed` while iterating, the full suite on the final code before handing work back, and no re-run on code that has not changed. It says which report each of those runs reads and writes, so a narrow run never replaces the full-suite record. It also says `unity test` refuses a project that is open in an Editor. Closing the user's Editor to make room, or starting a test run while they are in Play Mode, is not the answer. The main skill file's test section points at it, so the flags no longer read as CI-only. +- **Editors built from source**: The main skill file and `auth-license-cloud.md` no longer suggest a signature-check setting for an Editor built from source: the Editor identity helper signs in only Unity-signed Editors on macOS and Windows. +- **`projects` description**: The main skill file's command table quotes the new `unity projects` help line, "Create, open, upgrade, and link local Unity projects (Unity Cloud, GitHub/GitLab)", and says linking a folder to Unity Cloud is `projects link cloud`, not `cloud`. +- **Pipeline commands are named by group and name.** The main skill file, `integration-advanced.md` and `playmode-verification-loop.md` run them as `unity command editor status`, `unity command editor.playmode start`, `unity command script eval` and so on, where they used the flat names (`editor_status`, `editor_play`, `eval`). `integration-advanced.md` explains the form, and that a package from before command groups is retried under its old names with a one-time warning to run `unity pipeline upgrade`. ### Removed -- **Paved mode**: the `UNITY_CLI_FTUE` row in `SKILL.md`'s environment variable table and the paved mode paragraph in `projects-templates.md` are gone, since the CLI no longer has the mode. Envelopes no longer carry `"paved"`, and `projects create` no longer writes `UserSettings/UnityCliPaved.json` or reports `pavedSettings`. +- **Paved mode**: the `UNITY_CLI_FTUE` row in the main skill file's environment variable table and the paved mode paragraph in `projects-templates.md` are gone, since the CLI no longer has the mode. Envelopes no longer carry `"paved"`, and `projects create` no longer writes `UserSettings/UnityCliPaved.json` or reports `pavedSettings`. ## CLI `1.0.0-beta.13` (2026-10-07) @@ -217,10 +228,10 @@ Aligned to the CLI's `1.0.0-beta.13` release. Everything below was documented ah ### Changed -- **`UNITY_PROJECT_PATH` for per-worktree agents**: `SKILL.md`'s one-Editor-per-worktree paragraph now tells agents to set `UNITY_PROJECT_PATH=` once for the session, and names the commands that don't read it (`recompile`, `close`, `mcp configure`). The environment-variable table lists every command that honors it, `unity mcp` included. `integration-advanced.md` adds the variable to the target resolver's order and shows `UNITY_PROJECT_PATH=... unity mcp`. -- **Auth broker and development apps**: `SKILL.md` and `auth-license-cloud.md` now say that a broker started for a development app is a separate broker with its own address and sign-in, that it refuses Unity-signed apps, and that Unity apps refuse it. +- **`UNITY_PROJECT_PATH` for per-worktree agents**: The main skill file's one-Editor-per-worktree paragraph now tells agents to set `UNITY_PROJECT_PATH=` once for the session, and names the commands that don't read it (`recompile`, `close`, `mcp configure`). The environment-variable table lists every command that honors it, `unity mcp` included. `integration-advanced.md` adds the variable to the target resolver's order and shows `UNITY_PROJECT_PATH=... unity mcp`. +- **Auth broker and development apps**: The main skill file and `auth-license-cloud.md` now say that a broker started for a development app is a separate broker with its own address and sign-in, that it refuses Unity-signed apps, and that Unity apps refuse it. - `build-run-test.md`'s Build section now says `unity build --format json` writes only the result document to stdout, with the progress frames and the streamed Editor log on stderr, and that the streamed log masks the credentials the CLI passes the Editor (the `-accessToken` value, the Android keystore passwords) in `build`, `run` and `test`. -- **One Editor per worktree, and report a failed call.** `SKILL.md` now tells an agent working in several worktrees to make each one with `unity vcs git worktree add --into `, open the project inside it with `unity open`, and target that Editor by its full project path. It never drives an Editor whose project isn't its own checkout. Once Safe Mode, a sandbox and a slow import are ruled out, it also reports a timeout or an Editor lifecycle failure to the user instead of silently working around it. It offers `unity bug --area pipeline-package` and asks first. +- **One Editor per worktree, and report a failed call.** The main skill file now tells an agent working in several worktrees to make each one with `unity vcs git worktree add --into `, open the project inside it with `unity open`, and target that Editor by its full project path. It never drives an Editor whose project isn't its own checkout. Once Safe Mode, a sandbox and a slow import are ruled out, it also reports a timeout or an Editor lifecycle failure to the user instead of silently working around it. It offers `unity bug --area pipeline-package` and asks first. - The bootstrap recipe's step 6 and the `unity status` reference now pass the project's full path to `unity status --until-ready --project-path`, and say how the flag matches. A path that exists matches that project only, so a sibling checkout such as `MyGame-lighting` never ends the wait for `MyGame`, and a bare name still matches any project path containing it. - `build-run-test.md`'s Accelerator example ran `unity build` with `--target StandaloneLinux64` and no `--output-path`. A desktop target with neither `--execute-method` nor `--profile` is a built-in player build, which requires an output path, so the example exited 2. It now passes `--output-path ./Build/MyGame.x86_64`. - **`open` never moves a project onto Unity 6.7 or later.** `projects-templates.md` documents that `unity open` and `unity projects open` exit `2` with `PROJECT_UPGRADE_REQUIRED` instead, and point at `unity projects upgrade`. @@ -235,7 +246,7 @@ Aligned to the CLI's `1.0.0-beta.12` release. Everything below was documented ah - **`--with-pipeline` on `unity projects create`**: `projects-templates.md` documents adding `com.unity.pipeline` during creation, its never-fails-the-create warnings, the `pipeline` result field and its error codes, and the agent-session hint; `integration-advanced.md` points at it from the Pipeline setup section. - **`--cloud-org` and `--no-sign` on `unity assets export`**: `projects-templates.md` documents that Unity 6.6+ exports are signed by default, how the signing organization resolves, the pre-spawn refusals (exit `3` / `4`), `ASSETS_EXPORT_SIGNING_FAILED`, and the new `signed` / `signingOrganizationId` result fields. -- **`--no-wait` and `--wait-timeout ` on `install`, `install-modules` and `projects require`**: documented in `editors-install.md` under "Waiting on another install", with exit code 9 and the `INSTALL_LOCK_BUSY` error code they fail with, including that exit 9 can follow a partial install. Exit 9 is also in `SKILL.md`'s exit code table. +- **`--no-wait` and `--wait-timeout ` on `install`, `install-modules` and `projects require`**: documented in `editors-install.md` under "Waiting on another install", with exit code 9 and the `INSTALL_LOCK_BUSY` error code they fail with, including that exit 9 can follow a partial install. Exit 9 is also in the main skill file's exit code table. - **Experimental FEX-Emu support on Linux arm64**: `editors-install.md` documents the `UNITY_EXPERIMENTAL_FEX_EMU=1` opt-in, the FEX-Emu and RootFS it requires, the `fex-emu` doctor row, and the `FEX_EMU_EXPERIMENTAL` notification. - **The `source` field on plugin runtime rows**: `integration-advanced.md`'s `unity plugin` section says what `machine`, `package-manager` and `managed` mean on `plugin install`/`upgrade`/`list` and `doctor` rows, and what a runtime row ending `dependency-unavailable` means. - `--coppa ` on `projects create`, `projects link cloud`, `projects link vcs`, and `vcs setup`, and the `coppa` field those commands report when they create a Unity Cloud project. Documented as a "COPPA declaration" note under `projects create` in `projects-templates.md`, with the flag added to the cloud-question, `link` and URL-form flag lists in the same file. @@ -264,10 +275,10 @@ Aligned to the CLI's `1.0.0-beta.11` release. Cut automatically by the release t ### Changed -- The install one-liners in SKILL.md no longer set `UNITY_CLI_CHANNEL=beta`. A bare `install.sh` / `install.ps1` run already installs the latest beta until a stable release exists, and the stable release after that. +- The install one-liners in the main skill file no longer set `UNITY_CLI_CHANNEL=beta`. A bare `install.sh` / `install.ps1` run already installs the latest beta until a stable release exists, and the stable release after that. - `projects-templates.md`'s `projects create` walkthrough said the interactive Unity Cloud question defaults to No. It defaults to Yes, matching what the rest of the same file already said. Corrected the one contradicting sentence. - `cloud-automation.md` said missing arguments or flag values could produce plain-text usage errors even under `--format json`. They fail with exit `2` and the ordinary JSON failure shape, `errors[].code` `INVALID_COMMAND_ARGS`. -- SKILL.md and `auth-license-cloud.md` no longer mention a feature-gated command family that isn't part of the public command surface. +- The main skill file and `auth-license-cloud.md` no longer mention a feature-gated command family that isn't part of the public command surface. ## CLI `1.0.0-beta.10` (2026-09-14) @@ -281,7 +292,7 @@ Aligned to the CLI's `1.0.0-beta.10` release. Much of this release's surface was - **`ProjectSettings/UnityCliConfig.json` and `unity config resolve [project]`** — the committed per-project build/test defaults layer (nine keys), the global `config set build.target …` layer beneath it, the precedence order, and the command that names which layer a value came from — in `config-hub.md`, with a pointer from Build. - **`unity command --result-only`** — the envelope-free JSON result mode, in `integration-advanced.md`, alongside the readable rendering of `recompile` / `recompile_status` / `test_status` / `run_tests` results. - **`unity license status`'s `floatingServer` / `machineId` fields** — in `auth-license-cloud.md`. -- **`UNITY_NO_AUTH_BROKER`, `UNITY_CLI_HOME`, `UNITY_NO_EDITOR_IDENTITY_SERVER`** — added to the environment-variables table in SKILL.md, with a short paragraph under Auth explaining the on-demand resident auth broker, the hardware-sealed token store, and the peer code-signature check. +- **`UNITY_NO_AUTH_BROKER`, `UNITY_CLI_HOME`, `UNITY_NO_EDITOR_IDENTITY_SERVER`** — added to the environment-variables table in the main skill file, with a short paragraph under Auth explaining the on-demand resident auth broker, the hardware-sealed token store, and the peer code-signature check. ### Changed @@ -289,10 +300,10 @@ Aligned to the CLI's `1.0.0-beta.10` release. Much of this release's surface was - `unity status` — the `starting` state (Editor still booting) noted alongside `unreachable`. - `unity self-update` — noted that an interrupted download resumes on the next run and that a Brotli-compressed artifact is preferred when published. - `unity install` — noted the bounded retry on transient download failures and that `--resume` also recovers an interrupted module download. -- Command index (SKILL.md) refreshed: `assets` added; `config` gains `resolve`; `build` gains `run`. +- Command index (main skill file) refreshed: `assets` added; `config` gains `resolve`; `build` gains `run`. - Refreshed the latest-version note to `1.0.0-beta.10`. - The `unity commands` note no longer links to a Hub-only doc; it was the skill’s only relative link outside its own tree, so the standalone copy published to Unity-Technologies/skills is now self-contained. -- **Template selection defaults to URP.** The bootstrap workflow in `SKILL.md` and the Templates section of `projects-templates.md` now name `com.unity.template.urp-blank` (Universal 3D) and `com.unity.template.universal-2d` (Universal 2D) as the defaults, mark `com.unity.template.3d` / `com.unity.template.2d` as the Built-in Render Pipeline templates (deprecated from 6.5, removed in 6.7), and note that `renderPipeline` is blank for `universal-2d` in `templates list` output. Every `projects create` / `projects new` / `templates info` example now uses `urp-blank`. Previously the skill's examples all used the Built-in `com.unity.template.3d` and said the URP id “varies by version”. +- **Template selection defaults to URP.** The bootstrap workflow in the main skill file and the Templates section of `projects-templates.md` now name `com.unity.template.urp-blank` (Universal 3D) and `com.unity.template.universal-2d` (Universal 2D) as the defaults, mark `com.unity.template.3d` / `com.unity.template.2d` as the Built-in Render Pipeline templates (deprecated from 6.5, removed in 6.7), and note that `renderPipeline` is blank for `universal-2d` in `templates list` output. Every `projects create` / `projects new` / `templates info` example now uses `urp-blank`. Previously the skill's examples all used the Built-in `com.unity.template.3d` and said the URP id “varies by version”. ## CLI `1.0.0-beta.9` (2026-09-08) @@ -306,13 +317,13 @@ Aligned to the CLI's `1.0.0-beta.9` release. Several pieces of this release's su - **`unity auth consumers`** / **`unity auth revoke `** — list and manage the applications using this machine's Unity sign-in through the auth broker. - **`unity config get|set|list|unset `** — the generic key-value interface over the existing `proxy` / `proxy.bypass` / `accelerator` / `update-check` settings, documented in `config-hub.md` alongside the purpose-built subcommands it shares storage with. - **`unity doctor`'s bundled third-party components section** — noted as a one-paragraph addition to the existing Doctor writeup; it's informational, not a check, so it didn't need more than that. -- The always-on `cli telemetry` usage ping, the sign-in token store's machine-sealing, and the self-installed-vs-Homebrew PATH-conflict warning — each is a background/security behavior with no new command surface, so each got a sentence in the relevant existing section (Analytics, SKILL.md's Notes, and Self-update respectively) rather than a section of its own. -- **"Sandboxed agent tooling can hide a running Editor"**, a new `integration-advanced.md` section under `status`, plus a matching callout in SKILL.md. Interim guidance: a restrictive sandbox around an agent's own shell commands can make `unity status`/`command`/`list` report no reachable Editor even when one is genuinely running, on Windows (a separate restricted account can't read the Editor's discovery file) and macOS (a network sandbox can block the loopback connection to it). Says plainly not to conclude the Editor is down from that alone, and never to suggest disabling the sandbox. Superseded once the CLI itself reports this case with its own distinct message — this section says so and should shrink to match at that point. +- The always-on `cli telemetry` usage ping, the sign-in token store's machine-sealing, and the self-installed-vs-Homebrew PATH-conflict warning — each is a background/security behavior with no new command surface, so each got a sentence in the relevant existing section (Analytics, the main skill file's Notes, and Self-update respectively) rather than a section of its own. +- **"Sandboxed agent tooling can hide a running Editor"**, a new `integration-advanced.md` section under `status`, plus a matching callout in the main skill file. Interim guidance: a restrictive sandbox around an agent's own shell commands can make `unity status`/`command`/`list` report no reachable Editor even when one is genuinely running, on Windows (a separate restricted account can't read the Editor's discovery file) and macOS (a network sandbox can block the loopback connection to it). Says plainly not to conclude the Editor is down from that alone, and never to suggest disabling the sandbox. Superseded once the CLI itself reports this case with its own distinct message — this section says so and should shrink to match at that point. ### Changed - **Extended the sandboxed-agent guidance into the scene/GameObject/asset editing workflow.** The "Sandboxed agent tooling can hide a running Editor" note (added above) was previously reachable only from the top-of-skill "Drive a running Editor" quickstart. The `unity status`-first Common workflow — the section that actually fires before any scene/GameObject/prefab/asset edit — had no mention of it, so a sandboxed agent hitting a false "no Editor" there had nothing telling it to doubt that result. Observed in the wild: a Codex-sandboxed agent took a `unity status` false negative at face value and improvised an undocumented batch-mode Editor workaround instead of saying so and falling back to a disclosed file edit, producing an asset that wasn't actually materialized until a later build ran. The workflow now rules out Safe Mode and sandbox interference side by side before permitting the file-edit fallback, and `integration-advanced.md`'s own guidance now names the improvised-workaround failure mode explicitly, not just silent file-editing. -- Command index (SKILL.md) and global-flags/environment tables refreshed for the above. +- Command index (main skill file) and global-flags/environment tables refreshed for the above. - `unity install`/`install-modules`'s child-modules flag examples now lead with `--child-modules`/`--no-child-modules` (matching `unity editors module add`), noting the old `--cm`/`--no-cm` shorts still work. - `unity modules list`'s column table now names the last column `Aliases` (renamed from `downloaderName` in `--format json`). - Refreshed the latest-version note to `1.0.0-beta.9`. diff --git a/skills/unity-cli/references/auth-license-cloud.md b/skills/unity-cli/references/auth-license-cloud.md index c8b48f0..095ff1d 100644 --- a/skills/unity-cli/references/auth-license-cloud.md +++ b/skills/unity-cli/references/auth-license-cloud.md @@ -1,6 +1,6 @@ # Auth, license & cloud — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. @@ -85,10 +85,10 @@ Three behaviors worth knowing before scripting these: #### Access tokens for scripts and other tools -`unity auth token` prints an access token from the CLI's sign-in, so a script, `curl` or another Unity tool can call Unity services as the signed-in user or service account without running its own sign-in. In the text formats stdout holds the token and nothing else (`--quiet` keeps it), so capture it directly. +`unity auth token` prints an access token from the CLI's sign-in, so a script, `curl` or another Unity tool can call Unity services as the signed-in user or service account without running its own sign-in. With `--format human` stdout holds the token and nothing else (`--quiet` keeps it), so capture it with that flag. Piped, the CLI defaults to `--format tsv`, which prints a `key`/`value` table of the same data as `--json` (`accessToken`, `expiresAt`, `authMode`), so a bare `$(unity auth token)` captures the table. ```bash -TOKEN=$(unity auth token) +TOKEN=$(unity auth token --format human) curl -H "Authorization: Bearer $TOKEN" ... # The token, its expiry (ISO 8601) and the auth mode, in the envelope @@ -245,7 +245,7 @@ unity cloud status --format json # Organizations unity cloud orgs --format json -unity cloud org current # print the active default org (named when signed in) +unity cloud org current # print the active default org (named when signed in); a script reads the id with --json unity cloud org set-default # set active default org unity cloud org clear-default # revert to "All Organizations" diff --git a/skills/unity-cli/references/build-run-test.md b/skills/unity-cli/references/build-run-test.md index d9f7392..0e304d7 100644 --- a/skills/unity-cli/references/build-run-test.md +++ b/skills/unity-cli/references/build-run-test.md @@ -1,11 +1,11 @@ # Run, test & build — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ### Contents - Run — batch/headless execution @@ -231,7 +231,7 @@ Outside GitHub Actions the format is inert — the `::`-prefixed lines are ordin #### Code coverage -`--coverage` drives Unity's [Code Coverage package](https://docs.unity3d.com/Packages/com.unity.testtools.codecoverage@latest) by passing `-enableCodeCoverage -coverageResultsPath ` (plus `-coverageOptions` when `--coverage-options` is given). `--coverage-output` defaults to `CodeCoverage` relative to the working directory. +`--coverage` drives Unity's [Code Coverage package](https://docs.unity3d.com/Packages/com.unity.testtools.codecoverage@/manual/index.html) by passing `-enableCodeCoverage -coverageResultsPath ` (plus `-coverageOptions` when `--coverage-options` is given). `--coverage-output` defaults to `CodeCoverage` relative to the working directory. Coverage **degrades gracefully**: if the project does not depend on `com.unity.testtools.codecoverage` (checked in `Packages/manifest.json`, then `Packages/packages-lock.json`), the CLI prints a warning naming the missing package, skips the coverage flags, and runs the tests normally. It never fails the test run for a missing coverage package — `-enableCodeCoverage` on a project without it silently produces nothing, which is the confusing outcome this replaces. `--coverage-output` / `--coverage-options` without `--coverage` is an error. @@ -255,7 +255,7 @@ Precedence with the other options: | Option | When sharding | |---|---| | `--mode` | Unchanged — selects the platform, and is orthogonal to the split. | -| `--filter` | Applied **by the CLI**, to narrow the inventory before the shard is taken from what survives. It has to be: the editor accepts a single `-testFilter`, and on a sharded run the slice's explicit name list already occupies it, so a `--filter` passed through would be dropped. Filtering here also makes the `tests` reported in `--format json` the ones that will actually run. It accepts the editor's own syntax — a semicolon-separated list of full names or regular expressions, each optionally negated with `!`. Note this ordering does **not** rebalance anything: assignment hashes each name independently, so filtering before or after the partition gives the same membership, and a filter can still leave a shard empty. | +| `--filter` | Applied **by the CLI**, to narrow the inventory before the shard is taken from what survives. It has to be: the editor accepts a single `-testFilter`, and on a sharded run the slice's explicit name list already occupies it, so a `--filter` passed through would be dropped. Filtering here also makes the `tests` reported in `--format json` the ones that will actually run. It is a semicolon-separated list of full test names or regular expressions, each optionally negated with `!`. A regular expression uses the Rust `regex` syntax, searched anywhere in the name and case-sensitive; it has no lookahead, lookbehind or backreferences. An entry that is not a valid expression and is not a test's exact name is refused (exit 6) with the reason, instead of matching nothing. Note this ordering does **not** rebalance anything: assignment hashes each name independently, so filtering before or after the partition gives the same membership, and a filter can still leave a shard empty. | | `--output`, `--junit-output`, `--coverage-output` | Every artifact path gains a `.shard-N-of-M` suffix before its extension, so shards sharing a working directory never overwrite each other and a merge step can collect them by glob. | Two cases end the run early rather than producing something misleading. A slice with **no tests assigned** (more shards than tests) skips the editor entirely and exits 0 with a warning — launching with an empty filter would run the whole suite, turning `M` shards into `M` full runs. A slice whose assembled filter is **too long for a single editor argument** fails and tells you to raise the shard count, which shortens every slice. A test whose name contains a semicolon cannot be expressed in the editor's filter syntax at all, so it fails rather than silently not running. @@ -380,7 +380,7 @@ It triggers an asset refresh plus script recompile, polls until compilation fini **Requires a running Editor with the Pipeline package.** That is what makes it fast (the Editor is already warm) and it means no build target has to be configured. There is no batch-mode fallback: with no reachable Editor it reports which Editors it found and what to do, and exits `12`, as `unity command` does. -**It cannot report errors that put the Editor into Safe Mode.** An Editor that *boots* with compile errors loads no Pipeline package, so there is nothing to ask and you get exit `12`. This command reports errors you introduce into an Editor that is **already running** — the normal edit loop, where a failed compile keeps the server alive. See the Safe Mode note in `SKILL.md` for the recovery loop. +**It cannot report errors that put the Editor into Safe Mode.** An Editor that *boots* with compile errors loads no Pipeline package, so there is nothing to ask and you get exit `12`. This command reports errors you introduce into an Editor that is **already running** — the normal edit loop, where a failed compile keeps the server alive. See the Safe Mode note in [integration-advanced.md](integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors) for the recovery loop. **Exit codes are the whole point for CI.** `0` compiled (or nothing needed recompiling), `6` compilation reported errors, `12` **no Editor could be reached, so whether the code compiles is unknown**. Treat `6` as terminal and `12` as worth retrying after fixing the environment — you never have to match on the message text. Several Editors running is a `6`: pick one with `--project-path`. @@ -513,7 +513,7 @@ unity build run /path/to/MyProject --build-path ./Build/other/MyGame.exe # a d ### Unity Accelerator — shared asset-import cache -The [Unity Accelerator](https://docs.unity3d.com/Manual/UnityAccelerator.html) is Unity's asset-import cache server: on import the Editor downloads a prebuilt artifact on a hash hit instead of re-importing. It pays off exactly where the CLI is used most — clean CI checkouts, ephemeral containers, branch switches, parallel agent worktrees. +The [Unity Accelerator](https://docs.unity3d.com//Documentation/Manual/UnityAccelerator.html) is Unity's asset-import cache server: on import the Editor downloads a prebuilt artifact on a hash hit instead of re-importing. It pays off exactly where the CLI is used most — clean CI checkouts, ephemeral containers, branch switches, parallel agent worktrees. **Persist the endpoint once** with `unity config accelerator ` (see [config-hub.md](config-hub.md)), and `run`, `test` and `build` inject it automatically. Per-invocation control: diff --git a/skills/unity-cli/references/cloud-automation.md b/skills/unity-cli/references/cloud-automation.md index 4189af2..7c17f47 100644 --- a/skills/unity-cli/references/cloud-automation.md +++ b/skills/unity-cli/references/cloud-automation.md @@ -405,7 +405,8 @@ table has one `phase` and `seconds` row per phase, with empty `seconds` for a `builds log` prints the whole log there is now. `--compact` asks for the short log. `--follow` keeps reading every 15 seconds and prints only new lines until -the build finishes. In NDJSON each line is a `{"type":"log","line":,"text":}` +the build finishes. In `--format tsv` the first row is `line` (`--no-header` +leaves it out), then one row per log line. In NDJSON each line is a `{"type":"log","line":,"text":}` frame and the result's `data` is `{"lines":,"complete":}`; JSON returns one envelope with `{"log":,"complete":}`. `complete` says whether the build had finished when the read ended. @@ -759,7 +760,8 @@ unity pipeline automation jobs logs "" --step "" --follow ``` Without `--step` it reads every step's log, printing each under a header naming -its step. `--step` reads one step. `--follow` reads that step's log as it's +its step (under `--format tsv`, one `line` header and a row per line, with +no step headers). `--step` reads one step. `--follow` reads that step's log as it's written, until it ends; it needs `--step` (exit `2` without it). In NDJSON each line is `{"type":"log","stepId":,"line":,"text":}`, numbered within its step, and the result's `data` is `{"lines":}`, so text isn't diff --git a/skills/unity-cli/references/collaboration.md b/skills/unity-cli/references/collaboration.md index cf91144..58d4a84 100644 --- a/skills/unity-cli/references/collaboration.md +++ b/skills/unity-cli/references/collaboration.md @@ -1,6 +1,8 @@ # Collaboration — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--proxy`, …) apply to every command below. **`--yes` is not a global flag** — it is bound per-command elsewhere in the CLI and no collaboration command accepts it, so passing it @@ -23,8 +25,6 @@ including the 3D pins and sketch overlays whose payloads are described under needs no package: it talks to the collaboration service directly, so it works with or without the Editor open. Annotations created either way are visible to both. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ### Contents - Shared behavior @@ -379,7 +379,7 @@ else inferred from the current project (see [Shared behavior](#shared-behavior)) | `reactions add` / `reactions remove` | ` ` | emoji is a single Unicode emoji, e.g. `👍` | | `thumbnail upload` | ` ` | image file; MIME inferred from extension (jpg/png/gif/webp) | | `thumbnail download` | `` | `-o, --output ` (default `./thumbnail`), `--width ` (an integer of at least 50); **no `--force`** — errors if the file exists ("Delete it first") | -| `read` | `` | `--timestamp ` (default now) — marks the thread read up to that time (per-user read receipt) | +| `read` | `` | `--timestamp ` (default now) — marks the thread read up to that time (per-user read receipt). Accepts `YYYY-MM-DD` or an RFC 3339 / ISO 8601 date-time (`2026-01-02T03:04:05Z`, `2026-01-02T03:04:05+02:00`); any other form exits 2 | | `subscribe` / `unsubscribe` | `` | per-thread notification subscription for the current user | ```bash diff --git a/skills/unity-cli/references/common-workflows.md b/skills/unity-cli/references/common-workflows.md new file mode 100644 index 0000000..741268b --- /dev/null +++ b/skills/unity-cli/references/common-workflows.md @@ -0,0 +1,462 @@ +# Common workflows — unity-cli reference + +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. Read this when the main page points here. + +### Contents + +- Common workflows +- Inspect and run cloud builds and Pipeline Automation jobs +- Edit a scene, GameObject, or asset — `unity status` first +- Use a catalog plugin for a task the built-in commands don't cover +- Error codes: cause and fix +- Bootstrap a new project from scratch +- Find and install a missing editor +- Open a project with the correct editor +- CI: activate a license, then build +- CI: batch-mode build +- CI: run tests and publish results +- Debug the CLI + +## Common workflows + +### Inspect and run cloud builds and Pipeline Automation jobs + +Read [cloud-automation.md](cloud-automation.md) for every command in +both groups, context/authentication, per-command filters and sorting, +output fields, pagination (including the leaves that refuse `--page`/`--limit` +rather than ignoring them), errors, and redaction. `pipeline cloud-build` works with Build Automation; +`pipeline automation` works with Pipeline Automation. Neither needs a running Editor +or the local Pipeline package. Use numeric organization IDs for service accounts. +The inventory commands are read-only. The commands that act on work start and +cancel builds, download artifacts, trigger pipelines, and follow or act on jobs; +`builds cancel`, `jobs terminate` and `jobs reject` ask first unless `--yes` is +given, and none of them change configuration. + +JSON/NDJSON return full API-shaped results under `data`, as Collab does; NDJSON +has one terminal result, without item frames. Preserve native fields and free-form +metadata, subject to the reference's bounded secret protections and public-API +redaction assumption. Table projections remain separate. Explicit local build +targets retain `_local`; missing targets aren't local. These conventions apply +to follow-up cloud-automation work too. + +### Edit a scene, GameObject, or asset — `unity status` first + +**Before editing any scene, GameObject, prefab, or asset, run `unity status` to detect a connected Editor.** If one is reachable, drive it with live commands instead of touching project files — the Editor applies changes to the *actual active scene* and keeps its in-memory state in sync. + +```bash +unity status # is an Editor connected? (look for state "ready") +unity command # discover the scene/GameObject commands THIS Editor exposes +# then drive it with the commands it lists — for example, if your Editor exposes them: +unity command gameobject create # act on the live, active scene +unity command scene save # persist the active scene +``` + +Commands are grouped and invoked as `unity command `. Their names are defined by the Editor, so run `unity command` to see the exact set — don't assume a name. + +> **Never hand-edit `.unity`, `.prefab`, or `.asset` YAML while a live Editor is reachable.** Raw-file edits are: +> - **error-prone** — fileIDs and GUIDs are assigned by hand and easy to get wrong; +> - **invisible** to the running Editor until a reimport, so the change silently fails to take effect; and +> - **prone to hitting the wrong file** — e.g. writing to `SampleScene.unity` while the Editor's active scene is actually `Demo2.unity`, producing valid-looking YAML that changes nothing the user sees. + +**Rule out two false negatives before concluding no Editor is reachable — both look identical to a genuinely closed Editor, and both are easy to get wrong under time pressure:** + +- **Safe Mode.** If an Editor *is* running for this project but `unity command` won't connect, it may be stuck in **Safe Mode** from a compile error rather than genuinely absent. Run `unity status`: if it reports Safe Mode (`STATUS_SAFE_MODE`, with the compile errors), editing the C# source to fix the compile errors *is* the correct move, not a fallback. See [integration-advanced.md → Recovering from Safe Mode](integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors). +- **A sandboxed agent shell.** If your own shell commands run inside a restrictive sandbox — the normal case for a coding agent like this one — the sandbox can hide a genuinely running Editor from `unity status` the same way. This applies to **every** scene/GameObject/prefab/asset task that reaches this preflight, not only ones that obviously need a live Editor: a task you could otherwise finish without any CLI involvement (e.g. generating an asset through ordinary Editor APIs) can still get funneled into "no Editor" here and derailed. Don't treat "no instances" as proof the Editor is down, and don't quietly improvise a third path — like driving a separate batch-mode Editor process to approximate what a live connection would have done — as a substitute for a disclosed file edit. Say plainly that your sandbox may be blocking your view of a real Editor, and ask whether one is actually open before falling back. Full detail: [integration-advanced.md → Sandboxed agent tooling can hide a running Editor](integration-advanced.md#sandboxed-agent-tooling-can-hide-a-running-editor). + +Only fall back to editing files directly once you've ruled out both of the above — and say so explicitly ("no live Editor detected, editing the file directly"). + +### Use a catalog plugin for a task the built-in commands don't cover + +The CLI ships a catalog of Unity plugins, installed on demand. **Before approximating a request +some other way, or saying the CLI can't do it, check whether a catalog plugin covers it.** A plugin +is Unity's own tool for its class of request, and using it is almost always the better answer. +`unity plugins` always lists the full catalog, installed or not, and the command search +(see "Find a command" on the main page) matches each plugin's name and description. +The steps below use the Unity AI Generators plugin (`ai`), which covers "generate a +texture/sprite/image/3D model for my project", as the example. Every catalog plugin works the same +way. + +1. **Find the plugin and check whether it's installed.** + ```bash + unity commands --grep "" --format json + unity plugins --format json + ``` + Find the entry whose `id` is the plugin's (`"ai"` here) and read its `installed` field + (`true` / `false`). + +2. **Not installed? Tell the user, then ask, never install silently.** Say plainly that Unity + ships an AI Generators plugin that covers this, and wait for a yes before running: + ```bash + unity plugin install ai + ``` + A refusal is a normal answer: fall back to whatever you would otherwise have done, and don't + ask again in the same conversation. + + `unity plugin install --local` writes the plugin's agent skill into the current project + (`/.claude/skills/...` and the other project-local client folders) instead of each AI + client's user-wide folder. It applies only to clients that already have Unity's skill in that + project, and Claude Desktop is skipped because its skills are user-wide only. `unity plugin + upgrade` never adds a copy: it updates the plugin's skill only where it is already installed, + user-wide or in the current project. Run it from that project to refresh its copy. + + `ai` is alpha, and during alpha it's gated to Unity staff on Unity's internal network. An + ordinary user's `unity plugin install ai` can fail with a **sign-in** message (Unity AI + Generators is limited to Unity staff, so sign in with a Unity staff account) or, once + past that, a plain **download failure** if the network it needs isn't reachable from where + you're running. Neither is a bug in the request: report the message and fall back, the same as + any other refusal. + + `unity plugin install` and `unity plugin upgrade` install the newest build the catalog offers + you, whatever its channel. When that build is a prerelease (`beta`, or `alpha`/`nightly` for + Unity staff), a warning says so before the download, in the envelope's `warnings` under + `--format json`. Pass it on to the user: a prerelease may change or break between versions. + + A plugin whose registry entry carries license terms shows them and waits for an answer + before anything downloads. `unity plugin install ` and `unity plugin upgrade ` ask on + a terminal. A run that cannot ask (`--non-interactive`, CI, piped input) fails with the + error code `PLUGIN_EULA_REQUIRED` and downloads nothing, and a "no" fails with + `PLUGIN_EULA_DECLINED`. Pass `--accept-eula` only after the user has read the terms and + agreed: it is their acceptance, never yours to give. An accepted version is remembered, so an + upgrade asks again only when the terms changed. `--dry-run` on either command prints the terms + and what would change, asks nothing, records nothing and downloads nothing. In + `--format json`, a row for a plugin with terms carries `eula` (`required`, `accepted` or + `declined`); a plugin with no terms has no such field. A `--dry-run` row also carries `dryRun: true` and an `eulaNotice` object (`version`, `url`, + `label`, `message`, `links`) with the terms to read. `--quiet` never hides the terms. A notice + the registry carries but the CLI cannot read refuses the install under `PLUGIN_EULA_REQUIRED`. + + A plugin can need other plugins. `unity plugin install ` installs the ones it requires + first, each with its own license step, and reports each as its own row. If one of them cannot + install, the plugin itself is not installed, and its row names the one that stopped it. + `unity plugin remove ` refuses a plugin another installed plugin requires: remove the + other one first. `unity plugin --json` lists each entry's `dependencies` (`id`, `optional`). + +3. **Pick up its agent skill in the same session.** A catalog plugin can ship its own agent skill + inside its payload (`ai` does), and installing the plugin does not, by itself, make that skill + visible to you; it has to be mirrored the same way this skill itself is: + ```bash + unity skill install # e.g. claude-code, first time this session + unity skill refresh # already mirrored earlier? re-render it fresh + ``` + `unity plugin install`'s own last line already tells you which one applies: it points at + `unity skill install` right after installing a copy that ships a skill, and at + `unity skill refresh` once one is already mirrored but the plugin's copy just changed. Confirm + where it landed with `unity skills --format json` (look for the row whose `skill` field + names the plugin's own skill, e.g. `unity-ai`, and read its `path`), then read that file before + driving the plugin's commands. Don't guess its command surface from this skill, which only + documents `unity` itself. + +**A command invoked before any of this** (`unity ai …` typed straight, or suggested from memory) +**fails with a clear, actionable message** naming the exact install command (`unity plugin install +ai`), in both human and machine (`--format json` / `--format ndjson`) output, under the stable +error code `TOOL_NOT_INSTALLED`. Read that message rather than guessing why the command did +nothing; the same shape (`TOOL_UNSUPPORTED_PLATFORM`, `TOOL_RUNTIME_NOT_INSTALLED`) covers the +two other reasons a catalog tool can't run. + +### Error codes: cause and fix + +| Code | Cause | Fix | +|---|---|---| +| `EDITOR_NOT_RUNNING` (exit 12) | A `--port`, `--pid` or `--instance` pin matches no running Editor | Run `unity status`, then fix the pin or open the Editor | +| `AMBIGUOUS_EDITOR` | No running project matches, and the error lists the candidates | Pin with `--project-path` from that list | +| `TOOL_NOT_INSTALLED` | The catalog plugin isn't installed | Run the install command the message names, eg `unity plugin install ai` | +| `TOOL_UNSUPPORTED_PLATFORM` | The tool doesn't run on this OS or CPU | Tell the user; don't retry | +| `TOOL_RUNTIME_NOT_INSTALLED` | The tool's runtime is missing | Follow the install step the message names | +| `PLUGIN_EULA_REQUIRED` | The plugin has license terms the run can't ask about, or can't read | Show the terms with `--dry-run`; pass `--accept-eula` only after the user agrees | +| `PLUGIN_EULA_DECLINED` | The user said no to the terms | Stop; never retry with `--accept-eula` | + +### Bootstrap a new project from scratch + +> For a **guided** end-to-end experience — concept questions, installing the Editor in the +> background while you plan, package selection, and monetization handoff — use the +> **`new-unity-project`** skill. This section is the raw CLI recipe that skill builds on; use it +> directly when you just want the commands. + +Take an idea to a running, version-controlled project using only the CLI. Decide the **target +platforms first** — they determine which Editor modules you install in step 2. You can add +modules later (`unity install-modules`), but a project can't build for a platform until that +platform's module is installed, so it's simplest to decide up front. + +```bash +# 1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md). +unity --version +unity auth status --format json # if signed out: unity auth login +unity license status --format json # if none active: unity license activate + +# 2. Pick and install an Editor with the modules your target platforms need. +# Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream +# release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as +# evaluation-only, never for a project you intend to ship. A deadline argues for LTS. +# (lts / latest aliases work almost everywhere a version is accepted — `templates` is the +# exception; see step 3.) +unity releases --stream lts --limit 5 --format json +unity install lts --module android --module ios --yes --accept-eula # add --module webgl, etc. +unity editors --installed --format json # confirm it landed + +# 3. List the real template ids this Editor offers — don't guess them — and pick by RENDER +# PIPELINE, not just by 2D/3D. Default to the URP templates: +# 3D → com.unity.template.urp-blank ("Universal 3D") +# 2D → com.unity.template.universal-2d ("Universal 2D": URP + the 2D packages) +# com.unity.template.3d and com.unity.template.2d are the Built-in Render Pipeline templates +# (displayName "… (Built-In Render Pipeline)"): deprecated from Unity 6.5, gone in 6.7. Use +# them only when the user explicitly asks for Built-in. Confirm the pick with the JSON +# `renderPipeline` field — it is blank for universal-2d on current releases, so match that +# one by id. +# `templates` resolves the lts / latest aliases through the release catalog, as `install` +# does, but the version you just installed (read it from `editors --installed`) is the one +# whose templates you want. +unity templates --editor-version <6000.x.y> --type core --format json + +# 4. Create the project. The first positional arg is the NAME; --output-dir sets the parent directory. +# All options supplied, so it won't prompt; add --non-interactive in CI. +# (To publish it to a remote in the same step, use the source-control forms below instead.) +unity projects create "MyGame" --output-dir ~/UnityProjects \ + --editor-version lts --template com.unity.template.urp-blank + +# 5. Add the Pipeline package BEFORE the first open. `unity command`, `unity status` and +# `unity command script eval` all need it, and templates don't include it. The Editor reads +# Packages/manifest.json when it loads the project, so installing first means the package +# is live from the first open. +unity pipeline install --project-path ~/UnityProjects/MyGame + +# 6. Open the project and wait until its Editor is ready to take commands. Pass the project's +# full path: a path that exists matches that project's Editor only, so an Editor open on a +# sibling checkout such as ~/UnityProjects/MyGame-lighting can't end the wait. +cd ~/UnityProjects/MyGame +unity open . +unity status --until-ready --project-path ~/UnityProjects/MyGame --format json +``` + +**Then build the scene in the live Editor, not in batch mode.** Create GameObjects, wire +components, and set asset references with `unity command script eval` (or the Editor's own `unity command` +tools) against the running Editor, and read the result back the same way. Each step can be +checked before the next one. A script run through `unity run -- -executeMethod` is the +**fallback** for when no Editor can stay open (CI, a headless build box). It can't see what it +produced: a reference saved as null, such as a `UIDocument` with no `PanelSettings`, still +reports success. If you do use batch mode, open the result in a live Editor and inspect it before +calling the work done. How to get an Editor to drive: +[integration-advanced.md → Getting an Editor to drive](integration-advanced.md#getting-an-editor-to-drive). + +**Source control — let the user choose.** The CLI publishes the new project to a fresh remote in +one step for any provider. **Always pass tokens on stdin** (`--git-token-from-stdin`) so secrets never +land in shell history or the process list. Pick based on the project — don't default to one: + +- **Git — GitHub / GitLab** (`--vcs github` / `--vcs gitlab`). Ubiquitous. For asset-heavy games + add **Git LFS** (`--git-lfs`) so large binaries don't bloat history. +- **Unity Version Control — UVCS** (`--vcs uvcs`). Unity's own VCS, built for large binary game + assets: it handles them natively (**no LFS needed**) and supports file locking — often the + better fit for art-heavy projects or larger teams. Auth uses your Unity sign-in; `--vcs-region` + selects the region. + +```bash +# Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you +# want to add packages/assets BEFORE the first commit (see the new-unity-project flow). +unity projects create "MyGame" --output-dir ~/UnityProjects \ + --editor-version lts --template com.unity.template.urp-blank \ + --vcs github --git-namespace my-org --git-repo my-game \ + --git-visibility private --git-default-branch main --git-token-from-stdin --git-lfs + +# Unity Version Control (UVCS) — handles binaries natively, so no LFS: +unity projects create "MyGame" --output-dir ~/UnityProjects \ + --editor-version lts --template com.unity.template.urp-blank \ + --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region +``` + +Feed the token to `--git-token-from-stdin` from a secret store, never a literal — e.g. +`… --git-token-from-stdin <<<"$GIT_TOKEN"` where `$GIT_TOKEN` comes from your CI/secret manager +(UVCS uses your Unity sign-in, so no token is needed). + +**Working with a UVCS workspace day to day: a few wrapped reads, everything else straight through +to `cm`.** The split is deliberate and worth teaching, because guessing wrong wastes a user's time: + +- **`unity vcs uvcs `** wraps the reads that **join `cm`'s data to your project** — + `locks` (who holds a lock, *and which locks cover files you have already changed*), + `changesets`, and `review`. Those joins are the thing `cm` cannot do for you, and they come in a + stable envelope, so prefer them whenever something *parses* the output. +- **`unity uvcs `** forwards the whole command line to `cm` verbatim, `--help` and + `--format` included. That is the supported route, not a workaround: `cm` owns and versions this + vocabulary, so wrapping it would pin a paraphrase that goes stale. Reach for it for **partial + checkout**, **shelves**, and **taking or releasing a lock**, and when a human reads the output. + +```bash +unity vcs uvcs locks # who holds what, and what collides with your changes +unity uvcs lock list # the raw listing, cm's own flags and output +unity uvcs partial update /Assets/Levels # cm's own vocabulary, unchanged +unity uvcs shelve -c "wip: lighting pass" +``` + +Every verb, flag and trap: [version-control.md](version-control.md). + +`unity cm ` is the same passthrough under cm's own name. Both need the `cm` client; install +it with `unity plugin install plastic` if a command says it is missing. + +**Beyond setup, the `vcs` group covers the whole day-2 loop** — `status`, `sync`, `switch`, +`merge-setup`, `conflicts` / `explain` / `resolve`, `diff`, `blame`, `summarize`, `affected`, +`hooks`, `doctor`, `providers` — and the Unity semantics are the reason to reach for it over raw +`git`. Full reference, with the flags and the traps: +[version-control.md](version-control.md). + +**Git tokens belong to the user's credential manager, not the CLI.** When no token flag or env var +is given, the CLI asks `git credential fill` and uses whatever the configured helper returns; it +stores nothing it is passed or told. Don't suggest the CLI can save a Git token, and don't reach for +a token flag when the user already has a working credential helper. If they want a different token +per organization, that is `git config --global credential.useHttpPath true` plus a multi-account +helper such as [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager). +The CLI passes the full repo URL so the helper can discriminate, but it never installs or +reconfigures a helper. `UNITY_GITHUB_TOKEN` / `UNITY_GITLAB_TOKEN` are one token per provider, so a +CI job spanning several orgs should pass `--git-token-from-stdin` per invocation instead. See +[references/projects-templates.md](projects-templates.md) for the full +source-control flag set. For a purely local Git repository instead, initialize git with a +Unity-appropriate ignore so the multi-GB `Library/` and other generated folders are never committed: + +```bash +cd ~/UnityProjects/MyGame +git init -b main +# Download (do not pipe to a shell) a maintained Unity .gitignore: +curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore + +# Asset-heavy game? Keep large binaries out of git history with Git LFS: +git lfs install +git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png" # adjust to your asset types +git add .gitattributes + +git add -A +git status # sanity-check: Library/ Temp/ obj/ Build/ must NOT be staged +git commit -m "Initial Unity project: MyGame" +git ls-files | grep -c '^Library/' # must print 0 +``` + +**What the CLI does and doesn't cover.** The CLI handles editor, project, and source control. +It has no top-level package command. To add UPM (Unity Package Manager) packages beyond the +template, use the **`unity-package-management`** skill: it runs the Pipeline `package add` +command through `unity command`, with a batch-mode C# script as the fallback. For monetization/backend, hand off to the dedicated skills: `implement-in-app-purchases` +(IAP), `levelplay-unity-integration` (ads), or `build-live-game` (accounts, cloud save, +economy, remote config, leaderboards). Once steps 5 and 6 above are done, work in the open +Editor. + +**Installed the Pipeline package while the Editor was already open?** The Editor picks up the +manifest change only when it next refreshes. Until then `unity status` reports +`STATUS_PIPELINE_LOAD_PENDING` (or `STATUS_NO_INSTANCES` on CLI releases before that code +existed). An Editor that is still opening or importing reports the same code until it finishes, +so wait for that first (`unity status --until-ready`). The CLI can't trigger the refresh itself: +if the Editor has finished opening, ask the user to switch to the Unity Editor window, then +re-run `unity status --until-ready`. Installing before the first open (step 5) avoids this +entirely. + +### Find and install a missing editor + +```bash +# 1. Check what's installed +unity editors --installed --format json + +# 2. Browse available LTS versions +unity releases --lts --limit 5 --format json + +# 3. Install +unity install 6000.0.47f1 --yes --accept-eula +``` + +### Open a project with the correct editor + +```bash +# 1. Check the project's required editor version +unity projects info /path/to/MyProject --format json +# Look at "editorVersion" in the result + +# 2. Confirm that editor is installed +unity editors --installed --format json + +# 3. Open (warns if the editor version is missing) +unity open /path/to/MyProject +``` + +### CI: activate a license, then build + +```bash +# 1. Activate a license without signing in; a service account cannot activate one. +# A perpetual or legacy serial: store it as the CI secret UNITY_LICENSE_SERIAL +# (the name `unity ci init` generates) and pass it to the step, e.g. in GitHub +# Actions `env: { UNITY_LICENSE_SERIAL: ${{ secrets.UNITY_LICENSE_SERIAL }} }`. +# A serial tied to a subscription needs a signed-in user, so for those seats use +# --floating, or the offline --generate-request / --file path (see "Headless / +# fleet license activation" in references/auth-license-cloud.md). +unity license activate # reads UNITY_LICENSE_SERIAL from the step env, so the serial stays off argv; or: unity license activate --floating + +# 2. Only if the job also runs cloud commands: export UNITY_SERVICE_ACCOUNT_ID and +# UNITY_SERVICE_ACCOUNT_SECRET from the CI secret store. Every later command reads +# them directly, with no `unity auth login` and nothing written to a credential +# store (which a headless runner may not have). + +# 3. Build +unity build /path/to/MyProject \ + --editor-version 6000.0.47f1 \ + --target StandaloneLinux64 \ + --execute-method Builder.PerformBuild \ + --allow-install +echo "Exit code: $?" + +# 4. Return the license when done (serial or assigned seats) +unity license return --yes +``` + +### CI: batch-mode build + +Prefer the dedicated `unity build` command (handles batch mode, logging, and CI flags): + +```bash +unity build /path/to/MyProject \ + --editor-version 6000.0.47f1 \ + --target StandaloneLinux64 \ + --execute-method Builder.PerformBuild \ + --allow-install +echo "Exit code: $?" +``` + +Or use `unity run` (batch mode is automatic — never pass `-batchmode`/`-quit`): + +```bash +unity run /path/to/MyProject \ + --editor-version 6000.0.47f1 \ + --allow-install \ + -- -executeMethod Builder.PerformBuild -logFile build.log +echo "Exit code: $?" +``` + +Writing scripts for a player build? Keep each `MonoBehaviour` alone in a `.cs` file named after its class. Several in one file can run fine in the Editor and Play Mode, yet the built player crashes at startup saying a scene file such as `level0` is corrupted. See [build-run-test.md](build-run-test.md#build). + +### CI: run tests and publish results + +```bash +unity test /path/to/MyProject \ + --editor-version 6000.0.47f1 \ + --mode EditMode \ + --report-format junit \ + --output ./test-results.xml \ + --allow-install \ + --timeout 600 +case $? in + 0) echo "All tests passed" ;; + 8) echo "Tests failed — report to developers, do not retry" ;; + *) echo "Run did not complete — infrastructure failure, safe to retry" ;; +esac +``` + +Exit `8` means the run finished and reported failing tests; any other non-zero code means it never produced a verdict. Under `--format json` the same split is `errors[0].code`: `TESTS_FAILED` versus `TEST_RUN_ERROR` / `TEST_TIMED_OUT`. + +`--report-format junit` makes `--output` a JUnit-schema report, which GitHub Actions and GitLab ingest as native test results with no converter step. It is written even when tests fail. Drop the flag for the NUnit3 default, or use `--report-format nunit,junit` to get both from one run. Add `--coverage` to collect coverage via the Unity Code Coverage package — it warns and carries on if the project doesn't have the package. See [build-run-test.md](build-run-test.md). + +**Iterating on a change, not gating a pipeline?** Run the cheapest test that can fail for the change. Try EditMode first. Use `--filter`, `--affected` or `--rerun-failed` while you work. Run the full suite on the final code, once per mode, before you hand the work back. Never re-run a suite on code that has not changed, unless the run exited `6` with no verdict. Keep the NUnit default for these runs, because `--affected` and `--rerun-failed` cannot read the JUnit-only report the CI example above writes. [build-run-test.md](build-run-test.md#run-the-cheapest-test-that-proves-the-change) has the rule, and which report each flag reads and writes. `unity test` refuses a project that is open in an Editor: don't close the user's Editor to make room, and don't start a test run while they are in Play Mode. + +### Debug the CLI + +```bash +# Check auth + installed editors + recent errors in one command +unity doctor --format json + +# Follow live logs during an install +unity logs --follow --level info +``` + +--- + diff --git a/skills/unity-cli/references/config-hub.md b/skills/unity-cli/references/config-hub.md index f950d9f..88a65d6 100644 --- a/skills/unity-cli/references/config-hub.md +++ b/skills/unity-cli/references/config-hub.md @@ -1,11 +1,11 @@ # Config & Hub — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ### Contents - Config — persisted CLI configuration @@ -78,13 +78,13 @@ Print where the CLI keeps its configuration: the settings file every `config` ke ```bash unity config path # Config file: ... / Config directory: ... -unity config path --format tsv # file... and directory... rows +unity config path --format tsv # keyvalue header, then file and directory rows unity config path --json # {file, directory} ``` #### config accelerator -View or change the [Unity Accelerator](https://docs.unity3d.com/Manual/UnityAccelerator.html) (asset-import cache server) endpoint. Once persisted, `unity run`, `unity test` and `unity build` inject it into the Editor automatically — see [build-run-test.md](build-run-test.md). +View or change the [Unity Accelerator](https://docs.unity3d.com//Documentation/Manual/UnityAccelerator.html) (asset-import cache server) endpoint. Once persisted, `unity run`, `unity test` and `unity build` inject it into the Editor automatically (see the run, test and build reference). ```bash # Show the resolved endpoint and its source diff --git a/skills/unity-cli/references/diagnostics-maintenance.md b/skills/unity-cli/references/diagnostics-maintenance.md index 1c780ad..2751e46 100644 --- a/skills/unity-cli/references/diagnostics-maintenance.md +++ b/skills/unity-cli/references/diagnostics-maintenance.md @@ -1,11 +1,11 @@ # Diagnostics & maintenance — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ### Contents - Logs — application logs @@ -133,6 +133,8 @@ unity ci init --dry-run unity ci init --project-path ./MyProject --overwrite ``` +Piped or redirected with no `--format`, `--dry-run` prints tsv: a `line` header, then one row per line of the workflow. To save the bare YAML to a file, pass `--format human` (`unity ci init --dry-run --format human > workflow.yml`). + The generated workflow installs the CLI, restores the editor download cache and the project's `Library/` folder, installs the editor version from `ProjectSettings/ProjectVersion.txt`, activates a license, runs `unity doctor --ci` as a preflight, runs the tests with a JUnit report, builds, uploads the report and the build, and returns the license seat in a teardown step that runs even when the job failed or was cancelled. What it derives from the project: the editor version (rejected unless it parses as a real Unity version, since it is interpolated into an install command on the runner), and the editor module the build target needs where that is unambiguous — `Android`, `iOS`, `tvOS`, `WebGL`, `WindowsStoreApps`, `VisionOS`, `Lumin`. The standalone desktop targets get no module, because each has il2cpp / mono / server variants and picking one from the target alone would be a guess; asking for `StandaloneOSX` or `StandaloneWindows64` warns that the install step needs a `--module` you choose. @@ -199,7 +201,7 @@ unity doctor --ci --skip-license Every check carries a machine-readable `code` (`LICENSE_NONE`, `EDITOR_NOT_INSTALLED`, `DISK_SPACE_LOW`, `NETWORK_UNREACHABLE`, …) plus a remediation `hint`. In `--format json` the per-check results stay in `data` even on failure, with one coded entry per failure in `errors`. Output is redacted and carries no tokens and no absolute user paths, so it is safe to paste into a public CI log. -`--ci` is always explicit — it is never inferred from `CI=true`, because a report that silently changed shape and exit code on a runner would be a trap. Note that the CLI already defaults to `--format tsv` whenever stdout is redirected, which in CI it usually is; that output leads with a `verdict` row. +`--ci` is always explicit — it is never inferred from `CI=true`, because a report that silently changed shape and exit code on a runner would be a trap. Note that the CLI already defaults to `--format tsv` whenever stdout is redirected, which in CI it usually is; that output is a `keyvalue` header, then one row per `--format json` field under its key path: `verdict`, then `checks.0.id`, `checks.0.status`, `checks.0.code`, `checks.0.message` and so on. A script that read `verdict...` or `check.` rows reads those keys now; `--no-header` drops the header row. --- @@ -273,7 +275,7 @@ unity version --format json unity --format json --version ``` -`unity version` reports the CLI version, release channel (`stable`, `beta`, …), commit, platform, architecture, and runtime — the same version fact `env` and `doctor` carry, as one parseable object. It honors `--format` (`human`, `json`, `tsv`, `ndjson`); human output is the bare version string. +`unity version` reports the CLI version, release channel (`stable`, `beta`, …), commit, platform, architecture, and runtime — the same version fact `env` and `doctor` carry, as one parseable object. It honors `--format` (`human`, `json`, `tsv`, `ndjson`); human output is the bare version string, and `tsv` is a `keyvalue` table with one row per field. A bare `unity --version` still prints only the version string, so scripts that parse it are unaffected. The `--version` flag switches to the structured object only when an explicit machine format is given *before* it (`unity --json --version`, `unity --format json --version`, or `UNITY_FORMAT=json unity --version`) — the flag terminates parsing, so a trailing format after `--version` is not seen. For order-independent machine output, prefer the `unity version` subcommand. @@ -306,13 +308,13 @@ unity cache key --target Android unity cache key ./MyProject ``` -Whenever stdout is not an interactive terminal — a pipe, a redirect, or any CI runner — the key is the only thing written to it, so it drops straight into a shell substitution or a workflow expression. (On an interactive colour terminal the CLI's usual one-line banner still prints above it, as it does for every command; `--quiet` suppresses that.) +Whenever stdout is not an interactive terminal — a pipe, a redirect, or any CI runner — the format defaults to `tsv`, a `keyvalue` table of the same members `--json` carries (the `key` row holds the hash). To get the bare key for a shell substitution or a workflow expression, pass `--format human`: it prints the key and nothing else. (On an interactive colour terminal the CLI's usual one-line banner still prints above it, as it does for every command; `--quiet` suppresses that.) Pass the project path if the workflow's working directory isn't the project: ```yaml - id: cachekey - run: echo "key=$(unity cache key MyProject --target Android)" >> "$GITHUB_OUTPUT" + run: echo "key=$(unity cache key MyProject --target Android --format human)" >> "$GITHUB_OUTPUT" - uses: actions/cache@v4 with: path: MyProject/Library @@ -603,6 +605,8 @@ unity completion powershell After `unity command` (and its aliases `cmd` and `request`), Tab offers the connected Editor's commands, then a group's commands, then the chosen command's parameters not yet typed. The shell asks the CLI at Tab time, for the Editor of the project in the working directory or `UNITY_PROJECT_PATH`, and waits at most 1 second. With no Editor, or a slow one, Tab offers nothing there. Nothing is cached. Scripts generated before this need regenerating to get it. +With `--json` or `--format ndjson`, the script comes inside the standard envelope: `data.shell` names the shell and `data.script` holds the script text. Every other format prints the script itself. + --- ### Bug — report a bug diff --git a/skills/unity-cli/references/docs-workflow.md b/skills/unity-cli/references/docs-workflow.md index 412c291..a63f443 100644 --- a/skills/unity-cli/references/docs-workflow.md +++ b/skills/unity-cli/references/docs-workflow.md @@ -1,6 +1,8 @@ # Docs workflow: find, cite and match Unity documentation -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, environment +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables and exit codes. The full flag list for `unity docs` and `unity docs toc` is in [diagnostics-maintenance.md](diagnostics-maintenance.md#docs--version-matched-unity-documentation); this file is the order an agent follows, with 2D examples. @@ -8,8 +10,6 @@ is the order an agent follows, with 2D examples. **Why use it:** the pages `unity docs` resolves match the Editor version of the project you are in. An API remembered from another Unity version is a common source of wrong code, 2D physics and Tilemap included. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ## Contents - The flow @@ -55,6 +55,10 @@ unity docs --url UnityEngine.SpriteRenderer # a qualified name matches exactly unity docs --url --manual "2D physics" # the manual is a search, so this returns a search address ``` +Run in a terminal, these print the bare address. Piped or captured, the CLI defaults to `--format tsv`, a +`key`/`value` table of the same data `--format json` carries (`url` is one row). To capture the address alone, +add `--format human`: `URL=$(unity docs --url Rigidbody2D --format human)`. + A bare class name or `Class.member` matches the page whose path ends with it (preferring `UnityEngine`, then `UnityEditor`). A name two pages tie on goes to search rather than a guess. The lookup never fails the command: offline, a qualified name is built directly when a version is known (a project or diff --git a/skills/unity-cli/references/editors-install.md b/skills/unity-cli/references/editors-install.md index 2c11ef7..ff42a66 100644 --- a/skills/unity-cli/references/editors-install.md +++ b/skills/unity-cli/references/editors-install.md @@ -1,6 +1,6 @@ # Editors, install & modules — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. @@ -94,7 +94,7 @@ unity editors path 6000.0.47f1 unity editors path 6000.0.47f1 --architecture arm64 --json ``` -Honors `--architecture` and `--format` / `--json`, and reports ambiguous matches so you can narrow by version or architecture. +Honors `--architecture` and `--format` / `--json`, and reports ambiguous matches so you can narrow by version or architecture. `--format ndjson` prints the same `data` as `--json`, as one result line. #### editors install-path @@ -172,7 +172,7 @@ unity editors prune --remove-missing unity editors prune --remove-missing --yes ``` -Unlike `--remove`, this never touches the filesystem — the folder is already gone, so there is nothing to delete, and confirming only updates the registry. It doesn't require the running-editor check to succeed, since nothing can be running out of a folder that no longer exists. The two flags are independent and neither implies the other; `--format json`/`ndjson` carry the missing-path rows under `data.missing`. +Unlike `--remove`, this never touches the filesystem — the folder is already gone, so there is nothing to delete, and confirming only updates the registry. It doesn't require the running-editor check to succeed, since nothing can be running out of a folder that no longer exists. The two flags are independent and neither implies the other; `--format json`/`ndjson` carry the missing-path rows under `data.missing`. Under `--format tsv` (the default when piped) a run that finds missing editors prints its json `data` as one `keyvalue` record: a `key value` header, then one row per json key path, such as `editors.0.version` or `missing.0.path`. A removal that was never attempted prints no `removed` row. A run with nothing missing prints the plain `editors` table. #### editors verify diff --git a/skills/unity-cli/references/exit-codes.md b/skills/unity-cli/references/exit-codes.md new file mode 100644 index 0000000..a267596 --- /dev/null +++ b/skills/unity-cli/references/exit-codes.md @@ -0,0 +1,53 @@ +# Exit codes — unity-cli reference + +Part of the **`unity-cli`** skill. Read this when the main page points here. + +## Exit codes + +Branch on the exit code, then on `errors[0].code` in the json or ndjson envelope. **Retry** says +whether running the same command again, unchanged, can succeed. A command that starts work +(`pipeline cloud-build builds start`, `pipeline automation pipelines trigger`) would start it +again, so once its request may have been sent, never re-run it: follow what it started instead. +`unity commands --json` carries this table as `exitCodes`, with the error codes that pick each +exit. `6` covers every failure no more specific code names, including a `unity command` result +that reports `success: false` or a failed `status`; a missing project, an Editor that +isn't running, an unknown Editor command and a timeout have their own codes (`11` to `14`). A +request that gets no answer (offline, a failed DNS lookup, a refused connection, a dead proxy) +exits `7`; a timeout is `14`, and a reset connection or an unreadable body is +`6`. A TLS or certificate failure is `ERR_NETWORK` too, so retrying a `7` does not always help, +and a request already sent may have reached the server: retry only a command that is safe to +repeat. + + +| Code | Name | Retry | Meaning | +|---|---|---|---| +| 0 | `SUCCESS` | no | The command succeeded. | +| 1 | `ERROR` | no | An unexpected or unsupported state. | +| 2 | `BAD_ARGS` | no | A usage error: an unknown command or option, or a bad value. | +| 3 | `AUTH_ERROR` | no | Not signed in, the session expired, or permission was denied. | +| 4 | `NEEDS_CONFIG` | no | Setup is missing: a required tool, setting or link. | +| 6 | `COMMAND_FAILED` | no | The command failed, or its result reported a failure, and no more specific code names why. | +| 7 | `NETWORK_UNREACHABLE` | yes | A required service could not be reached. | +| 8 | `TESTS_FAILED` | no | The tests ran, and some failed. | +| 9 | `INSTALL_LOCKED` | yes | Another process holds the install lock. | +| 10 | `READY_TIMEOUT` | yes | The Editor did not become ready in time. | +| 11 | `NOT_FOUND` | no | What the command names does not exist: a project, a release, a module. | +| 12 | `EDITOR_UNREACHABLE` | yes | No running Editor answered: none is running, none matches, or it refused the connection. | +| 13 | `REMOTE_COMMAND_FAILED` | no | The Editor answered, but it has no command by that name. | +| 14 | `TIMEOUT` | yes | An operation ran out of time: an Editor request, an HTTP request, a batch run. | +| 15 | `RUN_FAILED` | no | A build or job the command waited on finished unsuccessfully. | +| 16 | `JOB_SUSPENDED` | yes | A job the command watched waits on a person to resume or approve it. | +| 17 | `UNAVAILABLE` | yes | The target answered but can't do this now: it is busy. | +| 18 | `AWAITING_INPUT` | yes | The target answered but waits on a person first: a dialog to dismiss, a prompt to answer. | +| 130 | `INTERRUPTED` | yes | Interrupted by Ctrl-C (SIGINT). | +| 141 | `OUTPUT_CLOSED` | no | The reader of stdout closed the pipe. | +| 143 | `TERMINATED` | yes | Terminated by SIGTERM. | + + +`8` is `unity test` only: the tests ran and some failed. A run that never completed exits `6` +and a timed-out one `14`, so CI can retry those and never blindly re-run a failing test. `9`: +earlier items of the same install may already be in place (`data.completedUids`). `10` is +`unity open --until-ready` only; the Editor is still running. `17` is an Editor that is loading, +compiling, reloading or in Safe Mode: retry later. `18` is a modal dialog blocking it: list and +answer it with `unity command editor dialog`, then retry. + diff --git a/skills/unity-cli/references/global-flags-env.md b/skills/unity-cli/references/global-flags-env.md new file mode 100644 index 0000000..10f5aae --- /dev/null +++ b/skills/unity-cli/references/global-flags-env.md @@ -0,0 +1,89 @@ +# Global flags and environment variables — unity-cli reference + +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. Read this when the main page points here. + +### Contents + +- Global flags +- Environment variables + +## Global flags + +These work on every command: + +| Flag | Description | +|---|---| +| `--format ` | Output format: `human` (default), `json`, `tsv`, `ndjson`, `github`. Also via `UNITY_FORMAT` env var. | +| `--json` | Global shorthand for `--format json`, accepted on every command (e.g. `unity status --json`, `unity doctor --json`). Passing it with a different `--format` (e.g. `--json --format tsv`) is a usage error (exit 2); `--json` overrides `UNITY_FORMAT`. | +| `--no-banner` | Suppress the branded header — use in scripts | +| `--no-header` | Leave the header row out of `tsv` tables. The header row is the column names, which are the same keys the `json` rows use (`version`, `upgradeTo`, ...). An empty `tsv` result is the header row alone, so with `--no-header` it is no output at all. | +| `--no-pager` | Turn off paging. Governs both pagers: the external one over the long listings (`unity command`, `releases`, `editors`, `changelog`, `logs`) and the interactive one in `unity projects`. Also via `UNITY_NO_PAGER` (presence-based — any value, including `0`, disables it). | +| `--non-interactive` | Disable all interactive prompts — use in CI | +| `--quiet` | Hide notices, warnings and progress in human and tsv output. Errors, the exit code and the `tsv` rows stay, so a script that pipes with `--quiet` still gets its data. json output never changes, and ndjson output does not either, except that a few listings still drop their rows (see [Notes](notes.md)). | +| `--verbose` | Print full error details (stack trace + cause chain) on failure. Also via `UNITY_VERBOSE`. | +| `--proxy ` | HTTP/HTTPS/SOCKS/PAC proxy URL for this invocation. Also via `UNITY_PROXY`. Takes precedence over standard `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` env vars and the persisted `proxy.json` setting. | +| `--proxy-disable` | Disable proxy for this invocation, ignoring all sources (env vars, persisted config, system settings). | +| `--log-proxy` | Log one redacted entry per outbound request to `proxy-request.json` — for reproducing proxy issues. Also via `UNITY_LOG_PROXY=1` or the `proxyRequestLogging` setting. | +| `--no-log-proxy` | Opt a single invocation out of proxy request logging when it's enabled globally. | +| `--color ` | Control colored output for this invocation, overriding `NO_COLOR`/`FORCE_COLOR` and TTY auto-detection. Governs every ANSI-emitting surface (help, tables, spinners, errors), not just `human` output. | +| `--no-color` | Shorthand for `--color never`. Whichever of `--color`/`--no-color` appears last on the line wins. | + +**Always use `--format json` when you need to parse output programmatically.** If you read `tsv` instead, select columns by header name, not position: a command's `tsv` columns keep their names and order, and a flag that adds information (such as `editors --long`) only appends columns at the end. Failures in `tsv` go to stderr, so stdout holds only data. A single-record answer (`unity env`, `unity config proxy`, `unity doctor`, `unity editors default`, `unity install-path` and the like) is a `keyvalue` table instead, one row per field keyed by its `json` path (`values.editor`, `tools.0.id`), so `unity install-path` piped prints the path on its `path` row, not bare; `unity cache key` is one too, so a script that needs the bare key passes `--format human`. + +**Every listing has one JSON shape.** Read the rows from `.data.items[]`. Beside them, `.data.total` is the full count (`null` when the service doesn't report one), `.data.nextPage` (pass it to the command's `--page`, `--skip` or `--offset`, whichever it takes: `--offset` for `collab annotations count --grouped`) or `.data.nextCursor` (pass it to `--next` or `--cursor`) is `null` on the last page, and `.data.partial` is `true` when the listing stopped before it finished. Under `--format ndjson` the rows stream one per line and the last line, `type: "result"`, carries `count` and the same paging fields. Some listings still carry their older keys too (`instances`, `entries`, `results`); prefer `items`. + +`--accelerator ` and `--no-accelerator` are **not** root globals — they are accepted only on `run`, `test` and `build`, and only after the command name. See [build-run-test.md](build-run-test.md). + +**`unity projects` is the only command that pages IN-PROCESS.** It shows 10 projects per screen and waits for a keypress between screens, and only when stdout is a terminal. Paging is off for redirected stdout, under every machine format (`json`, `ndjson`, `tsv`, `github`), and under `--all`, `--watch`, or `--no-pager` / `UNITY_NO_PAGER`. + +**The long listings page through an external pager, like `git log`.** `unity command` (the bare listing), `unity releases`, `unity editors`, `unity changelog`, and `unity logs` pipe human output through `less -RFX` on a terminal; `-F` quits by itself when the output fits one screen. `$UNITY_PAGER` then `$PAGER` override the choice and run through a shell, so `PAGER="less -S"` works; a blank value is ignored rather than treated as an opt-out. Like `projects`'s pager this one is **`human`-only**, and it never engages for redirected stdout, any machine format (`json`, `tsv`, `ndjson`, `github`), `--quiet`, `TERM=dumb`, the streaming modes (`editors --watch`, `logs --follow`), a named `unity command `, or inside `unity shell`. A broken pager costs the paging, not the output: a `$PAGER` naming something that is not there is resolved before anything spawns (a warning on stderr names it, and on Windows a bare name also finds `.com` programs such as `more`), and one that spawns and then dies has its output reprinted to the terminal, decided from the pager's exit status (a clean exit is a normal `q` and discards; a failure status reprints). A pager that exits 0 without reading (`PAGER=true`) is indistinguishable from `q`, so its output is lost. One that merely *waits* is not broken; the CLI waits with it. + +A branded Unity header (logo, wordmark, CLI version) renders on the landing surfaces — bare `unity`, `unity --help` / `-h`, and `unity help`. It's shown only on a TTY, prints at most once, and degrades to compact, uncolored text on narrow terminals, without Unicode, or under `NO_COLOR`. Piped output is unaffected. Use `--no-banner` to suppress it in scripts. Bare `unity` prints usage and exits 0. The header's accent is brand blue (`#0F70CB` on a light background, `#6EB8FF` on a dark one), in 24-bit color where the terminal supports it and the nearest 256-color entry otherwise. The background comes from `UNITY_THEME`, then `COLORFGBG`, then, on the header only, a terminal query. The query runs only where the terminal can answer (Windows Terminal, VS Code, or a Unix terminal with `TERM` set), and waits at most 100 ms; no reply means dark. Git Bash is never queried. Subcommand help and the command listing never query the terminal: they use `UNITY_THEME`, then `COLORFGBG`, then dark. Where the header cannot query, set `UNITY_THEME=light` or `UNITY_THEME=dark` to choose the background yourself. + +## Environment variables + +All CLI env vars use the `UNITY_` prefix. A CLI flag always overrides the corresponding env var. + +| Variable | Mirrors flag | Description | +|---|---|---| +| `UNITY_FORMAT` | `--format` | Output format (`human`, `json`, `tsv`, `ndjson`, `github`). `HUB_FORMAT` is a deprecated alias. | +| `UNITY_EDITOR_VERSION` | `--editor-version` | Editor version (e.g. `2023.3.0f1`, `latest`, `lts`). Read by every command that takes `--editor-version`, `build` included; `build` prints a notice when the variable chose its Editor. Not read by the `pipeline cloud-build` filters. | +| `UNITY_ARCHITECTURE` | `--architecture` | Chip architecture (`x86_64`, `arm64`). `build` names it in the same notice. | +| `UNITY_PROJECT_PATH` | `--project-path` | Project path when none is passed. Read by every command that takes `--project-path` (the Editor-connecting commands, `recompile`, `pipeline`, `collaboration`, `assets`, `auth default`, `templates create`/`pack`, `projects link`, `projects unlink vcs` and the `vcs` commands that act on a project) and by `open`. A path argument or `--project-path` wins over it. Not read by `close` (and `projects close`), `projects unlink cloud`, `mcp configure` or `ci init`. | +| `UNITY_QUIET` | `--quiet` | Suppress non-essential output. | +| `UNITY_VERBOSE` | `--verbose` | Show full error details on failure. | +| `UNITY_NON_INTERACTIVE` | `--non-interactive` | Disable interactive prompts. | +| `UNITY_NO_BANNER` | `--no-banner` | Suppress the branded banner. | +| `UNITY_THEME` | — | `light` or `dark` (any case): the terminal background the branded header assumes, so its accent reads on it. Wins over `COLORFGBG` and the header's terminal query, and is the fallback where that query cannot run (Git Bash, a legacy console, or `TERM` unset). Help and the command listing rely on it and `COLORFGBG`, never on a query. Any other value is ignored. | +| `UNITY_NO_PAGER` | `--no-pager` | Turn off paging — both the external pager over the long listings and `unity projects`'s interactive one. Presence-based: any value counts, including `0`. | +| `UNITY_PAGER` | — | The pager to use for the long listings, overriding `$PAGER` and the `less -RFX` default. Runs through a shell, so flags work (`less -S`). A blank value is ignored, not an opt-out. | +| `PAGER` | — | Same as `UNITY_PAGER`, consulted only when that is unset or blank. | +| `LESS` / `LV` / `LESSCHARSET` / `MORE` | — | Passed to the pager only when you have not set them, defaulting to `FRX`, `-c`, `utf-8`, and `FRX`. `LESSCHARSET` keeps multi-byte glyphs readable where the locale does not declare UTF-8; `MORE` exists because `more` on macOS/BSD is `less` under another name and reads `$MORE`, so without it `PAGER=more` waits for a keypress even for one line. | +| `UNITY_RUN_TIMEOUT` | `--timeout` | Timeout for `unity run` in seconds. | +| `UNITY_TEST_TIMEOUT` | `--timeout` | Timeout for `unity test` in seconds. | +| `UNITY_CLOUD_ORG` | `--cloud-org` | Active Unity Cloud organization id or name for a single call. | +| `UNITY_CLOUD_PROJECT` | `--cloud-project` | Cloud project ID or name (a service account needs the ID); used by Cloud Build inventory. Pipeline Automation inventory is organization-scoped. | +| `UNITY_NO_CLOUD` | `--no-cloud` | Decline the Unity Cloud link on `projects create` and `projects upgrade`. Presence-based: any value counts, including `0`. On `projects create` and `projects upgrade`, an explicit `--cloud`, `--cloud-project`, `--cloud-org` or `--coppa` wins over it. `projects create --vcs uvcs` is refused with it set unless one of those flags overrides it. | +| `UNITY_SERVICE_ACCOUNT_ID` | — | Service account client ID for non-interactive (CI) auth. | +| `UNITY_SERVICE_ACCOUNT_SECRET` | — | Service account client secret for non-interactive (CI) auth. | +| `UNITY_PROXY` | `--proxy` | HTTP/HTTPS/SOCKS/PAC proxy URL. Takes precedence over `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` and the persisted `proxy.json` setting. | +| `UNITY_NO_UPDATE_CHECK` | — | Disable the background "update available" check (see `unity config update-check`). | +| `UNITY_CLI_ROLLBACK_KEEP` | — | How many previous CLI versions `unity self-update` keeps for `--rollback`, from 1 to 10 (default 3). | +| `UNITY_NO_AGENT_HINTS` | — | Stop suggesting Unity's agent plugin or skill when an AI agent runs `unity`: Claude Code's install prompt, the `unity setup codex` / `grok` / `antigravity` / `copilot` tip, and the `unity skill install` tip (an `AGENT_PLUGIN_AVAILABLE` entry in the envelope's `notifications` under `--format json`), plus the once-a-day `unity skill sync` notice when installed Unity skills are older than the CLI's pin (`AGENT_SKILLS_OUTDATED`). Presence-based: any value counts. A tip asks you to get the user's approval before running its command. | +| `UNITY_NO_CRASH_REPORT` | — | Disable anonymous crash/error reporting (Sentry) entirely. The Hub's "Send crash reports" setting, when off, also disables it. | +| `UNITY_NO_CLI_INVOKED_TELEMETRY` | — | Stop the anonymous once-per-run `cli telemetry` usage ping. Presence-based: any value counts. | +| `DO_NOT_TRACK` | — | The cross-tool [Console Do Not Track](https://consoledonottrack.com) setting. Any value but empty, `0` or `false` stops the `cli telemetry` usage ping and the upload of opt-in usage data. Licensing records are not affected. | +| `UGS_CLI_TELEMETRY_DISABLED` | — | The UGS CLI's telemetry switch, honored exactly like `DO_NOT_TRACK`. Any value but empty, `0` or `false` stops the `cli telemetry` usage ping and the upload of opt-in usage data. Licensing records are not affected. | +| `UNITY_LOG_PROXY` | `--log-proxy` | Log one redacted entry per outbound request to `proxy-request.json`. Truthy values: `1`, `true`. | +| `UNITY_ACCELERATOR` | `--accelerator` | Unity Accelerator endpoint (`host:port`). Outranks the persisted `accelerator.json`; `--accelerator` outranks it. | +| `UNITY_NO_ELEVATE` | `--no-elevate` | Windows: skip the elevated (UAC) install helper for `install` / `install-modules`, so the install service runs unelevated. The Editor's NSIS installer still asks for elevation on demand if Windows requires it for your account — an administrator token always does; a standard user never does. | +| `UNITY_INSTALL_RETRIES` | `--retries` (`install-modules` only) | Number of times `install` and `install-modules` retry an editor or module download whose transfer or validation fails. `0` disables retries; `unity install` has no `--retries` flag, so set the variable there. | +| `UNITY_NO_AUTH_BROKER` | — | Skip the resident auth broker and read credentials directly from the OS keyring. By default every command that needs a token goes through a broker that starts on demand and exits after two idle minutes (see [auth-license-cloud.md](auth-license-cloud.md)). | +| `UNITY_CLI_HOME` | — | Install root for the install script and `unity self-install`, on every platform including Windows: the binary lands in `/bin` instead of the default location. | +| `UNITY_NO_EDITOR_IDENTITY_SERVER` | — | Disable the background identity helper that `unity open` starts to answer the Editor’s sign-in lookups when no Hub is running (see [projects-templates.md](projects-templates.md)). Presence-based. | +| `UNITY_EXPERIMENTAL_FEX_EMU` | none | Linux arm64 only, experimental and unsupported: run the x86_64 Editor under FEX-Emu. `1`, `true` or `yes` turns it on, and it takes effect only when FEX-Emu and an x86_64 RootFS are installed (`unity doctor` checks). C# script compilation is known to crash under FEX-Emu. See [editors-install.md](editors-install.md). | + +**CI service account auth:** Set both `UNITY_SERVICE_ACCOUNT_ID` and `UNITY_SERVICE_ACCOUNT_SECRET` to skip the browser OAuth flow — this keeps the secret out of the process argument list and shell history. These map to the `--client-id` / `--secret-from-stdin` inputs of `unity auth login`, but reading the credentials from the environment isn't a full login: it doesn't run the interactive flow or persist credentials to the keyring. + diff --git a/skills/unity-cli/references/integration-advanced.md b/skills/unity-cli/references/integration-advanced.md index ee4cdb5..8f01276 100644 --- a/skills/unity-cli/references/integration-advanced.md +++ b/skills/unity-cli/references/integration-advanced.md @@ -1,11 +1,11 @@ # Integration & advanced — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ## Contents - Targeting one of several running Editors @@ -115,7 +115,7 @@ unity mcp --tool-groups `unity mcp` lists one tool per Editor command, and `unity mcp --tool-groups` lists one tool per Editor command group instead. `unity mcp configure` writes `--tool-groups` into the entries it creates, so a client set up with it gets groups. An entry an older `configure` wrote runs plain `unity mcp` and keeps its per-command tools, so a client allow list that names them keeps working. Run `configure` again to switch that entry to groups; it warns that the tool names change, and an allow list then has to name the group tools. A group tool is named by its group (`scene`, `gameobject`, `settings_player`, ...) with every space and dot written as `_`. A group tool takes the command to run in `command` and that command's parameters in `args`: call the `scene` tool with `{"command": "save", "args": {"path": "Assets/Main.unity"}}`. Its description lists every command with its parameters, required ones first, a `?` marking an optional one, an object's own keys in braces and a short note in brackets on what a value is, for example `set_field(target: string, field: string (SerializedProperty path), value: string, component?: string)`. A long group keeps every command's parameters and leaves out the one-line summaries it has no room for. Grouping keeps a full Editor catalog, about 180 commands, to about 40 tools, under the tool limits of VS Code (128), Windsurf (100) and Cursor (40), and in a much smaller listing. The four job tools stay their own tools, and so do the commands that run code (`script_eval`, `exec`), so approving a group never approves running C#. A group too large for one description is split over several tools (`scene`, `scene_2`). `job_start` takes a command by its full name (`test run`). -`--tools ` keeps only the commands whose names match the comma-separated list, and `--exclude-tools ` then hides the ones that match its list. Both apply to commands, so with groups a hidden command leaves its group tool, and a group with none left is not listed. In both, `*` matches any run of characters, and names are case-sensitive. Each command's own tool, without `--tool-groups`, is named by its full command name with every space and dot written as `_` (`script_eval`, `test_run`, `settings_player_get`), so every tool has its own name in the characters all clients accept. An older package that lists only flat names keeps them as its tool names (`eval`, `run_tests`), so call the name `tools/list` shows. A pattern matches a command under every spelling it answers to: the tool name, the full name's dotted form (`script.eval`), and the old flat name an older package uses (`eval`, `run_tests`). Excluding `script_eval`, `script.eval` or `eval` therefore hides the same tool, and a call under any of them is refused. A smaller tool list saves the client's context. The filter also applies to the tools a later `tools/list_changed` notification announces. Calling a hidden tool fails with an error that names the tools the session exposes, and the call never reaches the Editor. An empty entry, or a pattern with a character other than letters, digits, `_`, `-`, `.`, and `*`, is a usage error. +`--tools ` keeps only the commands whose names match the comma-separated list, and `--exclude-tools ` then hides the ones that match its list. Both apply to commands, so with groups a hidden command leaves its group tool, and a group with none left is not listed. With groups, an entry also matches a group by its dotted name (`editor.playmode`) or its tool name (`editor_playmode`) and covers every command in it, so `--tools editor_playmode` lists that group tool whole. In both, `*` matches any run of characters, and names are case-sensitive. Each command's own tool, without `--tool-groups`, is named by its full command name with every space and dot written as `_` (`script_eval`, `test_run`, `settings_player_get`), so every tool has its own name in the characters all clients accept. An older package that lists only flat names keeps them as its tool names (`eval`, `run_tests`), so call the name `tools/list` shows. A pattern matches a command under every spelling it answers to: the tool name, the full name's dotted form (`script.eval`), and the old flat name an older package uses (`eval`, `run_tests`). Excluding `script_eval`, `script.eval` or `eval` therefore hides the same tool, and a call under any of them is refused. A smaller tool list saves the client's context. The filter also applies to the tools a later `tools/list_changed` notification announces. Calling a hidden tool fails with an error that names the tools the session exposes, and the call never reaches the Editor. An empty entry, or a pattern with a character other than letters, digits, `_`, `-`, `.`, and `*`, is a usage error. `--exclude-tool-groups ` hides whole command groups, every command in them. An entry matches a group by its dotted name (`editor.playmode`) or its tool name (`editor_playmode`), and `*` matches any characters. It applies without `--tool-groups` too. A call to a command in a hidden group, direct, through its group or through `job_start`, is refused before it reaches the Editor. A pattern with a character other than letters, digits, `_`, `-`, `.`, and `*` is a usage error. An `--exclude-tools` list written for one tool per command keeps working with groups. @@ -127,7 +127,7 @@ unity mcp --tool-groups With an Editor connected, the list also holds `job_start`, `job_status`, `job_wait` and `job_cancel`, with no option needed, so an agent in an MCP session can run a long Editor job instead of holding a tool call open. `job_start` takes `command` (one of the session's Editor tools, except `eval` and the other commands that run code, which keep their own tools) and its `arguments`, starts it the way `unity command --detach` does, and returns `{ jobId, state }`. The other three take that `job_id` and answer like `unity job status --format json`. `job_wait` waits at most `timeout` seconds (30 by default, 45 at most); if the job is still running then, it returns its state with `stillRunning: true` rather than an error, so call it again. When the Editor's `com.unity.pipeline` predates jobs, each answers with the same error `--detach` prints. -When the Editor cannot be reached or does not respond in time (a modal dialog, for example), the `capture_game_view` / `capture_scene_view` tools return an error saying the Editor could not be captured. They take no screenshot of the desktop unless `UNITY_MCP_DESKTOP_FALLBACK=1` is set in the `unity mcp` server's environment; with it set, they fall back to an OS-level screenshot of every display, and the result says so in a note, since it captures the screen rather than the specific view. The server also declares support for `tools/list_changed` and notifies the client when the tool catalog changes, so a session started before any Editor was running picks up the Editor’s tools without a restart. Until then, the list holds one `unity-cli-status` tool. Its description says why the Editor's tools are missing, in the words `unity command` uses (no Editor open for the project, for example). Calling it checks again. `--tools` and `--exclude-tools` don't hide it. +When the Editor cannot be reached or does not respond in time (a modal dialog, for example), the `capture_game_view` / `capture_scene_view` tools return an error saying the Editor could not be captured. They take no screenshot of the desktop unless `UNITY_MCP_DESKTOP_FALLBACK=1` is set in the `unity mcp` server's environment; with it set, they fall back to an OS-level screenshot of every display, and the result says so in a note, since it captures the screen rather than the specific view. The server also declares support for `tools/list_changed` and notifies the client when the tool catalog changes, so a session started before any Editor was running picks up the Editor’s tools without a restart. Until then, the list holds one `unity-cli-status` tool. Its description says why the Editor's tools are missing, in the words `unity command` uses (no Editor open for the project, for example). Calling it checks again. `--tools` never hides it; an `--exclude-tools` entry that matches it (`*status*`, `unity-*`) does. #### mcp configure — register the server in an AI client @@ -277,7 +277,7 @@ unity setup all --dry-run unity setup all --format json ``` -It takes `--dry-run` and every output format. The json `data` is `clients`, one object per client with `client`, `displayName`, `kind` (`plugin` or `skills`), `outcome` (`installed`, `already_installed`, `skipped`, `failed` or `dry_run`), `plugin` (`id`, `version`, plugin agents only), `skills` (`name`, `version`, what was installed, module skills included), `warnings` (notes for that client, present only when there are any) and, on failure, `error` (`code`, `message`), plus `skillsToLoad`, the skills to read now. A machine with no agents reports an empty `clients` and exits 0. +It takes `--dry-run` and every output format. The json `data` is `clients`, one object per client with `client`, `displayName`, `kind` (`plugin` or `skills`), `outcome` (`installed`, `already_installed`, `skipped`, `failed` or `dry_run`), `plugin` (`id`, `version`, plugin agents only), `skills` (`name`, `version`, what was installed, module skills included), `warnings` (notes for that client, present only when there are any) and, on failure, `error` (`code`, `message`), plus `skillsToLoad`, the skills to read now. A machine with no agents reports an empty `clients` and exits 0. `--format tsv` is a `key`/`value` header row, then one row per leaf of that `data` under its key path (`clients.0.client`, `clients.0.outcome`, ...); `--no-header` leaves the header out. The same holds for `unity setup `. - **Edited skill.** A managed skill still matching what the CLI wrote is updated. One you edited is left alone: its outcome is `skipped`, `warnings` names `unity skill install --force` to overwrite it, and the run still exits 0. - **MCP.** A client that can run shell commands uses the CLI and its skills, so `setup all` registers no MCP server for it. Run `unity mcp configure ` yourself if the user wants one. Only a client with no shell is configured automatically, and a failure there has the error code `MCP_CONFIGURE_FAILED`; retry it with `unity mcp configure --yes`. @@ -320,7 +320,7 @@ A default `unity skill install ` writes every Unity skill side by side: - **Offline.** When the download fails, the run installs the two embedded skills (`unity-cli` and `new-unity-project`), warns with the names of the pinned skills it couldn't install, and still exits `0`. Run it again once the machine is online. - **Records.** Under `--format json`, a record for an embedded or repo skill carries `source` (`embed` for a skill built into the CLI, `repo` for one from the pinned repository) and, for a repo skill, `commit`, the pinned commit it came from. A pinned skill the offline run skipped has `skipped: true` and `skipReason: "offline"`. -`unity skill install --all` installs into every agent client found on this machine, the clients `unity setup all` finds. A plugin agent gets the skills client it reads from: Claude Code `claude-code`, Codex `codex`, Grok Build `grok`, GitHub Copilot CLI `vscode`. It leaves out Antigravity and Qwen Code: install their skills with `unity skill install antigravity` or `unity skill install qwen`, or with `unity setup antigravity` or `unity setup qwen`, which also installs the plugin. It never runs an agent's own CLI, installs no plugin and configures no MCP server, so it needs no git; `unity setup` does those. Each client's run is non-interactive: it updates a copy an older CLI wrote that nobody edited, and skips an edited copy or a skill a plugin already provides, unless you pass `--yes`. It prints one line per client (in a terminal, the machine-state block `unity setup all` prints, whose "Load skills" row names only `unity-cli` and `new-unity-project`), and one client failing doesn't stop the rest; the run then exits `6`, with a `SKILL_INSTALL_CLIENT_FAILED` entry per failed client in `errors`. `--format json` `data` holds every client's skill records, each carrying its `client`. With no client found it says so and exits `0`. It can't be combined with a client name or `--list` (exit `2`). The Unity CLI install scripts run `unity skill install --all --non-interactive` after installing the binary. +`unity skill install --all` installs into every agent client found on this machine, the clients `unity setup all` finds. A plugin agent gets the skills client it reads from: Claude Code `claude-code`, Codex `codex`, Grok Build `grok`, GitHub Copilot CLI `vscode`. It leaves out Antigravity and Qwen Code: install their skills with `unity skill install antigravity` or `unity skill install qwen`, or with `unity setup antigravity` or `unity setup qwen`, which also installs the plugin. It never runs an agent's own CLI, installs no plugin and configures no MCP server, so it needs no git; `unity setup` does those. Each client's run is non-interactive: it updates a copy an older CLI wrote that nobody edited, and skips an edited copy or a skill a plugin already provides, unless you pass `--yes`. It prints the install records (in a terminal, the machine-state block `unity setup all` prints, whose "Load skills" row names only `unity-cli` and `new-unity-project`; under `--format tsv`, a header row of the record keys, `client`, `clientDisplayName`, `local`, `path`, `action` and the rest, then one row per skill and client), and one client failing doesn't stop the rest; the run then exits `6`, with a `SKILL_INSTALL_CLIENT_FAILED` entry per failed client in `errors`. `--format json` `data` holds every client's skill records, each carrying its `client`. With no client found it says so and exits `0`. It can't be combined with a client name or `--list` (exit `2`). The Unity CLI install scripts run `unity skill install --all --non-interactive` after installing the binary. Supported clients: `claude-code`, `claude-desktop`, `grok`, `cursor`, `windsurf`, `vscode`, `cline`, `codex`, `opencode`, `antigravity`, `qwen`. Each is written in the format that client expects, at its platform-correct location. Not every client supports both scopes — some are user-global only, others project-local only — and `--list` reports which, so check there rather than guessing. @@ -371,10 +371,10 @@ When an agent without the plugin's hook runs `unity` and the Unity skills it ins `unity skill show` prints the embedded skill straight to stdout — no prompt, no file written, no network call — for a client (or an agent already reading this skill) that only wants the content, not a filesystem write it may not be permitted to make. ```bash -# The skill's SKILL.md (default) +# The skill's main file (default) unity skill show -# List every embedded file (SKILL.md first, then docs and references, in sort order) +# List every embedded file (the main skill file first, then docs and references, in sort order) unity skill show --list # Show one specific file from that list @@ -409,7 +409,7 @@ unity skill disable unity-cli --dry-run unity skill enable unity-cli ``` -Disabling renames the skill's `SKILL.md` to `SKILL.md.disabled` and records the choice. Every supported client discovers a skill by finding `SKILL.md` in its directory, so that one rename is what stops it loading — on all of them, identically. The rest of the tree stays where it is, which makes enabling a rename back rather than a reinstall. +Disabling renames the skill's main file to `SKILL.md.disabled` and records the choice. Every supported client discovers a skill by finding that main file under its usual name in its directory, so that one rename is what stops it loading — on all of them, identically. The rest of the tree stays where it is, which makes enabling a rename back rather than a reinstall. `unity skill refresh` skips a disabled skill and keeps tracking it, so a refresh never silently switches one back on. `unity skill install ` does re-enable it, and says so — installing is an explicit request to have the skill active. @@ -837,7 +837,7 @@ unity status --until-ready --project-path ~/UnityProjects/megacity --format json unity status --until-ready --timeout 60 --format json ``` -Reads the lockfile the Pipeline package writes per running Editor (faster and more CI-friendly than `pipeline editors`). Each row names its project as `projectPath` and its Editor as `editorVersion`; `project` and `version` hold the same values and are deprecated. While an Editor is in Play mode, its row also carries `frameCount` and `playerLoopTicking` when the installed `com.unity.pipeline` reports them; `playerLoopTicking: false` outside a pause means the game is frozen (see [playmode-verification-loop.md](playmode-verification-loop.md)). Stale-heartbeat instances are reported as `unreachable` without an HTTP probe. An Editor that is still starting up, or whose main thread a modal dialog freezes, is reported as `starting` rather than `ready` (the CLI probes the Editor’s main thread directly), so a script that polls `status` does not treat a booting or frozen Editor as ready. A frozen Editor that nothing has asked about for 60 seconds reads `unreachable` instead, because the Pipeline package refreshes its heartbeat only when asked. An Editor busy running another command still reads `ready`. Read the error code, not the exit code: `starting` yields `STATUS_NOT_READY`, and the failure codes below exit 6, except `STATUS_NO_INSTANCES` and `STATUS_ALL_UNREACHABLE`, which exit 12. When the Editor reports the dialog (Unity 6000.7 or later), the `starting` row carries `blockedBy` (`reason: "dialog"`, and `dialogs` with each one’s `level` and `title`, innermost last) and the code is `STATUS_BLOCKED_BY_DIALOG`: someone has to answer the dialog, so `--until-ready` stops at once instead of waiting. An older Editor can’t name it, so its row is plain `starting`. With `--format json`/`ndjson`, emits a `success: false` envelope (`STATUS_NO_INSTANCES` / `STATUS_PIPELINE_LOAD_PENDING` / `STATUS_NOT_READY` / `STATUS_BLOCKED_BY_DIALOG` / `STATUS_SAFE_MODE` / `STATUS_ALL_UNREACHABLE`) and a non-zero exit when no Editor is reachable, so CI scripts can gate on Editor availability. `STATUS_SAFE_MODE` means an Editor is in Safe Mode: its row is `unreachable` with `safeMode.compileErrors` (see [Recovering from Safe Mode](#recovering-from-safe-mode-connection-fails-because-of-compile-errors)). `STATUS_PIPELINE_LOAD_PENDING` means an Editor has the project open with the package in its manifest but hasn't loaded it yet (see [Getting an Editor to drive](#getting-an-editor-to-drive)). +Reads the lockfile the Pipeline package writes per running Editor (faster and more CI-friendly than `pipeline editors`). Each row names its project as `projectPath` and its Editor as `editorVersion`; `project` and `version` hold the same values and are deprecated. While an Editor is in Play mode, its row also carries `frameCount` and `playerLoopTicking` when the installed `com.unity.pipeline` reports them; `playerLoopTicking: false` outside a pause means the game is frozen (see the Play-mode verification loop reference). Stale-heartbeat instances are reported as `unreachable` without an HTTP probe. An Editor that is still starting up, or whose main thread a modal dialog freezes, is reported as `starting` rather than `ready` (the CLI probes the Editor’s main thread directly), so a script that polls `status` does not treat a booting or frozen Editor as ready. A frozen Editor that nothing has asked about for 60 seconds reads `unreachable` instead, because the Pipeline package refreshes its heartbeat only when asked. An Editor busy running another command still reads `ready`. Read the error code, not the exit code: `starting` yields `STATUS_NOT_READY`, and the failure codes below exit 6, except `STATUS_NO_INSTANCES` and `STATUS_ALL_UNREACHABLE`, which exit 12. When the Editor reports the dialog (Unity 6000.7 or later), the `starting` row carries `blockedBy` (`reason: "dialog"`, and `dialogs` with each one’s `level` and `title`, innermost last) and the code is `STATUS_BLOCKED_BY_DIALOG`: someone has to answer the dialog, so `--until-ready` stops at once instead of waiting. An older Editor can’t name it, so its row is plain `starting`. With `--format json`/`ndjson`, emits a `success: false` envelope (`STATUS_NO_INSTANCES` / `STATUS_PIPELINE_LOAD_PENDING` / `STATUS_NOT_READY` / `STATUS_BLOCKED_BY_DIALOG` / `STATUS_SAFE_MODE` / `STATUS_ALL_UNREACHABLE`) and a non-zero exit when no Editor is reachable, so CI scripts can gate on Editor availability. `STATUS_SAFE_MODE` means an Editor is in Safe Mode: its row is `unreachable` with `safeMode.compileErrors` (see [Recovering from Safe Mode](#recovering-from-safe-mode-connection-fails-because-of-compile-errors)). `STATUS_PIPELINE_LOAD_PENDING` means an Editor has the project open with the package in its manifest but hasn't loaded it yet (see [Getting an Editor to drive](#getting-an-editor-to-drive)). **Waiting for ready: use `--until-ready`, not a polling loop.** After `unity open`, after `editor.playmode start` (which drops the Pipeline listener for about 8 seconds), or after a domain reload, `unity status --until-ready` keeps checking until a matching Editor reports `ready`, then prints the same envelope a plain `status` would, with exit 0. It works when no Editor exists yet at the moment you call it, as long as one appears before the timeout. `--port` and `--project-path` scope every check, so a ready Editor for another project never ends the wait. A `--project-path` that is an existing directory matches that project only, so pass the project's full path: an Editor open on a sibling checkout (`MyGame-lighting` next to `MyGame`) is another project and never matches it. A value that isn't a directory, such as the bare name `megacity`, matches any project path containing it, case-insensitively. `--timeout ` sets the budget (default 300; `0` takes one check). On timeout it exits 6 and the envelope reports the last state it saw, with that state’s usual code, so read `errors[0].code` exactly as you would for a plain `status`. `--timeout` without `--until-ready` is rejected (exit 2, `STATUS_TIMEOUT_REQUIRES_UNTIL_READY`). The batch-mode caveat above still applies: an Editor that `status` never lists is never reported ready, so `--until-ready` would wait out the whole budget for it. @@ -1128,7 +1128,7 @@ Set shell-local defaults so you stop repeating flags. Every setting is per-sessi # unity> unset format # clear one setting (format | verbose | banner | project | org) ``` -`UNITY_PROJECT_PATH` and `UNITY_CLOUD_ORG` are also honored as environment variables; [SKILL.md](../SKILL.md#environment-variables) lists the commands that read `UNITY_PROJECT_PATH`. +`UNITY_PROJECT_PATH` and `UNITY_CLOUD_ORG` are also honored as environment variables; the global flags and environment variables reference lists the commands that read `UNITY_PROJECT_PATH`. #### Machine/agent mode — `--protocol ndjson` diff --git a/skills/unity-cli/references/notes.md b/skills/unity-cli/references/notes.md new file mode 100644 index 0000000..9440bfc --- /dev/null +++ b/skills/unity-cli/references/notes.md @@ -0,0 +1,30 @@ +# Notes — unity-cli reference + +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. Read this when the main page points here. + +### Contents + +- Notes + +## Notes + +- `--non-interactive` and `--yes` together suppress all prompts — use both in CI. +- A short flag means one thing on every command: `-y` is `--yes` wherever `--yes` exists, `-a` is `--architecture`, `-e` is `--editor-path`, `-f` is `--force`, `-i` is `--installed`, `-l` is `--list`, `-m` is `--module`, `-o` is `--output` and `-r` is `--releases`. Every other option takes its long name: `unity projects` and `unity projects size` spell "every project" `--all`, `logs` and `projects logs` spell `--follow`, `projects import` spells `--input`, `build` and `run` spell `--log-file`, `projects` spells `--modified`, `templates location` spells `--reset`, and `foundry get` spells `--out`. An old spelling the CLI still accepts (`-a`, `-m`, `-i`, `-l`, `-r`, `-f` or `-o` on those, `--project` on `status`, `--template-version`, `--hub-version`, `--package-version`, `--list-components`, `--install-dir`, `--childModules`, `--wait-timeout`, `--git-token-stdin`, `--group_by` on `command`, `--local-space` on `collaboration annotations`, `--project-id` and `--organization-id` on `collaboration`, `-v` on `projects`, `--since` on `releases` and `vcs git migrate-lfs`, `--project` on `assets export`, `assets import` and `auth default`, `--path` on `build run`, `--project-path` on `projects clone`, `--skip` on `releases` and `cloud projects`, `--out` on `collaboration annotations export`, `collaboration attachments download` and `collaboration thumbnail download`) prints a warning naming the spelling to use; so does `--verbose` on `editors` and `projects`, which still shows every column but now spells it `--long`; in `--format json` it is in the envelope's `warnings`. Use the new spelling, so the warning never lands in a log you parse. +- `--timeout` takes a whole number of seconds written as digits (`--timeout 600`) on every command, and so do `UNITY_BUILD_TIMEOUT`, `UNITY_RUN_TIMEOUT` and `UNITY_TEST_TIMEOUT`. A unit, fraction or exponent (`30s`, `5m`, `1.5`, `1e3`) is a usage error (exit `2`), so convert minutes to seconds yourself. +- `--format json` always produces machine-readable output; prefer it over parsing human text. Error envelopes are pretty-printed with the same 2-space indent as success envelopes. The envelope's `command` is the full command path (`projects list`, `cloud org list`), the same in json and ndjson and on success and failure; it is `""` when no command matched, such as an unknown one. +- **`success` is `true` exactly when the exit code is `0`.** A status command whose answer is no (`unity auth status` signed out, `unity license status` with no license, `unity status` with no ready Editor) is a failure: `success: false`, an `errors[0].code` naming the answer, and its report still in `data`. A listing that finds nothing (`unity editors running` with no Editor) succeeds with an empty list. +- **A streamed named command has no CLI envelope.** When the project's `com.unity.pipeline` formats a named command's output itself (see `references/integration-advanced.md`), `unity command --format json` (or `--json`) prints the command's own result, one JSON value per line, with no `success`, `errors` or `data` wrapper, so its rows are not under `.data.items[]`. Branch on the exit code, which is the command's own, not one from the [exit-code table](exit-codes.md): `0` means it succeeded and any other code that it did not, such as `1` for a failed command, `102` when the Editor was busy and refused it (retry), or `106` when it was cancelled. A cancel that follows your Ctrl-C or a SIGTERM to the CLI exits `130` or `143` instead. With an older `com.unity.pipeline` the envelope and every rule in this list apply. +- **Read failures from stdout, not stderr.** A failed command still writes a complete document to stdout: under `--format json` an envelope with `success: false` and a populated `errors` array (`errors[0].code` is the stable token to branch on); under `--format ndjson` the usual terminal `{"type":"result","success":false,…}` frame. **Every ndjson stream ends with exactly one terminal `{"type":"result"}` frame, on success too**, so a stream without one was truncated. Table-shaped listings (`unity editors`, `unity editors upgrade --check`, `unity templates`, `unity releases`, `unity projects`, `unity contexts`, `unity auth accounts`, `unity modules`, `unity command`, `unity skills`, `unity logs`, `unity cloud orgs`, `unity cloud projects` and the like) write one row per line first, each starting with `"type":"row"` so you can tell a row from a `progress` or `result` frame, then a terminal frame whose `data` is `{count, total, nextPage|nextCursor, partial}` (some listings keep older keys there too). A `unity templates` row keeps its own `type` (the template type) with no `"row"` marker. A single-record answer (`unity version`, `unity language`, `unity env`, `unity doctor`, `unity config proxy`, `unity cache info`, `unity context current`, `unity editors default`, `unity install-path`, `unity diagnose update` and the like) is that frame alone, its `data` the same as `--format json`. `--quiet` never changes json output. It never changes ndjson output either, except that `unity editors upgrade`, `unity build --list-targets` and `unity build --list-profiles` still drop their rows under `--quiet` (the terminal frame stays), a known bug; leave `--quiet` off when you need those rows. A warning in either format appears only in `warnings`, never on stderr. A `--watch` or `--follow` stream, which only ends on Ctrl-C, writes its rows and no terminal frame. **Branch on `success`, never on `data`** — `data` is usually `null` on a failure, but not always: a partial `unity editors add` failure carries a row per path, and an ambiguous `unity auth switch` carries `data.candidates` for you to disambiguate with. Check `success` and the exit code — never treat empty stdout as a failure signal, and do not parse stderr, which carries only human diagnostics in these formats. If stdout is empty on a non-zero exit, that is a known bug in that command rather than a shape you should code against. +- **Never merge stderr into stdout when you parse (`2>&1`, or a tool that captures both as one stream).** Stdout alone is a complete, valid document under `--format json` and `--format ndjson`, but stderr carries human diagnostics. Merged in, those lines trail the JSON, and a parser fails with `Extra data` or a decoder needs `raw_decode`. Capture the two streams separately (`unity … --format json 2>err.txt >out.json`) and parse stdout only, or discard stderr with `2>/dev/null` (`2>NUL` on Windows cmd). No agent install hint goes to stderr under these formats: the tips ride the envelope's `notifications`, and Claude Code's `` tag is printed under every format but these two. +- `unity [path]` is a shorthand for `unity open [path] --editor-version `. Works with `lts`, `latest`, or a full version string like `6000.0.47f1`. +- The CLI supports kubectl-style plugins: any `unity-` binary on PATH is callable as `unity `. +- Terminal output is hardened against control-character / escape-sequence injection from server-provided values (project titles, editor versions, module names) — C0 controls and non-SGR escape sequences are stripped from table/list/tree output, and now also from Commander usage errors, the `unity bug` log-archive warning, and `unity projects add`/`remove` machine (tsv) output, while SGR color/style codes are preserved. +- The CLI reports anonymous crashes and errors via Sentry to help fix bugs (no IP address or hostname; home-directory paths and token-like values scrubbed before send), aligned with the Unity Hub. Opting in to analytics additionally attaches an anonymized machine id; opted-out users stay fully anonymous. Set `UNITY_NO_CRASH_REPORT`, or turn off "Send crash reports" in the Hub's settings, to disable reporting entirely. Separately again, every run sends one anonymous `cli telemetry` usage ping even when nobody answered the consent prompt; turning analytics off (in the CLI, or in the Hub while signed in), `DO_NOT_TRACK`, `UGS_CLI_TELEMETRY_DISABLED`, or `UNITY_NO_CLI_INVOKED_TELEMETRY` stops it — see [diagnostics-maintenance.md](diagnostics-maintenance.md#analytics--usagetelemetry-consent). +- `unity --version` prints the version you have. `unity self-update --check --format json` says whether a newer one exists on your installed channel (a beta follows betas). `unity self-update --check --channel stable --format json` checks for a stable release, for example when moving off a beta once GA ships. +- **Always use the latest version of the Unity CLI unless you are told to use a specific version.** A newer CLI regularly adds commands and output fields these docs describe, so an outdated one fails in ways that read like the docs being wrong. +- Since `0.1.0-beta.8` the CLI checks in the background for a newer version and prints an unobtrusive "update available" notice (interactive sessions only; never delays a command). Turn it off with `unity config update-check off` or the `UNITY_NO_UPDATE_CHECK` env var. +- The same check also covers plugins the CLI installed (`unity plugin install`): when one has a newer version, a notice names it and suggests `unity plugin upgrade`, at most once a day. The same two switches turn it off. +- **Under `--format json` and `--format ndjson` that same notice reaches you as a `notifications` array on the envelope** — see the Notifications section of the main skill page. Over MCP it arrives once per session, as prose in the server's `initialize` `instructions`. +- Outbound HTTP from every CLI command honors the resolved proxy (see `unity config proxy`). An invalid `--proxy` value (malformed URL or unsupported scheme) fails with a usage error (exit 2) instead of being silently ignored. Inspect what the CLI actually resolved with `unity env --format json` or `unity doctor --format json` — both surface the active proxy URL, its source, and auth source. diff --git a/skills/unity-cli/references/playmode-verification-loop.md b/skills/unity-cli/references/playmode-verification-loop.md index 773e094..65b27b9 100644 --- a/skills/unity-cli/references/playmode-verification-loop.md +++ b/skills/unity-cli/references/playmode-verification-loop.md @@ -1,14 +1,14 @@ # Play-mode verification loop -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and the general "drive a running Editor" workflow. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, ...) apply to every command below. [integration-advanced.md](integration-advanced.md) covers the Pipeline command surface generally; this page is the recipe for one specific loop: enter Play mode, confirm the game is actually running (not frozen), look at it, read its console, and tune it, all without leaving the CLI. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ## Contents - Why this loop, and not `editor.playmode start` + a screenshot diff --git a/skills/unity-cli/references/projects-templates.md b/skills/unity-cli/references/projects-templates.md index 370ca7e..3cb7d81 100644 --- a/skills/unity-cli/references/projects-templates.md +++ b/skills/unity-cli/references/projects-templates.md @@ -1,11 +1,11 @@ # Projects, releases & templates — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ### Contents - Projects — list, open, create, register, clone, link @@ -715,7 +715,7 @@ unity projects unlink vcs /path/to/MyProject unity projects unlink vcs /path/to/MyProject --unlink-workspace ``` -With piped or redirected stdout and no `--format` (so `tsv`), `link cloud` and `unlink cloud` print one row with six tab-separated columns: result (`linked`, `already-linked`, `unlinked`, `not-linked`), project path, cloud project ID, project name, organization ID, and `true`/`false` for whether a cloud project was created. For `link cloud` the name is the cloud project's. `unlink cloud` reports the link the project held before it was removed, with the name saved alongside it (the local project's title when the CLI made the link), and `not-linked` leaves the three cloud columns empty. For `link cloud`, `--format json` has the full payload (`cloudProject`, `cloudOrgSource`, `coppa`). `unlink cloud` JSON reports only `path` and `unlinked`, so read the removed link from its TSV row. +With piped or redirected stdout and no `--format` (so `tsv`), `link cloud` and `unlink cloud` print a `keyvalue` table of the same members `--json` carries (`path`, and for `link cloud` `cloudProject`, `cloudOrgSource` and `coppa`), a header row first and one row per leaf, so a script selects a row by key and not by position. `--no-header` leaves the header out. `unlink cloud` reports the link it removed as `cloudProjectId`, `projectName` and `organizationId` (`null` when the registry row lacked one), beside `path` and `unlinked`. The other `projects` write commands follow the same rule: `pin`, `unpin`, `add`, `remove`, `import` and the `projects create` result under tsv start with a header row, as do `link vcs`, `unlink vcs`, `clone `, `templates location`, `edit`, `delete`, `create` and `pack`, and `ci init` (whose `--dry-run` prints a `line` header, then one row per line of the workflow). A script that wants the bare value reads `--json` (its `data`), because `--format human` prints a sentence. `link vcs` shares the source-control flag set documented under `projects create`. `link cloud` / `link vcs` accept `--cloud-org ` (env `UNITY_CLOUD_ORG`), and `--coppa ` for the cloud project they create (see the COPPA declaration note under `projects create`). diff --git a/skills/unity-cli/references/version-control.md b/skills/unity-cli/references/version-control.md index 1f32841..083d7b2 100644 --- a/skills/unity-cli/references/version-control.md +++ b/skills/unity-cli/references/version-control.md @@ -1,6 +1,8 @@ # Version control — unity-cli command reference -Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +Relative links in this file resolve to the skill directory's `references/` folder. + +Part of the **`unity-cli`** skill. See the main skill page for CLI install, global flags, environment variables, exit codes, and common workflows. All global flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. @@ -20,8 +22,6 @@ Unity coat of paint, the Unity part is the point. the argument or the flag, not both: both is a usage error (exit `2`). Verbs whose argument is a file (`diff`, `blame`, `explain`, `resolve`) or a worktree (`git worktree remove`) don't take the flag. -Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page. - ## Contents - Map diff --git a/skills/unity-cli/references/worktrees.md b/skills/unity-cli/references/worktrees.md new file mode 100644 index 0000000..64bc766 --- /dev/null +++ b/skills/unity-cli/references/worktrees.md @@ -0,0 +1,3 @@ +# One Editor per worktree — unity-cli reference + +Working in several worktrees or agent sessions: use one Editor per worktree. Make each worktree with `unity vcs git worktree add --output-dir `, so you choose where it lands. `--output-dir` is optional: `--format json` reports the real worktree and project paths, and only the human output masks the account name in a home-directory path. The Unity project is `` when it sits at the repository root, and `/` when it doesn't. Open that project's own Editor with `unity open `. Then pin every call that reaches the Editor to that project: pass `--project-path `, or prefix the call with the variable, as in `UNITY_PROJECT_PATH= unity command editor status`. Most agent tools run each command in a fresh shell, so an `export` or a bare assignment in one call never reaches the next one. Every command that takes `--project-path` reads the variable when you pass no path, and so does `unity open`. Only `close`, `projects unlink cloud`, `mcp configure` and `ci init` don't read it: pass the path to those. Without the variable, a bare `unity open` opens the project of the current directory, which is still your source checkout. Target that Editor by the same full path every time, including `unity status --until-ready --project-path `. A path that exists matches only that project, while a bare name also matches a sibling whose path contains it. Never drive an Editor whose project is not your own checkout (or one of its Multiplayer Play Mode clones). An Editor open on a sibling worktree answers every command just like yours. A command sent there edits that checkout's scenes, and its Play mode, recompiles and imports run against that checkout's code. If your own Editor isn't open, open it. If it has gone away, tell the user rather than borrowing the one that is running.