Run custom commands in the Unity CLI

Use unity command to run custom commands and Pipeline package commands, list command group contents, and learn how the Unity CLI resolves commands.

Read time 3 minutes

Last updated 4 days ago

Use

unity command

to run commands defined with the

[CliCommand]

attribute, including Pipeline package commands and your own custom commands.

Note

For commands built into the Unity CLI, such as

unity install

unity open

, refer to Unity CLI reference.

Run a command

To run a command from the Unity CLI, pass its group, its name, and any arguments to

unity command


unity command <group> <name> [args]

For example, the following command creates an Animator Controller with the

create_controller

command in the

animation.animator

group:


unity command animation.animator create_controller

Type the group as a single token, with dots between subgroups. For example, type

animation.animator

, not

animation animator

Run a command by its ID

You can also run a command by its ID:


unity command <group>.<name> [args]

In an ID, the last dot-separated segment is the command name and everything before it is the group. For example,

unity command build.run

runs the

run

command in the

build

group.

Run a command without its group

Every command belongs to a group, but in some cases you can leave the group out when you run the command.

Run commands in the global group

Commands in the

global

group can run with or without the group name. For example, if the

global

group contains a

status

command, the following commands are equivalent:


unity command global statusunity command status

When you run a command without a group, the Unity CLI looks up the name in the

global

group first.

Run a command with a unique name

If no other group has a command with the same name, you can run the command without its group. For example, if

create_controller

exists only in the

animation.animator

group, the following commands are equivalent:


unity command animation.animator create_controllerunity command create_controller

This shortcut only works for names that are unique across all groups. For example,

create

exists in both the

animation.clip

and

animation.timeline

groups, so you must include the group:


unity command animation.clip create

Tip

In scripts and batch files, include the group even when the command name is unique. If someone later adds a command with the same name to another group, or to the

global

group, a command without its group might stop working or run a different command.

List commands in a group

To list the contents of a group, pass only the group:


unity command animation           # Lists the contents of animation, such as subgroupsunity command animation.animator  # Lists the contents of animation.animator, such as commands

Groups have no default command, so passing only a group always lists its contents instead of running a command.

How the Unity CLI resolves a command

The Unity CLI checks the first token after

unity command

in the following order:

If the token is a group and a command name follows it, the Unity CLI runs that command.
If the token is a group and nothing follows it, the Unity CLI lists the group's contents.
If the token is a command ID, the Unity CLI runs that command.
If the token is the name of a command in the
```
global
```
group, the Unity CLI runs that command.
If the token isn't in the global group and is the name of a command that exists in only one group, the Unity CLI runs that command.

If the token doesn't match any of these cases, the Unity CLI returns an error. A single token that matches a group always lists that group, even if a command ID has the same spelling. For example, if the

build

group has both a

build.target

subgroup and a

target

command:


unity command build.target  # Lists the build.target subgroupunity command build target  # Runs the target command in the build group

Unity command-line interface (CLI)

Unity Pipeline

Unity Hub