unity-cli
Guide for using the experimental Unity CLI with bound UnitySkills projects
Install / Use
npx skills add Besty0728/Unity-Skills --skill unity-cliInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of unity-cli
unity-cli scores 91/100 on our quality scale, 1079th of 4,698 Development & Engineering skills we index (top 23%).
Its SKILL.md is 23 KB long, well organised into 15 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.
With 1,781 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so unity-cli is actively maintained.
- Our last check on 2026-10-29 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
unity-cli compared with similar skills
All 4 of these similar skills score higher than unity-cli; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| unity-cli (this skill)by Besty0728 | 91 | 1.8k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install unity-cli?
- Run
npx skills add Besty0728/Unity-Skills --skill unity-cli. The install tabs above show the steps for each supported agent. - Which AI agents does unity-cli work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is unity-cli safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is unity-cli still maintained?
- The repository was last updated about 2 months ago, so unity-cli is actively maintained.
Skill content
View source on GitHubname: unity-cli description: Guide for using the experimental Unity CLI with bound UnitySkills projects
Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via
GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.
Unity CLI (advisory)
Advisory module — no REST skills. All commands here run in YOUR shell on the user's machine, not through the REST server. That is the point: they work while the Unity Editor is closed.
Gate — read this first
Before using anything below, check the binding config:
<projectRoot>/Library/UnitySkills/cli_config.json
- File missing, unreadable, or
enabled: false→ Unity CLI is OFF for this project. Ignore this module entirely. Do not suggest installing the CLI unprompted; the user opts in viaWindow > UnitySkills → AI Config → Unity CLI Setup…. enabled: true→ usecliPathas the executable (it may not be on your PATH). Respect the per-feature switches infeatures:
{
"schemaVersion": 1,
"enabled": true,
"cliPath": "/Users/me/.local/bin/unity",
"cliVersion": "1.0.0-beta.5",
"projectPath": "/path/to/Project",
"editorVersion": "6000.0.32f1",
"boundAt": "2026-07-26T09:00:00Z",
"features": { "coldStart": true, "openArgs": true, "cliTest": true, "cliRun": false, "cliBuild": false }
}
Configs written by older plugin versions may lack the cliRun / cliBuild keys — for these two, a missing key means OFF (the first three keys keep their original semantics). Both also default to off on fresh binds; the user enables them per project in the panel.
The global registry (~/.unity_skills/registry.json) also carries cliBound / cliPath per running instance — use it for liveness checks only, never as authorization: the ONLY thing that authorizes CLI use for a project is that project's own cli_config.json. Do not cold-start any project whose own config you have not read, even if it appears in the registry. Also note projectPath inside the config is a bind-time snapshot — the directory you actually found the config under is authoritative (helper get_cli_config() already rewrites it); never open the stored path if it differs from the real project root.
Unity CLI is experimental (beta) and its command surface changes between releases — this document was verified against
1.0.0-beta.9(beta.7 was withdrawn the same day it shipped).cliVersionin the config is only a bind-time snapshot; the installed binary moves ahead of it. Before using a command whose semantics changed recently, read<cliPath> --versionand<cliPath> <command> --help—--helpis always the final authority for the binary on disk. beta9+<cliPath> skill show --list/--path <file>prints Unity's own agent skill read-only (offline, ~44k tokens in total — read one file at a time) — a second reference, never an authorization; this module's gates and DO NOT list still apply. If a command errors unexpectedly, run<cliPath> doctor --format jsonfirst (environment snapshot;--tail <n>for more log) and re-check--helpbefore retrying. Never modify the server or config to work around a CLI quirk.
1. Cold start / lifecycle (features.coldStart)
The one capability REST can never provide: starting the editor when it is not running.
<cliPath> status --format json # any editor instances running?
<cliPath> open "<projectPath>" --args -unityskills-coldstart
Always pass --args -unityskills-coldstart when cold-starting: the UnitySkills plugin detects this marker at editor startup and force-starts the REST server for this session, even if the user's Auto-start preference is off. Without the marker you depend on the user's saved preference. The marker is consumed once per editor session — it never overrides a mid-session manual stop.
Preflight — read-only, no feature switch needed. open / test / run / build all resolve the editor from the project's ProjectVersion.txt. Before the first CLI launch of a session run these checks; none of them modifies the project:
<cliPath> editors -i --format json # all versions: is the bound editorVersion installed?
<cliPath> doctor --ci --format json # beta6+: exit 6 = definitive blocker, 7 = retryable
<cliPath> projects verify "<projectPath>" --format json # beta6+: exit 6 = errors, 0 = clean or warnings only
doctor --ci(from the project root) checks licence, the project's editor, disk space and Unity services; branch onerrors[].code(LICENSE_NONE,EDITOR_NOT_INSTALLED,DISK_SPACE_LOW,NETWORK_UNREACHABLE):6→ stop and report,7→ retry a few times, then tell the user. Plaindoctoralways exits0. beta6–8 on macOS may hang on a keychain prompt — wrap it in a shell timeout.projects verifyneeds no Editor, licence or network and only detects:META_MISSING/META_ORPHAN/GUID_DUPLICATE/CONFLICT_MARKERS/MANIFEST_INVALIDexit6— report, never hand-repair; warnings (PATH_UNVERIFIABLE,EDITOR_VERSION_DRIFTvia--expect-editor <version>) exit0unless--strict.
If the editor is not installed, stop and tell the user — never run install or pass --allow-install (see DO NOT).
After launching, poll the UnitySkills REST server until ready (first import/compile can take minutes):
from unity_skills import wait_for_health
health = wait_for_health(timeout=600) # polls /health on ports 8090-8100
beta9+: open exits 6 (OPEN_EDITOR_EXITED) when the Editor dies inside the CLI's short watch window — report it at once instead of waiting on wait_for_health. Only that window is covered: an Editor that quits later is never observed, and older binaries exit 0 regardless, so a wait_for_health timeout remains the real failure signal.
Liveness triage — prefer this over blind retry. When REST is unreachable, determine whether an Editor is actually running before deciding to cold-start:
- Read the project's own
cli_config.jsonfirst. Only proceed if it exists andenabled: true. - Check the UnitySkills registry: read
~/.unity_skills/registry.json, find the entry whosepathequals the project root, then test itspid(ps -p <pid>/ Windowstasklist). Live pid → the editor is running but busy (Domain Reload / import) → keep the normal REST wait-and-retry; do not cold-start. - Cross-check with the CLI process list:
<cliPath> editors running --format json --non-interactivelists the Editor instances the CLI can see. This is useful confirmation, but it only sees instances the CLI's backend recognizes. - Check
Library/UnityLockfile. A held lockfile means an Editor instance is open on this project even if the registry entry is missing. <cliPath> statusis supplementary, not authoritative: it only reflects Unity Pipeline connection state. An empty table / non-zero exit does NOT mean the editor is closed — verified in practice: a running editor without the Pipeline package shows nothing.
If the PID, the CLI process list, or the lockfile indicates an Editor is already running, do not open, run, or build — Unity refuses a second instance on the same project. Only when none of the above show a live Editor for this project should you cold-start with open, then wait_for_health.
2. Launch with arguments (features.openArgs)
<cliPath> open "<projectPath>" --args -openscene "Assets/Scenes/Main.unity"
Anything after --args is passed to the Unity Editor as standard command-line arguments. Useful to land in a known state (specific scene, custom -executeMethod). Only at launch time — for an already-running editor use REST scene_load instead.
3. Headless tests (features.cliTest)
<cliPath> test "<projectPath>" --mode EditMode --filter <pattern> --output test-results.xml --timeout 1800
--mode <EditMode|PlayMode>— omit to run the editor's default test platform; cover both modes with two separate invocations.--filter <pattern>— only run tests whose names match.--output <path>— NUnit XML report (defaulttest-results.xml). In CI, continue to use this file for test results.- CI-only parameters —
test --helpmay list report/coverage flags (beta4+:--report-format nunit,junit,--junit-output,--coverage*) and, beta6+,--shard N/M,--retries N(re-runs only the failed tests,--timeoutper attempt, flaky tests named intest-results.retries.json, never-passing tests still exit8) and--rerun-failed(reads the failing set from--output, writestest-results.rerun.xml). beta9+--affected --since <ref>runs only the tests a change can reach (an approximation, writestest-results.affected.xml) — run--affected-comparefirst to measure its false-negative rate before trusting it. The selectors are mutually exclusive. Use a parameter only if the current binary'stest --helplists it; never guess names. --timeout <seconds>(envUNITY_TEST_TIMEOUT) — kills the Unity process after N seconds; disabled by default, always set one for unattended runs.- Extra editor arguments pass through after
--, e.g.-- -nographics. - Exit codes:
0all passed (also when--retriesrescued a flaky test — the flakiness is still reported). beta6+:8tests failed (errors[0].codeTESTS_FAILED);6no verdict — compile error, licence or Editor crash (TEST_RUN_ERROR),--timeoutexpiry (TEST_TIMED_OUT). beta3–5:6covers both — read the XML to tell them apart.7Unity services unreachable after CLI retries;130SIGINT;143SIGTERM; any other non-zero = the command itself failed — check stderr, the JSON envelope anderrors[].code, not just the XML. Retry6/7if at all; never retry8.
Routing rule:
- Interactive iteration (editor already running, quick feedback on a few tests) → REST
test_*skills. - Full regression / CI-style run, or editor closed →
unity test(headless, NUnit XML output). Do not rununity testagainst a project whose editor is open.
4. Batch runs (features.cliRun)
One-shot batch automation on the bound project only, while the editor is closed — the third lifecycle option between REST (editor open, interactive) and cold start (launch and keep serving):
<cliPath> run "<projectPath>" --timeout 1800 -- -executeMethod Your.Static.Method -quit
- Everything after
--is forwarded to the Unity Editor as standard command-line arguments;-executeMethod <static method>plus-quitis the typical shape (asset re-import, batch fixes, custom pipelines). - Streams the editor log to stdout and returns the editor's exit code — non-zero means the batch run failed. beta5+ reports an Editor crash as
stopped with signal SIG…(see §6) — an Editor crash, not a business-logic failure. --timeout <seconds>(envUNITY_RUN_TIMEOUT) — disabled by default; always set one, a hung batch editor otherwise blocks your shell forever.- Routing: editor already running → use REST skills, never
run(Unity refuses a second instance on the same project — sameLibrary/UnityLockfilerule as cold start). Editor closed + persistent session needed → cold start. Editor closed + one-shot task →run. run --command <name>drives Unity Pipeline package commands — not part of this workflow (see DO NOT).
5. Headless builds (features.cliBuild)
cliBuild is off by default. When the user enables it, choose the build path based on the installed CLI version, Unity Editor version, target platform, and whether a Build Profile exists:
Path 1 — Unity 6 Build Profile (beta4+)
<cliPath> build "<projectPath>" --profile "Windows" --output-path ./Builds/
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
