11 KiB

Raw Blame History

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.

Auth

# 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

# Log a specific stored account out, rather than the active one
unity auth logout user@example.com

# Skip the confirmation prompt
unity auth logout --yes

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.

# List stored accounts; "*" marks the active one
unity auth list
unity auth ls              # alias
unity auth list --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 ./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 the current directory unless --project is given, and errors if that path isn't a Unity project. Passing both an account and --clear is rejected.

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

# 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 licenses — assigned/subscription AND serial-activated (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).

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.

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

# 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               # * marks the active default project

# Default project, stored per organization
unity cloud project current                          # print the active default project id
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 project list --cloud-org <id-or-name>   # also via UNITY_CLOUD_ORG env var

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.

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 (--project-id), then UNITY_CLOUD_PROJECT, then the cloud link in the project directory's ProjectSettings/PlayerSettings.asset, then the stored default, so inside a cloud-linked project the link still wins. unity collaboration and the cloud-pipeline preview family both use this chain.

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.

11 KiB Raw Blame History