CLI reference

This page documents every command, subcommand, flag, and alias in the Viam CLI. For installation, authentication, and task-oriented guides, see the Viam CLI overview.

All commands use this format:

viam [global options] command [command options] [arguments...]

Commands

data

The data command allows you to manage machine data. With it, you can export data in a variety of formats, delete data, add or remove tags from all data that matches a given filter, or configure a database user to enable querying synced data directly in the cloud.

viam data export binary filter --destination=<output path> [...named args]
viam data export binary ids --destination=<output path> [...named args]
viam data export tabular --destination=<destination> --part-id=<part-id> --resource-name=<resource-name> --resource-subtype=<resource-subtype> --method=<method> [other options]
viam data delete binary --org-ids=<org-ids> --start=<timestamp> --end=<timestamp> [...named args]
viam data delete tabular --delete-older-than-days=<N>
viam data database configure --org-id=<org-id> --password=<db-user-password>
viam data database hostname --org-id=<org-id>
viam data tag ids add --tags=<tags> --binary-data-ids=<binary_ids>
viam data tag ids remove --tags=<tags> --binary-data-ids=<binary_ids>
viam data tag filter add --tags=<tags> [...named args from filter]
viam data tag filter remove --tags=<tags> [...named args from filter]
viam data index create --collection-type=<type> --index-path=<file> [--org-id=<org-id>] [--pipeline-name=<name>]
viam data index delete --collection-type=<type> --index-name=<name> [--org-id=<org-id>] [--pipeline-name=<name>]
viam data index list --collection-type=<type> [--org-id=<org-id>]

Examples:

# export binary data from the specified org with mime types image/jpeg and image/png to /home/robot/data
viam data export binary filter --mime-types=image/jpeg,image/png --org-ids=12345678-eb33-123a-88ec-12a345b123a1 --destination=/home/robot/data

# export tabular data to /home/robot/data for specified part id with resource name my_movement_sensor, subtype movement_sensor and method Readings
viam data export tabular --part-id=e1234f0c-912c-1234-a123-5ac1234612345 --resource-name=my_movement_sensor --resource-subtype=rdk:component:movement_sensor --method=Readings --destination=/home/robot/data

# delete binary data of mime type image/jpeg in an organization between a specified timestamp
viam data delete binary --org-ids=123 --mime-types=image/jpeg --start 2024-08-20T14:10:34-04:00 --end 2024-08-20T14:16:34-04:00

# 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

# get the hostname to access a MongoDB Atlas Data Federation instance
viam data database hostname --org-id=abc

# add tags to all data that matches the given ids in the current organization
viam data tag ids add --tags=new_tag_1,new_tag_2,new_tag_3 --binary-data-ids=123,456

# remove tags from all data that matches the given ids in the current organization
viam data tag ids remove --tags=new_tag_1,new_tag_2,new_tag_3 --binary-data-ids=123,456

# add tags to all data that matches a given filter
viam data tag filter add --tags=new_tag_1,new_tag_2 --location-ids=012 --machine-name=cool-machine --org-ids=84842  --mime-types=image/jpeg,image/png

# remove tags from all data that matches a given filter
viam data tag filter remove --tags=new_tag_1 --location-ids=012 --machine-name=cool-machine --org-ids=84842  --mime-types=image/jpeg,image/png

Viam currently only supports deleting approximately 500 files at a time. To delete more data iterate over the data with a shell script:

# deleting one hour of image data
for i in {00..59}; do
  viam data delete binary --org-ids=<org-id> --mime-types=image/jpeg,image/png --start=2024-05-13T11:00:00.000Z --end=2024-05-13T11:${i}:00.000Z
done

Command options

Positional arguments: tag

Named arguments

datapipelines

The datapipelines command provides access to data pipelines for processing machine data with MQL queries. Data pipelines help you optimize query performance for frequently accessed complex data transformations.

viam datapipelines create --org-id=<org-id> --name=<name> --schedule=<schedule> --mql=<mql-query> --data-source-type=<type> --enable-backfill=False
viam datapipelines rename --id=<pipeline-id> --name=<new-name>
viam datapipelines list --org-id=<org-id>
viam datapipelines describe --id=<pipeline-id>

Examples:

# create a new data pipeline with standard data source type (default)
viam datapipelines create --org-id=123 --name="Daily Sensor Summary" --schedule="0 9 * * *" --data-source-type=standard --mql='[{"$match": {"component_name": "sensor-1"}}]' --enable-backfill=False

# create a data pipeline with hot storage data source type for faster access
viam datapipelines create --org-id=123 --name="Real-time Analytics" --schedule="*/5 * * * *" --data-source-type=hotstorage --mql='[{"$match": {"component_name": "camera-1"}}]' --enable-backfill=False

# disable a pipeline
viam datapipelines disable --id=abc123

# enable a pipeline
viam datapipelines enable --id=abc123

# list all data pipelines in an organization
viam datapipelines list --org-id=123

# get detailed information about a specific data pipeline
viam datapipelines describe --id=abc123

# delete a data pipeline
viam datapipelines delete --id=abc123

Command options

Named arguments

dataset

The dataset command allows you to manage machine data in datasets. With it, you can add or remove images from a dataset, export data from a dataset, or filter a dataset by tags.

viam dataset create --org-id=<org-id> --name=<name>
viam dataset rename --dataset-id=<dataset-id> --name=<name>
viam dataset list --org-id=<org-id>
viam dataset list --dataset-ids=<dataset-ids>
viam dataset delete --dataset-id=<dataset-id>
viam dataset export --destination=<output-directory> --dataset-id=<dataset-id>
viam dataset data add filter --dataset-id=<dataset-id> [...named args]
viam dataset data remove filter --dataset-id=<dataset-id> [...named args]
viam dataset data add ids --dataset-id=<dataset-id>  --binary-data-ids=<binary-data-ids>
viam dataset data remove ids --dataset-id=<dataset-id> --binary-data-ids=<binary-data-ids>

Examples:

# create a new dataset
viam dataset create --org-id=123 --name=MyDataset

# rename dataset 123 from MyDataset to MyCoolDataset
viam dataset rename --dataset-id=123 --name=MyCoolDataset

# show dataset information for all datasets within a specified org
viam dataset list --org-id=123

# show dataset information for the specified dataset IDs
viam dataset list --dataset-ids=123,456

# delete the specified dataset
viam dataset delete --dataset-id=123

# export dataset abc to output directory ./dataset/example in two folders called "data" and "metadata"
viam dataset export --destination=./dataset/example --dataset-id=abc

# add images tagged with the "example" tag between January and October of 2023 to dataset abc
viam dataset data add filter --dataset-id=abc --location-ids=123 --org-ids=456 --start=2023-01-01T05:00:00.000Z --end=2023-10-01T04:00:00.000Z --tags=example

# remove images tagged with the "example" tag between January and October of 2023 to dataset abc
viam dataset data remove filter --dataset-id=abc --location-ids=123 --org-ids=456 --start=2023-01-01T05:00:00.000Z --end=2023-10-01T04:00:00.000Z --tags=example

# add images with binary data IDs aaa and bbb in the org 123 and location 456 to dataset abc
viam dataset data add ids --dataset-id=abc --binary-data-ids=aaa,bbb

# remove images with binary data IDs aaa and bbb in the org 123 and location 456 from dataset abc
viam dataset data remove ids --dataset-id=abc --binary-data-ids=aaa,bbb

Command options

Positional arguments

Named arguments

Using the ids argument

When you use the viam dataset data add and viam dataset data remove commands, you specify images to add or remove using their binary data IDs as a comma-separated list. For example, the following command adds three images specified by their binary data IDs to the specified dataset:

viam dataset data add ids --binary-data-ids=abc,123 --dataset-id=abc

The following command tags two images specified by their binary data IDs with three tags:

viam data tag ids add --tags=new_tag_1,new_tag_2,new_tag_3 --binary-data-ids=123,456

To find your organization’s ID, run viam organization list or navigate to your organization’s Settings page in the Viam app. Find Organization ID and click the copy icon.

To find the dataset ID of a given dataset, go to the DATASETS subtab of the DATA tab and select a dataset. Click … in the left-hand menu and click Copy dataset ID.

To find a location ID, run viam locations list or visit your fleet’s page and copy the Location ID.

To find the binary data ID of a given image, navigate to the DATA tab and select your image. The Binary Data ID is shown under the DETAILS subtab that appears on the right.

You cannot use filter arguments such as --start or --end with the ids argument.

Using the filter argument

When you use the viam dataset data add, viam dataset data remove or viam data tag 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 command adds all images captured between January 1 and October 1, 2023, that have the example tag applied, to the specified dataset:

viam dataset data add filter --dataset-id=abc --org-ids=123 --start=2023-01-01T05:00:00.000Z --end=2023-10-01T04:00:00.000Z --tags=example

The following command adds "new_tag_1" and "new_tag_2" to all images of type "image/jpeg" or "image/png" captured by the machine named "cool-machine" in organization 8484 and location 012:

viam data tag filter add --tags=new_tag_1,new_tag_2 --location-ids=012 --machine-name=cool-machine --org-ids=84842  --mime-types=image/jpeg,image/png

To find the dataset ID of a given dataset, go to the DATASETS subtab under the DATA tab and select a dataset. Click … in the left-hand menu and click Copy dataset ID.

To find a location ID, run viam locations list or visit your fleet’s page and copy from Location ID.

Copy export command

You can also have the filter parameters generated for you using the Filters pane of the DATA tab. Navigate to the DATA tab, make your selections from the search parameters under the Filters 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. Removing the viam data export string, you can use the same filter parameters (such as --start, --end, etc) with your viam data database add filter, viam data database remove filter, or viam data tag filter commands, except you must exclude the data type binary and tabular subcommands and --destination flags, which are specific to viam data export.

You cannot use the --binary-data-ids argument when using filter.

See Create a dataset for more information.

infer

The infer command enables you to run cloud inference on data. Cloud inference runs in the cloud, instead of on a local machine.

viam infer --binary-data-id <binary-data-id> --model-name <model-name> --model-org-id <org-id-that-owns-model> --model-version "2025-04-14T16-38-25" --org-id <org-id-that-executes-inference>
Inference Response:
Output Tensors:
  Tensor Name: num_detections
    Shape: [1]
    Values: [1.0000]
  Tensor Name: classes
    Shape: [32 1]
    Values: [...]
  Tensor Name: boxes
    Shape: [32 1 4]
    Values: [...]
  Tensor Name: confidence
    Shape: [32 1]
    Values: [...]
Annotations:
Bounding Box Format: [x_min, y_min, x_max, y_max]
  No annotations.

Named arguments

locations

The locations command allows you to manage the locations that you have access to. With it, you can list available locations, filter locations by organization, or create a new location API key.

viam locations list [<organization id>]
viam locations api-key create --location-id=<location-id>

Command options

Positional arguments: api-key

Named arguments

login

The login command allows you to authorize your device for CLI usage.

viam login
viam login api-key --key-id=<api-key-uuid> --key=<api-key-secret-value>
viam login print-access-token

Use viam login to authenticate using a personal access token, or viam login api-key to authenticate using an API key. See Authenticate.

Command options

Named arguments

logout

The logout command ends an authenticated CLI session.

viam logout

machines (alias robots and machine)

The machines command allows you to manage your machine fleet. This includes:

• Creating, updating, and deleting machines
• Listing all machines that you have access to, filtered by organization and location.
• Creating API keys to grant access to a specific machine
• Retrieving machine and machine part status
• Retrieving machine and machine part logs
• Controlling a machine by issuing component and service commands
• Accessing your machine with a secure shell (when this feature is enabled)
• Copy files from and to machines
• Enter an interactive terminal on your machines

viam machines create --name=<machine name> --location=<location id>
viam machines update --machine=<machine id> [--name=<new name>] [--location=<new location id>]
viam machines delete --machine=<machine id>
viam machines list
viam machines status --machine=<machine id>
viam machines logs --machine=<machine id> [...named args]
viam machines api-key create --machine-id=<machine id> --org-id=<org id> --name=<key name>
viam machines part list --machine=<machine id>
viam machines part logs --machine=<machine id> --part=<part id> [...named args]
viam machines part status --machine=<machine id>
viam machines part run --machine=<machine id> [--stream] --data <method>
viam machines part shell --machine=<machine id> --part=<part id>
viam machines part restart --machine=<machine id> --part=<part id>
viam machines part cp --part=<part id> <file name> machine:/path/to/file

Examples:

# create a new machine
viam machines create --name="My Machine" --location=12345

# update machine name or location
viam machines update --machine=123 --name="New Name"
viam machines update --machine=123 --location=67890

# delete a machine
viam machines delete --machine=123

# list all machines in an organization, in all locations
viam machines list --all --organization=12345

# get machine status
viam machines status  --machine=123

# create an API key for a machine
viam machines api-key create --machine-id=123 --name=MyKey

# stream logs from a machine
viam machines logs --machine=123

# list machine parts
viam machines part list --machine=123

# stream logs from a machine part
viam machines part logs --part=myrover-main --tail=true

# stream classifications from a machine part every 500 milliseconds from the Viam Vision Service with classifier "stuff_detector"
viam machines part run --part=myrover-main --stream=500ms \
--data='{"name": "vision", "camera_name": "cam", "classifier_name": "stuff_classifier", "n":1}' \
viam.service.vision.v1.VisionService.GetClassificationsFromCamera

# restart a part of a specified machine
viam machines part restart --part=123

# tunnel connections to the specified port on a machine part
viam machines part tunnel --part=123 --destination-port=1111 --local-port 2222

# Copy a single file to a machine:
viam machines part cp --part=123 my_file machine:/home/user/

# Recursively copy a directory to a machine:
viam machines part cp --part=123 -r my_dir machine:/home/user/

# Copy multiple files to a machine with recursion and keep original permissions and metadata for the files:
viam machines part cp --part=123 -r -p my_dir my_file machine:/home/user/some/existing/dir/

# Copy a single file from a machine to a local destination:
viam machines part cp --part=123 machine:my_file ~/Downloads/

# Recursively copy a directory from a machine to a local destination:
viam machines part cp --part=123 -r machine:my_dir ~/Downloads/

# Copy multiple files from the machine to a local destination with recursion and keep original permissions and metadata for the files:
viam machines part cp --part=123 -r -p machine:my_dir machine:my_file ~/some/existing/dir/

# Download FTDC data from a part to a local directory:
viam machines part get-ftdc --part=123 ~/some/existing/dir/

Command options

Positional arguments: api-key

Positional arguments: part

Named arguments

Using the --stream and --data arguments

Issuing the part command with the run positional argument allows you to run component and service (resource) commands for a selected machine part.

The --data parameter is required and you must specify both:

• Method arguments in JSON format
• A resource method (in the form of the protobuf package and method path)

The format of what is passed to the --data argument is:

'{"arg1": "val1"}' <protobuf path>

You can find the protobuf path for the Viam package and method in the Viam API package by navigating to the component or service directory and then clicking on the resource file. The protobuf path is the package name.

For example:

'{"name": "vision", "camera_name": "cam", "classifier_name": "my_classifier", "n":1}' \
viam.service.vision.v1.VisionService.GetClassificationsFromCamera

The --stream argument, when included in the CLI command prior to the --data command, will stream data back at the specified interval.

metadata

The metadata command allows you to read organization, location, machine, and machine part metadata.

viam metadata read --part-id=<part-id>

Command options

Named arguments

module

The module command allows to you to work with modules. This includes:

• Generating stub files for a new module
• Creating metadata for a modular resource
• Uploading a new module to the registry
• Uploading a new version of your module to the registry
• Updating an existing module in the Viam Registry
• Updating a module’s metadata file based on models it provides
• Building your module for different architectures using cloud runners
• Building a module locally and running it on a target device. Rebuilding & restarting if already running.
• Downloading a module package from the registry

See Update and manage modules you created for more information.

If you update and release your module as part of a continuous integration (CI) workflow, you can also automatically upload new versions of your module on release using a GitHub Action.

viam module generate
viam module create --name=<module-name> [--org-id=<org-id> | --public-namespace=<namespace>]
viam module update [--module=<path to meta.json>]
viam module update-models --binary=<binary> [...named args]
viam module build start --version=<version> [...named args]
viam module build local --module=<path to meta.json> [arguments...]
viam module build list [command options] [arguments...]
viam module build logs --id=<id> [...named args]
viam module reload [...named args]
viam module upload --version=<version> --platform=<platform> [--org-id=<org-id> | --public-namespace=<namespace>] [--module=<path to meta.json>] <module-path> --tags=<tags>
viam module download [command options]
viam module local-app-testing --app-url http://localhost:3000

Examples:

# auto-generate stub files for a new modular resource by following prompts
viam module generate

# generate metadata for and register a module named 'my-module' using your organization's public namespace:
viam module create --name=my-module --public-namespace=my-namespace

# generate metadata for and register a module named "my-module" using your organization's organization ID:
viam module create --name=my-module --org-id=abc

# update an existing module
viam module update --module=./meta.json

# update a module's metadata file based on models it provides
viam module update-models --binary=./packaged-module.tar.gz --module=./meta.json

# initiate a cloud build for a public GitHub repo
viam module build start --version "0.1.2"

# initiate a cloud build for a private GitHub repo
viam module build start --version "0.1.2" --token ghp_1234567890abcdefghijklmnopqrstuvwxyzABCD

# initiate a build locally without running a cloud build job
viam module build local

# list all in-progress builds and their build status
viam module build list

# initiate a build and return the build logs as soon as completed
viam module build logs --wait --id=$(viam module build start --version "0.1.2")

# build a module and run it on target machine
viam module reload --part-id e1234f0c-912c-1234-a123-5ac1234612345

# build and configure a module running on your local machine without shipping a tarball.
viam module reload-local --local

# restart a running module
viam module restart --id viam:python-example-module

# upload a new or updated custom module to the Viam Registry:
viam module upload --version=1.0.0 --platform=darwin/arm64 packaged-module.tar.gz --tags=distro:ubuntu,os_version:20.04,codename:focal,cuda:true,cuda_version:11,jetpack:5

# download a module package from the registry to the current directory
viam module download --id=acme:my-module

# download a module package from the registry to a specific directory
viam module download --id=acme:my-module --destination=/path/to/download/directory

# download a specific version of a module package for a specific platform
viam module download --id=acme:my-module --version=1.0.0 --platform=linux/amd64

# proxy your local Viam application and open a browser window and navigate to `http://localhost:8012/
viam module local-app-testing --app-url http://localhost:3000

Command options

Named arguments

Using the --org-id and --public-namespace arguments

All of the module commands accept either the --org-id or --public-namespace argument.

• Use the --public-namespace argument to supply the namespace of your organization. This will upload your module to the Viam Registry and share it with other users.
• Use the --org-id to provide your organization ID instead, This will upload your module privately within your organization.

You may use either argument for the viam module create command, but must use --public-namespace for the update and upload commands when uploading as a public module ("visibility": "public") to the Viam Registry.

Using the --platform argument

The --platform argument accepts one of the following architectures:

For information on which of these platforms are supported for cloud build, see Supported platforms for automatic updates.

You can use the uname -m command on your computer or board to determine its system architecture.

The viam module upload command only supports one platform argument at a time. If you would like to upload your module with support for multiple platforms, you must run a separate viam module upload command for each platform. Use the same version number when running multiple upload commands of the same module code if only the platform support differs.

If you specify a platform that includes any (such as any, any/amd64, or linux/any), a machine that deploys your module will select the most restrictive architecture from the ones you have provided for your module. For example, if you upload your module with support for any/amd64 and then also upload with support for linux/amd64, a machine running the linux/amd64 architecture deploys the linux/amd64 distribution, while a machine running the darwin/amd64 architecture deploys the any/amd64 distribution.

The Viam Registry page for your module displays the platforms your module supports for each version you have uploaded.

If you are using the build logs command, the --platform argument instead restricts the logs returned by the command to only those build jobs that match the specified platform.

Using the --version argument

The --version argument accepts a valid semver 2.0 version (example: 1.0.0). You set an initial version for your custom module with your first viam module upload command for that module, and can later increment the version with subsequent viam module upload commands.

Once your module is uploaded, users can select which version of your module to use on their machine from your module’s page on the Viam Registry. Users can choose to pin to a specific patch version, permit upgrades within major release families or only within minor releases, or permit continuous updates.

When you update a module configuration and then upload it, the entrypoint for that module defined in the meta.json file is associated with the specific --version for that upload. Therefore, you are able to change the entrypoint file from version to version, if desired.

Upload validation

When you upload a module, the command performs basic validation of your module to check for common errors. The following criteria are checked for every upload:

• The module must exist on the filesystem at the path provided to the upload command.
• The entry point file specified in the meta.json file must exist on the filesystem at the path specified.
• The entry point file must be executable.
• If the module is provided to the upload command as a compressed archive, the archive must have the .tar.gz or .tgz extension.

See Create a module and Update and manage modules you created for a detailed walkthrough of the viam module commands.

Using the build subcommand

You can use the module build start or module build local commands to build your custom module according to the build steps in your meta.json file:

• Use build start to build or compile your module on a cloud build host that might offer more platform support than you have access to locally.
• Use build local to quickly test that your module builds or compiles as expected on your local hardware.

To configure your module’s build steps, add a build object to your meta.json file like the following:

"build": {
  "setup": "./setup.sh",                  // optional - command to install your build dependencies
  "build": "./build.sh",                  // command that will build your module
  "path" : "dist/archive.tar.gz",         // optional - path to your built module
                                          // (passed to the 'viam module upload' command)
  "arch" : ["linux/amd64", "linux/arm64"] // architecture(s) to build for
}

#!/bin/bash
set -e
UNAME=$(uname -s)

if [ "$UNAME" = "Linux" ]
then
    echo "Installing venv on Linux"
    sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
    echo "Installing venv on Darwin"
    brew install python3-venv
fi

python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt

#!/bin/bash
pip3 install -r requirements.txt
python3 -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz <PATH-TO-EXECUTABLE>

#!/bin/bash
set -e
UNAME=$(uname -s)

if [ "$UNAME" = "Linux" ]
then
    echo "Installing venv on Linux"
    sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
    echo "Installing venv on Darwin"
    brew install python3-venv
fi

python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt
python3 -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz <PATH-TO-EXECUTABLE>

For example, the following extends the my-module meta.json file using the single build file approach, adding a new build object to control its build parameters when used with module build start or module build local:

{
  "module_id": "acme:my-module",
  "visibility": "public",
  "url": "https://github.com/<my-repo-name>/my-module",
  "description": "An example custom module.",
  "build": {
    "setup": "./setup.sh",
    "build": "./build.sh",
    "path": "dist/archive.tar.gz",
    "arch": ["linux/amd64", "linux/arm64"]
  },
  "entrypoint": "<PATH-TO-EXECUTABLE>"
}

When you initiate a build job using either start or local, the command returns the build ID of your job. Provide that build ID to the module build logs command to show the relevant build logs for that build.

For example, use the following to initiate a build, and return the build logs as soon as it completes:

viam module build logs --wait --id=$(viam module build start --version "0.1.2")

To list all in-progress builds and their build status, use the following command:

viam module build list

organizations

The organizations command allows you to list the organizations your authenticated session has access to, and to create a new organization API key.

viam organizations list
viam organizations api-key create --org-id=<org-id> [--name=<key-name>]
viam organizations support-email [get | set] --org-id=<org-id> --support-email=<support-email>
viam organizations logo set --org-id=<org-id> --logo-path=<logo-path>
viam organization auth-service [enable | disable] --org-id=<org-id>
viam organization auth-service oauth-app [create | update] --client-authentication [required | unspecified | not_required | not_required_when_using_pkce] \
    --client-name <client-name> --enabled-grants [password | unspecified | refresh_token | implicit | device_code | authorization_code] \
    --logout-uri=https://logoipsum.com --origin-uris=https://logoipsum.com \
    --pkce=[required | not_required | unspecified] --redirect-uris=https://logoipsum.com/callback \
    --url-validation=[allow_wildcards | unspecified | exact_match] --org-id=<org-id>
viam organization auth-service oauth-app [list] --org-id=<org-id>
viam organization auth-service oauth-app [read | delete] --org-id=<org-id> --client-id=<client-id>

Examples:

# list all the organizations that you are currently authenticated to
viam organizations list

# create a new organization API key in org 123
viam organizations api-key create --org-id=123 --name=my-key

See Manage API keys for more information.

Command options

Named arguments

packages

The packages command allows you to upload packages to the Viam Cloud or export packages from the Viam Cloud. For example, you can use this command to download ML models or modules from the registry.

viam packages upload --org-id=<org-id> --name=<package-name> --version=<version> --type=<type> --upload=<path-to-package.tar.gz> --model-framework=<framework>
viam packages export --org-id=<org-id> --name=<package-name> --version=<version> --type=<type> --destination=<path-to-export-destination>

Examples:

viam packages upload --org-id=123 --name=MyMLModel --version=1.0.0 --type=ml_model --upload=./the_package.tar.gz --model-framework=tensorflow
viam packages export --org-id=123 --name=MyMLModel --version=latest --type=ml_model --destination=.

Command options

Named arguments

parse-ftdc

The parse-ftdc command allows you to parse an FTDC file and open a REPL with extra options to inspect the data.

viam machines part get-ftdc --part=<part-id> ftdc-data
viam parse-ftdc --path ftdc-tmp/<part-id>/viam-server-<date>-<time>.ftdc

Command options

Named arguments

profiles

The profiles command allows you to manage different CLI authentication profiles, so you can easily switch between API key authentications (for example authentication to one organization versus another).

viam profiles add --profile-name=<name-of-profile-to-add> --key-id=<API-key-ID> --key=<API-key>
viam profiles update --profile-name=<name-of-profile-to-update> --key-id=<API-key-ID> --key=<API-key>
viam profiles list
viam profiles remove --profile-name=<name-of-profile-to-remove>

Examples:

# Add a new profile for authentication (throws error if profile already exists)
viam profiles add --profile-name=mycompany --key-id=54321zyx --key=123abcd1234

# Update an existing profile for authentication, or add it if it doesn't exist
viam profiles update --key=123abcd1234 --key-id=54321zyx --profile-name=mycompany

# List all existing profiles by name
viam profiles list

# Remove a profile
viam profiles remove --profile-name=mycompany

# Example of using a profile to see a list of machines available to that profile
viam --profile=mycompany machines list

See Manage API keys for more information.

Command options

Named arguments

training-script

Manage training scripts for custom ML training.

viam training-script upload --framework=<framework> --org-id=<org-id> --path=<path-to-script> --script-name=<script-name> --type=<type>
viam training-script update --org-id=<org-id> --script-name=<script-name> --visibility=<visibility>

Examples:

# upload a single label classification script in the tflite framework to organization 123
viam training-script upload --framework=tflite --org-id=123 --path=. --script-name=MyCustomTrainingScript --type=single_label_classification

# update MyCustomTrainingScript with public visibility
viam training-script update --org-id=123 --script-name=MyCustomTrainingScript --visibility=public --description="A single label classification training script"

Command options

Named arguments

train

Use a training script to train an ML model on data.

viam train submit managed --dataset-id=<dataset-id> --model-org-id=<model-org-id> --model-name=<model-name> --model-type=<model-type> --model-labels=<model-labels> [...named args]
viam train submit custom from-registry --dataset-id=<dataset-id> --org-id=<org-id> --model-name=<model-name> --script-name=<script-name> --version=<version> --args=<arg-key>=<arg-value> [...named args]
viam train submit custom with-upload --dataset-id=<dataset-id> --org-id=<org-id> --model-name=<model-name> --path=<path> --script-name=<script-name> --args=<arg-key>=<arg-value> [...named args]
viam train get --job-id=<job-id>
viam train logs --job-id=<job-id>
viam train cancel --job-id=<job-id>
viam train list --org-id=<org-id> --job-status=<job-status>
viam train containers list

Examples:

# submit training job on data in Viam Cloud with a Viam-managed training script
viam train submit managed --dataset-id=456 --model-org-id=123 --model-name=MyCoolClassifier --model-type=single_label_classification --model-labels=1,2,3

# submit custom training job with an existing training script in the Registry on data in Viam Cloud
viam train submit custom from-registry --dataset-id=<INSERT DATASET ID> --org-id=<INSERT ORG ID> --model-name=MyRegistryModel --model-version=2 --version=1 --script-name=mycompany:MyCustomTrainingScript  --args=num_epochs=3,model_type=multi_label

# submit custom training job with an uploaded training script on data in Viam Cloud
viam train submit custom with-upload --dataset-id=<INSERT DATASET ID> --model-org-id=<INSERT ORG ID> --model-name=MyRegistryModel --model-type=single_label_classification --model-version=2 --version=1 --path=<path-to-tar.gz> --script-name=mycompany:MyCustomTrainingScript --args=num_epochs=3,labels="'green_square blue_star'"

# get a training job from Viam Cloud based on training job ID
viam train get --job-id=123

# get training job logs from Viam Cloud based on training job ID
viam train logs --job-id=123

# cancel training job in Viam Cloud based on training job ID
viam train cancel --job-id=123

# list training jobs in Viam Cloud based on organization ID and job status
viam train list --org-id=123 --job-status=completed

Command options

Positional arguments: submit

Position arguments: submit custom

Named arguments

version

The version command returns the version of the Viam CLI. To update to the latest version of the CLI, run the installation steps again to download and install the latest version.

viam version

whoami

The whoami command returns the Viam user for an authenticated CLI session, or “Not logged in” if there is no authenticated session.

viam whoami

Global options

You can pass global options after the viam CLI keyword with any command.