Viam CLI

The Viam CLI (command line interface) tool enables you to manage your robots across organizations and locations from the command line. The CLI lets you:

• Retrieve organization and location information
• Manage robot fleet data and logs
• Control robots by issuing component and service commands.

For example, this CLI command moves a servo to the 75 degree position:

viam robot part run --robot 82c608a-1be9-46a5 --organization "Robot's Org" \
--location myLoc --part "myrobot-main" --data '{"name": "myServo", "angle_deg":75}' \
viam.component.servo.v1.ServoService.MoveRequest

Install

If you have Go installed, you can install the Viam CLI with the ‘go install’ command:

go install go.viam.com/rdk/cli/viam@latest

To confirm viam is installed and ready to use, issue the viam command from your terminal. If you see help instructions, everything is correctly installed. If you do not see help instructions, add your local go bin/ directory to your PATH variable. If you use bash as your shell, you can use the following command:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

Authenticate

Once you have successfully installed the Viam CLI, you need to authenticate your device for CLI usage with your Viam app account before you can control your robots with the CLI. Do this by issuing the command:

viam auth

This will open a new browser window with a prompt to start the authentication process. If a browser window does not open, the CLI will present a URL for you to manually open in your browser. Follow the instructions to complete the authentication process.

A successfully authenticated session is valid for 24 hours, unless you explicitly log out.

Manage your robots with the Viam CLI

With the Viam CLI installed and authenticated, you can use it to issue commands to your robot fleet. All Viam CLI commands use the following format:

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

CLI help

The Viam CLI has a built-in help system that lists all available commands. You can access it at any time by issuing the command:

viam help

You can also access contextual help by passing help as a command option for any CLI command, for example:

viam organizations help

Commands

auth

The auth command helps you authorize your device for CLI usage. See Authenticate

viam auth
viam auth print-access-token

Command options

data

The data command allows you to manage robot data. With it, you can export data in the format of your choice or delete specified data. You can filter the data this command operates on.

viam data export --destination=<output path> --data-type=<output data type> [...named args]
viam data delete [...named args]

Examples:

# export tabular data to /home/robot/data for org abc, location 123
viam data export --destination=/home/robot/data --data_type=tabular \
--org_ids=abc --location_ids=123

# export binary data from all orgs and locations, component name myComponent
viam data export --destination=/home/robot/data --data_type=binary \
--component_name myComponent

Command options

Named arguments

locations

The locations command lists all locations that the authenticated session has access to, grouped by organization. You can filter results by organization.

viam locations list [<organization id>]

Command options

logout

The logout command ends an authenticated CLI session

viam logout

organizations

The organizations command lists all organizations that the authenticated session belongs to.

viam organizations list

Command options

robot

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

• Retrieving robot and robot part status
• Retrieving robot and robot part logs
• Controlling a robot by issuing component and service commands
• Accessing your robot with a secure shell (when this feature is enabled)

viam robot status --organization=<org name> --location=<location name> --robot=<robot id>
viam robot logs --organization=<org name> --location=<location name> --robot=<robot id> [...named args]
viam robot part status --organization=<org name> --location=<location name> --robot=<robot id>
viam robot part run --organization=<org name> --location=<location name> --robot=<robot id> [--stream] --data <meth>
viam robot part shell --organization=<org name> --location=<location name> --robot=<robot id>

Examples:

# get robot status
viam robot status  --robot 82c608a-1be9-46a5-968d-bad3a8a6daa --organization "Robot's Org" --location myLoc

# stream error level logs from a robot part
viam robot part logs --robot 82c608a-1be9-46a5-968d-bad3a8a6daa \
--organization "Robot's Org" --location myLoc --part "myrover-main" --tail true

# stream classifications from a robot part every 500 milliseconds from the Viam Vision Service with classifier "stuff_detector"
viam robot part run --robot 82c608a-1be9-46a5-968d-bad3a8a6daa \
--organization "Robot's Org" --location myLoc --part "myrover-main" --stream 500ms \
--data '{"name": "vision", "camera_name": "cam", "classifier_name": "stuff_detector", "n":1}' \
viam.service.vision.v1.VisionService.GetClassificationsFromCamera

Command options

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 robot 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 streams data back at the specified interval.

robots

The robots command lists all robots that the authenticated session has access to, filtered by organization and location.

viam robots list

Command options

Named arguments

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.