unity-cli

Automates Unity Editor lifecycle, headless tests, and builds via the experimental Unity CLI.

Updated Aug 31, 2026
One-click install
npx skills add https://github.com/pikachu0310/codex-agent-ops-public --skill unity-cli-pikachu0310
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: unity-cli
Source: https://github.com/pikachu0310/codex-agent-ops-public/tree/main/.agents/skills/unity-skills/skills/unity-cli
Command: npx skills add https://github.com/pikachu0310/codex-agent-ops-public --skill unity-cli-pikachu0310

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Unity 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 batch builds impossible when the Editor is closed. This Skill governs safe use of the experimental Unity CLI so those operations work on a bound project without the Editor open. ## Core Features & Use Cases - Cold start and lifecycle control: Launch a closed Unity Editor with the -unityskills-coldstart marker, verify liveness via the registry, PID checks, and Library/UnityLockfile, then wait for REST health. - Headless tests and batch runs: Execute EditMode/PlayMode tests with NUnit XML output and run one-shot -executeMethod batch jobs with timeouts and structured exit codes. - Headless builds: Build via Unity 6 Build Profiles, built-in desktop targets, or custom C# build methods, with dirty-worktree guards and signal-aware crash diagnostics. - Use Case: In a CI pipeline, run unity test against a bound project with --format json --non-interactive and a timeout, then parse the NUnit XML report for results while the Editor stays closed. ## Quick Start Check the project's Library/UnitySkills/cli_config.json to confirm the CLI is enabled, then ask the agent to run the project's EditMode tests headlessly with JSON output and a timeout.

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 the Unity CLI test command with the project path, --mode EditMode or PlayMode, --output for the NUnit XML report, and --timeout for unattended runs. Exit code 0 means all tests passed, while 6 means at least one test failed.

How do I start a Unity Editor that is not running?

Use the CLI open command with the project path and pass --args -unityskills-coldstart so the UnitySkills plugin force-starts its REST server. First confirm the required editor version is installed with editors -i, then poll the REST /health endpoint until ready.

When should I use the Unity CLI instead of the UnitySkills REST API?

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

Can the Unity CLI build for Android or WebGL?

Yes, but mobile and WebGL targets require a custom static C# build method passed via --execute-method, with --output-path forwarded as -buildOutput. Built-in desktop builds and Unity 6 Build Profiles can run without a custom method on beta4 and later.

Why does the Unity CLI fail to start on older Linux distributions?

Starting with beta4, the Unity CLI requires glibc 2.34 or newer, so Ubuntu 20.04, Debian 11, RHEL 8, and Amazon Linux 2 are unsupported. The fix is upgrading the OS or using another machine, not reinstalling the CLI.

What authorizes the Unity CLI to operate on a project?

Only the project's own Library/UnitySkills/cli_config.json with enabled set to true authorizes CLI use, and per-feature flags gate cold starts, tests, runs, and builds. The global registry is for liveness checks only and never grants authorization.