Agent Skills: unityctl - Unity Editor Remote Control

unityctl - Unity Editor Remote Control

Control a running Unity Editor from the command line without batch mode.

Instructions

Setup (Required First)

1. Start the bridge daemon: unityctl bridge start
2. Launch Unity: unityctl editor run or manually open the project in Unity Editor
3. Verify connection: unityctl status

Refresh Assets After Script Changes

After modifying C# scripts, refresh assets to compile:

unityctl asset refresh

Returns compilation errors directly in the output (non-zero exit code on failure). Fix errors and re-run until compilation succeeds before entering play mode.

Common Commands

Status & Bridge:

unityctl status           # Check Unity running, bridge, and connection status
unityctl bridge start     # Start bridge daemon (runs in background)
unityctl bridge stop      # Stop bridge

Editor Lifecycle:

unityctl editor run         # Launch Unity Editor (auto-detects version)
unityctl editor stop        # Stop running Unity Editor

Play Mode:

unityctl play enter       # Enter play mode
unityctl play exit        # Exit play mode

Logs:

unityctl logs                 # Show all logs since last clear (auto-clears on play enter and compile)
unityctl logs -n 50           # Limit to last 50 entries
unityctl logs --stack         # Show stack traces for log entries
unityctl logs --full          # Show full history (ignore clear boundary)

Scenes:

unityctl scene list                            # List scenes
unityctl scene load Assets/Scenes/Main.unity   # Load scene

Testing:

unityctl test run                    # Run edit mode tests
unityctl test run --mode playmode    # Play mode tests

Screenshots:

unityctl screenshot capture          # Capture screenshot

Script Execution (Debugging Power Tool)

Execute arbitrary C# in the running editor via Roslyn. Invaluable for debugging and automation.

// tmp/get-version.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        return Application.version;
    }
}

unityctl script execute -f tmp/get-version.cs

You can also execute code directly with -c:

unityctl script execute -c "using UnityEngine; public class Script { public static object Main() { return Application.version; } }"

Scripts must define a class with a public static object Main() method. The return value is JSON-serialized.

Getting Help

unityctl --help              # List all commands
unityctl <command> --help    # Command-specific help

Examples

Workflow: Edit script, compile, and test:

# After editing C# files...
unityctl asset refresh       # Returns compilation errors if any
unityctl play enter
unityctl logs                # Check runtime logs (shows all since play enter)
unityctl play exit

Debug: Find all GameObjects in scene:

// tmp/find-objects.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        return GameObject.FindObjectsOfType<GameObject>().Length;
    }
}

unityctl script execute -f tmp/find-objects.cs

Debug: Inspect Player position:

// tmp/find-player.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        var go = GameObject.Find("Player");
        return go?.transform.position.ToString() ?? "not found";
    }
}

unityctl script execute -f tmp/find-player.cs

Debug: Log message to Unity console:

// tmp/log-message.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        Debug.Log("Hello from CLI");
        return "logged";
    }
}

unityctl script execute -f tmp/log-message.cs

Best Practices

• Run unityctl status to check overall project status before running commands
• Always run unityctl asset refresh after modifying C# files before entering play mode
• For script execution, write scripts to tmp/<scriptname>.cs and execute with -f

Troubleshooting

Run unityctl status first to diagnose issues.

| Problem | Solution | |---------|----------| | Bridge not responding | unityctl bridge stop then unityctl bridge start | | Editor not connected to newly started bridge | Normal, editor plugin uses exponential backoff, up to 30 seconds | | Connection lost after compile | Normal - domain reload. Auto-reconnects. | | "Project not found" | Run from project directory or use --project flag | | Editor not found | Use --unity-path to specify Unity executable |