From 8b7ef3e567ff4f87ed2ffc6f0b62e448f1d28d6f 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 14:34:09 +0000 Subject: [PATCH] chore: publish 2 skills (new-unity-project, unity-cli) --- skills/new-unity-project/SECURITY.md | 2 +- skills/new-unity-project/SKILL.md | 37 +++++- skills/unity-cli/CHANGELOG.md | 36 +++++- skills/unity-cli/SKILL.md | 40 +++--- .../references/auth-license-cloud.md | 8 +- skills/unity-cli/references/build-run-test.md | 45 +++---- .../unity-cli/references/cloud-automation.md | 114 ++++++++++++++++-- skills/unity-cli/references/collaboration.md | 43 ++++--- .../references/diagnostics-maintenance.md | 7 +- .../unity-cli/references/editors-install.md | 17 +-- .../references/integration-advanced.md | 35 ++++-- .../references/playmode-verification-loop.md | 9 ++ .../references/projects-templates.md | 70 +++++++---- .../unity-cli/references/version-control.md | 2 +- 14 files changed, 339 insertions(+), 126 deletions(-) diff --git a/skills/new-unity-project/SECURITY.md b/skills/new-unity-project/SECURITY.md index f4a022d..5c94292 100644 --- a/skills/new-unity-project/SECURITY.md +++ b/skills/new-unity-project/SECURITY.md @@ -20,7 +20,7 @@ of these as powerful capabilities. They are intentional, and limited by the safe writes and the cloud-link narration included — prints in one block before the create launches, and any line reverses on a word. Consent in the strict sense comes from guided mode's per-step asks; paved mode's bar is that nothing runs unannounced and nothing is irreversible. -- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA) and publishing each run only after the user says yes to a question the agent asks and waits on. +- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA and the Unity Editor Software Terms, which `unity terms accept --yes` records only after that yes) and publishing each run only after the user says yes to a question the agent asks and waits on. - **Only the user's own Editor and account.** Everything runs on this machine as this user. - **No remote code.** All executed C# comes from this skill's text and its delegated skills. - **Named commands first.** Where a dedicated `unity` command covers a step, the skill uses it. diff --git a/skills/new-unity-project/SKILL.md b/skills/new-unity-project/SKILL.md index b90120f..e533f96 100644 --- a/skills/new-unity-project/SKILL.md +++ b/skills/new-unity-project/SKILL.md @@ -45,9 +45,14 @@ with your client's multiple-choice question tool (plain text only without one), answer. Send it together with the delegated-skills offer (below) and any Step 1 question, so the user answers once. Offer the free **Unity Personal** license as the default choice, with the other license types (a subscription the -account already has, a serial, a floating server) as alternatives. The Personal choice itself says -that picking it accepts the Unity Personal EULA -(https://unity.com/legal/editor-terms-of-service/software), so the user sees it before answering. +account already has, a serial, a floating server) as alternatives. The question says that a yes +also accepts the Unity Editor Software Terms +(https://unity.com/legal/editor-terms-of-service/software) for every Editor this run opens, installed now or already on the machine, and +the Personal choice says it accepts the Unity Personal EULA (the same page), so the user sees both +before answering. Every Editor stops on its own terms dialog the first time it opens until they are +accepted, and an agent can't see or click that dialog. When sign-in and license are already set +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. @@ -141,6 +146,13 @@ Two decisions (paved: filled from the Defaults table, then **print the manifest* 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). + Confirm prerequisites, then **start the create as a background task** (`unity-cli` has module names and auth / license setup): @@ -149,8 +161,9 @@ unity --version # sign-in and license: settled before your first question (see # Start in the BACKGROUND. Module names per platform are in the unity-cli skill. # --bare only on the user's ask (see Mode). -unity projects create "" --path --editor-version latest \ - --template <3d|2d> --install-editor --module --accept-eula --format json +unity projects create "" --output-dir --editor-version latest \ + --template <3d|2d> --install-editor --module --accept-eula \ + [--cloud-org ] --format json ``` The command waits for the install, then creates the project, so its one result covers both. If you @@ -177,6 +190,17 @@ the platform modules with `unity install-modules -e -m --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. + ## Step 4 — Source control **Paved:** local git + Unity `.gitignore`. **Guided:** ask — Git (GitHub / GitLab; `--git-lfs` for @@ -234,7 +258,8 @@ whole step (no Pipeline install, no baseline): go to Step 8, which opens the pro 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 the open names the updated Editor, `unity open "" --editor-version +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 diff --git a/skills/unity-cli/CHANGELOG.md b/skills/unity-cli/CHANGELOG.md index 0dc4e36..7bd52f1 100644 --- a/skills/unity-cli/CHANGELOG.md +++ b/skills/unity-cli/CHANGELOG.md @@ -12,10 +12,25 @@ release's own dated section once the CLI actually ships it. ## [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 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 +- **`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. +- **MCP tool groups**: `integration-advanced.md` says `unity mcp --tool-groups` lists one tool per Editor command group, which takes the command in `command` and its parameters in `args` and lists every command's parameters in its description, that `unity mcp configure` writes the option while an entry an older `configure` wrote keeps one tool per command and the allow list that names them, that `--tools` and `--exclude-tools` hide commands from their groups, and that commands which run code (`script_eval`, `exec`) stay their own tools. Pending the CLI release that adds groups. + - **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.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. + ## CLI `1.0.0-beta.17` (2026-11-05) Aligned to the CLI's `1.0.0-beta.17` 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. @@ -37,6 +52,21 @@ 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. +- **`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. +- **OpenCode skill client**: `integration-advanced.md` lists `opencode` among the `unity skill install` clients and names its skill folders. It also says the install skips a copy OpenCode already loads from `.claude/skills` or `.agents/skills`. Pending the change shipping in a CLI release. +- **Cinemachine and Run In Background in `projects create`**: `projects-templates.md` says every 3D create adds `com.unity.cinemachine` (the newest release that supports the engine version), that a 2D project skips it with the new `NOT_APPLICABLE` reason, that every create sets `runInBackground: 1` in `ProjectSettings.asset`, and that neither writes an account-scoped value. The `steps` report gains `cinemachine` and `runInBackground`, and `--bare` leaves both out. Pending the change shipping in a CLI release. +- **Unity skills repo in `skill install` and `setup`**: `integration-advanced.md` says `unity skill install` also installs the Unity skills pinned from the Unity-Technologies/skills repository, that `--skill` repeats and takes a comma list, that the source is fixed, what an offline run installs, and the `source` and `commit` record fields. It documents `unity setup --yes` installing those skills when the plugin can't be installed, with `installedVia` and `skillsToLoad`. `SECURITY.md` covers the download. Pending the change shipping in a CLI release. +- **`skill show --skill`**: `integration-advanced.md` documents `unity skill show --skill new-unity-project`, which prints that embedded skill instead of `unity-cli`. Pending the change shipping in a CLI release. +- **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. +- **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. ## CLI `1.0.0-beta.15` (2026-10-29) @@ -164,7 +194,7 @@ Aligned to the CLI's `1.0.0-beta.14` release. Everything below was documented ah - **`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 headless 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. +- **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. @@ -281,7 +311,7 @@ Aligned to the CLI's `1.0.0-beta.9` release. Several pieces of this release's su ### 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 headless-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. +- **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. - `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`). @@ -376,7 +406,7 @@ Tracks the CLI's `1.0.0-beta.3` release. The CLI's own `[Unreleased]` changes at - Environment variables **`UNITY_NO_CONSENT_PROMPT`** (suppress the first-run consent prompt without recording a choice) and **`UNITY_NO_CRASH_REPORT`** (disable anonymous crash/error reporting). - Global **`--json`** shorthand (accepted on every command) in the global-flags table. - OSC 9;4 taskbar progress note for `unity install` on interactive terminals. -- **Driving a running Editor** — three patterns: **persistent headless** (launch the Editor binary in `-batchmode` *without* `-quit`; it stays resident and serves the Pipeline API — drive it with `unity command`/`list` --project-path), **warm/interactive** (`unity open`, which registers with `unity status` as `ready`), and **one-shot CI** (`unity run --command ` boots a batch Editor, runs one command, exits). Notes that a bare `unity run` is *not* persistent (batch runs to completion and exits) and — verified — that a batch-mode Editor serves commands but is **not** listed by `unity status`. Closes a gap where the Connected Editors section assumed a running Editor without saying how to get one. +- **Driving a running Editor** — three patterns: **persistent batch mode** (launch the Editor binary in `-batchmode` *without* `-quit`; it stays resident and serves the Pipeline API — drive it with `unity command`/`list` --project-path), **warm/interactive** (`unity open`, which registers with `unity status` as `ready`), and **one-shot CI** (`unity run --command ` boots a batch Editor, runs one command, exits). Notes that a bare `unity run` is *not* persistent (batch runs to completion and exits) and — verified — that a batch-mode Editor serves commands but is **not** listed by `unity status`. Closes a gap where the Connected Editors section assumed a running Editor without saying how to get one. - **Authoring custom `[CliCommand]` tools** — `[CliCommand]` / `[CliArg]` in the `Unity.Pipeline.Commands` namespace (assembly `Unity.Pipeline`), with `MainThreadRequired` / `RuntimeOnly` as **named properties on `[CliCommand]`** (not separate attributes); worked example, and hot-registration via `unity command recompile` → `unity list`. - **Editor-side `eval` / `eval_file`** — noted the runtime-discoverable production path via `unity command eval` / `unity command eval_file`, discovered from the connected Editor. - **Live-Editor control surfaced up front** — the skill `description` now advertises controlling a running/connected Editor (create/modify GameObjects, edit scenes, inspect the hierarchy, run C#) so agents pick the skill for scene/GameObject prompts, and a new top-of-skill **"Drive a running Unity Editor"** quickstart shows the minimal `unity status` → `unity command` path ahead of the install steps. diff --git a/skills/unity-cli/SKILL.md b/skills/unity-cli/SKILL.md index ca209a5..46fd7ce 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#, or run any unity command. +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. allowed-tools: - Bash --- @@ -39,6 +39,7 @@ Fields and flags: [integration-advanced.md](references/integration-advanced.md#q unity status # confirm a connected Editor (look for state "ready") unity command # list the commands the Editor exposes unity command editor.playmode start # run one — e.g. enter Play mode +unity command editor.playmode start --help # its parameters, read from the Editor # Run arbitrary C# — e.g. add a GameObject named "Joe" — when the Editor exposes script eval: unity command script eval --caller plugin --skill unity-cli 'new UnityEngine.GameObject("Joe");' ``` @@ -64,13 +65,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 --into `, so you choose where it lands. `--into` 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. +**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. -Requires the project's `com.unity.pipeline` package (Unity 6.0+) — add it once with `unity pipeline install`. Full details — launching a headless Editor to drive, `unity command` tool discovery, and authoring custom `[CliCommand]` tools — are in [integration-advanced.md](references/integration-advanced.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 `7` 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.** 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). > **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). @@ -139,7 +140,7 @@ These work on every command: **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. +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 @@ -155,6 +156,7 @@ All CLI env vars use the `UNITY_` prefix. A CLI flag always overrides the corres | `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. | @@ -173,6 +175,7 @@ All CLI env vars use the `UNITY_` prefix. A CLI flag always overrides the corres | `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. | @@ -188,6 +191,8 @@ All CLI env vars use the `UNITY_` prefix. A CLI flag always overrides the corres Append `-h` or `--help` to any command or subcommand, at any level: `unity --help`, `unity projects create --help`. +`unity command --help` asks the connected Editor for that command and prints its usage, description and parameters (name, type, required, default); a group name alone (`unity command editor.playmode --help`) lists the group's commands. The Editor gets at most 3 seconds. With no Editor, or no such command, the generic `unity command` help prints with one line saying why the parameters are missing and what to run. Help exits 0 either way and runs nothing. + Not sure which command? [Search, don't grep help](#find-a-command-search-dont-grep-help). `unity --help` and the unknown-command error end with that pointer too. Each search ends by naming the source it skipped and the command that searches it (`data.hint` in JSON): follow it before concluding nothing exists. ## Exit codes @@ -197,7 +202,8 @@ whether running the same command again, unchanged, can succeed. A command that s (`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; a missing project, an Editor that +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 @@ -213,7 +219,7 @@ repeat. | 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 for a reason no more specific code names. | +| 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. | @@ -302,7 +308,7 @@ Commands are grouped and invoked as `unity command `. Their names **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 headless 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). +- **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"). @@ -435,10 +441,10 @@ unity editors --installed --format json # confirm # 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; --path sets the parent directory. +# 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" --path ~/UnityProjects \ +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 @@ -479,13 +485,13 @@ land in shell history or the process list. Pick based on the project — don't d ```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" --path ~/UnityProjects \ +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" --path ~/UnityProjects \ +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 ``` @@ -557,7 +563,7 @@ 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 headless C# script as the fallback. For monetization/backend, hand off to the dedicated skills: `implement-in-app-purchases` +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. @@ -627,7 +633,7 @@ echo "Exit code: $?" unity license return --yes ``` -### CI: headless build +### CI: batch-mode build Prefer the dedicated `unity build` command (handles batch mode, logging, and CI flags): @@ -730,17 +736,17 @@ 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`, `build` spells `--output-path` 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`) 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. +- 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 and, for some agents, a one-line install hint (Claude Code gets a `` tag there). 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). `UNITY_NO_AGENT_HINTS=1` removes the hint line, but separate streams are the fix. +- **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`, or `UNITY_NO_CLI_INVOKED_TELEMETRY` stops it — see [diagnostics-maintenance.md](references/diagnostics-maintenance.md#analytics--usagetelemetry-consent). +- 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. diff --git a/skills/unity-cli/references/auth-license-cloud.md b/skills/unity-cli/references/auth-license-cloud.md index 7cbf5bb..c8b48f0 100644 --- a/skills/unity-cli/references/auth-license-cloud.md +++ b/skills/unity-cli/references/auth-license-cloud.md @@ -35,6 +35,10 @@ unity auth login --client-id --secret-from-stdin # Login without persisting credentials to the keyring (ephemeral CI) unity auth login --client-id --secret-from-stdin --no-store +# No system credential store (headless Linux, a locked Keychain): keep the +# sign-in in a plain, unencrypted file instead. Off unless you ask for it. +unity auth login --insecure-storage + # Sign the CLI out (clears its OAuth sign-in and any saved service-account # credentials). There is no confirmation prompt; --yes is accepted and changes nothing. unity auth logout @@ -44,7 +48,7 @@ unity auth logout unity auth logout user@example.com ``` -**How sign-in is served.** Every command’s OAuth token read goes through a resident auth broker — a background `unity` process started on demand by the first command that needs a token, exiting on its own after two idle minutes. It seals the token store to the machine’s hardware where available (a non-exportable TPM key on Windows, TPM2 via `systemd-creds` on Linux, then DPAPI, the Secret Service, the Keychain and a local key file, in that order), and `unity doctor` reports the active tier. On macOS and Windows it verifies a connecting process’s code signature and refuses an unsigned or non-Unity-signed peer. The Editor identity helper that signs in an Editor started by `unity open` applies the same rule, so an Editor built from source (unsigned or not Unity-signed) is not supported for automatic sign-in. Set `UNITY_NO_AUTH_BROKER=1` to bypass the broker and read the OS keyring directly. `unity auth consumers` (below) lists the applications in its audit trail and revocation list. +**How sign-in is served.** Every command’s OAuth token read goes through a resident auth broker — a background `unity` process started on demand by the first command that needs a token, exiting on its own after two idle minutes. It seals the token store to the machine’s hardware where available (a non-exportable TPM key on Windows, TPM2 via `systemd-creds` on Linux, then DPAPI, the Secret Service, the Keychain and a local key file, in that order), and `unity doctor` reports the active tier. On macOS and Windows it verifies a connecting process’s code signature and refuses an unsigned or non-Unity-signed peer. The Editor identity helper that signs in an Editor started by `unity open` applies the same rule, so an Editor built from source (unsigned or not Unity-signed) is not supported for automatic sign-in. Set `UNITY_NO_AUTH_BROKER=1` to bypass the broker and read the OS keyring directly. The local key file and the CLI's plain credential file are used only in insecure-storage mode, which `unity auth login --insecure-storage` (or `UNITY_INSECURE_STORAGE=1`) turns on. Without it, a sign-in with no working credential store fails and names the flag. In the mode, the login prints where the file is, `unity auth status` warns, and `unity doctor` names the file. To turn it off, sign in again without the flag, and unset `UNITY_INSECURE_STORAGE` if you set it. For CI, prefer the service-account environment variables, which need no credential store. `unity auth consumers` (below) lists the applications in its audit trail and revocation list. #### Multiple accounts @@ -92,7 +96,7 @@ unity auth token --json ``` - **OAuth sign-in:** an expired access token is refreshed before it prints. When the session can't be refreshed, nothing prints and the command exits `3` with `NOT_SIGNED_IN` or `SESSION_EXPIRED`. -- **Service account** (`UNITY_SERVICE_ACCOUNT_ID` / `UNITY_SERVICE_ACCOUNT_SECRET`, or `unity auth login --client-id`): prints the bearer Unity's token exchange mints for those credentials. Rejected credentials exit `3` (`AUTH_TOKEN_SERVICE_ACCOUNT_REJECTED`); any other mint failure exits `6`. +- **Service account** (`UNITY_SERVICE_ACCOUNT_ID` / `UNITY_SERVICE_ACCOUNT_SECRET`, or `unity auth login --client-id`): prints the bearer Unity's token exchange mints for those credentials, scoped to the project ID in `UNITY_CLOUD_PROJECT` (an ID, not a name). With no project set it exits `2` (`AUTH_TOKEN_PROJECT_REQUIRED`), and with a value that is not an ID `AUTH_TOKEN_PROJECT_INVALID`, both without calling Unity. Rejected credentials exit `3` (`AUTH_TOKEN_SERVICE_ACCOUNT_REJECTED`); any other mint failure exits `6`. - **`--audience` and `--scope` are refused** (exit `2`, `AUTH_TOKEN_NARROWING_UNSUPPORTED`) until Unity's token service can mint a narrowed token, rather than handing out a broader one than asked for. - The token is short-lived: fetch it again rather than storing it. The CLI never writes it to its logs; keep it out of yours. diff --git a/skills/unity-cli/references/build-run-test.md b/skills/unity-cli/references/build-run-test.md index c7f5c02..d9f7392 100644 --- a/skills/unity-cli/references/build-run-test.md +++ b/skills/unity-cli/references/build-run-test.md @@ -214,7 +214,7 @@ All of these flag-combination mistakes, and an unknown `--report-format` value, ```bash unity test /path/to/MyProject --format github -unity build --target StandaloneWindows64 --output-path ./Build/Game.exe --format github +unity build --target StandaloneWindows64 --output ./Build/Game.exe --format github ``` - **A failing command annotates the job.** Its error message is emitted as `::error::`, and a warning as `::warning::`, so the runner surfaces it as an annotation on the run rather than leaving it buried in the log. @@ -370,26 +370,27 @@ Options: `--mode EditMode|PlayMode`, `--filter `, `--editor-version `, `--timeout ` (default 120), `--focus` (bring the Editor forward first; off by default because an unfocused Editor still compiles), `--strict`. +Options: the project as `[path]` or `--project-path ` (not both), `--timeout ` (default 120), `--focus` (bring the Editor forward first; off by default because an unfocused Editor still compiles), `--strict`. --- @@ -397,11 +398,11 @@ Options: `--project-path `, `--timeout ` (default 120), `--focus` The first-class build workflow. Rule of thumb vs `unity run`: building a player → `unity build`; anything else headless → `unity run`. -Pick one build strategy: a Unity 6+ Build Profile (`--profile`), a built-in desktop player build (`--target` with a desktop target, `--output-path` required), or a custom `--execute-method` (your method is responsible for the actual build, including honoring `--output-path`). Non-desktop targets need `--profile` or `--execute-method`. +Pick one build strategy: a Unity 6+ Build Profile (`--profile`), a built-in desktop player build (`--target` with a desktop target, `--output` required), or a custom `--execute-method` (your method is responsible for the actual build, including honoring `--output`). Non-desktop targets need `--profile` or `--execute-method`. The build log is always written to the log file **and** streamed at the same time — to stdout, or to stderr under `--format json` so stdout holds only the result document; pass `--no-tail` to write the file only (the tail is also suppressed by `--quiet` and `--format ndjson`). The streamed copy masks the credentials the CLI passes the Editor (the `-accessToken` value, the Android keystore passwords) with `***`, as do `run` and `test` wherever they relay the Editor's log. -**How the outcome is decided — do not gate CI on Unity's exit code alone.** For a built-in build (`--profile`, or `--target` without `--execute-method`) the CLI does not trust Unity's process exit code by itself: a real Editor exits `0` from a player build its own log reports as failed. When the log carries Unity's terminal verdict, that verdict decides the outcome, so a failed build exits **6** even where the Unity process exited `0`, and the provenance manifest records the failure. A log with no verdict falls back to the exit code, and an `--execute-method` build always does — your method owns the code it returns, including when it deliberately tolerates a build it reports on itself. A build that succeeds with errors still in its log reports them on stderr rather than dropping them; they also ride `editorErrors` under `--format json`. +**How the outcome is decided — do not gate CI on Unity's exit code alone.** For a built-in build (`--profile`, or `--target` without `--execute-method`) the CLI does not trust Unity's process exit code by itself: a real Editor exits `0` from a player build its own log reports as failed. When the log carries Unity's terminal verdict, that verdict decides the outcome, so a failed build exits **6** even where the Unity process exited `0`, and the provenance manifest records the failure. A log with no verdict falls back to the exit code, with one addition: a clean exit `0` with no verdict and nothing at the `--output` path (or `.app`) is also a failure (exit **6**), since an Editor that dies before it builds looks exactly like that. An `--execute-method` build always falls back to the exit code alone — your method owns the code it returns, including when it deliberately tolerates a build it reports on itself. A build that succeeds with errors still in its log reports them on stderr rather than dropping them; they also ride `editorErrors` under `--format json`. **Writing scripts for a player build? Keep one `MonoBehaviour` per `.cs` file, named after its class.** Unity ties a `MonoBehaviour` to its script by file name, so `PlayerController` belongs alone in `PlayerController.cs`. Several in one file can run fine in the Editor and Play Mode with no warning. The built player then crashes at startup with `The file '.../level0' is corrupted! Remove it and launch unity again!`. `level0` is the first scene in the build (later ones are `level1`, `level2`, and so on), so the message points at scene data, not the scripts. If you see it, look for a `.cs` file that declares more than one `MonoBehaviour` (one deriving from another of yours counts) and give each its own file, named after its class, before you bisect scenes. Check the scripts you wrote or generated this session before you build, and leave existing code alone until the error appears. @@ -410,10 +411,10 @@ The build log is always written to the log file **and** streamed at the same tim unity build /path/to/MyProject \ --target StandaloneOSX \ --execute-method Builder.PerformBuild \ - --output-path ./build/output + --output ./build/output # Build with a Unity 6+ build profile -unity build /path/to/MyProject --profile "Windows Release" --output-path ./Build/MyGame.exe +unity build /path/to/MyProject --profile "Windows Release" --output ./Build/MyGame.exe # Common build targets: StandaloneOSX, StandaloneWindows64, StandaloneLinux64, Android, iOS, WebGL ``` @@ -429,7 +430,7 @@ unity build /path/to/MyProject --profile "Windows Release" --output-path ./Build | `--list-profiles` | List the project’s Build Profile assets (Unity 6+), then exit. | | `--create-profile ` | Create a Build Profile for a target and exit without building (Unity 6+); build with it afterwards via `--profile`. | | `--build-target-group ` | Forwarded to Unity as `-buildTargetGroup`. | -| `--output-path ` | Output path. With `--execute-method`, passed as `-buildOutput` (your method must honor it); otherwise the built-in build's destination (required). | +| `-o, --output ` | Output path (`--output-path` still works). With `--execute-method`, passed as `-buildOutput` (your method must honor it); otherwise the built-in build's destination (required). | | `--log-file ` | Log file path. Default: `/Logs/build--.log`. Streamed to stdout by default, stderr under `--format json` (see `--no-tail`). | | `--editor-version ` (env `UNITY_EDITOR_VERSION`) | Override editor version (default: from `ProjectVersion.txt`). The flag, then a non-empty variable, then `ProjectVersion.txt`, as `run` and `test` choose. | | `-e, --editor-path ` | Use a specific editor binary. A version passed here fails with a hint to use `--editor-version`. | @@ -441,7 +442,7 @@ unity build /path/to/MyProject --profile "Windows Release" --output-path ./Build | `--build-version ` | Explicit version string; only used with `--versioning-strategy custom`. | | `--allow-dirty-build` | Skip the uncommitted-changes guard (default: false). | | `--timeout ` (env `UNITY_BUILD_TIMEOUT`) | Abort a build that runs longer than this many seconds, exit **14** (`BATCH_TIMEOUT`). Disabled by default. | -| `--provenance-path ` | Where to write the provenance manifest. Default: beside the build output, or beside the log file when `--output-path` is not set. | +| `--provenance-path ` | Where to write the provenance manifest. Default: beside the build output, or beside the log file when `--output` is not set. | | `--no-provenance` | Do not write the provenance manifest. | When `UNITY_EDITOR_VERSION` or `UNITY_ARCHITECTURE` chose the build's Editor, `build` says so in one line: a stderr notice in `human`, `tsv` and `github`, and an envelope warning in `json` and `ndjson`. The build provenance records the Editor version either way. @@ -463,9 +464,9 @@ Keystore flags are validated together. Secrets passed as command-line flags surf **Versioning** — `semantic` and `tag` derive the version from git tags/history; `custom` requires an explicit `--build-version`; a dirty working tree is rejected unless `--allow-dirty-build` is passed. -**Provenance manifest** — every build that reaches the editor writes a JSON manifest recording what produced it: editor version and changeset, resolved package set, target, profile, execute method, version stamp, git revision and dirty flag, CLI version, timestamps, and outcome. Failed builds get one too, with the exit code, so they stay diagnosable. It is redacted for publication — paths are project-relative, `--args`, the Android keystore flags, the editor's install location and the hostname are never written, a git package reference keeps its locator but loses any embedded credentials, and a `file:` dependency is recorded as `file:` — so it can be attached to a release next to the artifact. Under `--format json` / `--format ndjson` the path is reported as `data.provenance` (omitted when no manifest was written), on failed builds as well as successful ones. The git revision is captured before the build starts, so an artifact written into the project does not make the manifest claim the build came from a dirty tree. `--provenance-path` and a relative `--output-path` both resolve against the current directory, matching what the CLI hands Unity. A manifest that cannot be written warns instead of failing the build. +**Provenance manifest** — every build that reaches the editor writes a JSON manifest recording what produced it: editor version and changeset, resolved package set, target, profile, execute method, version stamp, git revision and dirty flag, CLI version, timestamps, and outcome. Failed builds get one too, with the exit code, so they stay diagnosable. It is redacted for publication — paths are project-relative, `--args`, the Android keystore flags, the editor's install location and the hostname are never written, a git package reference keeps its locator but loses any embedded credentials, and a `file:` dependency is recorded as `file:` — so it can be attached to a release next to the artifact. Under `--format json` / `--format ndjson` the path is reported as `data.provenance` (omitted when no manifest was written), on failed builds as well as successful ones. The git revision is captured before the build starts, so an artifact written into the project does not make the manifest claim the build came from a dirty tree. `--provenance-path` and a relative `--output` both resolve against the current directory, matching what the CLI hands Unity. A manifest that cannot be written warns instead of failing the build. -**Output path in the result.** Under `--format json` / `--format ndjson` the resolved `--output-path` is reported as `data.outputPath`: the absolute, cwd-resolved path this build told Unity to write to, exactly as `--output-path` was supplied (never introspected out of the Editor or the Build Profile asset). It is present for every built-in build (`--profile`, an auto-discovered profile, or a legacy desktop `--target`), where `--output-path` is required, and `null` only for an `--execute-method` build invoked without `--output-path`, where the method picks its own destination the CLI has no way to learn (the same case that leaves nothing for `build run` to record; see below). Unity decides whether that path names a single file (a Windows `.exe`, a Linux binary) or a directory it writes into (a macOS `.app` bundle, a WebGL build, an Android Studio project export); the CLI reports the path it told Unity to use either way, without distinguishing the two. Like `version`, `outputPath` is serialized as `null` rather than omitted when unknown, and it carries the same value on a failed build's payload whenever one is written. This is a different value from the provenance manifest's own `build.outputPath` (above): the manifest's copy is project-relative and omitted whenever the resolved path falls outside the project, for portability and redaction; `data.outputPath` is always absolute and never redacted, since it rides the CLI's own stdout rather than a file meant to travel with the artifact. +**Output path in the result.** Under `--format json` / `--format ndjson` the resolved `--output` is reported as `data.outputPath`: the absolute, cwd-resolved path this build told Unity to write to, exactly as `--output` was supplied (never introspected out of the Editor or the Build Profile asset). It is present for every built-in build (`--profile`, an auto-discovered profile, or a legacy desktop `--target`), where `--output` is required, and `null` only for an `--execute-method` build invoked without `--output`, where the method picks its own destination the CLI has no way to learn (the same case that leaves nothing for `build run` to record; see below). Unity decides whether that path names a single file (a Windows `.exe`, a Linux binary) or a directory it writes into (a macOS `.app` bundle, a WebGL build, an Android Studio project export); the CLI reports the path it told Unity to use either way, without distinguishing the two. Like `version`, `outputPath` is serialized as `null` rather than omitted when unknown, and it carries the same value on a failed build's payload whenever one is written. This is a different value from the provenance manifest's own `build.outputPath` (above): the manifest's copy is project-relative and omitted whenever the resolved path falls outside the project, for portability and redaction; `data.outputPath` is always absolute and never redacted, since it rides the CLI's own stdout rather than a file meant to travel with the artifact. **Interrupt exit codes** — interrupting `unity build` exits with the conventional signal code (`130` for Ctrl-C / SIGINT, `143` for SIGTERM) rather than a generic `1`, so callers and CI can tell an aborted build apart from a failed one. The temporary Android keystore is scrubbed before exit. @@ -475,7 +476,7 @@ Keystore flags are validated together. Secrets passed as command-line flags surf ```bash # With --format json, stdout is the result document alone; the progress frames and the streamed log go to stderr: -unity build /path/to/MyProject --target StandaloneOSX --execute-method Builder.Build --output-path ./build/output --format json > result.json +unity build /path/to/MyProject --target StandaloneOSX --execute-method Builder.Build --output ./build/output --format json > result.json # stderr (each progress line is a JSON object, the Editor log lines between them): # {"type":"progress","command":"build","message":"Resolving project..."} # {"type":"progress","command":"build","message":"Resolving editor..."} @@ -497,14 +498,14 @@ unity build /path/to/MyProject --list-profiles --format json # Create a Build Profile for a target and exit without building (Unity 6000.0+), then build with it unity build /path/to/MyProject --create-profile WebGL -unity build /path/to/MyProject --profile WebGL --output-path ./Build/web +unity build /path/to/MyProject --profile WebGL --output ./Build/web -# Launch the project’s most recent recorded build without rebuilding (recorded = built with a known --output-path) +# Launch the project’s most recent recorded build without rebuilding (recorded = built with a known --output) unity build run /path/to/MyProject unity build run /path/to/MyProject --build-path ./Build/other/MyGame.exe # a different build ``` -`--list-targets`, `--list-profiles` and `--create-profile` each do their job and exit — no build happens. A `--target` outside the classic catalog fails with `BUILD_INVALID_TARGET` and points at `--profile`. A successful `unity build` with a known output path — a built-in build (`--output-path` is required there) or a `--profile` / `--execute-method` build that passed `--output-path` — records that path together with the target, architecture and Editor version, and `build run` launches that recording: a desktop player natively, a WebGL build from a loopback-only local HTTP server that opens in the default browser. An `--execute-method` build without `--output-path` chooses its own destination inside the method, so it records nothing and leaves any earlier record in place; launch such a build with `build run --build-path ` instead. `build run` fails cleanly (exit 6) when no build has been recorded yet, when the recorded build’s platform cannot run on this OS, or when its output is gone. +`--list-targets`, `--list-profiles` and `--create-profile` each do their job and exit — no build happens. A `--target` outside the classic catalog fails with `BUILD_INVALID_TARGET` and points at `--profile`. A successful `unity build` with a known output path — a built-in build (`--output` is required there) or a `--profile` / `--execute-method` build that passed `--output` — records that path together with the target, architecture and Editor version, and `build run` launches that recording: a desktop player natively, a WebGL build from a loopback-only local HTTP server that opens in the default browser. An `--execute-method` build without `--output` chooses its own destination inside the method, so it records nothing and leaves any earlier record in place; launch such a build with `build run --build-path ` instead. `build run` fails cleanly (exit 6) when no build has been recorded yet, when the recorded build’s platform cannot run on this OS, or when its output is gone. **Per-project defaults.** A committed `ProjectSettings/UnityCliConfig.json` declares `unity build` / `unity test` defaults (`build.target`, `build.outputPath`, `build.profile`, `build.timeout`, `test.mode`, `test.reportFormat`, `test.coverage`, `test.coverageOptions`, `test.timeout`) so they need not be repeated on every invocation; `unity config resolve [project]` shows the resolved value and which layer supplied it. See [config-hub.md](config-hub.md). @@ -528,7 +529,7 @@ The [Unity Accelerator](https://docs.unity3d.com/Manual/UnityAccelerator.html) i unity test /path/to/MyProject # One-shot override / opt-out -unity build /path/to/MyProject --target StandaloneLinux64 --output-path ./Build/MyGame.x86_64 --accelerator cache.example.com:10080 +unity build /path/to/MyProject --target StandaloneLinux64 --output ./Build/MyGame.x86_64 --accelerator cache.example.com:10080 unity test /path/to/MyProject --no-accelerator ``` diff --git a/skills/unity-cli/references/cloud-automation.md b/skills/unity-cli/references/cloud-automation.md index 173eddd..4189af2 100644 --- a/skills/unity-cli/references/cloud-automation.md +++ b/skills/unity-cli/references/cloud-automation.md @@ -17,6 +17,8 @@ and to start, follow, and act on builds and jobs. - Set up a build target - Create an app - Add a version to an app +- Add an action to an app version +- Create a pipeline - Read results - Handle failures @@ -34,7 +36,7 @@ and to start, follow, and act on builds and jobs. | An app's or pipeline's version history | `unity pipeline automation apps versions` / `pipelines versions` | | How many jobs are running or queued | `unity pipeline automation jobs stats` | | A build's steps, failures, artifacts, or log | `unity pipeline cloud-build builds steps` / `failures` / `artifacts` / `log` | -| How long each phase of a build took (staging only) | `unity pipeline cloud-build builds timeline` | +| How long each phase of a build took | `unity pipeline cloud-build builds timeline` | | One artifact file on disk | `unity pipeline cloud-build builds download` | | Start a build, wait for it, or cancel builds | `unity pipeline cloud-build builds start` / `cancel` | | Run a pipeline, or follow a job to its end | `unity pipeline automation pipelines trigger` / `jobs watch` | @@ -43,6 +45,8 @@ and to start, follow, and act on builds and jobs. | Create or change a build target | `unity pipeline cloud-build targets create` / `update` | | Create a Pipeline Automation app | `unity pipeline automation apps create` | | Add a version to an app | `unity pipeline automation apps versions create` | +| Add an action to an app version | `unity pipeline automation apps actions create` | +| Create a Pipeline Automation pipeline | `unity pipeline automation pipelines create` | | What changed in a target's configuration, and who changed it | `unity pipeline cloud-build targets auditlog` | | Connect the project to a repository, or list its connections | `unity pipeline cloud-build connections` / `connections create` | | Check that Build Automation can reach a repository | `unity pipeline cloud-build scm check-url` | @@ -55,9 +59,11 @@ stop](#confirm-wait-and-stop) before running them for a user. `targets create` and `update`, `connections create` and `credentials upload` change the project's configuration: read [Set up a build target](#set-up-a-build-target) first. `apps create` adds an app to the organization: read [Create an app](#create-an-app) -first, and [Add a version to an app](#add-a-version-to-an-app) before -`apps versions create`. They don't require a running Editor or -the local Pipeline package. Local `unity pipeline install|upgrade|list|list-versions` +first, [Add a version to an app](#add-a-version-to-an-app) before +`apps versions create`, and [Add an action to an app +version](#add-an-action-to-an-app-version) before `apps actions create`. Read +[Create a pipeline](#create-a-pipeline) before `pipelines create`. They don't +require a running Editor or the local Pipeline package. Local `unity pipeline install|upgrade|list|list-versions` commands manage the Editor package, not cloud resources. Check availability with `unity pipeline cloud-build --help` or @@ -383,12 +389,10 @@ unity pipeline cloud-build builds log "" --build-target "" --build-target "" --format json +unity pipeline cloud-build builds timeline "" --build-target "" --format json ``` JSON returns the API response under `data`, one key per phase in the order the @@ -614,6 +618,100 @@ service answers `AUTOMATION_FORBIDDEN`, exit `3`. `apps versions create` doesn't ask before it acts and takes no `--yes`: confirm the app and version with the user first. +## Add an action to an app version + +```sh +unity pipeline automation apps actions create "" 1.1.0 --file action.json --cloud-org "" --format json +unity pipeline automation apps actions create "" 1.1.0 --file action.json --name "Run Tests" --cloud-org "" --format json +``` + +`apps actions create` adds an action, the unit a pipeline step runs, to one +version of an app. The version must be a draft: add a new one with +`apps versions create` to change an app whose versions are published. + +`--file` is required (`-` reads stdin) and holds the action as JSON: `name`, +`description`, `definition`, and optionally `inputParameters`, +`outputParameters`, `secrets`, `requirements`, `metadata`, `timeout`, `storages` +and `terminationGracePeriodSeconds`. `--name` and `--description` override the +file's. The `definition`'s `type` is `docker` (a container: `imageName`, +`command`, `args`, `artifacts`, `environmentMapping`, ...) or `httprequest` (one +HTTP call); the service checks the rest. The CLI doesn't create `templateref` +actions. A saved action, or the +`--format json` envelope around one, works as the file; its `actionId` is left +out. + +```json +{ + "name": "Run Script", + "description": "Runs a Python script in a container", + "definition": { + "type": "docker", + "imageName": "python:3.12", + "command": ["/bin/sh", "-c"], + "args": ["python /workspace/main.py"] + } +} +``` + +The name is 2 to 64 letters, digits, spaces or hyphens, since the action's ID +is `--` with hyphens for spaces. The description is 20 +to 256 characters, and the version takes the form `1.0.0`, `1.0.0-rc.1` or +`1.0.0-sha.abc1234`. These, a missing or unknown `definition` type, and a +field the file sets twice are checked before any request (exit `2`). The service refuses a name the version +already has, or a version that isn't a draft, and the CLI shows its details. +Put credentials in the action's `secrets`, never in `environmentMapping`, +which the service returns in plain text. It needs the same role and +organization setting as `apps create`; otherwise the service answers +`AUTOMATION_FORBIDDEN`, exit `3`. + +`apps actions create` doesn't ask before it acts and takes no `--yes`: confirm +the app, version and action with the user first. + +## Create a pipeline + +```sh +unity pipeline automation pipelines create --file pipeline.json --cloud-org "" --format json +unity pipeline automation pipelines create --file pipeline.json --name "Nightly Build" --version 1.0.0 --tag nightly --cloud-org "" --format json +unity pipeline automation pipelines create --file saved-version.json --name "Nightly Copy" --version 1.0.0 --cloud-org "" --format json +``` + +`pipelines create` creates a pipeline in the organization and its first +version, a draft. The result is that version, shaped as `pipelines get` shows +one: the new pipeline's ID is `data.pipeline.id`, not the version object's +`id`. Pass that ID to `pipelines get`, `pipelines versions` and, once the +version is published, `pipelines trigger`. + +| Option | Sets | +|---|---| +| `--name`, `--description`, `--version` | Required, from the option or `--file`. Name 2 to 57 letters, digits, spaces or hyphens, description 20 to 256 characters, version like `1.0.0`, `1.0.0-rc.1` or `1.0.0-sha.abc1234` | +| `--tag` (repeatable) | Tags, replacing the file's | +| `--id ` | The pipeline's ID, instead of a generated one | +| `--file ` | The pipeline as JSON (`-` reads stdin); options override its fields | + +The file holds what no option sets: `steps`, `inputParameters`, +`outputParameters`, `secrets`, `storages` and `metadata`. Each step has an `id` +(lowercase letters, digits and hyphens), a `name`, and exactly one of `action`, +`pipeline` or `suspend`; copy a step's shape from `pipelines versions get +--format json` rather than guessing it. Any other field in the file is left +out. A saved `pipelines versions get --format json` result works as `--file`: +the CLI takes its pipeline's name, description and tags and its version's +steps, parameters, secrets, storages and metadata, and leaves the existing +pipeline's ID behind. Pass a new `--name` and a `--version` for the copy. +`--format json` prints secret values and `masked` parameter values as `***` +and leaves out credential fields, so a copy refuses (exit `2`) while any value +is still `***`: put the real values back, or remove those fields, and add back +any credentials the copy needs. + +Lengths, the name's characters, the version, the ID, and `steps` being an +array are checked before any request (exit `2`). The service checks the steps +themselves, and refuses an `--id` already in use, with exit `6` and its +details. Creating a pipeline needs the Automation Developer role; otherwise the +service answers `AUTOMATION_FORBIDDEN`, exit `3`. Only organization-wide +pipelines are created; the CLI doesn't create a project's pipelines. + +`pipelines create` doesn't ask before it acts and takes no `--yes`: confirm the +name and organization with the user first. + ## Trigger a pipeline and watch a job ```sh diff --git a/skills/unity-cli/references/collaboration.md b/skills/unity-cli/references/collaboration.md index cac896b..cf91144 100644 --- a/skills/unity-cli/references/collaboration.md +++ b/skills/unity-cli/references/collaboration.md @@ -39,9 +39,11 @@ Relative links in this file resolve to the skill directory's `references/` folde **Project scoping — `--cloud-project` OR an inferred project.** The project-scoped commands (`annotations`, `attachments`, `reactions`, `thumbnail`, `read`, `subscribe`, `unsubscribe`, and `jira issues create/get/link/unlink/search/types`) take both `--cloud-project ` (Unity Cloud -project id — find one with `unity cloud projects`, see [auth-license-cloud.md](auth-license-cloud.md)) -and `--project-path `. It takes an id only, not a project name. Neither is required: resolution -order is +project id or name — find one with `unity cloud projects`, see [auth-license-cloud.md](auth-license-cloud.md)) +and `--project-path `. A UUID is used as the project id. Any other value is a name, looked up +in the organization in scope: `--cloud-org`, else `UNITY_CLOUD_ORG`, else the stored default +organization. With no organization in scope a name is a usage error that names `--cloud-org`. An +ambiguous name fails and lists its matches. Neither option is required: resolution order is 1. explicit `--cloud-project`, else 2. the `UNITY_CLOUD_PROJECT` env var, else @@ -232,7 +234,7 @@ Annotation objects returned by `get`/`list`/`replies` (`--format json`) carry: ` | `annotations create` | `` | `--text`, `--reply-to `, `--status Active\|Draft`, `--metadata k=v`…, `--target-context k=v`…, `--camera`, `--local`, `--time`, `--attachments`, `--unresolve-root-annotation` | | `annotations delete` | `` | (confirmation — see Shared behavior) | | `annotations delete-fields` | ` ` | removes metadata fields; variadic; confirmation | -| `annotations export` | — | `--target ` — omitted, no target is sent and the export covers the whole project, see below; `--out ` (else stdout), `--resolve-users`; the service returns `assetId` + `assetName` here that `list` does not — the CLI copies the response page verbatim, so treat those as service behavior | +| `annotations export` | — | `--target ` — **defaults to `assets/projects//**` only**, see below; `-o, --output ` (else stdout), `--resolve-users`; the service returns `assetId` + `assetName` here that `list` does not — the CLI copies the response page verbatim, so treat those as service behavior | | `annotations get` | `` | `--fields a,b,c` or `--fields all` (table output only), `--resolve-users` | | `annotations` | — | `--query ` (optional — defaults to root threads only), `--next `, `--limit 1-100` (default 10), `--all`, `--sort Ascending\|Descending`, `--sort-field annotationId\|latestReply`, `--include-fields a,b`, `--fields a,b` or `--fields all` (table output only), `--full`, `--resolve-users` | | `annotations replies` | `` | `--next`, `--limit 1-100`, `--all`, `--sort`, `--status-filter All\|Active\|Sending\|Draft` (repeat flag), `--fields a,b` or `--fields all` (table output only), `--full`, `--resolve-users` | @@ -259,18 +261,20 @@ unity collaboration annotations --include-fields replyCount,latestReply --format unity collaboration annotations --cloud-project $PROJ \ --query '[{"type":"hasNot","field":"annotationParentId"}]' --all --format ndjson -# Export for offline analysis: the bare command sends no target (the whole project) -unity collaboration annotations export --cloud-project $PROJ --out annotations.json -# Restrict it to one asset +# Export for offline analysis — ONE prefix tree per run; the bare command covers +# only assets/**, so an Editor-annotated project needs both invocations. unity collaboration annotations export --cloud-project $PROJ \ - --target "unity/projects/$PROJ/assets//**" --out annotations-asset.json + --target "assets/projects/$PROJ/**" --output annotations-assets.json +unity collaboration annotations export --cloud-project $PROJ \ + --target "unity/projects/$PROJ/**" --output annotations-editor.json ``` -**`export` with no `--target` sends no target.** The request carries only the page size, which asks -the service for the whole project; no path prefix decides what is included. Compare its `count` with -`annotations count --grouped` per prefix when completeness matters. A `--target` the service finds no -assets for fails with HTTP 500 "No assets found for the provided ids"; the error then names the target -and suggests running without `--target`. +**`export` is not a whole-project export.** With no `--target` the command defaults to +`assets/projects//**`, so annotations under the separate `unity/projects//**` +tree are silently absent from the archive — and nothing in the output says so. Always pass `--target` +explicitly, once per prefix, when completeness matters. (Note the default differs from +`annotations count`, which defaults to the `unity/**` tree instead.) The CLI's own `--target` help +text says "the whole project", which contradicts the actual default — trust the prefix above. When the service answers an export with HTTP 500 "No assets found for the provided ids", an annotation points at an asset that no longer exists and the service refuses the whole export without naming it. The CLI @@ -327,7 +331,7 @@ over a camera view), **spatial** (labeled 3D anchor) — payload shapes in |---|---|---| | `attachments` | `` | `--resolve-users` | | `attachments delete` | ` ` | (confirmation — see Shared behavior) | -| `attachments download` | ` ` | `--out ` (default: the attachment's original filename in CWD, falling back to `` when it has no file path), `--force` (overwrite), `--width ` (resize image) | +| `attachments download` | ` ` | `-o, --output ` (default: the attachment's original filename in CWD, falling back to `` when it has no file path), `--force` (overwrite), `--width ` (resize image) | | `attachments upload` | ` ` | `--name` (display name), `--content-type` (override inferred MIME) | | `attachments add file` | ` ` | same options and **same handler** as `upload`; only the reported command label, the success message, and the JSON error code (`COLLAB_ATTACHMENTS_ADD_ERROR`) differ — use either | | `attachments add sketch` | `` | `--sketch-data ` **(required)**, `--camera ` **(required)**, `--time `, `--preview `, `--sketch-image `: pass **both files or neither** (one alone exits 2, `COLLAB_SKETCH_FILES_INCOMPLETE`, before any request) | @@ -347,7 +351,7 @@ unity collaboration attachments add spatial $ANNOTATION_ID --cloud-project $PROJ # Download; refuses to overwrite an existing file unless --force unity collaboration attachments download $ANNOTATION_ID $ATTACHMENT_ID --cloud-project $PROJ \ - --out ./shot.png --force + --output ./shot.png --force ``` Notes: @@ -374,7 +378,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` | `` | `--out ` (default `./thumbnail`), `--width ` (an integer of at least 50); **no `--force`** — errors if the file exists ("Delete it first") | +| `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) | | `subscribe` / `unsubscribe` | `` | per-thread notification subscription for the current user | @@ -388,7 +392,7 @@ unity collaboration unsubscribe $ANNOTATION_ID --cloud-project $PROJ # Thread thumbnails unity collaboration thumbnail upload $ANNOTATION_ID ./shot.png --cloud-project $PROJ -unity collaboration thumbnail download $ANNOTATION_ID --out ./thumb.png +unity collaboration thumbnail download $ANNOTATION_ID --output ./thumb.png ``` --- @@ -417,9 +421,10 @@ Connects Collaboration annotations to Jira. Three layers, three id types — don | `jira issues create/get/link/unlink/search/types` | `--cloud-project` / `--project-path`, or inferred — see [Shared behavior](#shared-behavior) | **The organization** of `jira server *`, `jira project add`/`delete`/`update` and `jira issues` -is `--cloud-org `, else the `UNITY_CLOUD_ORG` env var, else the stored default organization +is `--cloud-org `, else the `UNITY_CLOUD_ORG` env var, else the stored default organization (`unity cloud org set-default`, see [auth-license-cloud.md](auth-license-cloud.md)). It takes an -organization id only, not a name. An empty or whitespace-only flag or variable counts as not set. +organization id or name, and a name is matched against your organizations. An empty or whitespace-only +flag or variable counts as not set. Only when none of the three gives one is it missing. `jira configs` is the exception: it reads its scope only from what you type, apart from `UNITY_CLOUD_PROJECT` when you type neither option. diff --git a/skills/unity-cli/references/diagnostics-maintenance.md b/skills/unity-cli/references/diagnostics-maintenance.md index 97e756d..1c780ad 100644 --- a/skills/unity-cli/references/diagnostics-maintenance.md +++ b/skills/unity-cli/references/diagnostics-maintenance.md @@ -366,9 +366,10 @@ Separately again, every run (CI, an agent, a machine `--format` included) sends - explicitly turning analytics off (`unity analytics opt-out`, an opt-out answered at an older CLI's prompt, or turning it off in the Hub while signed in to the Hub; a Hub opt-out made while signed out is not visible to the CLI and does not stop it); - `DO_NOT_TRACK` set to any value but empty, `0` or `false` ([consoledonottrack.com](https://consoledonottrack.com)); +- `UGS_CLI_TELEMETRY_DISABLED` set to any value but empty, `0` or `false`, the same switch under the UGS CLI's name; - `UNITY_NO_CLI_INVOKED_TELEMETRY` set to any value. -`DO_NOT_TRACK` also stops the upload of opt-in usage data, even when you opted in. Usage data never holds a command for long: on a slow or unreachable network the CLI gives up on it after half a second. `unity analytics status` says what is collected, links the privacy policy, and reports whether the ping is on and why it is off. None of these settings stop the licensing records `unity license activate` files. +`DO_NOT_TRACK` or `UGS_CLI_TELEMETRY_DISABLED` also stops the upload of opt-in usage data, even when you opted in. Usage data never holds a command for long: on a slow or unreachable network the CLI gives up on it after half a second. `unity analytics status` says what is collected, links the privacy policy, and reports whether the ping is on and why it is off. None of these settings stop the licensing records `unity license activate` files. --- @@ -600,6 +601,8 @@ unity completion fish 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. + --- ### Bug — report a bug @@ -626,7 +629,7 @@ Prompts for title, description, email, reproducibility level, and which area the The report can also be supplied entirely through flags — `--title`, `--description`, `--steps` (repeatable, one line per value), `--reproducibility `, and `--email` (defaults to your Unity account email when signed in; otherwise required). On a terminal, any flags you pass skip their prompts and the remaining fields still ask; a non-interactive run submits without prompting. A non-interactive run with missing or invalid fields fails fast with a usage error (exit 2) listing the exact flags to add. -Use `--area ` to say which part of Unity the issue is in: the CLI itself, the connection to the Editor or the Pipeline package (`com.unity.pipeline`), the Editor or your project, licensing and signing in, or one of the plugins (`ugs`, `plastic`, `ai`, `transform`). Pass it whenever you know, because a failure that surfaces in CLI output is otherwise easy to misroute as a CLI bug when the Editor or the Pipeline package is at fault. It's optional and never blocks a report: pass `not-sure` when you don't know, or leave it out. On a terminal without `--area`, the reporter asks, with "Not sure" preselected; a non-interactive run without it submits with no area, the same report it sent before the flag existed. An unknown value is a usage error (exit 2). The answer is sent with the report as an `Issue area:` line in the report text, which is what triage sees. On a terminal, a plugin is offered as an area only while it is installed. A plugin area names the plugin and its installed version, and attaches the newest `.log` and `.txt` files from the log directories the plugin registry lists for it, redacted and size-capped like the other logs. Every report also lists the plugins installed on the machine, with their versions, as an `Installed plugins:` line. +Use `--area ` to say which part of Unity the issue is in: the CLI itself, the connection to the Editor or the Pipeline package (`com.unity.pipeline`), the Editor or your project, licensing and signing in, or one of the plugins (`ugs`, `plastic`, `ai`, `transform`, `assetlibrary`). Pass it whenever you know, because a failure that surfaces in CLI output is otherwise easy to misroute as a CLI bug when the Editor or the Pipeline package is at fault. It's optional and never blocks a report: pass `not-sure` when you don't know, or leave it out. On a terminal without `--area`, the reporter asks, with "Not sure" preselected; a non-interactive run without it submits with no area, the same report it sent before the flag existed. An unknown value is a usage error (exit 2). The answer is sent with the report as an `Issue area:` line in the report text, which is what triage sees. On a terminal, a plugin is offered as an area only while it is installed. A plugin area names the plugin and its installed version, and attaches the newest `.log` and `.txt` files from the log directories the plugin registry lists for it, redacted and size-capped like the other logs. Every report also lists the plugins installed on the machine, with their versions, as an `Installed plugins:` line. Use `--attachments ` (repeatable) to attach extra files — for example a crash log or a zipped copy of a subset of assets. Each path must be an existing, readable file; a folder is rejected (zip it yourself first), and a missing or unreadable path fails fast with a usage error (exit 2) naming the offending path. diff --git a/skills/unity-cli/references/editors-install.md b/skills/unity-cli/references/editors-install.md index bd2990a..2c11ef7 100644 --- a/skills/unity-cli/references/editors-install.md +++ b/skills/unity-cli/references/editors-install.md @@ -226,6 +226,9 @@ unity editor add /path/to/Unity/Editor # Skip fetching module metadata (faster, but modules won't be listed until refreshed) unity editor add /path/to/Unity/Editor --no-fetch-modules + +# Register an unsigned development build (for example a locally built trunk Editor) +unity editor add /path/to/Unity/Editor --skip-signature-check ``` --- @@ -364,20 +367,6 @@ unity install 6000.0.47f1 --download-only --operating-system windows -m il2cpp - Each payload is checked against its published size and checksum before the run reports success, and a payload that fails is removed. Only the modules you name with `-m` are fetched, and the license gate is unchanged: a non-interactive run needs `--accept-eula`. The envelope's items end as `downloaded` (listed in `data.completedUids`) and `data.path` is the download folder; the human summary says where the files are and that nothing was installed. `-d/--download-directory` still means a portable install and cannot be combined with it, nor can `--resume`, `--set-default` or `--list-modules` (exit 2). `--changeset` with another OS's `--operating-system` is still refused. -#### Headless Linux Editor (`--headless`) - -On Linux, a release can also ship a headless Editor that runs with no display, for CI and servers. `unity install` never picks it on its own: - -- `--headless` installs the headless Editor. A release without one, or a macOS or Windows target, fails with `INSTALL_HEADLESS_UNAVAILABLE`. The bundled catalog doesn't list the headless Editor, so the same error appears when the CLI falls back to it offline. -- Without it, the version picker (`unity install` with no version, on a terminal) asks which one, with the regular Editor selected. Any other run installs the regular Editor, even on a machine with no display. - -The headless Editor leaves out the modules it can't use, such as iOS and visionOS. A release without a headless Editor installs the regular one unless `--headless` was given. - -```bash -# A CI image: the headless Editor and Android support -unity install 6000.7.0f1 --headless -m android --accept-eula -``` - #### Linux arm64: experimental x86_64 Editor under FEX-Emu Unity ships no Linux arm64 Editor. On a Linux arm64 host you can opt in to running the x86_64 Editor under [FEX-Emu](https://github.com/FEX-Emu/FEX) by setting `UNITY_EXPERIMENTAL_FEX_EMU=1`. The opt-in takes effect only when a FEX-Emu entry point (`FEX`, or the older `FEXLoader`) is on PATH and an x86_64 RootFS resolves (`FEX_ROOTFS`, or the `RootFS` in FEX-Emu's own `Config.json`); `unity doctor` reports both as its `fex-emu` row. While it is active, `unity install` defaults to `x86_64`, and every Editor launch (`open`, `projects open`, `run`, `test`, `build`, `projects create`) runs as `FEX ` with no `binfmt_misc` needed. diff --git a/skills/unity-cli/references/integration-advanced.md b/skills/unity-cli/references/integration-advanced.md index f6a65d6..ee4cdb5 100644 --- a/skills/unity-cli/references/integration-advanced.md +++ b/skills/unity-cli/references/integration-advanced.md @@ -31,7 +31,7 @@ Relative links in this file resolve to the skill directory's `references/` folde 3. `--project-path ` — the Editor selector. With the flag absent, `UNITY_PROJECT_PATH` stands in for it. 4. Otherwise, the running Editor whose project directory **contains the current working directory**. With a project nested inside another, the deepest match wins. -**Pass `--project-path` whenever more than one Editor may be running.** Relying on step 4 means the target depends on the shell's cwd, which is rarely what an agent intends and is invisible in the command it ran. An agent working in its own worktree can instead prefix each call with `UNITY_PROJECT_PATH=`. An `export` only lasts as long as the shell, and most agent tools start a fresh shell for each command. `unity status` honors the variable too, but `unity recompile` does not: pass `--project-path` to it. +**Pass `--project-path` whenever more than one Editor may be running.** Relying on step 4 means the target depends on the shell's cwd, which is rarely what an agent intends and is invisible in the command it ran. An agent working in its own worktree can instead prefix each call with `UNITY_PROJECT_PATH=`. An `export` only lasts as long as the shell, and most agent tools start a fresh shell for each command. `unity status` and `unity recompile` honor the variable too. > `unity pipeline install` and `unity pipeline upgrade` take `--project-path` too, but they do **not** use this resolver — they pick among the editors that actually need the operation, showing an interactive selector on a terminal and a different, candidate-listing error without `data.candidates` otherwise. Everything below describes the shared resolver only. @@ -99,16 +99,31 @@ unity mcp --project-path /path/to/MyProject # Same, from the environment (the flag wins when both are set) UNITY_PROJECT_PATH=/path/to/MyProject unity mcp -# Expose only some tools, or hide some +# Expose only some commands, or hide some unity mcp --tools "script.eval,capture.*" unity mcp --exclude-tools "exec,script.eval,script.eval_file,test.run" + +# Hide every command that can destroy data or run code +unity mcp --exclude-annotations destructive + +# Hide whole command groups +unity mcp --exclude-tool-groups "scene,editor.*" + +# One tool per command group instead of one per command +unity mcp --tool-groups ``` -`--tools ` keeps only the tools whose names match the comma-separated list, and `--exclude-tools ` then hides the ones that match its list. In both, `*` matches any run of characters, and names are case-sensitive. Each tool 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. +`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. + +`--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. + +`--exclude-annotations ` hides the Editor commands whose MCP annotations include any entry of the comma-separated list: `read-only`, `destructive`, `idempotent` or `open-world`. `--exclude-annotations destructive` hides every command that deletes or overwrites data or runs code, such as `asset delete` and `script eval`. A call to a hidden command is refused before it reaches the Editor, with or without groups. Any other entry is a usage error that lists the four. `unity mcp` no longer accepts `--instance `: talking to an Editor requires that Editor's per-instance auth token, which a bare host and port can't carry, so the CLI always discovers running Editors itself — run from the project directory or pass `--project-path` to target one. Editors launched to create a new project (`-createproject`) are discovered too. -`unity mcp --cli-tools` also lists six read-only tools that run the CLI's own commands with no Editor running: `unity-status`, `unity-editors-list` (installed editors), `unity-projects-list`, `unity-projects-info`, `unity-releases` and `unity-doctor`. Each answers with the command's `--format json` envelope. Use it for an MCP client with no shell, such as Claude Desktop; `unity mcp configure` doesn't write the flag, so add it to the entry's arguments. +`unity mcp --cli-tools` also lists six read-only tools that run the CLI's own commands with no Editor running: `unity-status`, `unity-editors-list` (installed editors), `unity-projects-list`, `unity-projects-info`, `unity-releases` and `unity-doctor`. Each answers with the command's `--format json` envelope. Use it for an MCP client with no shell, such as Claude Desktop; `unity mcp configure` doesn't write the flag, so add it to the entry's arguments. The same goes for `--exclude-annotations` and `--exclude-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. @@ -479,7 +494,7 @@ completion and exits on its own (the log ends `Exiting batchmode successfully no three patterns below. Any resident Editor (batch or GUI) then answers in ~200–600 ms with no recompile and no domain reload, so an agent can iterate in a single session. -**Persistent headless (no GUI) — agent / SSH build box.** Launch the Editor binary directly in batch +**Persistent batch mode (no GUI) — agent / SSH build box.** Launch the Editor binary directly in batch mode and **omit `-quit`** so it stays resident and keeps serving the Pipeline API. The binary lives inside the install dir reported by `unity editors --installed` (`location`). @@ -536,7 +551,7 @@ registered command, prints its result, and exits — a fresh boot each time (no unity run /path/to/MyProject --command spawn_light --format ndjson -- --name Sun ``` -A resident Editor (headless or GUI) holds a license seat until it exits; the one-shot path releases it +A resident Editor (batch mode or GUI) holds a license seat until it exits; the one-shot path releases it on exit. #### pipeline (alias: pipe) — manage the Unity Pipeline package @@ -703,6 +718,8 @@ unity commands Each node in `data.commands` carries `name`, `aliases`, `description`, `arguments` (positional, with `required`/`variadic`), `options` (this command's own flags: `long`/`short`/`valuePlaceholder`/`default`/`description`), `globalOptions` (same shape — flags inherited from every ancestor, so `--format`/`--json`/etc. show up on every node without repeating a root-level dump, and a mid-tree umbrella's own options show up on its descendants too), and `subcommands` (the same shape, recursively). Hidden and dev-only surfaces are excluded — the same visibility rule `--help` uses — so what you see is exactly what the current build actually exposes. +**Add the connected Editor's commands: `unity commands --include-editor`.** The manifest then also lists the Pipeline commands of the Editor for the project `UNITY_PROJECT_PATH` names, else the one in the working directory, after the CLI's own. Every top-level entry carries `source`: `cli` for the CLI's commands, `editor` for the Editor's. An Editor entry has the node shape above (no aliases, arguments or subcommands; one option per parameter) plus `group`, `invoke` (`unity command `) and `parameters`, each with `name`, `type`, `required`, `description` and, when the Editor gives one, `default`. `data.editor` says whether the Editor was asked: `{"checked": true}`, or `{"checked": false, "reason": ...}` with `noEditor`, `ambiguous`, `failed` or `timedOut`, plus a warning naming the command that helps. The Editor gets at most 3 seconds. Without the flag the manifest never contacts an Editor. The human listing adds an `Editor commands` section, and the tsv rows add `command ` paths. + **Search it instead of dumping it: `unity commands --grep `** (or `unity command --query `, the same search). The same tree, plus the plugin catalog (the same universe `unity plugins` reports, installed or not) and the Pipeline commands of the live connected Editor, filtered to what matches. A command matches on its full path (`plugins`), name, aliases, description, arguments, or its own options; the inherited global options are not searched, since every command has them. A plugin matches on its id, display name, registry description, or the command word that runs it (`ugs`, `uvcs`, `cm`, `ai`): ```bash @@ -863,7 +880,7 @@ sandbox on that platform necessarily behaves this way: for a live connection — outside a sandboxed environment, the same "no Editor" result usually does mean what it says. - Don't quietly substitute a different workflow instead — e.g. driving a separate - headless Editor process to approximate what the live connection would have done. + batch-mode Editor process to approximate what the live connection would have done. That produces a different result (sometimes an incomplete one, materializing only once something else runs) without ever telling the user their task was rerouted. Say what's actually happening — sandbox suspected, live connection unavailable — @@ -935,7 +952,7 @@ first, then fix the compile errors at the source and restart: read the **narrowest** log available, in this order — each one after the first widens what you are reading: - 1. the `-logFile ` you launched the Editor with (see the persistent-headless launch above); + 1. the `-logFile ` you launched the Editor with (see the persistent batch-mode launch above); 2. `/Logs/Editor.log` — Unity 6 moves logging there early in boot, so it usually exists for the versions this workflow applies to; 3. the per-user **global** `Editor.log` below — the fallback older editors write, and the same log @@ -1092,7 +1109,7 @@ unity shell - Ctrl-C cancels a cancellable running command (such as `build`) and returns to the prompt; for a command that doesn't yet support cancellation the first Ctrl-C is held (with a hint) and a second quick press force-quits the session. - The prompt terminator is a heavy angle (`❯`) on Unicode-capable terminals, falling back to `>`; it shows the previous command's exit code when it was non-zero. - **Command history** persists across sessions — press ↑/↓ to recall previous commands (stored under the CLI data directory, capped at the most recent 1000 entries). Secret-bearing flag values (`--android-keystore-password`, `--client-secret`, `--serial`, `--git-token`, and the other keystore/token flags) are masked to `***` before being written to disk. -- **Tab completion** — press Tab to complete command names, subcommands, option flags, and option values (for example `--format`) against the live command tree, plus the shell's own builtins. +- **Tab completion** — press Tab to complete command names, subcommands, option flags, and option values (for example `--format`) against the live command tree, plus the shell's own builtins. After `command`, Tab offers the connected Editor's commands and the chosen command's parameters, waiting at most 1 second for the Editor. - Interactive prompts (confirmations, sign-in) work inside the shell, and a write in one command (`auth logout`, `config`, `editors default`, …) is visible to the next. - Piped/scripted sessions (`… | unity shell`) run every line and exit with the first command that failed (0 when every command succeeds), so a batch is usable in automation with `$?`. Interactive sessions still exit 0. - In a piped session and in `--protocol ndjson` mode, stdin carries the shell's own commands, so a command the shell dispatches sees an **empty stdin**. `--secret-from-stdin` and `--key-from-stdin` therefore read nothing there and report a missing secret (exit 2). `--git-token-stdin` reports nothing: it resolves no token and falls through to `--git-token`, the provider token environment variable, and the credential helper, so a clone or link can proceed with an ambient credential. Plugin lines (`unity-*` on PATH) are the exception: they still inherit the shell’s stdin and can read its command stream. Pass the secret another way (`--client-secret`, `--key`, `--git-token`, or its environment variable), or run that command outside the shell with the secret piped to it. diff --git a/skills/unity-cli/references/playmode-verification-loop.md b/skills/unity-cli/references/playmode-verification-loop.md index b2ef306..773e094 100644 --- a/skills/unity-cli/references/playmode-verification-loop.md +++ b/skills/unity-cli/references/playmode-verification-loop.md @@ -217,6 +217,15 @@ unity command console get -- --tail 50 --level error only need the compile-failure flag and entry counts, not the entries themselves, to poll cheaply while something else runs. +**Never run `console clear` to get a clean slate.** It empties the user's own **Console** window +too, including errors they asked you to fix. A failed Editor command also logs an Error there, so +red entries you caused are expected. To read only what your own steps logged, note the cursor that +`console status` returns before you start, then read from it: + +```bash +unity command console get -- --since --level error +``` + Older `com.unity.pipeline` documentation names this command `get_console_logs`, and before command groups it was `console` (with `console_status` and `clear_console` alongside it); the currently shipping command is `console get` (with `console status` and `console clear`), which is a diff --git a/skills/unity-cli/references/projects-templates.md b/skills/unity-cli/references/projects-templates.md index c0b4ee9..370ca7e 100644 --- a/skills/unity-cli/references/projects-templates.md +++ b/skills/unity-cli/references/projects-templates.md @@ -43,6 +43,7 @@ unity open /path/to/MyProject unity close /path/to/MyProject unity close /path/to/MyProject --timeout 60 unity close /path/to/MyProject --force +unity close /path/to/MyProject --if-saved # Same command, under the projects umbrella unity projects close /path/to/MyProject @@ -58,7 +59,7 @@ unity open /path/to/MyProject --accept-upgrades # Return once the Editor is ready for commands; fail fast if a dialog stops it unity open /path/to/MyProject --until-ready --timeout 600 --format json -# Start a headless batch-mode Editor and return once it is ready; stop it with unity close +# Start a batch-mode Editor and return once it is ready; stop it with unity close unity open /path/to/MyProject --batchmode --until-ready --format json # Open with a specific editor version @@ -93,7 +94,7 @@ Dialogs are matched by their English titles, so an Editor in another UI language **`command editor dialog` reads and answers the dialog an Editor waits on.** `unity command editor dialog` prints the dialog on top: its id, title, message and buttons. `unity command editor dialog answer