DOCS-1493: Add dataset CLI command (#2286)

docs/data/dataset.md

@@ -99,12 +99,16 @@ Click **Create dataset**, enter a name for your dataset and click **Create datas
 
 ![Create dataset UI](/data/create-dataset.png)
 
+Alternatively, you can use the [`viam data dataset add` command](/fleet/cli/#data) to add an image or group of images matching a specific filter using the Viam CLI.
+
 ### Remove an image from a dataset
 
 To remove an image from a dataset click on the delete button next to the dataset name.
 
 {{<gif webm_src="/data/delete-from-dataset.webm" mp4_src="/data/delete-from-dataset.mp4" alt="Remove from dataset">}}
 
+Alternatively, you can use the [`viam data dataset remove` command](/fleet/cli/#data) to remove an image or group of images matching a specific filter using the Viam CLI.
+
 ### View the data in a dataset
 
 Once you have added data to your dataset, you can view the data in your dataset by clicking on your dataset's name on the image sidebar or on the [**DATASETS** subtab](https://app.viam.com/data/datasets).

docs/fleet/cli.md

@@ -330,12 +330,15 @@ viam board list --organization=my-org
 ### data
 
 The `data` command allows you to manage robot data.
-With it, you can export data in the format of your choice, delete specified data, or configure a database user to enable querying synced tabular data directly in the cloud.
+With it, you can export data in a variety of formats, delete specified data, add or remove images from a dataset and filter a dataset by tags, or configure a database user to enable querying synced tabular data directly in the cloud.
 
 ```sh {class="command-line" data-prompt="$"}
 viam data export --destination=<output path> --data-type=<output data type> [...named args]
 viam data delete [...named args]
+viam data dataset add --dataset-id=<dataset-id> --file-ids=<file-id-or-ids> --location-id=<location-id> --org-id=<org-id> [...named args]
+viam data dataset remove --dataset-id=<dataset-id> --file-ids=<file-id-or-ids> --location-id=<location-id> --org-id=<org-id> [...named args]
 viam data database configure --org-id=<org-id> --password=<db-user-password>
+viam data database hostname --org-id=<org-id>
 ```
 
 Examples:
@@ -349,6 +352,9 @@ viam data export --destination=/home/robot/data --data_type=tabular \
 viam data export --destination=/home/robot/data --data-type=binary \
 --component-name myComponent
 
+# add images tagged with the "example" tag between January and October of 2023 to dataset abc
+viam data dataset add filter --dataset-id=abc --location-id=123 --org-id=123 --start=2023-01-01T05:00:00.000Z --end=2023-10-01T04:00:00.000Z --tags=example
+
 # configure a database user for the Viam organization's MongoDB Atlas Data
 # Federation instance, in order to query tabular data
 viam data database configure --org-id=abc --password=my_password123
@@ -363,10 +369,21 @@ viam data database hostname --org-id=abc
 | `export`      | export data in a specified format to a specified location  | - |
 | `database configure`      | create a new database user for the Viam organization's MongoDB Atlas Data Federation instance, or change the password of an existing user. See [Configure data query](/data/query/#configure-data-query)  | - |
 | `database hostname`      | get the MongoDB Atlas Data Federation instance hostname and database name. See [Configure data query](/data/query/#configure-data-query)  | - |
+| `dataset add`      | add a new image to an existing dataset by its file id, or add a group of images by specifying a filter | `filter` |
+| `dataset remove`      | remove an existing image from a dataset by its file id, or remove a group of images by specifying a filter | `filter` |
 | `delete binary`      | delete binary data  | - |
 | `delete tabular`      | delete tabular data  | - |
 | `--help`      | return help      | - |
 
+##### Positional arguments: `dataset`
+
+<!-- prettier-ignore -->
+| argument | description |
+| ----------- | ----------- | ----------- |
+| `filter`     | `add` or `delete` images from a dataset using a filter. See [Using the `filter` argument)](#using-the-filter-argument).|
+| `ids`     | `add` or `delete` images from a dataset by specifying one or more file ids as a comma-separated list. See [Using the `ids` argument)](#using-the-ids-argument).|
+| `--help`      | return help |
+
 ##### Named arguments
 
 <!-- prettier-ignore -->
@@ -377,22 +394,66 @@ viam data database hostname --org-id=abc
 | `--component-name`      | filter by specified component name  |`export`, `delete`| false |
 | `--component-type`     | filter by specified component type       |`export`, `delete`| false |
 | `--component-model`   | filter by specified component model       |`export`, `delete`| false |
+| `--dataset-id`   | dataset to add or remove images from     |`dataset`| true |
 | `--delete-older-than-days` | number of days, 0 means all data will be deleted | `delete` | false |
-| `--start`      | ISO-8601 timestamp indicating the start of the interval       |`export`, `delete`| false |
-| `--end`      | ISO-8601 timestamp indicating the end of the interval       |`export`, `delete`| false |
+| `--start`      | ISO-8601 timestamp indicating the start of the interval       |`export`, `delete`, `dataset`| false |
+| `--end`      | ISO-8601 timestamp indicating the end of the interval       |`export`, `delete`, `dataset`| false |
+| `--file-ids` | file-ids to add or remove from a dataset       |`dataset`| true |
+| `--location-id`      | location id for the file ids being added or removed from the specified dataset (only accepts one location id)       |`dataset`| true |
 | `--location-ids`      | filter by specified location id (accepts comma-separated list)       |`export`, `delete`| false |
 | `--method`       | filter by specified method       |`export`, `delete`| false |
 | `--mime-types`      | filter by specified MIME type (accepts comma-separated list)       |`export`, `delete`|false |
+| `--org-id` | org ID for the database user being configured (with `database`), or for the file ids being added or removed from the specified dataset (with `dataset`) | `database configure`, `database hostname`, `dataset` | true |
 | `--org-ids`     | filter by specified organizations id (accepts comma-separated list)       |`export`, `delete`| false |
 | `--parallel`      | number of download requests to make in parallel, with a default value of 10       |`export`, `delete`|false |
 | `--part-id`      | filter by specified part id      |`export`, `delete`| false |
 | `--part-name`     | filter by specified part name       |`export`, `delete`| false |
 | `--robot-id`     | filter by specified robot id       |`export`, `delete`| false |
 | `--robot-name`      | filter by specified robot name       |`export`, `delete`| false |
-| `--tags`      | filter by specified tag (accepts comma-separated list)       |`export`, `delete`| false |
-| `--org-id` | org ID for the database user | `database configure`, `database hostname` | true |
+| `--tags`      | filter by specified tag (accepts comma-separated list)       |`export`, `delete`, `dataset`| false |
 | `--password` | password for the database user being configured | `database configure` | true |
 
+##### Using the `ids` argument
+
+When you use the `viam dataset add` and `viam dataset remove` commands, you can specify the image to add or remove using its file id.
+To work with multiple images at once, you can specify multiple file ids as a comma-separated list.
+For example, the following adds three images specified by their file ids to the specified dataset:
+
+```sh {class="command-line" data-prompt="$"}
+viam data dataset add ids --dataset-id=abc --location-id=123 --org-id=123 --file-ids=abc,123,def
+```
+
+To find the dataset id of a given dataset, go to the [**Datasets** subtab](https://app.viam.com/data/datasets) under the **Data** tab on the Viam app and select a dataset.
+The dataset id can be found in the URL of the Viam app window when viewing a given dataset, following the `?id=` portion of the URL, resembling `abcdef1234567890abcdef12`.
+
+To find the file id of a given image, navigate to the [**Data** tab in the Viam app](https://app.viam.com/data/view) and select your image.
+Its **File ID** is shown under the **Details** subtab that appears on the right.
+
+You cannot use filter arguments, such as `--start` or `--end` when using `ids`.
+
+See [Datasets](/data/dataset/#datasets) for more information.
+
+##### Using the `filter` argument
+
+When you use the `viam dataset add` and `viam dataset remove` commands, you can optionally `filter` by common search criteria to `add` or `remove` a specific subset of images based on a search filter.
+For example, the following adds all images captured between January 1 and October 1, 2023, that have the `example` tag applied, to the specified dataset:
+
+```sh {class="command-line" data-prompt="$"}
+viam data dataset add filter --dataset-id=abc --org-ids=123 --start=2023-01-01T05:00:00.000Z --end=2023-10-01T04:00:00.000Z --tags=example
+```
+
+To find the dataset id of a given dataset, go to the [**Datasets** subtab](https://app.viam.com/data/datasets) under the **Data** tab on the Viam app and select a dataset.
+The dataset id can be found in the URL of the Viam app window when viewing a given dataset, following the `?id=` portion of the URL, resembling `abcdef1234567890abcdef12`.
+
+You can also have the filter parameters generated for you using the **Filtering** pane of the **Data** tab.
+Navigate to the [**Data** tab in the Viam app](https://app.viam.com/data/view), make your selections from the search parameters under the **Filtering** pane (such as robot name, start and end time, or tags), and click the **Copy export command** button.
+A `viam data export` command string will be copied to your clipboard that includes the search parameters you selected.
+You can use the same filter parameters (such as `--start`, `--end`, etc) with your `viam data database add filter` or `viam data database remove filter` commands, except you would exclude the `--data-type` and `--destination` flags, which are specific to `viam data export`.
+
+You cannot use the `--file-ids` argument when using `filter`.
+
+See [Datasets](/data/dataset/#datasets) for more information.
+
 ### locations
 
 The `locations` command allows you to manage the [locations](/fleet/locations/) that you have access to.