---
title: Define and name Unity CLI commands
product: Unity command-line interface (CLI)
canonical: https://docs.unity.com/en-us/unity-cli/command-name-conventions/define-command
last_updated: 2026-11-06
generated_at: 2026-11-11T15:53:35.512Z
locale: en-us
---

# Define and name Unity CLI commands

> Define Unity CLI commands with the CliCommand attribute, and choose consistent names for groups, commands, arguments, and tags.

To define a command, add the `[CliCommand]` attribute to a static method and pass the group the command belongs to:

```csharp
[CliCommand(
    group: "animation.animator",      // Required
    description: "Creates an Animator Controller asset.",
    Tags = new[] { "destructive" })]  // Optional labels only
static 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:

```csharp
[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`:

```bash
unity command animation.clip create
unity 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:

```bash
unity command settings.player get
unity 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`:

```bash
--group lighting --exclude-tag destructive
```

## Additional resources

* [Use the Unity CLI](/unity-cli/use-unity-cli.md)
* [Unity CLI reference](/unity-cli/reference.md)
* [Install Pipeline package](/unity-cli/unity-pipeline/unity-pipeline-package.md)