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...]
parameterdescription
global optionsoptional - list of flags that apply for commands
commandrequired - the specific CLI command to run
command optionsrequired for some commands - the operation to run for the specified command.
argumentsrequired for some commands - the arguments for the specified command operation. Some commands take positional arguments, some named 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

command optiondescriptionpositional arguments
print-access-tokenprints the access token the CLI uses during an authenticated CLI session-
helpreturn help-

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

command optiondescriptionpositional arguments
exportexport data in a specified format to a specified location-
deletedelete data-
helpreturn help-
Named arguments
argumentdescriptionapplicable commandsrequired
--destinationoutput directory for downloaded dataexporttrue
--data_typedata type to be downloaded: either binary or tabularexporttrue
--component_namefilter by specified component nameexport, deletefalse
--component_typefilter by specified component typeexport, deletefalse
--component_modelfilter by specified component modelexport, deletefalse
--startISO-8601 timestamp indicating the start of the intervalexport, deletefalse
--endISO-8601 timestamp indicating the end of the intervalexport, deletefalse
--location_idsfilter by specified location id (accepts comma-separated list)export, deletefalse
--methodfilter by specified methodexport, deletefalse
--mime_typesfilter by specified MIME type (accepts comma-separated list)export, deletefalse
--org_idsfilter by specified organizations id (accepts comma-separated list)export, deletefalse
--parallelnumber of download requests to make in parallel, with a default value of 10export, deletefalse
--part_idfilter by specified part idexport, deletefalse
--part_namefilter by specified part nameexport, deletefalse
--robot_idfilter by specified robot idexport, deletefalse
--robot_namefilter by specified robot nameexport, deletefalse
--tagsfilter by specified tag (accepts comma-separated list)export, deletefalse

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

command optiondescriptionpositional arguments
listlist all locations (name and id) that the authenticated session has access to, grouped by organizationorganization id : return results for specified organization only
helpreturn help-

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

command optiondescriptionpositional arguments
listlist all organizations (name and id) that the authenticated session belongs to-
helpreturn help-

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

command optiondescriptionpositional arguments
statusretrieve robot status for a specified robot-
logsretrieve logs for a specified robot-
partmanage a specified robot partstatus, run, logs, shell (see positional arguments: part)
helpreturn help-
Positional arguments: part
argumentdescription
statusretrieve robot status for a specified robot part
runrun 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.
logsget logs for the specified robot part
shellaccess a robot part securely using a secure shell. This feature must be enabled.
helpreturn help
Named arguments
argumentdescriptionapplicable commandsrequired
--organizationorganization name that the robot belongs tostatus, logs, parttrue
--locationlocation name that the robot belongs tostatus, logs, parttrue
--robotrobot id for which the command is being issuedstatus, logs, parttrue
--errorsboolean, return only errors (default: false)logsfalse
--partpart name for which the command is being issuedlogsfalse
--tailtail (stream) logs, boolean(default false)part logsfalse
--streamif specified, the interval in which to stream the specified data, for example, 100ms or 1spart runfalse
--datacommand data for the command being request to run (see data argument)part runtrue
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

command optiondescriptionpositional arguments
listlist all robots (name and id) that the authenticated session has access to in the specified organization and location-
helpreturn help-
Named arguments
argumentdescriptionapplicable commandsrequired
--organizationorganization name to filter bylisttrue
--locationlocation name to filter bylisttrue

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.

global optiondescription
--debugenable debug logging (default: false)