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

1. Use tokens in CI/CD, never plaintext passwords in repo files.
2. Validate before building — catch config errors early with project validate.
3. Version your builds — tag releases explicitly so CI output maps to source.
4. Cache build artifacts — reuse editor cache across runs to speed up CI.
5. Test locally first — verify CLI commands work on your machine before committing to CI.
6. Use official Docker images — pre-built images avoid OS dependency drift.
7. 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