Documentation

Unity command-line interface (CLI)

Unity Pipeline

Unity Hub

Download Unity Hub

Unity command-line interface (CLI)

Define and name Unity CLI commands

Define Unity CLI commands with the CliCommand attribute, and choose consistent names for groups, commands, arguments, and tags.
Read time 4 minutesLast updated 5 days ago
To define a command, add the 
[CliCommand]
attribute to a static method and pass the group the command belongs to:
[CliCommand(    group: "animation.animator",      // Required    description: "Creates an Animator Controller asset.",    Tags = new[] { "destructive" })]  // Optional labels onlystatic CommandResult CreateController(...)  // Command name: create_controller
The 
group
parameter is required. You can pass any group string. If no 
group
with that name exists yet, passing it creates the group.
To register a command in code instead of with the attribute, call 
CommandRegistry.RegisterCommand
. It takes the same 
group
parameter, and you must pass the name explicitly.

How the command name is derived

The 
name
parameter is optional. If you omit it, the command name is the method name converted to snake_case:

Rule

Method name

Command name

Split the name at each capital letter and join the words with 
_
.
CreateController
create_controller
Treat an acronym as one word.
GetUIElement
get_ui_element
Keep digits with the word before them.
Vector3Field
vector3_field

Override the command name

To set the command name yourself, pass 
Name
in the attribute. The value you pass replaces the derived name. Use this to rename a method without breaking the command name that users and scripts rely on:
[CliCommand(group: "animation.animator", Name = "create_controller")]static CommandResult MakeAnimatorController(...)

Name commands

Write group and command names in lowercase snake_case. The Pipeline package follows the conventions in this section for its own commands. They're recommendations, not requirements: you can use your own groups, names, and verbs.
If the last segment of the group already names the object the command acts on, use only a verb as the command name. For example, the command that creates a clip in the 
animation.clip
group is 
create
:
unity command animation.clip createunity command animation.timeline create
If the command acts on a different object, add the object after the verb. For example, the command that creates a controller in the 
animation.animator
group is 
create_controller
.
The following table shows examples of both patterns:

Group

Command name

Pattern

animation.clip
create
Verb only. The group already names the object.
animation.timeline
create
Verb only. The group already names the object.
animation.animator
create_controller
Verb and object.
lighting
get_settings
Verb and object.

Choose a verb

Reuse the verbs the Pipeline package already uses where they fit. Some verbs have a specific meaning:

Verb

Use it to

get
Return the state of one object.
list
Enumerate a known set of objects.
find
Query objects that match a condition.
create
Make a new persistent artifact, such as an asset.
add
Attach something to an existing parent object.
The other common verbs mean what they say: 
set
, 
delete
, 
remove
, 
rename
, 
move
, 
copy
, 
run
, 
cancel
, and 
status
.
You can also use domain verbs, such as 
bake
, 
apply
, 
import
, 
instantiate
, 
recompile
, 
save
, 
search
, 
start
, 
stop
, or 
switch
. If none of these verbs fit, use any other verb that describes the operation.
Tip
If a command starts a job, name the command that reports on that job after the verb followed by 
_status
. For example, 
bake
pairs with 
bake_status
, and 
recompile
pairs with 
recompile_status
.

Organize commands into subgroups

If an object has many commands, give it its own subgroup, such as 
animation.animator.controller
, and use plain verbs for the command names. If an object has only a few commands, include the object in the command name instead, such as 
create_controller
. The last segment of a subgroup is usually a noun. How you split a group is your decision as the command author.
The Pipeline package always uses subgroups for settings, with one subgroup per domain. For example, to read or write Player settings, use the 
settings.player
subgroup:
unity command settings.player getunity command settings.player set
Note
The 
capture
group is the only group whose name is a verb. Its command names are objects instead of verbs, such as 
capture game_view
and 
capture scene_view
.

Name arguments

Follow these rules when you name command arguments:
  • Use lowercase snake_case, such as 
    game_object
    , 
    module_name
    , or 
    max_depth
    . Don't use hyphens.
  • Name an argument that takes one asset or file path as 
    path
    . Name an argument that takes several paths as 
    paths
    .
  • Name Boolean flags as positive assertions. For example, use 
    enable
    rather than 
    enabled
    .
Arguments can only use types that the Unity CLI can convert from command-line parameters. The command system validates parameter types when it registers a command.

Add tags

Tags describe what a command is like, such as 
destructive
, 
async
, 
runtime
, or 
dry_run
. A command can have no tags or any number of tags. Don't use tags to say where a command lives, because that's the purpose of the group.
As groups and tags are separate, you can combine them to filter commands. For example, the following options list the commands in the 
lighting
group that aren't tagged 
destructive
:
--group lighting --exclude-tag destructive

Additional resources