| name | unity-cli |
| description | Use when installing, configuring, automating, troubleshooting, or migrating workflows involving the standalone Unity CLI, including Unity Editor installations, modules, projects, authentication, licensing, structured output, and CI. |
Unity CLI
Treat installed help as authoritative. The CLI is experimental. Syntax changes.
Identify and inspect
command -v unity
unity --version
unity --help
Confirm this is the standalone Unity CLI. Not:
- Unity Editor arguments.
- Deprecated Unity Hub CLI or
-- --headless.
- Unity Gaming Services CLI (
ugs).
- Unity Version Control (
cm).
- Package Manager.
- Third-party
unity tools.
Before each command:
- Detect OS and architecture.
- Check
unity --version and relevant help.
- Use the complete nested path:
unity projects clone --help.
- Classify the operation: read-only or state-changing.
- Check platform support and experimental notices.
Use generated references only for discovery. Confirm locally with --help.
Execute
- Start with the narrowest read-only inspection.
- Resolve aliases, versions, paths, architectures, modules, and required values from installed help.
- Use preview or dry-run only when that command exposes it.
- In automation, build separate argv. Never interpolate discovered values into shell code.
- Before mutations: explain target and effect; get required authorization.
- Check exit code. Verify state with a read-only command.
Automation
- Use only help-confirmed structured formats.
- Separate stdout and stderr. Parse stdout; retain stderr.
- Always check exit code. Never parse animated progress.
- Avoid CI prompts. Use non-interactive flags only when exposed by help.
- Pin CLI and Editor versions when reproducibility matters.
- Never log credentials, tokens, serials, offline licenses, or service-account secrets.
- Never copy flags across platforms without checking each platform's help.
Mutations
Mutations include:
- Install, upgrade, or uninstall CLI/Editor/modules.
- Register Editors; change defaults or global paths.
- Create, import, clone, link, unlink, delete, or upgrade projects.
- Change credentials, authentication, licenses, caches, proxy, language, analytics, or persistent config.
Require explicit authorization before license activation/return, credential removal, project deletion/upgrade, cache clearing, uninstall, or global-path changes. First inspect the complete command path with --help.
Troubleshoot
- Capture OS, architecture, executable path, version, exact argv, exit code, stdout, and stderr.
- Check the complete command path with
--help.
- Use help-exposed read-only diagnostics.
- Check PATH, permissions, network/proxy, credential store, non-interactive settings, Editor/version/module resolution, and platform support.
- Redact secrets and user paths.
- Stop on incomplete help, unexpected output shape, or unexpected mutation risk.
References
