UnityCommandLineLauncher 0.4.0

Unity Command Line Launcher

A terminal command to open Unity projects quickly from the command line.

Supported Platforms

• macOS
• Windows
• Linux

Commands

Name	Description
open [path]	Opens the Unity editor by searching for a project within path.
open	Shows a selection prompt of recent or favorite projects from the Unity Hub.
install [version]	Installs the Editor by version, fetching the revision, if necessary.
install-missing	Installs all Unity versions used by projects but not installed.
uninstall-unused	Uninstalls all Unity versions not used by any projects.
editor-revision [version]	Fetches the revision from Unity's API.
editor-path [version]	Gets the installation directory of the Editor, if installed.
editor-modules [version]	Lists installed modules for a Unity version.
project-version <path>	Gets the Unity version information from a project.
project-path [path]	Gets the Unity project root directory from a search path.
reset-project [path]	Deletes generated files and directories from a Unity project.
projects-using [version]	Finds all projects that use a specific Unity version.
version-usage	Lists installed Unity versions and indicates which are used.
create <directory> [version]	Creates a new empty Unity project in the directory.
upm-git-url [path]	Generates a package git URL for Unity Package Manager from a project.
hub	Executes Unity Hub interactively or with additional CLI arguments.
completion [shell]	Generates shell completion scripts (supports ZSH).

path can be a ProjectVersion.txt file or a directory (searches up and down for projects). If a directory contains multiple Unity projects, an interactive prompt will request a single selection.

If path is omitted, it can be selected interactively from a prompt that shows recent projects from the Unity Hub. Add the --favorite flag to show favorites instead.

If the version argument is omitted, an interactive prompt shows all installed editor versions.

---

Installation

NuGet Global Tool

The easiest way to install ucll is as a .NET global tool via NuGet:

dotnet tool install --global UnityCommandLineLauncher

Requirements:

• .NET 10.0 or newer

If you don't want to install .NET just for this tool, you can use a self-contained (standalone) binary, see below.

Updating:

dotnet tool update --global UnityCommandLineLauncher

Uninstalling:

dotnet tool uninstall --global UnityCommandLineLauncher

After installation, the ucll command will be available globally in your terminal.

From Source

1. Clone the repository.
2. Checkout a release tag and take note of the signature, e.g. git tag -v v1.0.0.
3. Navigate to the project directory:

   cd src/ucll
   

4. Produce a binary:

   dotnet publish
   

5. Find the binary in e.g. src/ucll/bin/osx-arm64/publish/

Download Binaries

Or, download a binary from the GitHub Releases page.

E.g. for macOS with an M4 Apple processor: ucll-osx-arm64.tar.gz

See Security.md for instructions on how to verify the authenticity of your download.

---

Setup

It is recommended to create an alias for ucll in your shell config (.zshrc, .bashrc, etc.):

echo 'alias unity="~/UnityCommandLineLauncher/src/ucll/bin/Release/osx-arm64/publish/ucll"' >> ~/.zshrc

This makes the tool available everywhere and allows you to pick a name.

Or, add the directory that contains the binary to your PATH variable.

export PATH=$PATH:~/UnityCommandLineLauncher/src/ucll/bin/Release/osx-arm64/publish/

You may need to make the file executable on Unix:

chmod +x ucll

Interaction Selection Prompt

Various commands have optional parameters which show a selection prompt:

• Use the arrow keys to select an item and press Enter to confirm
• Type on the keyboard to start searching.

Enhanced Fuzzy Search (Optional)

Install fzf 0.67.0 or newer:

brew install fzf

With fzf installed, the interactive project selection (ucll open) will use enhanced matching:

• Acronyms: cfp finds "core-frontend-platform"
• Typo tolerance: sigle-sign finds "single-sign-on"

Press the ESC key to cancel the prompt.

If fzf is not installed, the built-in search will be used as a fallback. Press CTRL + C to cancel the prompt. Known bug: This will leave the console cursor hidden.

Shell Completion (Optional)

ucll supports generating shell completion scripts to enable tab completion for commands and options.

ZSH Setup

1. Generate the completion script:

   ucll completion > ~/.zsh/completions/_ucll
   

2. Enable completions in your ~/.zshrc (if not already configured):

   # Add completion directory to fpath
   fpath=(~/.zsh/completions $fpath)
   
   # Initialize completion system
   autoload -Uz compinit && compinit
   

3. Reload your shell:

   exec zsh
   

   Or simply open a new terminal window.

Completion Usage

Once installed, you can use tab completion:

• ucll <TAB> - Shows all available commands
• ucll open <TAB> - Shows options like --favorite, --code-editor, --dry-run
• ucll version-usage <TAB> - Shows options like --plaintext, --modules

Updating Completions

When you update ucll or new commands are added, regenerate the completion script:

ucll completion > ~/.zsh/completions/_ucll
exec zsh

Unity Hub

• Ensure version 3.15.4 or newer is installed (https://unity.com/download)

---

Usage

Discover available commands and options:

ucll --help

Show more info about a command:

ucll open --help

Forward additional arguments to Unity Hub/Editor by separating them with a --:

ucll open path/to/project -- -batchmode -quit

ucll install 2022.3.10f1 -- --module webgl

Features

• Opens Unity projects from the terminal (faster than using the Unity Hub GUI)
• Interactive project selection from Unity Hub's recent projects (optional favorites filter)
• Detects Unity Editor version from projects
• Installs missing Unity Editor versions via Unity Hub
• Fetches changeset info from Unity API when missing in ProjectVersion.txt (e.g. legacy projects)
• Forwards additional Unity CLI arguments (e.g. -batchmode -quit)
• Auto-detects Unity Hub and Editor installation paths

Configuration

If Unity Hub and the editors are installed in their default location, there should be no configuration needed.

Installations are detected in the following order:

1. Environment variables (optional, see table below)
2. Default paths on platform
3. Search heuristic to find the paths

Environment variables are optional but speed up execution for non-default installations.

Platform	Environment Variable Example
macOS	UNITY_EDITOR_PATH="/Applications/Unity/Hub/Editor/{0}/Unity.app/Contents/MacOS/Unity"
	UNITY_HUB_PATH="/Applications/Unity Hub.app/Contents/MacOS/Unity Hub"
Windows	UNITY_EDITOR_PATH="C:\Program Files\Unity\Hub\Editor\{0}\Editor\Unity.exe"
	UNITY_HUB_PATH="C:\Program Files\Unity Hub\Unity Hub.exe"
Linux	UNITY_EDITOR_PATH="/home/<user>/Unity/Hub/Editor/{0}/Editor/Unity"
	UNITY_HUB_PATH="/home/<user>/Applications/Unity Hub.AppImage"

The placeholder {0} is part of the path pattern and will be replaced with the Editor version at runtime.

Tips & Examples

The command API is intentionally kept simple and (hopefully) logical. Save your favorite invocations as aliases to make the most out of this tool:

alias uo="ucll open --code-editor"

With this, opening a Unity project and the IDE in the current directory becomes a breeze:

uo .

Remember to take advantage of the builtin search to interactively select from multiple projects:

uo ~/repos

You can use the project-path command to cd into a directory (e.g. for updating git in a project) before opening Unity:

cd $(ucll project-path)

---

Design Background

Problems

• Unity Hub is slow to open and requires manual project management
• GUI-based workflows are cumbersome for multiple projects
• Unity Hub CLI has limitations:
  • requires hardcoded paths
  • needs changeset info for installations
  • install command requires architecture detection on macOS
• Managing many editor versions and projects can be cumbersome because of the missing usage overview

Solutions

• Terminal access is faster (global hotkeys, IDE integration, Finder context menu)
• The tool improves existing Unity Hub API
• Additional commands provide convenience functionality

---

Contributing

See the guideline.

See the developer readme for instructions on how to build and work with the source.