SkillAgentSearch skills...

unity-cli

Guide for using the experimental Unity CLI with bound UnitySkills projects

Install / Use

npx skills add Besty0728/Unity-Skills --skill unity-cli

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

91/100

Supported Platforms

Universal

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.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
14/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
unity-cli (this skill)by Besty0728911.8k53d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP 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.

name: 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 via Window > UnitySkills → AI Config → Unity CLI Setup….
  • enabled: true → use cliPath as the executable (it may not be on your PATH). Respect the per-feature switches in features:
{
  "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). cliVersion in 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> --version and <cliPath> <command> --help — --help is 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 json first (environment snapshot; --tail <n> for more log) and re-check --help before 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 on errors[].code (LICENSE_NONE, EDITOR_NOT_INSTALLED, DISK_SPACE_LOW, NETWORK_UNREACHABLE): 6 → stop and report, 7 → retry a few times, then tell the user. Plain doctor always exits 0. beta6–8 on macOS may hang on a keychain prompt — wrap it in a shell timeout.
  • projects verify needs no Editor, licence or network and only detects: META_MISSING / META_ORPHAN / GUID_DUPLICATE / CONFLICT_MARKERS / MANIFEST_INVALID exit 6 — report, never hand-repair; warnings (PATH_UNVERIFIABLE, EDITOR_VERSION_DRIFT via --expect-editor <version>) exit 0 unless --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:

  1. Read the project's own cli_config.json first. Only proceed if it exists and enabled: true.
  2. Check the UnitySkills registry: read ~/.unity_skills/registry.json, find the entry whose path equals the project root, then test its pid (ps -p <pid> / Windows tasklist). Live pid → the editor is running but busy (Domain Reload / import) → keep the normal REST wait-and-retry; do not cold-start.
  3. Cross-check with the CLI process list: <cliPath> editors running --format json --non-interactive lists the Editor instances the CLI can see. This is useful confirmation, but it only sees instances the CLI's backend recognizes.
  4. Check Library/UnityLockfile. A held lockfile means an Editor instance is open on this project even if the registry entry is missing.
  5. <cliPath> status is 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 (default test-results.xml). In CI, continue to use this file for test results.
  • CI-only parameters — test --help may 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, --timeout per attempt, flaky tests named in test-results.retries.json, never-passing tests still exit 8) and --rerun-failed (reads the failing set from --output, writes test-results.rerun.xml). beta9+ --affected --since <ref> runs only the tests a change can reach (an approximation, writes test-results.affected.xml) — run --affected-compare first to measure its false-negative rate before trusting it. The selectors are mutually exclusive. Use a parameter only if the current binary's test --help lists it; never guess names.
  • --timeout <seconds> (env UNITY_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: 0 all passed (also when --retries rescued a flaky test — the flakiness is still reported). beta6+: 8 tests failed (errors[0].code TESTS_FAILED); 6 no verdict — compile error, licence or Editor crash (TEST_RUN_ERROR), --timeout expiry (TEST_TIMED_OUT). beta3–5: 6 covers both — read the XML to tell them apart. 7 Unity services unreachable after CLI retries; 130 SIGINT; 143 SIGTERM; any other non-zero = the command itself failed — check stderr, the JSON envelope and errors[].code, not just the XML. Retry 6/7 if at all; never retry 8.

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 run unity test against 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 -quit is 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> (env UNITY_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 — same Library/UnityLockfile rule 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

View on GitHub
GitHub Stars1.8k
CategoryDevelopment
Updated1mo ago
Forks165

Languages

C#

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions