@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/unity-cli/SECURITY.md

@@ -0,0 +1,68 @@
+# Security notes — unity-cli skill
+
+This skill documents the official first-party [`unity` CLI](https://public-cdn.cloud.unity3d.com/hub/prod/cli/). A few of its capabilities are powerful by design and are flagged by automated skill scanners. They are intentional, first-party functionality with the safeguards described below.
+
+## Accepted risks
+
+These capabilities are accepted by design. Each is documented in full in the sections below; this table is the explicit, human-readable acknowledgment.
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Local Editor control and C# evaluation | Runs entirely on the local machine, as the current user, against the user’s own Editor — no remote access and no privilege the user lacks at their own terminal. |
+| `SEC_INSTALL_PIPE` | Install one-liners piped to a shell | HTTPS to Unity’s first-party CDN only; the installer verifies a SHA-256 pin against a same-origin manifest before executing anything. |
+| `SEC_AGENT_CONFIG_WRITE` | Writing agent skill files into AI clients’ configuration directories, turning an installed skill off or back on, and installing Unity’s own agent plugin into Claude Code, Codex, Grok Build, Antigravity, GitHub Copilot, or Qwen Code | Runs only on an explicit user command, is the command’s documented purpose, and is fenced by an ownership ledger — a copy this CLI did not write is never overwritten without `--force`, and the enable/disable verbs cannot act on one at all — plus symlink refusals and a warning before project-local installs from the home directory. The plugin install names one hardcoded first-party source, is performed by the agent’s own CLI (`claude`, `codex`, `grok`, `agy`, `copilot`, or `qwen`) rather than by writing files, and reinstalls nothing. |
+
+## Accepted, by-design capabilities
+
+### Installing skills into AI clients
+
+`unity skill install` and `unity skill refresh` write skill files — this skill, and the `unity-pipeline` skill a project's `com.unity.pipeline` package ships — into AI clients' configuration directories, along with the Unity skills pinned from the Unity-Technologies/skills repository, which automated scanners flag as an agent-persistence pattern. `unity setup <agent>` installs the same skills only when its plugin can't be installed and the user agrees at the prompt or passes `--yes`. The writes happen only when the user runs the command (nothing installs at load or in the background), the capability is the command's advertised purpose, and it is fenced: an install ledger records every write and a directory this CLI did not write is reported, never overwritten, without explicit `--force` consent; targets that resolve through a symlinked path component are refused; a package-shipped tree is read with file-count, per-file, and aggregate size bounds and never through symbolic links; and `--local` from the home directory warns first.
+
+The repository skills are downloaded, so the download is fenced too. The source repository and its download address are compiled into the CLI: no flag, setting or environment variable redirects them, and the download uses the CLI's normal TLS checks. The CLI pins a commit and a SHA-256 for each skill's file tree, and checks every skill against its pin before writing anything, so a changed or substituted archive writes nothing. Archive entries that would escape the skill folder, links, oversized files or archives, and non-text files are refused. Offline, only the skills embedded in the CLI are installed.
+
+### Syncing skills when an agent session starts
+
+`unity skill sync` is the one skill write that runs without the user typing it: Unity's agent plugin runs `unity skill sync --hook` when a session starts, which scanners flag as an agent-persistence pattern. The user consents by installing the plugin, whose description says it keeps the Unity skills current, and it is fenced more tightly than `skill install`. It writes only what a non-interactive `unity skill install` would: the embedded skills and the skills pinned and checked as above, into the one client the agent is. It never prompts, and has no `--yes` or `--force`, so it never overwrites a copy the user edited, a directory this CLI did not write, or a skill a plugin ships, and it leaves a disabled skill disabled. It runs no other command and installs no plugin or MCP server. After a run that reached the pinned repository it downloads nothing until the CLI or its pin changes. Under `--hook` its output is one plain line of context naming the skills it changed, or nothing.
+
+### Turning an installed skill off and back on
+
+`unity skill disable <skill>` and `unity skill enable <skill>` change whether a skill an AI client has already installed still loads. Disabling renames that skill's `SKILL.md` to `SKILL.md.disabled` inside its own directory and records the choice; enabling renames it back. Automated scanners flag this as skill suppression — a skill that can switch other skills off is a recognized malicious pattern, and reading it that way is correct as a default. Here it is the advertised purpose of a user-run command, and it is fenced:
+
+- **It can only reach installs this CLI itself recorded.** The set of skills these verbs can name comes entirely from the install ledger, so a skill this CLI did not install has no row, cannot be named, and cannot be found or touched. There is no path by which it disables a skill some other tool or the user placed.
+- **Nothing runs at load or in the background.** Both verbs act only when the user runs them, on a skill the user names; `--dry-run` reports without touching the filesystem.
+- **Nothing is deleted and no content is read or rewritten.** The only filesystem operation is renaming one fixed filename within the directory the ledger already records, so the skill's own files stay where they are and enabling restores the previous state exactly.
+- **The paths are bounded the same way installs are.** The only path formed is the recorded install directory joined with a constant filename, that directory has already passed the ledger's absolute-path validation, and a target reached through a symlinked directory component is refused rather than followed — the same guard `install` and `refresh` apply.
+
+The capability exists because a skill costs context in every session of the client that discovered it, whether or not it is ever used, so a user who installed several needs a way to stop paying for the ones a given project does not need — without deleting files they would otherwise have to reinstall.
+
+### Installing Unity’s agent plugin (Claude Code, Codex, Grok Build, Antigravity, GitHub Copilot, Qwen Code, VS Code, OpenCode)
+
+`unity setup claude` installs a plugin into Claude Code, which automated scanners flag as an agent-persistence pattern. It is fenced as follows. It runs only when the user runs the command, and this skill tells an agent to run it only when the user asks for the plugin or agrees to install it, never on its own initiative. The only source it can name is Anthropic’s official Claude Code marketplace, `anthropics/claude-plugins-official`, which lists Unity’s plugin and is compiled into the CLI: no argument, file, or environment variable can point it anywhere else. Claude Code accepts that marketplace name only from a repository under `github.com/anthropics/` ([Claude Code plugin security](https://code.claude.com/docs/en/plugins/security#identify-anthropics-marketplaces-by-name)), so a look-alike marketplace can’t take its place. It writes no files itself; it runs Claude Code’s own `claude plugin marketplace add` and `claude plugin install`, the documented install path, with fixed arguments, so Claude Code applies its own install handling. `--dry-run` prints both commands without running them, and an existing install is reported and never reinstalled or changed. It registers no MCP server of its own. After the plugin is installed or found already installed, it installs the Unity skills into the agent’s user-global skills folder, the same quiet run as `unity skill install <client>` that downloads from Unity’s pinned public skills repository with the same verification and the same refusal to overwrite an edited skill. A skill an older plugin still provides is skipped, and a failed skills step is a warning, not a failure. Every `unity setup <agent>` command below does the same for its own client.
+
+`unity setup codex` and `unity setup grok` install the same plugin into Codex and Grok Build under the same fence: they run only when the user runs them, and this skill tells an agent to run them only when the user asks for the plugin or agrees to install it. Their source is Unity’s own first-party marketplace, `Unity-Technologies/unity-agent-plugin`, compiled into the CLI, and nothing can point either command elsewhere. Each writes no files itself and runs only the agent's own documented install commands with fixed arguments: `codex plugin marketplace add` and `codex plugin add`, or `grok plugin install … --trust`. `--trust` is Grok Build's consent flag for a non-interactive install, and it is passed only because the user ran the command. `--dry-run` prints the commands without running them, and an existing, enabled install is reported and never reinstalled or changed. A Codex plugin the user disabled (`enabled = false` in Codex’s `config.toml`) is the one exception: `unity setup codex` treats it as not installed and runs the same two `codex` commands again, which re-enables it. That only happens when the user runs the command.
+
+`unity setup antigravity` installs the same plugin into Antigravity under the same fence. It runs only `agy plugin install` with Unity’s first-party repository, `Unity-Technologies/unity-agent-plugin`, as a fixed URL compiled into the CLI that nothing can point elsewhere, writes no files itself, prints the command under `--dry-run`, and reports an existing install without changing it.
+
+`unity setup copilot` installs the same plugin into GitHub Copilot under the same fence. It runs only when the user runs it, names only the compiled-in first-party repository, writes no files itself, and runs only the Copilot CLI's own documented commands with fixed arguments: `copilot plugin marketplace add` and `copilot plugin install`. `--dry-run` prints the commands without running them, and an install Copilot records as enabled is reported and never reinstalled or changed. A plugin the user disabled counts as not installed, so the same two commands run again and re-enable it, only when the user runs the command. When the marketplace is already registered, `copilot plugin marketplace add` exits with an error saying so, and the command treats that one message as done and goes on to the install step; any other failure stops it.
+
+`unity setup qwen` installs the same plugin into Qwen Code under the same fence. It runs only when the user runs it, names only the compiled-in first-party repository, writes no files itself, and runs only Qwen Code's own documented commands with fixed arguments: `qwen extensions install Unity-Technologies/unity-agent-plugin:unity --consent`, then `qwen extensions enable unity`. `--consent` is Qwen Code's flag for a non-interactive install, and it is passed only because the user ran the command. `--dry-run` prints the commands without running them, and an install Qwen Code has enabled for the current directory is reported and never reinstalled or changed. A disabled one counts as not installed, so the same two commands run again: the install fails because the extension exists, the command treats only that message, and only when the existing extension is Unity's own, as done, and the enable step turns it back on for the user's home directory. If it is still disabled for the current directory (a folder outside home), one more fixed command, `qwen extensions enable unity --scope workspace`, turns it on for that folder alone. Any other failure stops it.
+
+`unity setup vscode` and `unity setup opencode` have no plugin CLI to run. Each installs the Unity skills for its client, as above, and runs no other command. `setup vscode` only prints how to add Unity’s plugin from the compiled-in first-party repository in VS Code and edits no VS Code file. `setup opencode` writes exactly one file, `~/.config/opencode/plugins/unity.js`, whose body is compiled into the CLI and whose path nothing can change. It runs only when the user runs the command. The file is written through a temporary file and a rename, its first line records a SHA-256 of the body the CLI wrote, and a later run replaces only a copy that still matches that digest. A file the user edited, or wrote themselves, is left alone with a warning unless the user passes `--yes`. `--dry-run` writes nothing. When OpenCode starts a session, the plugin runs one fixed command, `unity skill sync opencode --hook --format json`, in the background, ignores any failure, and shows only what that command returns as a toast and a context message. It takes no input from the session, and the skills it updates come from the same pinned repository and verification as `unity skill install`.
+
+### Local Editor control and C# evaluation
+
+`unity command`, `unity command script eval`, and `unity shell --protocol ndjson` can drive a Unity Editor that is already open on the same machine and run C# through the project's `com.unity.pipeline` package. This executes **entirely on the local machine, in the current user's account, against the user's own Editor** — it is not remote access and grants no privilege the user does not already have at their own terminal. It is the CLI's core value for AI-assisted and automated Editor workflows.
+
+Machine/agent mode (`unity shell --protocol ndjson`) runs the exact commands the caller sends. It validates framing (malformed or unknown requests return an error frame rather than crashing or ending the session), runs every command non-interactively, and returns structured JSON response frames (JSON-serialized, so control characters are escaped for the consuming parser). Callers must feed it **trusted input only** — commands they construct themselves — and never commands assembled from untrusted third-party content, exactly as they would guard any shell.
+
+### Launching the project’s own build
+
+`unity build run` launches a player the CLI itself recorded from a previous `unity build` on the same machine — or the output the user names with `--build-path` — without rebuilding. It downloads nothing and runs nothing it did not just build or was not explicitly pointed at: a desktop player is started as the current user, and a WebGL build is served from a loopback-only local HTTP server that the default browser opens. Automated scanners flag documented executable paths (`./Build/…`) as local code execution; here the executable is the user’s own build artifact, on the user’s own machine, and the command refuses (exit 6) when no build has been recorded, when the recorded build’s platform cannot run on the current OS, or when its output is gone.
+### Install via the official CDN
+
+The documented install downloads and runs an install script from Unity's official CDN, `public-cdn.cloud.unity3d.com`, **over HTTPS (TLS)**. This pipe-to-shell pattern is a deliberate, industry-standard install convenience for a first-party tool. Beyond TLS, the script verifies the downloaded binary against the SHA-256 published in the channel's release manifest and aborts on mismatch — or when no SHA-256 tool is available — so a corrupted, truncated, or substituted download fails instead of executing. The manifest is fetched from the same CDN origin as the binary, so this is an integrity check against a bad or altered *download*, not a defense against a compromise of the origin itself; trust in the install ultimately rests on TLS and on Unity's control of that CDN.
+
+On Linux the script installs a self-contained binary under `~/.local/bin` and does not modify system package sources. Separately, Unity publishes `.deb` and `.rpm` packages (the `.rpm` is GPG-signed) to its official repositories, for users who prefer package-manager-managed updates. Installing either **does** change system state, and the two differ:
+
+- **Debian/Ubuntu (`.deb`, `apt`)** — adds a Unity apt repository entry and installs Unity's signing key into the system keyring (`/usr/share/keyrings`), so `apt` can verify and deliver subsequent updates.
+- **RHEL/Fedora (`.rpm`, `dnf`)** — adds a Unity yum repository entry with `gpgcheck` enabled, pointing `dnf` at the published key URL. It imports no key at install time.

package/skills/unity-cli/SKILL.md

@@ -0,0 +1,160 @@
+---
+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.
+allowed-tools:
+  - Bash
+---
+
+# Unity CLI
+
+**Always use the latest version of the Unity CLI unless you are told to use a
+specific version.** Newer releases regularly add commands and output fields
+these docs describe, so an outdated CLI fails in ways that read like the docs
+being wrong. Check with `unity self-update --check --format json`.
+
+**When you can run shell commands, use `unity command` and the rest of this CLI, not the Unity MCP server.** The CLI reaches more than the server's tools. MCP is for clients that have no shell.
+
+## Find a command: search, don't grep help
+
+**Never filter `unity --help` or a group's help with `grep`.** Help is long, and a grep over it drops the match or the context around it. Use the CLI's own search:
+
+```bash
+unity commands --grep license                 # built-in commands, plugins and the connected Editor's Pipeline commands
+unity command --query screenshot              # the same search
+```
+
+`unity commands --grep <pattern>` and `unity command --query <term>` are one search. It covers the CLI's built-in commands, the plugin catalog (installed or not) and the Pipeline commands of the live connected Editor, best match first. Plain words each match in any order; regex characters make it a regular expression. Each row says how to run it (`invoke`): `unity projects link cloud`, `unity command create_gameobject`, `unity <id>` for an installed plugin, or `unity plugin install <id>` for one not yet installed. In `--format json` each row also carries `kind` (`command`, `plugin`, `pipeline`), `path`, `description` and `matchedOn` (`name`, `description` or `option`), so act on `invoke` rather than parsing the table.
+
+- **Search before you work around the CLI or tell the user it can't help.** A request that names a Unity service, store or product feature (finding Asset Store assets, generating a texture, a cloud build) may be served by a catalog plugin that isn't installed yet, and nothing else on the machine will say so. Search with the request's own words (`unity commands --grep "asset store"`). A row whose `invoke` is `unity plugin install <id>` is that plugin: tell the user, and ask before installing it ([Use a catalog plugin](#use-a-catalog-plugin-for-a-task-the-built-in-commands-dont-cover)).
+- Use `unity command --query <term>` to search a specific Editor (`--project-path <project>`) or a Player (`--runtime <pattern>`, e.g. `unity command --query screenshot --runtime MyGame`).
+- `commands --grep` waits at most 3 seconds for the Editor; `command --query` waits for it. When the Editor was not searched, a last line says why (no Editor, no answer in time, several Editors) and what to run. Wait for the Editor first with `unity status --until-ready --project-path <project>`: before it connects, no Pipeline row is not proof nothing exists.
+
+Fields and flags: [integration-advanced.md](references/integration-advanced.md#querying-the-command-list).
+
+## Drive a running Unity Editor (if one is open)
+
+**If a Unity Editor is open on this machine, this CLI can control it live** — create and modify GameObjects, edit scenes and assets, inspect the hierarchy, and run arbitrary C# — through the project's **Pipeline** package (`com.unity.pipeline`). This runs entirely on your local machine, in your own user account, against your own open Editor: it is not remote access and grants no privilege you don't already have at your own terminal. When an Editor is available, drive it instead of hand-editing scene or asset files.
+
+```bash
+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
+# 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");'
+```
+
+**Pass `--caller plugin --skill <name>` on every `unity command` invocation.** `--skill` is the
+skill whose instructions produced the call, so a task skill that sends you here passes its own name
+rather than `unity-cli`. The flags are inert to the command itself; they only label the invocation.
+
+> **Verifying a running game, not just editing a scene?** Entering Play mode is setup, not proof:
+> an unfocused Editor or a locked desktop can freeze at frame 1 while `unity status` still reports it
+> as playing, and a screenshot can render a frozen frame that looks alive, or a flat color. The
+> ordered recipe for playing, confirming the game is actually advancing, capturing the view, reading
+> the console, and tuning it live with `script eval` is in
+> [playmode-verification-loop.md](references/playmode-verification-loop.md).
+
+### More than one Editor open? Pass `--project-path`
+
+Several Editors or MPPM clones? Pin one by `--project-path`, `--port`, `--pid` or `--instance`: [editor-targeting.md](references/editor-targeting.md).
+
+## Install the CLI (if not already installed)
+
+Only if `which unity` is empty: the macOS/Linux and Windows installers are in [setup-and-help.md](references/setup-and-help.md#install-the-cli-if-not-already-installed).
+
+## Global flags
+
+`--format`, `--quiet`, paging and proxy flags for every command: [global-flags.md](references/global-flags.md).
+
+## Environment variables
+
+Every `UNITY_*` variable and the flag it mirrors: [environment-variables.md](references/environment-variables.md).
+
+## Getting help
+
+`-h`/`--help` on any command, and what to do when you don't know which command: [setup-and-help.md](references/setup-and-help.md#getting-help).
+
+## Exit codes
+
+Branch on these before parsing output; retry guidance per code: [exit-codes.md](references/exit-codes.md).
+
+## Commands
+
+The full per-command reference — syntax, flags, and examples — lives in grouped files under
+[`references/`](references/). **Read the file for the command group you need**; all the global
+flags, environment variables, and exit codes above apply throughout. Every command also supports
+`-h` / `--help` (see [Getting help](#getting-help)).
+
+| Commands | Reference file |
+|---|---|
+| `auth` (login / logout / status / list / switch / default / consumers / revoke), `license` (activate / return / server), `cloud` (org / project) | [auth-license-cloud.md](references/auth-license-cloud.md) |
+| `pipeline cloud-build` (targets incl. groups, create, update, auditlog / builds incl. steps, timeline, failures, artifacts, log, download, start, cancel / credentials upload / connections / scm check-url / org free-tier / project / tooling), `pipeline automation` (apps / pipelines incl. trigger / jobs incl. watch, logs, terminate, resume, approve, reject / automations / bots / profiles / templates, plus `apps versions`, `pipelines versions`, `jobs stats`) | [cloud-automation.md](references/cloud-automation.md) |
+| `editors` (list / running / add / default / path / install-path / info / upgrade / prune / verify / module), `install`, `uninstall`, `modules`, `install-modules`, `terms` (accept / status) | [editors-install.md](references/editors-install.md) |
+| `projects` (list / create / clone / open / link / require / upgrade / export / import / pin / size / clean / exec; its help reads "Create, open, upgrade, and link local Unity projects (Unity Cloud, GitHub/GitLab)", so linking a folder to Unity Cloud is `projects link cloud`, not `cloud`), `open`, `close`, `releases`, `templates` (list / info / create / pack / delete), `assets` (`inspect` / `export`) | [projects-templates.md](references/projects-templates.md) |
+| `config` (proxy / update-check / accelerator / get / set / list / unset / resolve), `context` (save / use / list / current / delete), `hub install` | [config-hub.md](references/config-hub.md) |
+| `run`, `test`, `build` (+ `build run`), `recompile`, `watch` (`test`) | [build-run-test.md](references/build-run-test.md) |
+| `logs`, `doctor`, `env`, `version`, `cache`, `ci init`, `analytics`, `changelog`, `docs` (+ `toc`), `language`, `completion`, `bug`, `self-update`, `self-uninstall`, `diagnose proxy`, `diagnose accelerator`, `diagnose update` | [diagnostics-maintenance.md](references/diagnostics-maintenance.md). To find, cite and version-match Unity docs: [docs-workflow.md](references/docs-workflow.md) |
+| `mcp` (+ `configure`), `setup claude` / `codex` / `grok` / `antigravity` / `copilot` / `qwen` / `vscode` / `opencode`, `skill` (install / refresh / show), `plugin` (install / remove / upgrade / list / changelog), local `pipeline` (install / upgrade / list / list-versions), `command` / `commands` / `status` / `list`, `job` (status / wait / cancel), answering an open modal dialog (`command editor dialog` / `editor dialog answer`, or `editor.dialog list` / `answer` / `dismiss`), `shell` | [integration-advanced.md](references/integration-advanced.md) |
+| `vcs` — `setup` / `status` / `sync` / `switch` / `doctor` / `providers` / `merge-setup` / `conflicts` / `explain` / `resolve` / `diff` / `blame` / `summarize` / `affected` / `hooks`, `vcs git` (`migrate-lfs` / `worktree`), `vcs uvcs` (`locks` / `changesets` / `review`) | [version-control.md](references/version-control.md) |
+| `collaboration` (alias `collab`) — `annotations` / `attachments` / `thumbnail` / `reactions` / `read` / `subscribe` / `jira` | [collaboration.md](references/collaboration.md) |
+
+## Common workflows
+
+### Inspect and run cloud builds and Pipeline Automation jobs
+
+`pipeline cloud-build` and `pipeline automation` end to end: [cloud-workflows.md](references/cloud-workflows.md).
+
+### Edit a scene, GameObject, or asset — `unity status` first
+
+Read before editing any scene, prefab or asset: the preflight and the Safe Mode / sandbox false negatives in [scene-editing-preflight.md](references/scene-editing-preflight.md).
+
+### Use a catalog plugin for a task the built-in commands don't cover
+
+When a request names a Unity feature no built-in command covers, check the catalog first: [catalog-plugins.md](references/catalog-plugins.md).
+
+### Bootstrap a new project from scratch
+
+Raw CLI recipe from install to first commit (the `new-unity-project` skill is the guided path): [bootstrap-project.md](references/bootstrap-project.md).
+
+### Find and install a missing editor
+
+Check what is installed, browse LTS releases, then install one: [setup-and-help.md](references/setup-and-help.md#find-and-install-a-missing-editor).
+
+### Open a project with the correct editor
+
+```bash
+# 1. Check the project's required editor version
+unity projects info /path/to/MyProject --format json
+# Look at "editorVersion" in the result
+
+# 2. Confirm that editor is installed
+unity editors --installed --format json
+
+# 3. Open (warns if the editor version is missing)
+unity open /path/to/MyProject
+```
+
+### CI: activate a license, then build
+
+CI recipe that activates a license, builds, then returns it: [ci-recipes.md](references/ci-recipes.md#ci-activate-a-license-then-build).
+
+### CI: headless build
+
+Headless `unity build` and `unity run` invocations for CI: [ci-recipes.md](references/ci-recipes.md#ci-headless-build).
+
+### CI: run tests and publish results
+
+JUnit output, exit-code branching and test-selection rules: [ci-recipes.md](references/ci-recipes.md#ci-run-tests-and-publish-results).
+
+### Debug the CLI
+
+`unity doctor --json` and `unity logs --follow` while a run misbehaves: [setup-and-help.md](references/setup-and-help.md#debug-the-cli).
+
+## Notifications
+
+When a JSON envelope carries `notifications`: what to surface and what needs approval — [notifications.md](references/notifications.md).
+
+## Notes
+
+Parsing, output-shape and quoting rules to know before trusting a result: [notes.md](references/notes.md).
+

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

@@ -0,0 +1,318 @@
+# Auth, license & cloud — 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.
+
+### Contents
+
+- Auth
+- License — list, activate, return
+- Cloud — Unity Cloud organizations and projects
+
+---
+
+### 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
+# The secret must be piped in: a terminal on stdin is refused, and the
+# command stops waiting after 30 seconds if the pipe is never closed.
+
+# 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
+
+# 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
+
+# Sign one stored account out of the CLI, rather than the active one. Its saved
+# sign-in stays on the machine while another app, such as the Hub, still uses it.
+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.
+
+#### Multiple accounts
+
+The CLI stores more than one signed-in account and keeps one of them *active*. `unity auth login` adds an account; these three manage the set.
+
+```bash
+# List stored accounts; "*" marks the active one
+unity auth accounts
+unity auth accounts --format json
+
+# Make a stored account active (by email or id) — no browser round-trip
+unity auth switch user@example.com
+
+# Show the account a project uses for cloud commands
+unity auth default
+
+# Pin this project to an account, regardless of which one is active
+unity auth default user@example.com
+
+# Target a project other than the current directory
+unity auth default user@example.com --project-path ./MyGame
+
+# Remove the pin; the project follows the active account again
+unity auth default --clear
+```
+
+Three behaviors worth knowing before scripting these:
+
+- **A project pin beats the active account.** If a project has a default set, commands run inside it keep using that account even after `unity auth switch` — the switch reports this rather than failing silently. Use `auth default --clear` to hand the project back to the active account.
+- **Service-account credentials outrank both.** When `UNITY_SERVICE_ACCOUNT_ID` / `UNITY_SERVICE_ACCOUNT_SECRET` are set (or a service account is signed in), they take precedence over every stored account and `auth switch` says so instead of appearing to work. Unset them, or `unity auth logout`, before switching.
+- **`auth switch` is ambiguity-aware.** Given a string matching several stored accounts it fails rather than guessing, and under `--format json` carries the candidates in `data.candidates` so a script can disambiguate. Pass the full email or the account id.
+
+`unity auth default` resolves the project from `--project-path`, then `UNITY_PROJECT_PATH`, then the current directory, and errors if that path isn't a Unity project. Passing both an account and `--clear` is rejected.
+
+#### Access tokens for scripts and other tools
+
+`unity auth token` prints an access token from the CLI's sign-in, so a script, `curl` or another Unity tool can call Unity services as the signed-in user or service account without running its own sign-in. In the text formats stdout holds the token and nothing else (`--quiet` keeps it), so capture it directly.
+
+```bash
+TOKEN=$(unity auth token)
+curl -H "Authorization: Bearer $TOKEN" ...
+
+# The token, its expiry (ISO 8601) and the auth mode, in the envelope
+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`.
+- **`--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.
+
+#### Start the sign-in service for a plugin
+
+`unity auth broker ensure` makes sure the CLI's sign-in service (the auth broker) is running, starting it when nothing answers. It then connects as a sign-in would, so exit `0` means the CLI would use that service, not only that something answers. A plugin that reads the signed-in session through the broker runs it before it needs a token. It reads no credential and needs no sign-in.
+
+```bash
+unity auth broker ensure
+# {"state": "already-running" | "started" | "disabled" | "unavailable" | "refused", "address": <socket path or null>}
+unity auth broker ensure --json
+```
+
+- `already-running` and `started` exit `0`.
+- `disabled` exits `6` with `AUTH_BROKER_DISABLED`: `UNITY_NO_AUTH_BROKER` is set.
+- `unavailable` exits `6` with `AUTH_BROKER_UNAVAILABLE`: no service answers and none could start.
+- `refused` exits `6` with `AUTH_BROKER_REFUSED`: a service answers, but the CLI will not use it (it could not be verified as genuine Unity software, or is too old). The message names the fix.
+- Every failure's envelope still carries `data`.
+
+#### Consumers — see who's used your sign-in, and mark one revoked
+
+Some products use your Unity sign-in without holding your refresh token themselves, brokering through the CLI's own auth broker instead. `unity auth consumers` lists every application in the broker's audit trail on this machine, plus any in the local revocation list, and `unity auth revoke` records one in that list. Read the Granted and Denied columns before concluding an application used your sign-in: one with only denials never received a token, and a revoked application with no audit history appears with no activity at all.
+
+```bash
+# Application, scopes, grants/denials, and when it was last used
+unity auth consumers
+unity auth consumers --format json
+
+# Add an application to the local revocation list (every scope it asked for)
+unity auth revoke "Some Tool"
+
+# Remove it from the list
+unity auth revoke "Some Tool" --restore
+```
+
+Both are local-only — reading the broker's audit trail and a local revocation list — so neither needs sign-in or the network. On a machine that has never run the broker, `auth consumers` reports an empty list rather than an error. `auth revoke` without `--restore` revokes; with it, it un-revokes; either way it reports the actual resulting state (e.g. "already revoked") rather than assuming the write changed anything. **The list is not enforced yet:** the auth broker does not consult it when it hands out tokens, so a revoked application can still use your sign-in. Neither `auth revoke` nor `unity auth logout` currently stops an application that already has broker access; `logout` keeps the account's saved sign-in while the Hub still uses it.
+
+The stored token itself is sealed to the machine that wrote it (TPM-backed on Windows/Linux where available, Keychain on macOS, with a local-key-file fallback everywhere), so a copied token-store file is worthless on another machine. `unity doctor` reports which protection is in force.
+
+**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.)
+
+The two still share one account list. So an account you signed in to in the Hub shows up in `unity auth accounts` even though the CLI is not signed in to it, and `unity auth status` can report "not signed in" while `auth accounts` shows that account. To use it from the CLI, try `unity auth switch <account>` first: when that account's sign-in is readable on this machine, it becomes the CLI's active account with no browser round trip. When it has no usable sign-in, run `unity auth login` and sign in as that account in the browser; `auth switch` cannot sign an account in.
+
+**Using the Hub's sign-in is your explicit choice.** When the CLI is signed out and the Hub is signed in, `unity auth login` shows the Hub's account and the `unity auth switch <account>` command that makes it the CLI's active account with no browser sign-in, then carries on with the browser sign-in. It asks nothing, and bare `unity auth` prints its group help. Running that `switch` command makes the Hub's account the CLI's active account, exactly as `unity auth switch` always does, and changes nothing in the Hub. The CLI never takes the Hub's sign-in on its own. `unity auth status --json` reports `adoptable: true`, the account and `adoptCommand`, and under `--json` `unity auth login` writes that `unity auth switch` command (not the account) as an `adoptable=` progress frame on stderr. An agent should show the user that command rather than run it unasked. Once switched, signing out of the Hub doesn't sign the CLI out. If you only want the CLI in order to activate a perpetual or legacy serial license, you do not need to sign in at all: see [Headless / fleet license activation](#headless--fleet-license-activation).
+
+**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 written to stderr so machine consumers can capture the URL without parsing human text, and stdout stays the result envelope alone.
+
+A login that stores a session (the browser sign-in, or a service account without `--no-store`) ends with the machine-state summary: the account, organization, license, Editors, network when unreachable, the skills to load and the next command. In the human format it prints after the success line, and `--quiet` drops it. Under `--json` and `--format ndjson`, each thing that blocks creating a project is a `notifications` entry with its `code` and fix (`ENGINE_NOT_INSTALLED` or `NETWORK_UNREACHABLE`, for example), and the array is left out when nothing blocks. `--format ndjson` ends every successful login with the same `result` frame the json envelope carries (`loggedIn`, `user` or `mode`, `clientId`, `stored`). A failed login, `--no-store` and `--help` print no summary.
+
+`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 licenses             # 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
+#   or export UNITY_LICENSE_SERIAL and run `unity license activate` bare: the serial stays off argv
+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 licenses — assigned/subscription AND serial-activated (prompts to confirm; --yes skips)
+unity license return
+unity license return --yes
+
+# Floating (network) license server
+unity license servers      # the configured floating license server(s)
+unity license server status    # reachability + available seats
+unity license server health    # the server's own health report (GET /v1/status)
+```
+
+`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.
+
+On a floating-only machine the licensing client holds no license until the Editor leases a seat at startup. When no license is held and the configured floating server answers as healthy, `unity license status` exits `0`, says the Editor leases a seat when it starts, and reports `floatingServerHealthy: true` (`false`, with exit `4`, when the server is not healthy). `active` stays `false`, since no seat is held yet.
+
+`unity license status` also reports `floatingServer` (the licensing server this machine is configured against) and `machineId` (the identity the licensing client reports to it) — the two values to match against a lease record when a floating seat looks stuck. Both are always present in `--format json` / `ndjson`; human and `tsv` output shows them only when a floating server is configured.
+
+`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`, `--floating`, `--file` and `--generate-request` need no sign-in, and `--file` and `--generate-request` also work offline. `--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).
+
+**Service accounts.** The `license` commands recognize service-account sessions (`UNITY_SERVICE_ACCOUNT_ID` / `UNITY_SERVICE_ACCOUNT_SECRET`, or `unity auth login --client-id`): `unity license status` reports `Signed in: yes (service account)` and includes the auth mode in JSON. Unity's licensing backend does **not** accept service-account tokens for license activation, so with a service-account session the default entitlement mode and `--personal` fail up front — before contacting the licensing client — with guidance toward the unattended options (`--floating`, `--file`, `--generate-request`, or a perpetual `--serial`). `unity license return` lists and returns serial-activated licenses too (not just assigned/subscription seats) — important for CI machines that activate per run — and returns each license individually, so when only some can be freed it reports what succeeded (in text and in the JSON `returned` / `failed` fields) instead of an all-or-nothing failure.
+
+#### Headless / fleet license activation
+
+For build agents, lab machines, and any machine with no browser. There is **no username/password option**: the CLI only signs a user in through the browser, and a service account cannot activate a license, because Unity's licensing backend does not accept service-account tokens for activation. None of the paths below needs a signed-in account.
+
+```bash
+# Perpetual or legacy Pro/Plus serial: no sign-in needed
+unity license activate --serial <serial> --non-interactive --format json
+
+# Air-gapped machine: write a request, exchange it elsewhere, then import the license file
+unity license activate --generate-request ./unity.alf      # on the offline machine
+# ...exchange unity.alf for a .ulf license file on a machine with internet access
+#    (Unity's manual activation page), then copy the .ulf back...
+unity license activate --file ./Unity_lic.ulf              # on the offline machine
+
+# Floating (network) licenses: lease a seat from the configured server
+unity license server status                                # check the server and its free seats first
+unity license activate --floating
+
+# Decommissioning a machine: give the seat back so the serial can be activated elsewhere
+unity license return --yes --non-interactive
+```
+
+- **`--serial`** activates a serial-number license without signing in, on every platform. A serial tied to a subscription can still be refused with "This license requires a signed-in Unity account"; sign in on that machine, or use one of the other paths.
+- **`--generate-request` then `--file`** is the offline path. The request file identifies this machine, so import the resulting license file on the same machine that generated the request. Both talk to the Unity Licensing Client on the machine, and the CLI downloads that client (about 110 MB) the first time a `license` command needs it. Stage it while the machine, or the image it is built from, still has network access: run `unity license status` once. With no client installed, that fetches one into the CLI's data folder. A `Unity.Licensing.Client` already on `PATH` is used instead when no downloaded copy exists, with no version check, and an older one fails the handshake, so update or remove an older `PATH` client before staging. The downloaded client lands in the data folder of the user who ran the command (under `HOME`, or `XDG_CONFIG_HOME` when set), so run the staging step as the same user, with the same `HOME`, that will run the CLI later; a client staged as root in an image build is not found by a container that runs as another user. Otherwise, put a current `Unity.Licensing.Client` on a shared `PATH`.
+
+  On an image with no license yet, `unity license status` exits `4` (no license active), which is expected at this point. A fail-fast shell or a Dockerfile `RUN` stops on it, so accept exactly `4` and keep every other failure, such as `6` when the client could not be fetched:
+
+  ```bash
+  unity license status || [ $? -eq 4 ]
+  ```
+
+  ```powershell
+  unity license status; if ($LASTEXITCODE -notin 0, 4) { exit $LASTEXITCODE }
+  ```
+- **`--floating`** needs a floating license server configured on the machine first (exit `4` otherwise). `unity license servers` shows which one is configured.
+- **`license return`** returns serial-activated licenses as well as assigned ones. Run it before you reimage or retire a machine, or that activation keeps counting against the serial's limit. It needs `--yes` when nothing can answer a prompt. A license imported offline with `--file` cannot be returned this way: `license return` reports it as activated manually and leaves it in place.
+
+`unity license servers` 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. When the licensing client cannot read the seats (it can't with nobody signed in) but the server answers its `/v1/status` as healthy, `server status` still reports it reachable and exits `0`, says seat usage is not available, and adds `seatsUnavailable: true` to the JSON.
+
+`unity license server health` asks the configured server directly for its health on its anonymous `/v1/status` endpoint, through the CLI's own proxy settings; it does not need the licensing client or a sign-in. It reports the server's `status` (`Healthy`, `Degraded` or `Unhealthy`) and `version`, plus `reachable`, `healthy` and `httpStatus` in `--format json` / `ndjson`. Exit `0` when the server is Healthy or Degraded, `4` when no server is configured, and `6` when it is unreachable, Unhealthy, or answers without a status (for example a proxy error page). A non-zero run writes `success: false` and keeps the report in `data`, with `LICENSE_SERVER_NOT_CONFIGURED`, `LICENSE_SERVER_UNREACHABLE` or `LICENSE_SERVER_UNHEALTHY`.
+
+---
+
+### 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 orgs --format json
+unity cloud org current                       # print the active default org (named when signed in)
+unity cloud org set-default <id-or-name>      # set active default org
+unity cloud org clear-default                 # revert to "All Organizations"
+
+# Create an organization (company profile: individual or company, plus country)
+unity cloud org create "<name>" --first-name Ada --last-name Lovelace --country GB
+unity cloud org create "<name>" --company-name "Nebula Games Inc." --country US --region CA --set-default
+
+# Projects in the active organization
+unity cloud projects --format json               # * marks the active default project
+unity cloud projects --search "<text>" --limit 20 --offset 40 --format json   # one page, by name
+
+# To link a local folder to a cloud project, use `unity projects link cloud <path>` (see projects-templates.md);
+# `unity cloud project --help` and `unity projects link cloud --help` point at each other
+
+# Default project, stored per organization
+unity cloud project current                          # print the saved default project, and the project linked to this folder
+unity cloud project set-default <id-or-name>         # project UUID, Genesis id, or exact name
+unity cloud project clear-default                     # drop this organization's default
+
+# Override the active organization for a single call
+unity cloud projects --cloud-org <id-or-name>   # also via UNITY_CLOUD_ORG env var
+```
+
+**Creating an organization takes a name and a company profile**, the same fields the Unity
+Dashboard's create dialog asks for. `--type individual` needs `--first-name` and `--last-name`;
+`--type company` needs `--company-name`. `--type` can be left out when the name flags already say
+which it is, and passing both kinds is refused. `--country` is a two-letter ISO 3166-1 alpha-2 code (`GB`,
+not `GBR`, and not `UK`, which is not an ISO code). `--region` is the ISO 3166-2 subdivision (`CA`, or `US-CA`) and is
+required for the US, Canada, and Mexico and refused for every other country. The organization name
+is trimmed and capped at 40 characters; person and company names follow the Dashboard's own
+character rules. Everything passed is validated before the sign-in check and before any request,
+so a typo costs no network call. Omitted fields are prompted for on a terminal; under
+`--non-interactive`, or when output is redirected, the command fails naming every missing option.
+Whether a country or subdivision code actually exists is the server's call, and its field-level
+reason is reported as-is. `--set-default` makes the new organization active, exactly as
+`org set-default` would; if the setting cannot be written the organization is still reported as
+created, with a warning that the default did not take effect. A name already in use is reported as
+such rather than as an HTTP status. Machine output is a create-specific shape carrying `id` and
+`name` only, deliberately not `org list`'s row, since the create response has no `role` and the
+default marker describes a list rather than a single new organization.
+
+**The default project is per organization.** `set-default` stores the project's UUID against the
+active organization's Genesis id, so switching your active organization switches which default
+applies, and `clear-default` only drops the active organization's. `cloud project current` and
+`clear-default` read and write the settings file directly, so they need no network and no session
+when the organization comes from your stored default; passing `--cloud-org <name>` needs a lookup,
+so that path requires a session like the rest. `cloud project current` labels what it prints as the
+saved default, and inside a Unity project folder linked to a cloud project it also prints that linked
+project. Setting a default never changes which project a folder is linked to (`projects link cloud`
+does that). Under `--format json`, `activeCloudProjectId` still holds the default, with
+`defaultCloudProjectId` and `linkedCloudProjectId` beside it (`null` outside a linked project folder).
+Under `--format tsv`, which is the default when output is piped, it prints the same fields as
+`key<TAB>value` lines after a `key`/`value` header row (an empty value where `json` has `null`).
+
+**What consumes it.** Commands that need a Unity Cloud project but were not given one fall back to
+the stored default. The order is the explicit flag (`--cloud-project`), then `UNITY_CLOUD_PROJECT`,
+then the cloud link in the project directory's `ProjectSettings/ProjectSettings.asset`, then the
+stored default, so inside a cloud-linked project the link still wins. `unity collaboration` uses
+this chain. `unity projects link cloud` applies the default too, with its own order (`--cloud-project`,
+then `UNITY_CLOUD_PROJECT`, then the default, see projects-templates.md). `unity projects create` does
+not read the default: it creates a new cloud project unless `--cloud-project` names one or `--no-cloud`
+(or `UNITY_NO_CLOUD`) declines. `cloud project current` prints the saved default, not necessarily the
+folder's project: under `--format json`, `linkedCloudProjectId` is the folder's link.
+
+**A project in another organization.** `set-default` looks in the active organization first. When the project is in
+another of your organizations, the error names that organization (`UNKNOWN_CLOUD_PROJECT`, exit `2`, with the
+organization under `data.organization` in `--format json`). Run `unity cloud org set-default <genesis id>`, then
+`set-default` again. When the organization comes from `--cloud-org` or `UNITY_CLOUD_ORG`, the other organizations are
+not checked, because that value overrides the saved default.
+
+**Exit codes.** The `cloud` and `auth` commands map an authentication failure (expired or missing session, rejected sign-in) to `3`, and any other operational failure (network, server error) to `6` — so scripts can distinguish "sign in again" from a genuine command failure. `unity auth status` / `logout` follow the same convention. A status command that answers no is a failure in `--format json` too: signed out, `unity auth status` and `unity cloud status` exit `3` with `success: false` and `errors[0].code` `NOT_SIGNED_IN` (or `SESSION_EXPIRED`); `unity license status` with no license exits `4` with `LICENSE_NOT_ACTIVE`; `unity license server status` exits `4` with `LICENSE_SERVER_NOT_CONFIGURED` or `6` with `LICENSE_SERVER_UNREACHABLE`. Each keeps its report in `data` (`loggedIn: false`, `active: false`, `reachable: false`), so read `success` or the exit code, they always agree.
+
+---
+