name: unity-cli description: > Install, configure, and use the Unity Command Line Interface (CLI) for automated production workflows, project management, and cloud integration. Use when setting up CLI-based build automation, CI/CD pipelines, Editor/module management, authentication, or localhost API calls via the experimental Unity Pipeline package. Designed for verifiable, machine-readable game production workflows where the build machine must be describable and tests must return evidence. Triggers on: Unity CLI, unity command line, unity automation, unity ci/cd, unity build script, unity pipeline, unity production workflows. allowed-tools: Bash Read Write Edit Glob Grep compatibility: > macOS, Linux, Windows with .NET 6.0+ runtime. Requires active Unity license or trial account. Works with Unity 2020 LTS and later projects. Experimental CLI and Pipeline package as of July 2026. metadata: tags: unity, cli, automation, ci-cd, build, project-management, cloud, licensing, production, pipeline version: "1.1.0" source: https://unity.com/kr/blog/meet-the-unity-cli

Unity CLI

Streamline Unity project workflows and automation through the command line.

When to use this skill

Install and verify the Unity CLI in your environment
Set up authentication for CI/CD pipelines or automated builds
Create or manage Unity projects programmatically
Automate build, test, or project initialization workflows
Configure cloud save, licensing, or organization settings
Integrate Unity CLI into GitHub Actions, Jenkins, or similar CI systems

When not to use this skill

For interactive game development workflows → use unity-gamedev-skill-pack
For graphics/rendering tasks → use threejs-* or engine-specific skills
For UI design in game context → use game-studio-harness or open-design-game-ui-*
For VFX or animation → use game-vfx or video-motion-previs

Instructions

Step 1: Capture the automation intent

Identify:

Goal: build automation, project setup, CI/CD integration, cloud operations, or licensing
Environment: local development, GitHub Actions, Jenkins, GitLab CI, or custom runner
Scope: single project, monorepo, or organization-wide automation
Auth: service account, personal token, or interactive login

Step 2: Check prerequisites

Verify:

dotnet --version
which unity-cli || which unity

If not installed, proceed to Step 3.

Step 3: Install Unity CLI

Local installation:

bash .agent-skills/unity-cli/scripts/setup.sh --install

Docker (CI/CD):

Use official Unity Docker images with CLI pre-installed:

docker pull unityci/editor:<version>-<platform>-<architecture>

Manual (system-wide):

Follow Unity CLI installation docs and add to PATH.

Step 4: Authenticate

Interactive login:

unity-cli manage licensing --authenticate

CI/CD token (recommended):

export UNITY_SERIAL=<serial>
export UNITY_EMAIL=<email>
export UNITY_PASSWORD=<password>

unity-cli manage licensing --validate

For service accounts, use personal access tokens instead of plaintext passwords.

Step 5: Run common workflows

Create a new project:

unity-cli project create --name myproject --template 3d

Manage Editor installations:

# List available Editor versions
unity-cli install --list

# Install exact Editor version with specific modules
unity-cli install 2023.2.10f1 -m android ios webgl --accept-eula --yes

# Open project with auto-detected Editor version
unity-cli open ./MyGame

Build with verifiable output (JSON/TSV):

# Machine-readable build output
unity-cli build --project /path/to/project \
  --platform WebGL \
  --output /path/to/build \
  --format json > build-result.json

# Parse results in CI
cat build-result.json | jq '.success'

Invoke the Pipeline package (localhost API):

# Requires: com.unity.pipeline experimental package installed
# Requires: Editor running with --api-port flag

# Example: Evaluate C# in running Editor
curl -X POST http://localhost:14000/eval \
  -H "Authorization: Bearer $PIPELINE_TOKEN" \
  -d '{"code": "Debug.Log(Application.version)"}'

Validate setup:

unity-cli doctor

Run tests with evidence:

unity-cli test --project /path/to/project \
  --results-file test-results.xml \
  --format json > test-output.json

Step 6: Integrate into CI/CD

Example GitHub Actions workflow:

name: Unity Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: bash .agent-skills/unity-cli/scripts/setup.sh --ci
      - run: unity-cli build --project . --platform WebGL --output ./dist
      - uses: actions/upload-artifact@v3
        with:
          name: build
          path: ./dist

See references/ci-cd-patterns.md for Jenkins, GitLab CI, and other runners.

Step 7: Troubleshoot failures

License validation fails:

unity-cli manage licensing --validate --verbose

Build fails with missing dependencies:

unity-cli project validate --project /path/to/project

CLI not found:

bash .agent-skills/unity-cli/scripts/setup.sh --diagnose

Common issues and solutions are in references/troubleshooting.md.

Examples

Example 1: Set up CI/CD for a WebGL build

A GitHub Actions workflow needs to build a game for WebGL. Use the skill to install the exact Editor version, validate the project, build with structured output, and parse results.

Example 2: Verify game build in production

An AI agent needs to confirm that a build succeeded and retrieve the output path. Use JSON-formatted build output to parse success/failure and let the agent make decisions based on structured results.

Example 3: Query running Editor via Pipeline package

A CI job needs to check build info while the Editor is running. Install the com.unity.pipeline package, start the Editor with --api-port, and query custom CLI commands from the script.

Best practices

Use tokens in CI/CD, never plaintext passwords in repo files.
Validate before building — catch config errors early with project validate.
Version your builds — tag releases explicitly so CI output maps to source.
Cache build artifacts — reuse editor cache across runs to speed up CI.
Test locally first — verify CLI commands work on your machine before committing to CI.
Use official Docker images — pre-built images avoid OS dependency drift.
Keep CLI updated — periodically refresh to latest stable version for bug fixes and new features.

References

Unity CLI Documentation
references/commands.md — detailed command reference
references/ci-cd-patterns.md — GitHub Actions, Jenkins, GitLab CI examples
references/production-workflows.md — verifiable game production workflows with evidence
references/troubleshooting.md — common errors and solutions
scripts/setup.sh — automated install and verification

CLI Unity

Recommandé pour