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