# Datasets and training with the CLI Create and populate datasets, submit training jobs, manage training scripts, and run inference from the command line or in automation scripts. ##### Prerequisites You need the Viam CLI installed and authenticated. See [Viam CLI overview](https://docs.viam.com/cli/overview/) for installation and authentication instructions. ## Find your IDs To find your organization ID: ```sh viam organizations list ``` To list datasets and find dataset IDs: ```sh viam dataset list --org-id= ``` To list training containers and find valid container versions: ```sh viam train containers list ``` ## Manage datasets ### Create a dataset ```sh viam dataset create --org-id= --name=my-dataset ``` The CLI prints the new dataset’s name and ID: ```sh Created dataset my-dataset with dataset ID: abcdef12-3456-7890-abcd-ef1234567890 ``` Save the dataset ID for subsequent commands. ### List datasets List all datasets in your organization: ```sh viam dataset list --org-id= ``` List specific datasets by ID: ```sh viam dataset list --dataset-ids=abc,def ``` ### Add images to a dataset Adding images to a dataset creates references to the binary data items, it does not copy the data. Removing images removes the references without deleting the underlying data. Add images matching a filter (uses the same filter flags as [data export](https://docs.viam.com/cli/manage-data/#export-images-and-binary-files)): ```sh viam dataset data add filter \ --dataset-id= \ --org-ids= \ --location-ids= \ --tags=defective \ --start=2026-01-01T00:00:00Z \ --end=2026-03-01T00:00:00Z ``` Add specific images by ID: ```sh viam dataset data add ids \ --dataset-id= \ --binary-data-ids=aaa,bbb,ccc ``` ### Remove images from a dataset By filter: ```sh viam dataset data remove filter \ --dataset-id= \ --tags=low-quality ``` By ID: ```sh viam dataset data remove ids \ --dataset-id= \ --binary-data-ids=aaa,bbb ``` ### Export a dataset Download all data from a dataset to a local directory. The export includes the binary files plus a `dataset.jsonl` file with annotation metadata (classification labels, bounding boxes, timestamps, file paths) that Viam’s training infrastructure consumes. ```sh viam dataset export \ --dataset-id= \ --destination=./my-dataset ``` To export only the metadata without downloading binary files (useful for inspecting annotations): ```sh viam dataset export \ --dataset-id= \ --destination=./my-dataset \ --only-jsonl ``` ### Merge datasets Combine multiple datasets into a new one: ```sh viam dataset merge \ --name=combined-dataset \ --dataset-ids=abc,def,ghi ``` ### Rename and delete datasets ```sh viam dataset rename --dataset-id= --name=new-name ``` Deleting a dataset removes the dataset and its references, but does not delete the underlying binary data. ```sh viam dataset delete --dataset-id= ``` ## Submit training jobs ### Train with a built-in model type Submit a managed training job using one of Viam’s built-in model types: ```sh viam train submit managed \ --dataset-id= \ --model-org-id= \ --model-name=my-detector \ --model-type=single_label_classification \ --model-framework=tflite \ --model-labels=defective,good ``` On success, the CLI prints the job ID: ```sh Submitted training job with ID abcdef12-3456-7890-abcd-ef1234567890 ``` Model types: `single_label_classification`, `multi_label_classification`, `object_detection`. ### Train with a custom training script Submit a job using a custom script from the registry: ```sh viam train submit custom from-registry \ --dataset-id= \ --model-name=my-custom-model \ --org-id= \ --script-name= \ --version= \ --container-version= ``` Submit a custom script by uploading it directly: ```sh viam train submit custom with-upload \ --dataset-id= \ --model-name=my-custom-model \ --model-org-id= \ --script-name=my-training-script \ --path=./my-training-script/ \ --framework=tflite \ --container-version= ``` ### Monitor training jobs List training jobs in your organization: ```sh viam train list --org-id= ``` Filter by status: ```sh viam train list --org-id= --job-status=completed ``` Get details on a specific job (use the job ID from `train submit` or `train list`): ```sh viam train get --job-id= ``` View training logs: ```sh viam train logs --job-id= ``` Cancel a running job: ```sh viam train cancel --job-id= ``` ## Manage training scripts Upload a custom training script to the registry: ```sh viam training-script upload \ --path=./my-training-script/ \ --script-name=my-training-script \ --framework=tflite ``` Update script visibility: ```sh viam training-script update \ --script-name=my-training-script \ --visibility=public ``` Test a training script locally before uploading (use `viam train containers list` to find valid container versions). Local testing runs in a Docker container that mirrors the cloud training environment. The container validates that your script directory contains `setup.py` and `model/training.py`. #### Note Local testing uses Google Vertex AI containers, which are linux/x86_64 only. On ARM Macs, Docker runs them through Rosetta emulation, which may be slower. ```sh viam training-script test-local \ --dataset-root=./my-dataset/ \ --training-script-directory=./my-training-script/ \ --container-version= ``` ## Run inference Run inference on a single image using a trained model: ```sh viam infer \ --binary-data-id= \ --model-org-id= \ --model-name=my-detector \ --model-version=latest ``` To find binary data IDs, export data with `viam data export` or browse the DATA page in the Viam app.