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...]

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

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 --org-id=<org-id> --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>]

data export tabular

Export tabular or sensor data to a specified location in the .ndjson output format. You can copy this from the UI with a filter. See Copy export command.

# 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

data export binary filter

Export binary or image data matching a filter to a specified location. Binary data will be downloaded in the original output it was specified as. You can copy this from the UI with a filter. See Copy export command.

# 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

data export binary ids

Export binary or image data by binary data ID to a specified location.

viam data export binary ids --destination=<output path> --binary-data-ids=<binary-data-ids>

data delete binary

Delete binary data from the Viam Cloud.

# 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

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

data delete tabular

Delete tabular data from the Viam Cloud.

viam data delete tabular --org-id=<org-id> --delete-older-than-days=<N>

data 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.

# 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

data database hostname

Get the MongoDB Atlas Data Federation instance hostname and connection URI. See Configure data query.

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

data tag ids add

Add tags to all data that matches the given binary data IDs.

# 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

See Using the ids argument for details on retrieving the IDs.

data tag ids remove

Remove tags from all data that matches the given binary data IDs.

# 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

data tag filter add

Add tags to all data that matches a given filter. See Using the filter argument.

# 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

data tag filter remove

Remove tags from all data that matches a given filter. See Using the filter argument.

# 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

data index create

Create a custom index on a data collection.

viam data index create --collection-type=<type> --index-path=<file> [--org-id=<org-id>] [--pipeline-name=<name>]

data index delete

Delete a custom index from a data collection.

viam data index delete --collection-type=<type> --index-name=<name> [--org-id=<org-id>] [--pipeline-name=<name>]

data index list

List all custom indexes for a data collection.

viam data index list --collection-type=<type> [--org-id=<org-id>]

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>
viam datapipelines enable --id=<pipeline-id>
viam datapipelines disable --id=<pipeline-id>
viam datapipelines delete --id=<pipeline-id>

datapipelines create

Create a new data pipeline.

# 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

datapipelines rename

Rename a data pipeline.

viam datapipelines rename --id=<pipeline-id> --name=<new-name>

datapipelines list

List all data pipelines in an organization.

viam datapipelines list --org-id=123

datapipelines describe

Get detailed information about a specific data pipeline.

viam datapipelines describe --id=abc123

datapipelines enable

Resume executing a disabled data pipeline.

viam datapipelines enable --id=abc123

datapipelines disable

Stop executing a data pipeline without deleting it.

viam datapipelines disable --id=abc123

datapipelines delete

Delete a data pipeline.

viam datapipelines delete --id=abc123

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 merge --name=<new-dataset-name> --dataset-ids=<dataset-id-1>,<dataset-id-2> [--org-id=<org-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>

dataset create

Create a new dataset.

viam dataset create --org-id=123 --name=MyDataset

dataset rename

Rename an existing dataset.

viam dataset rename --dataset-id=123 --name=MyCoolDataset

dataset list

List dataset information from specified IDs or for an org ID.

# 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

dataset delete

Delete a dataset.

viam dataset delete --dataset-id=123

dataset export

Download all the data from a dataset to a specified output directory in two folders called “data” and “metadata”.

viam dataset export --destination=./dataset/example --dataset-id=abc

dataset merge

Merge multiple datasets into a new dataset.

viam dataset merge --name=CombinedDataset --dataset-ids=123,456 --org-id=789

dataset data add ids

Add new images to an existing dataset by binary data ID. See Using the ids argument for details on retrieving the IDs.

viam dataset data add ids --dataset-id=abc --binary-data-ids=aaa,bbb

dataset data add filter

Add to an existing dataset images that match a specified filter.

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

dataset data remove ids

Remove images from an existing dataset by binary data ID. See Using the ids argument for details on retrieving the IDs.

viam dataset data remove ids --dataset-id=abc --binary-data-ids=aaa,bbb

dataset data remove filter

Remove from an existing dataset images that match a specified filter.

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

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.

defaults

The defaults command sets or clears default argument values so you do not have to pass the same --org-id or --location-id flag on every command. Once set, the value is read from your CLI config and used as the default for any command that accepts that argument.

viam defaults set-org --org-id=<org-id>
viam defaults clear-org
viam defaults set-location --location-id=<location-id>
viam defaults clear-location

defaults set-org

Set the default organization argument.

defaults clear-org

Clear the default organization argument.

defaults set-location

Set the default location argument.

defaults clear-location

Clear the default location argument.

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.

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=<organization>]
viam locations api-key create [--location-id=<location-id>] [--name=<name>] [--org-id=<org-id>]

locations list

List all locations (name and id) that the authenticated session has access to, grouped by organization.

viam locations list [--organization=<organization>]

locations api-key create

Create an API key for a specific location.

viam locations api-key create --location-id=<location-id>

login

The login command authorizes your device for CLI usage. By default, viam login opens a browser to authenticate using a personal access token. Pass --no-browser to authenticate in a headless environment without opening a browser. Use viam login api-key to authenticate using an API key, or viam login print-access-token to print the access token used by the current session. See Authenticate.

viam login [--no-browser]
viam login api-key --key-id=<api-key-uuid> --key=<api-key-secret-value>
viam login print-access-token

login api-key

Authenticate to Viam using an organization, location, or machine part API key.

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

login print-access-token

Print the access token used to authenticate the current CLI session.

viam login print-access-token

logout

The logout command ends an authenticated CLI session.

viam logout

machines (aliases robots, robot, 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> [--new-name=<new name>] [--new-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 --part=<part id> [...named args]
viam machines part status --part=<part id>
viam machines part run --part=<part id> --method=<method> [--data=<data>] [--stream=<interval>]
viam machines part shell --machine=<machine id> --part=<part id>
viam machines part restart --machine=<machine id> --part=<part id>
viam machines part history --part=<part id>
viam machines part cp --part=<part id> <file name> machine:/path/to/file
viam machines part add-job --part=<part id> [--config=<json or path>]
viam machines part update-job --part=<part id> --name=<job name> --config=<json or path>
viam machines part delete-job --part=<part id> --name=<job name>
viam machines part add-trigger --part=<part id> [--config=<json or path>]
viam machines part delete-trigger --part=<part id> --name=<trigger name>

To use part shell and part cp, add the ViamShellDanger fragment, which contains the latest version of the shell service.

machines create

Create a new machine in a specified location.

viam machines create --name="My Machine" --location=12345

machines update

Move a machine from one location to another and/or rename the machine.

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

machines delete

Delete a machine. Passing location and organization is optional but speeds up the process.

viam machines delete --machine=123

machines list

List all machines that the authenticated session has access to in a specified organization or location. Defaults to first organization and location alphabetically.

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

machines status

Retrieve machine status for a specified machine.

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

machines logs

Retrieve logs for a specified machine.

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

machines api-key create

Create an API key for a specific machine.

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

machines part list

List machine parts.

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

machines part status

Retrieve machine status for a specified machine part.

viam machines part status --machine=<machine id>

machines part run

Run a component or service command, optionally at a specified interval. For commands that return data in their response, you can use this to stream data. See Using the --stream and --data arguments.

# 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 \
--method=viam.service.vision.v1.VisionService.GetClassificationsFromCamera \
--data='{"name": "vision", "camera_name": "cam", "classifier_name": "stuff_classifier", "n":1}'

machines part logs

Get logs for the specified machine part.

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

machines part shell

Access a machine part securely using a secure shell to execute commands. To use this feature you must add the ViamShellDanger fragment. The ViamShellDanger fragment contains the latest version of the shell service, which you must add to your machine before copying files or using the shell.

viam machines part shell --machine=<machine id> --part=<part id>

machines part restart

Restart a machine part.

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

machines part history

Display the configuration history for a machine part.

viam machines part history --part=<part id>

machines part cp

Copy files to and from a machine part. To use this feature you must add the ViamShellDanger fragment, which contains the shell service, to your machine. Once added you can use cp in a similar way to the Linux scp command to copy files to and from machines.

# 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/

machines part tunnel

Tunnel connections to a specified port on a machine part. You must explicitly enumerate ports to which you are allowed to tunnel in your machine’s JSON config. See Tunnel to a machine part.

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

machines part get-ftdc

Download FTDC data from a machine part. Requires the shell service.

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

machines part create

Create a new part on a machine.

viam machines part create --machine=<machine id> --part-name=<new part name>

machines part delete

Delete a part.

viam machines part delete --part=<part id>

machines part add-resource

Add a component or service to a part’s configuration by specifying an API and model triplet.

viam machines part add-resource --part=<part id> --name=<resource name> --model-name=<namespace:type:model>

machines part remove-resource

Remove a resource from a part’s configuration.

viam machines part remove-resource --part=<part id> --name=<resource name>

machines part fragments add

Attach a configuration fragment to a part.

viam machines part fragments add --part=<part id> [--fragment=<fragment name or id>]

machines part fragments remove

Detach a configuration fragment from a part.

viam machines part fragments remove --part=<part id> [--fragment=<fragment name or id>]

machines part motion print-config

Print the motion planning configuration for the part.

viam machines part motion print-config --part=<part id>

machines part motion print-status

Print current motion state for the part.

viam machines part motion print-status --part=<part id>

machines part motion get-pose

Get the pose of a component in a reference frame.

viam machines part motion get-pose --part=<part id> --component=<component name>

machines part motion set-pose

Command a component to move to a specific pose.

viam machines part motion set-pose --part=<part id> --component=<component name>

machines part add-job

Add a scheduled job that runs a method on a resource at a given interval. Run without --config to launch an interactive builder, or pass --config with inline JSON or a path to a JSON file.

A job config object accepts the following fields:

• name (required): unique name for this job.
• schedule (required): one of continuous, a Go duration (for example, 5s, 1h30m, 500ms), or a cron expression (for example, 0 0 * * *, or */5 * * * * * with seconds).
• resource (required): name of the component or service to run the method on.
• method (required): gRPC method name. For example, DoCommand or GetReadings.
• command (optional): JSON object passed as the argument to DoCommand.
• log_configuration (optional): for example, {"level":"debug"}. Level must be one of debug, info, warn, or error.

# launch the interactive job builder
viam machines part add-job --part=<part id>

# add a job from inline JSON
viam machines part add-job --part=<part id> \
    --config '{"name":"my-job","schedule":"1h","resource":"my-sensor","method":"GetReadings"}'

# add a job from a JSON file
viam machines part add-job --part=<part id> --config ./job.json

machines part update-job

Update an existing job’s configuration by name. The --config flag accepts a single JSON object (inline or a path to a JSON file) with the fields to change. Only the fields provided will be updated; all other fields remain unchanged. The job name cannot be changed.

# change the schedule
viam machines part update-job --part=<part id> --name=my-job --config '{"schedule":"30m"}'

# change multiple fields
viam machines part update-job --part=<part id> --name=my-job \
    --config '{"schedule":"0 0 * * *","method":"DoCommand","command":{"action":"reset"}}'

machines part delete-job

Delete an existing scheduled job by name.

viam machines part delete-job --part=<part id> --name=my-job

machines part add-trigger

Add a trigger to a machine part. Run without --config to use an interactive form, or provide --config with inline JSON or a path to a JSON file.

Trigger configs support the following event types:

• part_online: liveness check.
• part_data_ingested: fires when data of the specified types is ingested.
• conditional_data_ingested: fires when data ingested by a specific data capture method matches a condition.
• conditional_logs_ingested: fires when logs at the specified levels are ingested.

Each trigger requires notifications, an array of objects with type (email or webhook), value, and seconds_between_notifications.

# launch the interactive trigger builder
viam machines part add-trigger --part=<part id>

# add a trigger from inline JSON
viam machines part add-trigger --part=<part id> \
    --config '{"name":"my-online-trigger","event":{"type":"part_online"},"notifications":[{"type":"email","value":"user@example.com","seconds_between_notifications":60}]}'

# add a trigger from a JSON file
viam machines part add-trigger --part=<part id> --config ./trigger.json

machines part delete-trigger

Delete a trigger from a machine part by name.

viam machines part delete-trigger --part=<part id> --name=<trigger name>

Using the --stream and --data arguments

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

You specify the resource method with --method. Use either the short name (for example, DoCommand or GetReadings) together with --component=<name>, or the full protobuf package and method path (for example, viam.service.vision.v1.VisionService.GetClassificationsFromCamera).

The --data parameter accepts method arguments as a JSON object. For example:

viam machines part run --part=<part-id> \
    --method=viam.service.vision.v1.VisionService.GetClassificationsFromCamera \
    --data='{"name": "vision", "camera_name": "cam", "classifier_name": "my_classifier", "n":1}'

You can find the protobuf path for any 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.

The --stream argument streams data back at the specified interval, for example 100ms or 1s.

metadata

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

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

metadata read

Read organization, location, machine, and machine part metadata.

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 --build-id=<build-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

module generate

Generate a new module with stub files and a meta.json file. Recommended when starting a new module.

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

module create

Generate a meta.json file and register the metadata with the Viam registry. Recommended when you already have working module code.

# 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

module update

Update your module’s metadata and documentation in the Viam registry. Updates are based on changes to meta.json, the module README.md, and the model readme namespace_module_model.md. Viam automatically runs update when you upload your module, as well as when you trigger a cloud build with Viam’s default build action.

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

module update-models

Update the module’s metadata file with the models it provides.

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

module upload

Validate and upload a new or existing custom module on your local filesystem to the Viam Registry. See Upload validation for more information.

Pass the path to the file, directory, or compressed archive (with .tar.gz or .tgz extension) that contains your custom module code as a positional argument.

# 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

module reload

Build a module in the cloud and configure the target machine to download it directly. Rebuild and restart if the module is already running.

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

module reload-local

Build a module locally and run it on a target machine. Rebuild and restart if it is already running. The module is loaded to ~/.viam/packages-local/namespace_module-name_from_reload-module.tar.gz on the target machine.

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

module restart

Restart a running module.

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

module build start

Start a module build in a cloud runner using the build step in your meta.json file. See Using the build subcommand.

# 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

module build local

Start a module build locally using the build step in your meta.json file. See Using the build subcommand.

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

module build list

List the status of your cloud module builds. See Using the build subcommand.

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

module build logs

Show the logs from a specific cloud module build. See Using the build subcommand.

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

module download

Download a module package from the registry.

# 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

module local-app-testing

Test your viam application locally. This will stand up a local proxy at http://localhost:8012 to simulate the Viam application server.

# 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

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 --build-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 [get | set] --org-id=<org-id> [--logo-path=<logo-path>]
viam organizations firebase-config [set | read | delete] --org-id=<org-id> [--app-id=<app-id>] [--firebase-config-path=<path>]
viam organizations billing-service get-config --org-id=<org-id>
viam organizations billing-service [enable | update] --org-id=<org-id> --address=<address>
viam organizations billing-service disable --org-id=<org-id>
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>

See Manage API keys for more information.

organizations list

List all organizations (name, ID, and namespace) that the authenticated session has access to.

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

organizations api-key create

Create a new organization API key.

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

organizations support-email get

Get the support email for an organization.

viam organizations support-email get --org-id=<org-id>

organizations support-email set

Set the support email for an organization.

viam organizations support-email set --org-id=<org-id> --support-email=<support-email>

organizations logo set

Upload the logo for an organization from a local file.

viam organizations logo set --org-id=<org-id> --logo-path=<logo-path>

organizations logo get

Get the logo for an organization.

viam organizations logo get --org-id=<org-id>

organizations firebase-config set

Upload a Firebase config JSON for a specific app ID. Organization owner only.

viam organizations firebase-config set --org-id=<org-id> --app-id=com.example.myapp --firebase-config-path=./firebase-config.json

organizations firebase-config read

Read Firebase config metadata for an organization. Organization owner only.

viam organizations firebase-config read --org-id=<org-id>

organizations firebase-config delete

Delete a Firebase config for a specific app ID. Organization owner only.

viam organizations firebase-config delete --org-id=<org-id> --app-id=com.example.myapp

organizations billing-service get-config

Get the billing service config for an organization.

viam organizations billing-service get-config --org-id=<org-id>

organizations billing-service enable

Enable the billing service for an organization.

viam organizations billing-service enable --org-id=<org-id> --address=<address>

organizations billing-service update

Update the billing service for an organization.

viam organizations billing-service update --org-id=<org-id> --address=<address>

organizations billing-service disable

Disable the billing service for an organization.

viam organizations billing-service disable --org-id=<org-id>

organizations auth-service enable

Enable auth-service for OAuth applications.

viam organization auth-service enable --org-id=<org-id>

organizations auth-service disable

Disable auth-service for OAuth applications. Disabling the auth-service does not delete your OAuth token, it will just take off the custom branding.

viam organization auth-service disable --org-id=<org-id>

organizations auth-service oauth-app create

Create a new OAuth application.

viam organization auth-service oauth-app create --client-authentication=<policy> --client-name=<name> --enabled-grants=<grants> --logout-uri=<uri> --origin-uris=<uris> --pkce=<pkce> --redirect-uris=<uris> --url-validation=<validation> --org-id=<org-id>

organizations auth-service oauth-app update

Update an existing OAuth application.

viam organization auth-service oauth-app update --org-id=<org-id> --client-id=<client-id> [other options]

organizations auth-service oauth-app list

List OAuth applications for an organization.

viam organization auth-service oauth-app list --org-id=<org-id>

organizations auth-service oauth-app read

Read an OAuth application.

viam organization auth-service oauth-app read --org-id=<org-id> --client-id=<client-id>

organizations auth-service oauth-app delete

Delete an OAuth application.

viam organization auth-service oauth-app delete --org-id=<org-id> --client-id=<client-id>

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 --path=<path-to-package.tar.gz> --org-id=<org-id> --name=<package-name> --version=<version> --type=<type>
viam packages export --type=<type> [--org-id=<org-id>] [--name=<package-name>] [--version=<version>] [--destination=<path-to-export-destination>]

packages upload

Upload a package to the Viam Cloud.

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

packages export

Download a package from the Viam Cloud.

viam packages export --type=ml_model --org-id=123 --name=MyMLModel --version=latest --destination=.

parse-ftdc

The parse-ftdc command parses an FTDC (Full-Time Diagnostic Data Capture) file and opens an interactive REPL for inspecting performance metrics collected by viam-server. This is a diagnostic tool. Viam support may ask you to run it when troubleshooting performance issues.

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

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.

profiles add

Add a new profile for authentication. Throws an error if the profile already exists.

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

profiles update

Update an existing profile for authentication, or add it if it doesn’t exist.

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

profiles list

List all existing profiles by name.

viam profiles list

profiles remove

Remove a profile.

viam profiles remove --profile-name=<name-of-profile-to-remove>

resource

The resource command enables, disables, or updates individual resources (components and services) on a machine part. Use it to temporarily disable a resource without removing it from the configuration, or to update attributes without using the Viam app.

viam resource enable --part=<part> --resource-name=<resource-name> [--resource-name=<resource-name> ...]
viam resource disable --part=<part> --resource-name=<resource-name> [--resource-name=<resource-name> ...]
viam resource update --part=<part> --resource-name=<resource-name> --config=<json-or-path>

Examples:

# enable a single resource
viam resource enable --part=abc123 --resource-name=my-sensor

# enable multiple resources at once
viam resource enable --part=abc123 --resource-name=my-sensor --resource-name=arm-1

# update a resource attribute inline
viam resource update --part=abc123 --resource-name=my-sensor --config='{"pin": "38"}'

# update from a JSON file
viam resource update --part=abc123 --resource-name=my-sensor --config=/path/to/updates.json

# delete an attribute by passing an empty value
viam resource update --part=abc123 --resource-name=my-sensor --config='{"pin": ""}'

resource enable

Enable one or more resources on a machine part.

viam resource enable --part=<part> --resource-name=<resource-name> [--resource-name=<resource-name> ...]

resource disable

Disable one or more resources on a machine part. Disabled resources are not started by viam-server.

viam resource disable --part=<part> --resource-name=<resource-name> [--resource-name=<resource-name> ...]

resource update

Replace a resource’s attributes with new values. The --config flag accepts inline JSON or a path to a JSON file. An empty JSON object deletes all attributes.

viam resource update --part=<part> --resource-name=<resource-name> --config=<json-or-path>

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

train submit managed

Submit a training job on data in the Viam Cloud with a Viam-managed training script.

# 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

train submit custom from-registry

Submit a custom training job with an existing training script in the registry on data in the Viam Cloud.

# 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

train submit custom with-upload

Upload a draft training script and submit a custom training job on data in the Viam Cloud.

# 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'"

train get

Get a training job from the Viam Cloud based on training job ID.

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

train logs

Get the logs of a training job from the Viam Cloud based on training job ID.

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

train cancel

Cancel a training job in the Viam Cloud based on training job ID.

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

train list

List training jobs in Viam Cloud based on organization ID and job status.

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

train containers list

List supported Docker container images for custom training.

viam train containers list

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>

training-script upload

Upload an ML training script to the registry.

# 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

training-script update

Update the visibility of an ML training script in the registry.

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

traces

The traces command imports viam-server trace files to an OTLP endpoint or prints them to the console. Use it to debug machine performance and request flow with a tracing backend such as Jaeger or Tempo.

The import-remote, print-remote, and get-remote subcommands require the machine to have a valid shell-type service. Organization and location are required if you are identifying the part by name rather than ID.

viam traces import-local <traces-file> [--endpoint=<host:port>]
viam traces import-remote --part=<part> [--endpoint=<host:port>] [--organization=<org>] [--location=<location>]
viam traces print-local <traces-file>
viam traces print-remote --part=<part> [--organization=<org>] [--location=<location>]
viam traces get-remote --part=<part> [target] [--organization=<org>] [--location=<location>]

traces import-local

Import traces from a local viam-server trace file to an OTLP endpoint.

viam traces import-local <traces-file> [--endpoint=<host:port>]

Pass the path to a local viam-server trace file as a positional argument.

traces import-remote

Import traces from a remote machine to an OTLP endpoint.

viam traces import-remote --part=<part> [--endpoint=<host:port>] [--organization=<org>] [--location=<location>]

traces print-local

Print traces from a local trace file to the console.

viam traces print-local <traces-file>

Pass the path to a local viam-server trace file as a positional argument.

traces print-remote

Print traces from a remote machine to the console.

viam traces print-remote --part=<part> [--organization=<org>] [--location=<location>]

traces get-remote

Download traces from a remote machine to a local file. If [target] is omitted, the file is saved to the current working directory.

viam traces get-remote --part=<part> [target] [--organization=<org>] [--location=<location>]

update

The update command updates the CLI to the latest version. If the CLI was installed with Homebrew, it updates through Homebrew. Otherwise, it downloads and replaces the binary directly.

viam update

version

The version command returns the version of the Viam CLI. To update to the latest version of the CLI, run viam update.

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

xacro

The xacro command converts ROS xacro files to URDF using a Docker container. Use it to integrate ROS-based robot descriptions with Viam’s frame system.

viam xacro convert --input-file=<file> --output-file=<file> [other options]

Examples:

# basic conversion
viam xacro convert --input-file=robot.xacro --output-file=robot.urdf

# pass xacro arguments
viam xacro convert --input-file=arm.xacro --output-file=arm.urdf --args=name:=ur20

# collapse fixed-joint chains so only one end effector exists
viam xacro convert --input-file=robot.xacro --output-file=robot.urdf --collapse-fixed-joints

xacro convert

Convert a xacro file to URDF.