---
description: >-
  Manage datasets, used to store files from a robot run or drone flight.
  Includes file upload and download.
sidebar:
  order: 5
title: roboto datasets
---
```bash
roboto datasets [-h]
                {create,delete,delete-files,download-files,import-external-file,list-files,rename-directory,rename-file,search,show,update,upload-files} ...
```

**Arguments**

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

## roboto datasets create

Create a new dataset.

```bash
roboto datasets create [-h] [-m [KEY=VALUE ...]] [-t [TAG ...]]
                       [-d DESCRIPTION] [-n NAME]
                       [--device-id DEVICE_ID] [--org ORG]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-m, --metadata <KEY=VALUE>` | Zero or more `<key>=<value>` pairs to add to this dataset's metadata. Metadata can be modified after creation. |
| `-t, --tag <tag>` | One or more tags to add to this dataset. Tags can be modified after creation. |
| `-d, --description <description>` | A human readable description of this dataset. |
| `-n, --name <name>` | A human readable name for this dataset. |
| `--device-id <device_id>` | The device ID to associate with this dataset. The device must already exist in the organization. |
| `--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 datasets delete

Delete a dataset and all contained resources.

```bash
roboto datasets delete [-h] -d DATASET_ID
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |

## roboto datasets delete-files

Delete files from a dataset.

```bash
roboto datasets delete-files [-h] -d DATASET_ID [-i [INCLUDE ...]]
                             [-x [EXCLUDE ...]]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `-i, --include <include>` | Zero or more include filters |
| `-x, --exclude <exclude>` | Zero or more exclude filters |

## roboto datasets download-files

Download a file or directory from a dataset.

```bash
roboto datasets download-files [-h] -d DATASET_ID -p PATH
                               [-i [INCLUDE ...]] [-x [EXCLUDE ...]]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `-p, --path <path>` Required | The download destination for this operation. |
| `-i, --include <include>` | Zero or more include filters (if path points to a directory) |
| `-x, --exclude <exclude>` | Zero or more exclude filters (if path points to a directory) |

## roboto datasets import-external-file

Import a file from an external storage location (e.g. a pre-registered S3 bucket) into a dataset.

```bash
roboto datasets import-external-file [-h] -d DATASET_ID [-p PATH]
                                     [-f FILE]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `-p, --path <path>` | Destination path within the dataset (relative to the root) where the file will be imported. Defaults to the filename at the dataset root if not specified. |
| `-f, --file <file>` | The URI of the file to import, e.g. s3://my-bucket/path/to/file.txt for S3 files. |

## roboto datasets list-files

List files in a dataset.

```bash
roboto datasets list-files [-h] -d DATASET_ID [-i [INCLUDE ...]]
                           [-x [EXCLUDE ...]]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `-i, --include <include>` | Zero or more include filters (if path points to a directory) |
| `-x, --exclude <exclude>` | Zero or more exclude filters (if path points to a directory) |

## roboto datasets rename-directory

Rename or move a directory within a dataset.

```bash
roboto datasets rename-directory [-h] -d DATASET_ID -o OLD_PATH
                                 -p NEW_PATH
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `-o, --old-path <old_path>` Required | Current path of the directory, relative to the dataset root. Example: 'logs/session1'. |
| `-p, --new-path <new_path>` Required | New path for the directory, relative to the dataset root. Use a path with fewer components to move the directory up the tree, a different name at the same depth to rename in place, or a path under a different parent to move sideways. Example: 'session1' to move 'logs/session1' up one level. |

## roboto datasets rename-file

Rename or move a file within a dataset.

```bash
roboto datasets rename-file [-h] -d DATASET_ID -f FILE_ID -p NEW_PATH
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `-f, --file-id <file_id>` Required | ID of the file to rename or move. |
| `-p, --new-path <new_path>` Required | New path for the file, relative to the dataset root. Use a path with fewer components to move the file up the directory tree, a different name at the same depth to rename in place, or a path under a different directory to move sideways. Example: 'logs/session1.bag' or 'session1.bag'. |

## roboto datasets search

Search for datasets matching filter criteria.

```bash
roboto datasets search [-h] [--metadata [KEY=VALUE ...]]
                       [--tag [TAG ...]] [--org ORG]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `--metadata <KEY=VALUE>` | Zero or more `<key>=<value>` pairs which represent dataset metadata. `value` is parsed as JSON. e.g. --metadata foo=bar --metadata baz.nested=200 |
| `--tag <tag>` | One or more tags associated with this dataset. 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 datasets show

Display detailed information about a dataset.

```bash
roboto datasets show [-h] -d DATASET_ID
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |

## roboto datasets update

Update metadata or properties of an existing dataset.

```bash
roboto datasets update [-h] -d DATASET_ID [--description DESCRIPTION]
                       [--name NAME] [--put-tags [PUT_TAGS ...]]
                       [--remove-tags [REMOVE_TAGS ...]]
                       [--put-metadata [KEY_PATH=VALUE ...]]
                       [--remove-metadata [KEY_PATH ...]]
                       [--device-id DEVICE_ID]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `--description <description>` | A new description to add to this dataset. Specify `null` to clear the description. |
| `--name <name>` | A new name for this dataset. Specify `null` to clear the name. |
| `--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>=<value>` formatted pairs. An attempt is made to parse `value` as JSON; if this fails, `value` is stored as a string. If `key` 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` |
| `--device-id <device_id>` | Set or update the device ID associated with this dataset. Specify `null` to clear the device association. |

## roboto datasets upload-files

Upload a file or directory to a dataset.

```bash
roboto datasets upload-files [-h] -d DATASET_ID [--device-id DEVICE_ID]
                             -p PATH [-x [EXCLUDE ...]]
```

**Arguments**

| Argument | Description |
| --- | --- |
| `-h, --help` | show this help message and exit |
| `-d, --dataset-id <dataset_id>` Required | A unique ID used to reference a single dataset |
| `--device-id <device_id>` | The device ID to associate with these files. The device must already exist in the organization. |
| `-p, --path <path>` Required | The path to a file or directory to upload. |
| `-x, --exclude <exclude>` | Zero or more exclude filters (if path points to a directory) |