unity-cli

Automates Unity Editor cold starts, headless tests, batch runs, and builds via the Unity CLI.

Updated Aug 18, 2026
One-click install
npx skills add https://github.com/ethanJPope/Our-Main-Hackathon-Game --skill unity-cli-ethanjpope
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: unity-cli
Source: https://github.com/ethanJPope/Our-Main-Hackathon-Game/tree/main/.agents/skills/unity-skills/skills/unity-cli
Command: npx skills add https://github.com/ethanJPope/Our-Main-Hackathon-Game --skill unity-cli-ethanjpope

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Unity Editor automation normally requires the editor to be running and reachable through the UnitySkills REST server, which makes cold starts, CI-style headless test runs, and unattended builds impossible. This Skill governs safe use of the experimental Unity CLI so those lifecycle operations work while the editor is closed. ## Core Features & Use Cases - Cold Start & Lifecycle: Launch the bound Unity project with the -unityskills-coldstart marker, verify the installed editor version, and triage liveness via the registry, lockfile, and CLI process list before starting anything. - Headless Tests & Batch Runs: Run EditMode/PlayMode tests with NUnit XML output and timeouts, or execute one-shot -executeMethod batch automation while the editor is closed. - Headless Builds: Build via Unity 6 Build Profiles, built-in desktop targets, or custom C# build methods, with dirty-worktree guards and structured exit codes. - Use Case: In a CI pipeline, run unity test against a bound project with --format json --non-interactive and a timeout to produce an NUnit XML report without ever opening the editor interactively. ## Quick Start Read the project's Library/UnitySkills/cli_config.json to confirm the CLI is enabled, then ask the assistant to cold-start the bound Unity project and wait for the REST health endpoint.

Frequently Asked Questions about unity-cli

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run Unity tests headlessly from the command line?

Use `unity test <projectPath> --mode EditMode --output test-results.xml --timeout 1800` with the Unity CLI. It runs without opening the editor interactively and writes an NUnit XML report; exit code 0 means all passed, 6 means failures.

How do I cold-start the Unity Editor when it is not running?

Run `unity open <projectPath> --args -unityskills-coldstart` after confirming the project's cli_config.json has enabled:true. The marker forces the UnitySkills REST server to start, then poll /health until ready.

When should I use the Unity CLI versus the UnitySkills REST API?

Use the CLI only when the editor is closed: cold starts, full headless test runs, batch runs, and builds. Once the editor is running and /health responds, all normal operations go through REST skills, since Unity refuses a second instance on the same project.

Does the Unity CLI work on older Linux distributions?

Starting with beta4, the Unity CLI requires glibc 2.34+ and no longer supports Ubuntu 20.04, Debian 11, RHEL/CentOS 8, or Amazon Linux 2. On those systems it fails with a glibc error rather than 'command not found'.

Why does the Unity CLI refuse to build my project?

The build command refuses to run with uncommitted changes as a dirty-worktree guard. Commit your changes first, or pass --allow-dirty-build only when the user explicitly requests it.

What are the limitations of the Unity CLI automation workflow?

It operates only on the bound project with an enabled cli_config.json, never installs editors or passes --allow-install, and cannot run against a project whose editor is already open. Feature availability also varies by CLI beta version.