unityctl - Unity Editor Remote Control

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

Instructions

Setup (Required First)

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

Refresh Assets After Script Changes

After modifying C# scripts, refresh assets to compile:

bash

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:

bash

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:

bash

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

Play Mode:

bash

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

Logs:

bash

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:

bash

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

Testing:

bash

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

Screenshots:

bash

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;
    }
}

bash

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

You can also execute code directly with -c:

bash

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

bash

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

Examples

Workflow: Edit script, compile, and test:

bash

# 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;
    }
}

bash

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";
    }
}

bash

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";
    }
}

bash

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

Search AI Tools

unity-editor

Install this agent skill to your Project

SKILL.md

unityctl - Unity Editor Remote Control

Instructions

Setup (Required First)

Refresh Assets After Script Changes

Common Commands

Script Execution (Debugging Power Tool)

Getting Help

Examples

Best Practices

Troubleshooting