refactor(unity-cli): split command catalog into references + index

skills/unity-cli/references/auth-license-cloud.md

@@ -0,0 +1,105 @@
+#  — unity-cli command reference
+
+Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags,
+environment variables, exit codes, and common workflows. All global flags (`--format json`,
+`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below.
+
+---
+
+### Auth
+
+```bash
+# Check login status
+unity auth status --format json
+
+# Login (opens browser for OAuth)
+unity auth login
+
+# Login with service account credentials (CI — skips browser)
+# Preferred: read secret from stdin to avoid shell-history and process-list exposure
+unity auth login --client-id <id> --secret-from-stdin
+
+# A --client-secret flag also exists, but passing a secret as a
+# command-line argument exposes it in shell history and the process list.
+# Avoid it — use --secret-from-stdin (above) or the
+# UNITY_SERVICE_ACCOUNT_ID / UNITY_SERVICE_ACCOUNT_SECRET env vars instead.
+
+# Login without persisting credentials to the keyring (ephemeral CI)
+unity auth login --client-id <id> --secret-from-stdin --no-store
+
+# Logout (clears both service-account and OAuth credential slots)
+unity auth logout
+
+# Skip the confirmation prompt
+unity auth logout --yes
+```
+
+**Separate sign-in from Hub.** As of `0.1.0-beta.8`, the CLI and the GUI Hub store their sign-in credentials **separately** — signing in to one no longer signs you out of (or overwrites the account of) the other, so each can stay signed in as a different account. (In earlier betas they shared a single keyring session.)
+
+**Service-account credentials via env vars** (`UNITY_SERVICE_ACCOUNT_ID` + `UNITY_SERVICE_ACCOUNT_SECRET`) mint bearer tokens automatically for the duration of the process — no browser round-trip, no keyring write. If only one of the two is set, the CLI prints a warning on stderr instead of silently falling back to the keyring/OAuth identity.
+
+The interactive `unity auth login` flow prints the sign-in URL to the terminal **before** attempting to launch the browser, which unblocks remote/headless sessions (SSH, containers, dev VMs) where `xdg-open` / `open` has no graphical session to attach to. With `--format json`, an `auth_url=…` progress frame is emitted so machine consumers can capture the URL without parsing human text.
+
+`unity auth status` reflects real session state (including an explicit "session expired" message), not optimistic local assumptions. `unity doctor` and `unity cloud status` report the same real session state.
+
+---
+
+### License — list, activate, return
+
+```bash
+# List the Unity licenses active on this machine
+unity license
+unity license list             # explicit form, identical output
+unity license --format json    # machine-readable
+
+# Summary: active license(s) + sign-in state
+unity license status
+
+# Activate a license — choose exactly one mode (default = signed-in subscription)
+unity license activate                              # signed-in user's subscription (entitlement) licenses
+unity license activate --serial SC-…                # serial-based (ULF) activation, no sign-in needed
+unity license activate --personal --accept-eula     # free Unity Personal license (must accept the EULA)
+unity license activate --floating                   # lease a seat from the configured floating server
+unity license activate --file ./Unity_lic.ulf       # offline activation from a .ulf / .xml file
+unity license activate --generate-request ./req.alf # write an offline activation request (air-gapped)
+
+# Return the active assigned/subscription licenses (prompts to confirm; --yes skips)
+unity license return
+unity license return --yes
+
+# Floating (network) license server
+unity license server list      # the configured floating license server(s)
+unity license server status    # reachability + available seats
+```
+
+`list` columns: product, license type (`Floating` / `Assigned` / `ULF`), organization, and expiry. `status` prints a one-glance summary — the active license(s) and whether you're signed in — and exits non-zero (`4`) when no license is active, so it works as a scriptable health check. The first licensing command downloads the Unity licensing client on demand; as of `0.1.0-beta.8`, if the client is unavailable `list` reports a clear error and exits non-zero (matching `status`), rather than printing an empty list.
+
+`activate` takes a single mode flag (combining them is a usage error). The default (no flag) and `--personal` activate the signed-in user's entitlements — sign in first with `unity auth login`. `--personal` also requires `--accept-eula` to acknowledge the Unity Personal license terms. `--serial` / `--file` work offline without sign-in. `--floating` requires a configured floating license server (exit `4` if none is set). `--generate-request` writes a `.alf` request for air-gapped activation instead of activating. `return` returns the active licenses, prompting for confirmation first — pass `--yes` to skip (required in non-interactive shells and with `--json`). All honor `--json` / `--format` and exit non-zero on failure (`2` bad usage, `3` sign-in required, `4` floating not configured, `6` licensing-client error).
+
+`unity license server list` shows the configured floating license server (from the `licensingServiceBaseUrl` machine setting; a pure settings read, no client download). `unity license server status` contacts that server and reports reachability plus available seats — exit `4` when no server is configured, `6` when configured but unreachable.
+
+---
+
+### Cloud — Unity Cloud organizations and projects
+
+Requires being signed in (`unity auth login`).
+
+```bash
+# Show cloud sign-in state and active organization
+unity cloud status --format json
+
+# Organizations
+unity cloud org list --format json
+unity cloud org current                       # print the active default org id
+unity cloud org set-default <id-or-name>      # set active default org
+unity cloud org clear-default                 # revert to "All Organizations"
+
+# Projects in the active organization
+unity cloud project list --format json
+
+# Override the active organization for a single call
+unity cloud project list --cloud-org <id-or-name>   # also via UNITY_CLOUD_ORG env var
+```
+
+---
+

skills/unity-cli/references/build-run-test.md

@@ -0,0 +1,133 @@
+#  — unity-cli command reference
+
+Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags,
+environment variables, exit codes, and common workflows. All global flags (`--format json`,
+`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below.
+
+---
+
+### Run — batch/headless execution
+
+```bash
+# Run a Unity project headless (batch mode is automatic — do NOT pass -batchmode/-quit)
+unity run /path/to/MyProject -- -executeMethod Builder.Build
+
+# Override editor version
+unity run /path/to/MyProject --editor-version 6000.0.47f1 -- -nographics -logFile out.log
+
+# Install editor automatically if missing
+unity run /path/to/MyProject --allow-install -- -executeMethod Builder.Build
+
+# Kill the Unity process after 300 seconds (useful in CI to prevent hangs)
+unity run /path/to/MyProject --timeout 300 -- -executeMethod Builder.Build
+# Equivalent via env var:
+UNITY_RUN_TIMEOUT=300 unity run /path/to/MyProject -- -executeMethod Builder.Build
+```
+
+`unity run` always launches the editor in batch mode and forwards the args after `--` to the Unity executable, then returns the editor's exit code.
+
+**Reserved flags — do NOT pass these after `--`.** The command adds them itself: `-batchmode`, `-quit`, `-projectPath`, `-useHub`, `-hubIPC`. Passing any of them fails fast (before launch) with exit code 6:
+
+```
+Error: Forwarded argument '-batchmode' conflicts with a reserved Unity flag managed by this command. Remove it from the args after `--`.
+```
+
+Flags like `-nographics`, `-logFile <path>`, and `-executeMethod <Class.Method>` are not reserved and are forwarded normally.
+
+When `--timeout <seconds>` is set, the process receives SIGTERM at the deadline; if still alive after 2 s it receives SIGKILL. The command exits with code 6 (EXIT_COMMAND_FAILURE) on timeout.
+
+---
+
+### Test — run EditMode/PlayMode tests
+
+```bash
+# Run tests and write an NUnit XML report (omitting --mode runs the editor's default platform)
+unity test /path/to/MyProject
+
+# Run a specific platform (--mode is case-insensitive: EditMode/editmode both work)
+unity test /path/to/MyProject --mode EditMode
+unity test /path/to/MyProject --mode PlayMode --output ./results/play.xml
+
+# Run only tests whose names match a filter
+unity test /path/to/MyProject --filter "MyNamespace.MyTests"
+
+# Pin the editor version, installing it if missing; cap the run at 600 s
+unity test /path/to/MyProject --editor-version 6000.0.47f1 --allow-install --timeout 600
+# Equivalent via env var:
+UNITY_TEST_TIMEOUT=600 unity test /path/to/MyProject
+
+# Forward extra editor args after -- (reserved test flags are rejected)
+unity test /path/to/MyProject -- -nographics
+```
+
+`unity test` launches the editor's built-in test runner in batch mode (`-runTests -testPlatform <mode> -testResults <path> -testFilter <pattern>`), waits for it to finish, and writes the report to `--output` (default `test-results.xml`). It exits 0 when the run succeeds and 6 (EXIT_COMMAND_FAILURE) when the editor exits non-zero — i.e. reports test failures or fails to run. It runs the tests **directly via the editor command line** — no pipeline package or server is involved. `--mode` is optional; when omitted, `-testPlatform` is not passed and the editor runs its default platform.
+
+It deliberately does **not** pass `-quit`: `-runTests` quits the editor itself once results are written, so forcing `-quit` would terminate it before the report exists. Anything after `--` is forwarded to the editor verbatim, except reserved flags managed by the command (`-projectPath`, `-batchmode`, `-runTests`, `-testPlatform`, `-testResults`, `-testFilter`, `-quit`, `-useHub`, `-hubIPC`), which are rejected.
+
+Options: `--mode EditMode|PlayMode`, `--filter <pattern>`, `--output <path>`, `--editor-version <version>` (env `UNITY_EDITOR_VERSION`), `-e, --editor-path <path>`, `-a, --architecture <arch>`, `--allow-install`, `--timeout <seconds>` (env `UNITY_TEST_TIMEOUT`).
+
+---
+
+### Build
+
+`--target` and `--execute-method` are both **required** — Unity has no built-in command-line build, so your `executeMethod` is responsible for the actual build (including honoring `--output-path`).
+
+```bash
+# Build a project (requires --target and --execute-method)
+unity build /path/to/MyProject \
+  --target StandaloneOSX \
+  --execute-method Builder.PerformBuild \
+  --output-path ./build/output
+
+# Common build targets: StandaloneOSX, StandaloneWindows64, StandaloneLinux64, Android, iOS, WebGL
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--target <target>` | Build target (required). |
+| `--execute-method <method>` | Static C# method to invoke, e.g. `Builder.PerformBuild` (required). |
+| `--build-target-group <group>` | Forwarded to Unity as `-buildTargetGroup`. |
+| `-o, --output-path <path>` | Passed as `-buildOutput` (your method must honor it). |
+| `-l, --log-file <path>` | Log file path. Default: `<project>/Logs/build-<target>-<timestamp>.log`. |
+| `--editor-version <version>` | Override editor version (default: from `ProjectVersion.txt`). |
+| `-e, --editor-path <path>` | Use a specific editor binary. |
+| `-a, --architecture <arch>` | Editor architecture (`x86_64` or `arm64`). |
+| `--args <string>` | Extra arguments passed to Unity (shell-split). |
+| `--no-tail` | Do not stream the log to stdout in real time. |
+| `--allow-install` | Install the project's editor version if missing. |
+| `--versioning-strategy <strategy>` | `semantic`, `tag`, `custom`, or `none` (default: `none`). |
+| `--build-version <version>` | Explicit version string; only used with `--versioning-strategy custom`. |
+| `--allow-dirty-build` | Skip the uncommitted-changes guard (default: false). |
+
+**Android signing & export** (applied to Android targets only):
+
+| Flag | Description |
+|---|---|
+| `--android-export-type <type>` | `apk`, `aab`, or `android-studio-project`. |
+| `--android-keystore-base64 <b64>` | Keystore file, base64-encoded. |
+| `--android-keystore-password <pass>` | Keystore password. |
+| `--android-key-alias <alias>` | Key alias within the keystore. |
+| `--android-key-alias-password <pass>` | Key alias password. |
+| `--android-target-sdk-version <N>` | Target SDK version. |
+| `--android-symbol-type <type>` | `none`, `public`, or `debugging`. |
+| `--android-version-code <N>` | Android version code. |
+
+Keystore flags are validated together. Secrets passed as command-line flags surface in the process list and can be echoed into CI logs. Supply `--android-keystore-base64`, `--android-keystore-password`, and `--android-key-alias-password` from CI secret environment variables (e.g. `--android-keystore-password "$KEYSTORE_PASSWORD"`), never as inline literals, and source those variables from a dedicated CI secret store. Note that sourcing from an env var only avoids hard-coding the literal — the expanded value still appears in `argv`, so also mask it in CI log output.
+
+**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.
+
+```bash
+# With --format json, stdout includes newline-delimited JSON progress frames before the final envelope:
+unity build /path/to/MyProject --target StandaloneOSX --execute-method Builder.Build --format json
+# Output (each line is a JSON object):
+# {"type":"progress","command":"build","message":"Resolving project..."}
+# {"type":"progress","command":"build","message":"Resolving editor..."}
+# {"type":"progress","command":"build","message":"Starting Unity..."}
+# {"type":"progress","command":"build","message":"Unity exited (code 0)"}
+# { "success": true, "command": "build", "data": { "target": "...", "logFile": "..." } }
+```
+
+---
+

skills/unity-cli/references/config-hub.md

@@ -0,0 +1,103 @@
+#  — unity-cli command reference
+
+Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags,
+environment variables, exit codes, and common workflows. All global flags (`--format json`,
+`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below.
+
+---
+
+### Config — persisted CLI configuration
+
+The `config` command group manages settings that persist across invocations.
+
+#### config proxy
+
+View or change the configured HTTP/HTTPS/SOCKS/PAC proxy. The persisted value is read by every CLI command that issues outbound HTTP (releases, install, auth, telemetry, etc.).
+
+```bash
+# Show the effective proxy configuration (resolution source + auth source)
+unity config proxy
+unity config proxy --json
+
+# Persist a proxy URL
+unity config proxy http://proxy.example.com:8080
+
+# Embedded userinfo (user:password@host) is supported and redacted in echo
+# output, but prefer leaving credentials out of the URL — the CLI looks them
+# up in the OS keyring instead (see Resolution priority below).
+
+# Persist with bypass list (hosts that should NOT go through the proxy)
+unity config proxy http://proxy.example.com:8080 --bypass "localhost,127.0.0.1,*.internal"
+
+# SOCKS / PAC variants
+unity config proxy socks5://proxy.example.com:1080
+unity config proxy pac+http://wpad.example.com/proxy.pac
+unity config proxy pac+file:///etc/proxy.pac
+
+# Clear the persisted proxy
+unity config proxy --unset
+```
+
+**Supported schemes:** `http://`, `https://`, `socks://`, `socks4://`, `socks4a://`, `socks5://`, `socks5h://`, `pac+http://`, `pac+https://`, `pac+file://`.
+
+**Resolution priority** (highest → lowest):
+1. `--proxy <url>` global flag (one-shot override for the current invocation)
+2. `UNITY_PROXY` env var
+3. Standard env vars: `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY`
+4. Persisted `proxy.json` (`unity config proxy <url>`)
+5. System proxy settings (where supported)
+
+Credentials missing from the URL are looked up in the OS keyring (shared with the GUI Hub); Kerberos/SPNEGO-authenticated proxies are supported. `--proxy-disable` short-circuits all of the above for the current invocation, which is the recommended way to diagnose a misconfigured proxy without clearing it.
+
+#### config update-check
+
+New in `0.1.0-beta.8`. Enable or disable the background check for a newer CLI version (the unobtrusive "update available" notice; interactive sessions only, never delays a command). Equivalent to the `UNITY_NO_UPDATE_CHECK` env var.
+
+```bash
+unity config update-check          # show the current setting
+unity config update-check off      # disable
+unity config update-check on       # enable
+unity config update-check --json
+```
+
+---
+
+### Hub — install the Unity Hub application
+
+Bootstrap Unity Hub on a clean machine from the command line.
+
+```bash
+# Install the latest stable Hub for the current OS + architecture
+unity hub install
+
+# Install a specific Hub version
+unity hub install --hub-version 3.17.0
+
+# Force reinstall even when Hub is already detected
+unity hub install --force
+
+# Run the installer silently (Windows only)
+unity hub install --headless
+
+# Override architecture (e.g. x64 Hub on Apple Silicon via Rosetta)
+unity hub install --architecture x64
+
+# Skip the installer code-signature check (unsigned/local builds — not recommended)
+unity hub install --skip-signature-check
+```
+
+Options: `-f` / `--force`, `--headless` (silent installer, Windows only), `-a` / `--architecture x64|arm64` (env `UNITY_ARCHITECTURE`), `--hub-version <version>` (default latest), `--skip-signature-check`.
+
+**Integrity & signature verification** — every download is checked against the SHA-512 from the HTTPS manifest, then the installer's **code signature** is verified before it runs with elevation: on macOS via `codesign` (signer `Developer ID Application: Unity Technologies`), on Windows via Authenticode (signer subject `Unity Technologies`), checked *before* the UAC prompt. Verification is **fail-closed** — if it fails or the verifier is unavailable, the command aborts with exit 6 and does not run the installer. Linux `.AppImage` has no standard verifier, so it is SHA-512-only. Pass `--skip-signature-check` to bypass (prints a warning; not recommended).
+
+**`--hub-version` behaviour** — fetches the version-specific manifest from the CDN; if that version does not exist, the command exits with code 6 (no fallback to latest).
+
+```bash
+# JSON output
+unity hub install --format json
+```
+
+Emits `{ "success": true, "command": "hub install", "data": { "version": "3.x.x", "installed": true } }` on success, or an `{ "alreadyInstalled": true, "installedPath": "…" }` payload when Hub was already present.
+
+---
+