---
description: >-
  Create, edit and invoke reusable actions that run containerized code on your
  datasets.
sidebar:
  order: 1
title: roboto actions
---
```bash
roboto actions [-h]
               {create,delete,init,invoke,invoke-local,list-invocations,search,show,update} ...
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |

## roboto actions create

Create a new action.

```bash
roboto actions create [-h] [--from-file ACTION_CONFIG_FILE]
                      [--name NAME] [--description DESCRIPTION]
                      [--short_description SHORT_DESCRIPTION]
                      [--inherits_from <action_name> | <action_name>@<digest> | <org>/<action_name> | <org>/<action_name>@<digest>]
                      [--image IMAGE]
                      [--parameter ['name=<name>|required=<true|false>|default=<value>|description=<description>' ...]]
                      [--metadata [KEY=VALUE ...]] [--tag [TAG ...]]
                      [--timeout TIMEOUT] [--org ORG]
                      [--vcpu {256,512,1024,2048,4096,8192,16384}]
                      [--memory MEMORY] [--storage STORAGE] [--gpu]
                      [--entrypoint ENTRY_POINT] [--command COMMAND]
                      [--command-form {exec,shell}] [--workdir WORKDIR]
                      [--env [KEY=VALUE ...]]
                      [--requires-downloaded-inputs REQUIRES_DOWNLOADED_INPUTS]
                      [--yes]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `--from-file <action_config_file>` | Path to a file containing Action configuration. Other CLI arguments specified will override the values in the config file. |
| `--name <name>` | Name of the action. Not modifiable after creation. An action is considered unique by its (name, docker_image_name, docker_image_tag) tuple. |
| `--description <description>` | Optional description of action. Modifiable after creation. |
| `--short_description <short_description>` | Optional description of action. Modifiable after creation. |
| `--inherits_from <action_name> \| <action_name>@<digest> \| <org>/<action_name> \| <org>/<action_name>@<digest>` | Partially or fully qualified reference to action from which to inherit configuration. Inheriting from another action is mutually exclusive with specifying a container image (`--image`), entrypoint (`--entrypoint`), command (`--command`), working directory (`--workdir`), env vars (`--env`), or parameter(s) (`--parameter`). |
| `--image <image>` | Associate a Docker image with this action. Modifiable after creation. |
| `--parameter 'name=<name>\|required=<true\|false>\|default=<value>\|description=<description>'` | Zero or more parameters (space-separated) accepted by this action. `name` is the only required attribute. `default` values, if provided, are JSON parsed. This argument can be specified multiple times. Parameters can be modified after creation. Argument values must be wrapped in quotes. e.g. `--put-parameter 'name=my_param\|required=true\|description=My description of my_param'` |
| `--metadata <KEY=VALUE>` | Zero or more `<key>=<value>` format key/value pairs which represent action metadata. `value` is parsed as JSON. Metadata can be modified after creation. |
| `--tag <tag>` | One or more tags to annotate this action. Modifiable after creation. |
| `--timeout <timeout>` | Optional timeout for an action in minutes, defaults to 30 minutes or 12 hours depending on tier. |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |
| `--requires-downloaded-inputs <requires_downloaded_inputs>` | Optional flag which indicates that invocations of this action require their inputs downloaded to the working directory before running. This is the default. |
| `--yes` | If action with same name already exists, update the existing action without prompting for confirmation. |

**Resource requirements**

Specify required compute resources.

| Argument | Description |
| --- | --- |
| `--vcpu {256,512,1024,2048,4096,8192,16384}` | CPU units to dedicate to action invocation. Defaults to 512 (0.5vCPU). |
| `--memory <memory>` | Memory (in MiB) to dedicate to action invocation. Defaults to 1024 (1 GiB). Supported values range from 512 (0.5 GiB) to 122880 (120 GiB). Supported values are tied to selected vCPU resources. See documentation for more information. |
| `--storage <storage>` | Ephemeral storage (in GiB) to dedicate to action invocation. Defaults to 21 GiB. Supported values range from 21 to 200, inclusive. |
| `--gpu` | This is a placeholder; it currently does nothing. In the future, setting this option will invoke the action in a GPU-enabled compute environment. |

**Container parameters**

Specify parameters to pass to the action's Docker container at runtime.

| Argument | Description |
| --- | --- |
| `--entrypoint <entry_point>` | Container ENTRYPOINT override. Supports passing empty string ("") as an override, which unsets the ENTRYPOINT specified in the docker image. If updating or invoking action which has existing ENTRYPOINT override, specify `null` to remove the override. Refer to docker documentation for more: https://docs.docker.com/engine/reference/builder/#entrypoint and https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime |
| `--command <command>` | Container CMD override. If updating or invoking action which has existing CMD override, specify `null` to remove the override. Refer to docker documentation for more: https://docs.docker.com/engine/reference/builder/#cmd and https://docs.docker.com/engine/reference/run/#cmd-default-command-or-options |
| `--command-form {exec,shell}` | In `exec` form, the provided `--command` str is split into a list of strings (e.g., `--command "-c 'print(123)'"` is parsed as `["-c", "print(123)"]`). In `shell` form, the provided `--command` str is not split (e.g., `--command "python -c 'print(123)'"` is parsed as `["python -c 'print(123)'"]`). Default: `exec`. |
| `--workdir <workdir>` | If updating, specify `null` to clear existing workdir. Refer to docker documentation for more: https://docs.docker.com/engine/reference/run/#workdir |
| `--env <KEY=VALUE>` | Zero or more `<key>=<value>` formatted pairs to set as container ENV vars. Do not use ENV vars for secrets (such as API keys). See documentation: https://docs.docker.com/engine/reference/run/#env-environment-variables |

## roboto actions delete

Delete action and all of its related subresources.

```bash
roboto actions delete [-h] [--org ORG] action_reference: <action_name>
```

**Arguments**

| Argument | Description |
| --- | --- |
| `action_reference: <action_name>` Required | Exact name of action to delete. |
| `-h, --help` | show this help message and exit |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |

## roboto actions init

Initialize a new action package.

```bash
roboto actions init [-h] [path]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `path` | Existing directory under which an action package will be created. |
| `-h, --help` | show this help message and exit |

## roboto actions invoke

Invoke an action on the hosted platform.

```bash
roboto actions invoke [-h] [--file-query FILE_QUERY]
                      [--session-id SESSION_IDS]
                      [--session-query SESSION_QUERY]
                      [--topic-query TOPIC_QUERY]
                      [--dataset DATASET_ID] [--file-path FILE_PATHS]
                      [--org ORG]
                      [-p <PARAMETER_NAME>=<PARAMETER_VALUE>]
                      [--timeout TIMEOUT]
                      [--idempotency_id IDEMPOTENCY_ID]
                      [--output-dataset-id OUTPUT_DATASET_ID]
                      [--vcpu {256,512,1024,2048,4096,8192,16384}]
                      [--memory MEMORY] [--storage STORAGE] [--gpu]
                      [--entrypoint ENTRY_POINT] [--command COMMAND]
                      [--command-form {exec,shell}] [--workdir WORKDIR]
                      [--env [KEY=VALUE ...]]
                      <action_name> | <action_name>@<digest> | <org>/<action_name> | <org>/<action_name>@<digest>
```

**Arguments**

| Argument | Description |
| --- | --- |
| `<action_name> \| <action_name>@<digest> \| <org>/<action_name> \| <org>/<action_name>@<digest>` Required | Partially or fully qualified reference to Action on which to operate. |
| `-h, --help` | show this help message and exit |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |
| `-p, --parameter <PARAMETER_NAME>=<PARAMETER_VALUE>` | Parameter in `<parameter_name>=<parameter_value>` format. `parameter_value` is parsed as a string. Can be specified multiple times for multiple parameters. Default: `{}`. |
| `--timeout <timeout>` | Optional timeout for an action in minutes, defaults to 30 minutes or 12 hours depending on tier. |
| `--idempotency_id <idempotency_id>` | Optional unique ID which ensures that an invocation is run exactly once. |
| `--output-dataset-id <output_dataset_id>` | Unique identifier for a dataset to which any files written to the invocation's output directory will be uploaded. |

**Selector-Based Input**

Specify input data with a RoboQL query or by session ID. Mutually exclusive with dataset and file path-based input.

| Argument | Description |
| --- | --- |
| `--file-query <file_query>` | RoboQL query to select input files. |
| `--session-id <session_ids>` | Unique identifier for a session to use as input. Can be specified multiple times for multiple sessions. |
| `--session-query <session_query>` | RoboQL query to select input sessions. |
| `--topic-query <topic_query>` | RoboQL query to select input topics. |

**Dataset and File Path-Based Input**

Specify input data with a dataset ID and one or more file paths. Mutually exclusive with selector-based input.

| Argument | Description |
| --- | --- |
| `--dataset <dataset_id>` | Unique identifier for a dataset to use as the data source for this invocation. Required if --file-path is provided. |
| `--file-path <file_paths>` | Specific file path from the dataset. Can be specified multiple times for multiple file paths. Requires --dataset to be specified. |

**Resource requirements**

Specify required compute resources.

| Argument | Description |
| --- | --- |
| `--vcpu {256,512,1024,2048,4096,8192,16384}` | CPU units to dedicate to action invocation. Defaults to 512 (0.5vCPU). |
| `--memory <memory>` | Memory (in MiB) to dedicate to action invocation. Defaults to 1024 (1 GiB). Supported values range from 512 (0.5 GiB) to 122880 (120 GiB). Supported values are tied to selected vCPU resources. See documentation for more information. |
| `--storage <storage>` | Ephemeral storage (in GiB) to dedicate to action invocation. Defaults to 21 GiB. Supported values range from 21 to 200, inclusive. |
| `--gpu` | This is a placeholder; it currently does nothing. In the future, setting this option will invoke the action in a GPU-enabled compute environment. |

**Container parameters**

Specify parameters to pass to the action's Docker container at runtime.

| Argument | Description |
| --- | --- |
| `--entrypoint <entry_point>` | Container ENTRYPOINT override. Supports passing empty string ("") as an override, which unsets the ENTRYPOINT specified in the docker image. If updating or invoking action which has existing ENTRYPOINT override, specify `null` to remove the override. Refer to docker documentation for more: https://docs.docker.com/engine/reference/builder/#entrypoint and https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime |
| `--command <command>` | Container CMD override. If updating or invoking action which has existing CMD override, specify `null` to remove the override. Refer to docker documentation for more: https://docs.docker.com/engine/reference/builder/#cmd and https://docs.docker.com/engine/reference/run/#cmd-default-command-or-options |
| `--command-form {exec,shell}` | In `exec` form, the provided `--command` str is split into a list of strings (e.g., `--command "-c 'print(123)'"` is parsed as `["-c", "print(123)"]`). In `shell` form, the provided `--command` str is not split (e.g., `--command "python -c 'print(123)'"` is parsed as `["python -c 'print(123)'"]`). Default: `exec`. |
| `--workdir <workdir>` | If updating, specify `null` to clear existing workdir. Refer to docker documentation for more: https://docs.docker.com/engine/reference/run/#workdir |
| `--env <KEY=VALUE>` | Zero or more `<key>=<value>` formatted pairs to set as container ENV vars. Do not use ENV vars for secrets (such as API keys). See documentation: https://docs.docker.com/engine/reference/run/#env-environment-variables |

## roboto actions invoke-local

Invoke an action locally using Docker.

```bash
roboto actions invoke-local [-h] [--org ORG] [--file-query FILE_QUERY]
                            [--session-id SESSION_IDS]
                            [--session-query SESSION_QUERY]
                            [--topic-query TOPIC_QUERY]
                            [--dataset DATASET_ID]
                            [--file-path FILE_PATHS]
                            [-p <PARAMETER_NAME>=<PARAMETER_VALUE>]
                            [--workspace-dir WORKSPACE_DIR] [--dry-run]
                            [action_or_path]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `action_or_path` | Action to invoke locally. Can be: |

- A path to local action directory (e.g., '.', './my-action', '/abs/path')
- An action reference (e.g., 'my-action', 'org/my-action', 'action@digest')
- Omitted to use current directory

Examples:

```bash
roboto actions invoke-local                    # Use current directory (implied)
roboto actions invoke-local .                  # Use current directory (explicit)
roboto actions invoke-local ./my-action        # Use local action
roboto actions invoke-local my-action          # Fetch from platform
roboto actions invoke-local org/my-action      # Fetch from specific org
```

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |
| `-p, --parameter <PARAMETER_NAME>=<PARAMETER_VALUE>` | Parameter in `<parameter_name>=<parameter_value>` format. `parameter_value` is parsed as a string. Can be specified multiple times for multiple parameters. Default: `{}`. |
| `--workspace-dir <workspace_dir>` | Workspace directory for local execution. Only applicable when invoking a platform action (not an action defined in a local directory). If not specified, a temporary directory is created. |
| `--dry-run` | Run in dry-run mode. Actions should use this flag to gate side effects such as uploading files, modifying metadata, or making non-idempotent API calls. |

**Selector-Based Input**

Specify input data with a RoboQL query or by session ID. Mutually exclusive with dataset and file path-based input.

| Argument | Description |
| --- | --- |
| `--file-query <file_query>` | RoboQL query to select input files. |
| `--session-id <session_ids>` | Unique identifier for a session to use as input. Can be specified multiple times for multiple sessions. |
| `--session-query <session_query>` | RoboQL query to select input sessions. |
| `--topic-query <topic_query>` | RoboQL query to select input topics. |

**Dataset and File Path-Based Input**

Specify input data with a dataset ID and one or more file paths. Mutually exclusive with selector-based input.

| Argument | Description |
| --- | --- |
| `--dataset <dataset_id>` | Unique identifier for a dataset to use as the data source for this invocation. Required if --file-path is provided. |
| `--file-path <file_paths>` | Specific file path from the dataset. Can be specified multiple times for multiple file paths. Requires --dataset to be specified. |

## roboto actions list-invocations

List invocations for action.

```bash
roboto actions list-invocations [-h] [--org ORG]
                                <action_name> | <action_name>@<digest> | <org>/<action_name> | <org>/<action_name>@<digest>
```

**Arguments**

| Argument | Description |
| --- | --- |
| `<action_name> \| <action_name>@<digest> \| <org>/<action_name> \| <org>/<action_name>@<digest>` Required | Partially or fully qualified reference to Action on which to operate. |
| `-h, --help` | show this help message and exit |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |

## roboto actions search

Search for existing actions.

```bash
roboto actions search [-h] [--name NAME] [--actionhub]
                      [--metadata [KEY=VALUE ...]] [--tag [TAG ...]]
                      [--org ORG]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `--name <name>` | If querying by action name, must provide an exact match; patterns are not accepted. |
| `--actionhub` | Search Actions published to the Roboto Action Hub |
| `--metadata <KEY=VALUE>` | Zero or more `key=value` pairs which represent action metadata. `value` is parsed as JSON. e.g. `--metadata foo=bar --metadata baz.nested=200` |
| `--tag <tag>` | One or more tags associated with this action. e.g. `--tag foo --tag bar` |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |

## roboto actions show

Show details for an action.

```bash
roboto actions show [-h] [--org ORG]
                    <action_name> | <action_name>@<digest> | <org>/<action_name> | <org>/<action_name>@<digest>
```

**Arguments**

| Argument | Description |
| --- | --- |
| `<action_name> \| <action_name>@<digest> \| <org>/<action_name> \| <org>/<action_name>@<digest>` Required | Partially or fully qualified reference to Action on which to operate. |
| `-h, --help` | show this help message and exit |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |

## roboto actions update

Update an existing action.

```bash
roboto actions update [-h] [--description DESCRIPTION]
                      [--short-description SHORT_DESCRIPTION]
                      [--image IMAGE] [--timeout TIMEOUT]
                      [--put-parameter ['name=<name>|required=<true|false>|default=<value>|description=<description>' ...]]
                      [--remove-parameter [PARAMETER_NAME ...]]
                      [--put-tags [PUT_TAGS ...]]
                      [--remove-tags [REMOVE_TAGS ...]]
                      [--put-metadata [KEY_PATH=VALUE ...]]
                      [--remove-metadata [KEY_PATH ...]] [--org ORG]
                      [--vcpu {256,512,1024,2048,4096,8192,16384}]
                      [--memory MEMORY] [--storage STORAGE] [--gpu]
                      [--entrypoint ENTRY_POINT] [--command COMMAND]
                      [--command-form {exec,shell}] [--workdir WORKDIR]
                      [--env [KEY=VALUE ...]]
                      action_reference: <action_name>
```

**Arguments**

| Argument | Description |
| --- | --- |
| `action_reference: <action_name>` Required | Exact name of action to update. |
| `-h, --help` | show this help message and exit |
| `--description <description>` | Optional description of action. Specify `null` to unset existing description. |
| `--short-description <short_description>` | Optional short description of an action. Specify `null` to unset existing description. |
| `--image <image>` | Register a Docker image with this action. Can neither be unset nor set an empty string. |
| `--timeout <timeout>` | Optional timeout for an action in minutes, defaults to 30 minutes or 12 hours depending on tier. |
| `--put-parameter 'name=<name>\|required=<true\|false>\|default=<value>\|description=<description>'` | Add parameter(s) or overwrite existing parameter(s) with the same name. Argument values must be wrapped in quotes. e.g. `--put-parameter 'name=my_param\|required=true\|description=My description of my_param'` |
| `--remove-parameter <parameter_name>` | Remove parameter(s) with the given name(s). |
| `--put-tags <put_tags>` | Add each tag in this sequence if it doesn't exist |
| `--remove-tags <remove_tags>` | Remove each tag in this sequence if it exists |
| `--put-metadata <KEY_PATH=VALUE>` | Zero or more `key_path=value` formatted pairs. An attempt is made to parse `value` as JSON; if this fails, `value` is stored as a string. If `key_path` already exists, existing value will be overwritten. Dot notation is supported for nested keys. Examples: `--put-metadata 'key1=value1' 'key2.subkey1=value2' 'key3.sublist1=["a","b","c"]'` |
| `--remove-metadata <key_path>` | Remove each key from dataset metadata if it exists. Dot notation is supported for nested keys. e.g. `--remove-metadata key1 key2.subkey3` |
| `--org <org>` | The calling organization ID. Gets set implicitly if in a single org. The `ROBOTO_ORG_ID` environment variable can be set to control the default value; without it, the default is the `org_id` of the config file profile in use, which `roboto setup` saves. |

**Resource requirements**

Specify required compute resources.

| Argument | Description |
| --- | --- |
| `--vcpu {256,512,1024,2048,4096,8192,16384}` | CPU units to dedicate to action invocation. Defaults to 512 (0.5vCPU). |
| `--memory <memory>` | Memory (in MiB) to dedicate to action invocation. Defaults to 1024 (1 GiB). Supported values range from 512 (0.5 GiB) to 122880 (120 GiB). Supported values are tied to selected vCPU resources. See documentation for more information. |
| `--storage <storage>` | Ephemeral storage (in GiB) to dedicate to action invocation. Defaults to 21 GiB. Supported values range from 21 to 200, inclusive. |
| `--gpu` | This is a placeholder; it currently does nothing. In the future, setting this option will invoke the action in a GPU-enabled compute environment. |

**Container parameters**

Specify parameters to pass to the action's Docker container at runtime.

| Argument | Description |
| --- | --- |
| `--entrypoint <entry_point>` | Container ENTRYPOINT override. Supports passing empty string ("") as an override, which unsets the ENTRYPOINT specified in the docker image. If updating or invoking action which has existing ENTRYPOINT override, specify `null` to remove the override. Refer to docker documentation for more: https://docs.docker.com/engine/reference/builder/#entrypoint and https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime |
| `--command <command>` | Container CMD override. If updating or invoking action which has existing CMD override, specify `null` to remove the override. Refer to docker documentation for more: https://docs.docker.com/engine/reference/builder/#cmd and https://docs.docker.com/engine/reference/run/#cmd-default-command-or-options |
| `--command-form {exec,shell}` | In `exec` form, the provided `--command` str is split into a list of strings (e.g., `--command "-c 'print(123)'"` is parsed as `["-c", "print(123)"]`). In `shell` form, the provided `--command` str is not split (e.g., `--command "python -c 'print(123)'"` is parsed as `["python -c 'print(123)'"]`). Default: `exec`. |
| `--workdir <workdir>` | If updating, specify `null` to clear existing workdir. Refer to docker documentation for more: https://docs.docker.com/engine/reference/run/#workdir |
| `--env <KEY=VALUE>` | Zero or more `<key>=<value>` formatted pairs to set as container ENV vars. Do not use ENV vars for secrets (such as API keys). See documentation: https://docs.docker.com/engine/reference/run/#env-environment-variables |