Unity CLI output formats and automation
Configure Unity CLI output formats, handle errors and exit codes, and use environment variables to control CLI behavior in scripts, Continuous Integration (CI) pipelines, and agent workflows.
Read time 7 minutesLast updated 2 days ago
When you run the Unity CLI from a script, a CI pipeline, or an AI agent, use the output formats, error envelope, exit codes, and environment variables on this page to get predictable, machine-readable results and to handle failures without parsing text. The CLI chooses a default output format based on the context and supports explicit formats for automation.
Format selection
Format | Selected when | Notes |
|---|---|---|
| Output goes to an interactive terminal. | Colorized, animated progress, aligned columns. |
| Output goes to a pipe or file. | Tab-separated, one record per line. Machine-parseable. |
| You set | Structured output for use with |
| You set | One JSON object per line. Long-running commands, such as |
| You set | Failures print as GitHub Actions annotations ( |
Select a format explicitly with the global flag:
unity editors -i --format jsonunity editors -i --format tsvunity install lts --format ndjson
Note
--json--format json--formatTip
When you pipe CLI output, the default format changes to tab-separated values (TSV). If a script expects human-readable text, set explicitly, or parse TSV, JSON, or NDJSON instead. Use for a single buffered result and when you also want streamed progress frames from long-running commands.
--format humanjsonndjsonColor output
Use the global flag to control colored output directly instead of relying only on the and environment variables. is shorthand for . Color affects only output. The , , and formats never emit color.
--color <auto|always|never>NO_COLORFORCE_COLOR--no-color--color neverhumanjsontsvndjsonError output
The CLI writes errors and diagnostic messages to , leaving available for data output. In and modes, a failed command still writes a complete result to . In mode, the result is an envelope with and an array. In mode, the result contains the terminal frame with . Branch on the stable error code, such as in mode, instead of parsing . Usage errors, such as a mistyped option, report .
stderrstdoutjsonndjsonstdoutjsonsuccess: falseerrorsndjsonresultsuccess: falseerrors[0].codejsonstderrINVALID_COMMAND_ARGSTo capture both streams in a shell:
unity install 6000.3.7f1 > install.log 2>&1
Exit codes
Code | Meaning |
|---|---|
| Success. |
| A general error occurred. Inspect |
| Usage error: invalid flags, invalid option values, or missing required arguments. |
| Authentication or authorization failure, such as a rejected sign-in or an expired session. |
| Configuration required: the arguments are valid, but a required preference or context isn't set. |
| The command's primary operation failed. For example, an Editor install failed, or the Editor exited with an error. For |
| A Unity service couldn't be reached, even after the CLI retried, or |
| |
| The command was interrupted with Ctrl+C ( |
| The command was terminated with |
Note
When a CI job retries a failed run, retry only exit code or . A means the run didn't finish, for example because of a compile error, an unavailable license, an Editor crash, or , so a retry can still produce results. An means the tests themselves failed, so a retry produces the same result.
unity test676--timeout8Environment variables
Global CLI options have environment variable equivalents, and some behaviors are controlled only through the environment. A command-line flag takes precedence over its environment variable.
Variable | Effect |
|---|---|
| Default output format ( |
| Suppress non-essential output, like |
| Suppress the Unity banner, like |
| Disable interactive prompts, like |
| Pager for long human-readable output. Falls back to |
| Never page output, like |
| Default Unity project path for commands that accept |
| Default Unity Cloud organization for commands that accept |
| Default Unity Cloud project id for |
| Proxy server URL, like |
| Log one redacted entry per outbound request for proxy troubleshooting, like |
| Number of retries for module downloads that fail intermittently, like |
| Windows only. Skip the elevated (UAC) install helper, like |
| End |
| Disable the background check for CLI updates. |
| Create projects without the Unity Cloud step, like |
| Allow an unattended run to install missing tools, such as Git LFS, without asking. |
| Turn the Git hooks installed by |
| Disable anonymous crash and error reporting. |
| Suppress the one-time first-run analytics consent prompt without recording a choice. |
| Unity Accelerator endpoint ( |
| Disables the background identity-server process that answers an Editor's sign-in requests when no Hub is running. |
| Disables the resident auth broker that serves your sign-in to CLI commands and read credentials directly from the keyring instead. The broker starts on demand and exits after two minutes of inactivity. |
| Installation directory for the install script. When set, the script installs the CLI to |
| Specifies how the CLI's background sign-in helpers verify the code signature of a connecting Editor or client. On macOS and Windows the default is |
| Authenticate as a Unity service account for unattended workflows. Set both. |
Progress output
Long-running commands (such as ) render animated progress bars on an interactive terminal and a static summary when complete. Progress output is for human readers. Don't parse it in scripts. For a machine-readable result, use ; to also stream machine-readable progress updates while the command runs, use , which emits typed progress frames followed by a final result frame.
install--format json--format ndjson