Viam CLI

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

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

viam robots 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

You can download the Viam CLI executable using one of the options below. Select the tab for your platform and architecture. If you are on Linux, you can use the uname -m command to determine your system architecture.

To download the Viam CLI on a macOS computer, run the following commands:

brew tap viamrobotics/brews
brew install viam

To download the Viam CLI on a Linux computer with the aarch64 architecture, run the following commands:

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64
sudo chmod a+rx /usr/local/bin/viam

To download the Viam CLI on a Linux computer with the amd64 (Intel x86_64) architecture, run the following commands:

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64
sudo chmod a+rx /usr/local/bin/viam

You can also install the Viam CLI using brew on Linux amd64 (Intel x86_64):

brew tap viamrobotics/brews
brew install viam

If you have Go installed, you can build the Viam CLI directly from source using 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

To later update the Viam CLI tool on Linux, use the steps above to reinstall the latest version. to later update the Viam CLI tool on macOS, run brew upgrade viam.

Authenticate

Once you have installed the Viam CLI, you must authenticate your CLI session with Viam in order to run CLI commands.

You can authenticate your CLI session using either a personal access token or an organization API key. To use an organization API key to authenticate, you must first create an organization API key.

  • To authenticate your CLI session using a personal access token:

    viam login
    

    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.

  • To authenticate your CLI session using an organization API key:

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

    If you haven’t already, create an organization API key to use this authentication method.

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

After the session expires or you log out, you must re-authenticate to use the CLI again.

Create an organization API key

To use an organization API key to authenticate your CLI session, you must first create one:

  1. First, authenticate your CLI session. If your organization does not already have an organization API key created, authenticate using a personal access token.

  2. Then, run the following command to create a new organization API key:

    viam organizations api-key create --org-id <org-id> --name <key-name>
    

    Where:

    • org-id is your organization ID. You can find your organization ID by running viam organizations list or by visiting your organization’s Settings page in the Viam app.
    • key-name is an optional name for your API key. If omitted, a name will be auto-generated based on your login info and the current time.

The command will return a key id and a key value. You will need both to authenticate using viam login api-key.

Once created, you can then use the organization API key to authenticate future CLI sessions. To switch to using an organization API key for authentication right away, logout then log back in using viam login api-key.

An organization can have multiple API keys.

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 or manage custom modules. 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.

See the list of commands below.

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 the --help flag as a command option for any CLI command, for example:

viam organizations --help

Commands

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-

login

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

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 organization API key. If you haven’t already, you must create an organization API key first in order to authenticate using one.

Command options

command optiondescriptionpositional arguments
api-keyauthenticate to Viam using an organization API key-
print-access-tokenprints the access token used to authenticate the current CLI session-
--helpreturn help-
Named arguments
argumentdescriptionapplicable commandsrequired
--key-idthe key id (UUID) of the organization API keyapi-keytrue
--keythe key value of the organization API keyapi-keytrue

logout

The logout command ends an authenticated CLI session.

viam logout

module

The module command allows to you to manage custom modules This includes:

viam module create --name <module-id> [--org-id <org-id> | --public-namespace <namespace>]
viam module update [--org-id <org-id> | --public-namespace <namespace>] [--module <path to meta.json>]
viam module upload --version <version> --platform <platform> [--org-id <org-id> | --public-namespace <namespace>] [--module <path to meta.json>] <packaged-module.tar.gz>

Examples:

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

# generate metadata for 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

# 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

See Upload a custom module and Update an existing module for a detailed walkthrough of the viam module commands.

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.

Command options

command optiondescriptionpositional arguments
creategenerate new metadata for a custom module on your local filesystem-
updateupdate an existing custom module on your local filesystem with recent changes to the meta.json file-
uploadvalidate and upload a new or existing custom module on your local filesystem to the Viam registry. See Upload validation for more information
--helpreturn help-
Named arguments
argumentdescriptionapplicable commandsrequired
--forceskip local validation of the packaged module, which may result in an unusable module if the contents of the packaged module are not correctuploadfalse
--modulethe path to the meta.json file for the custom module, if not in the current directoryupdate, uploadfalse
--namethe name of the custom module to be createdcreatetrue
--org-idthe organization ID to associate the module to. See Using the --org-id argumentcreate, update, uploadtrue
--public-namespacethe namespace to associate the module to. See Using the --public-namespace argumentcreate, update, uploadtrue
--platformthe architecture of your module binary. See Using the --platform argumentuploadtrue
--versionthe version of your module to set for this upload. See Using the --version argumentuploadtrue
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, suitable for uploading your module to the Viam registry and sharing with other users.
  • Use the --org-id to provide your organization ID instead, suitable for sharing 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:

  • darwin/arm64 - macOS computers running the arm64 architecture, such as Apple Silicon.
  • darwin/amd64 - macOS computers running the Intel x86_64 architecture.
  • linux/arm64 - Linux computers or boards running the arm64 (aarch64) architecture, such as the Raspberry Pi.
  • linux/amd64 - Linux computers or boards running the Intel x86_64 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.

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

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 robot 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 validates your local packaged module to ensure that it meets the requirements to successfully upload to the Viam registry. The following criteria are checked for every upload:

  • The packaged module must exist on the filesystem at the path provided to the upload command.
  • The packaged module must use the .tar.gz or .tgz extension.
  • 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.
The meta.json file

When uploading a custom module, the Viam registry tracks your module’s metadata in a meta.json file. This file is created for you when you run the viam module create command, with the module_id field pre-populated based on the --name you provided to create. If you later make changes to this file, you can register those changes with the Viam registry by using the viam module update command.

The meta.json file includes the following configuration options:

NameTypeInclusionDescription
module_idstringRequiredThe name of the module, including its namespace
visibilitystringRequiredWhether the module is accessible only to members of your organization (private), or visible to all Viam users (public). You can change this setting later using the viam module update command.

Default: private
urlstringOptionalThe URL of the GitHub repository containing the source code of the module.
descriptionstringRequiredA description of your module and what it provides.
modelsobjectRequiredA list of one or more models provided by your custom module. You must provide at least one model, which consists of an api and model key pair.
entrypointstringRequiredThe name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program.

For example, the following represents the configuration of an example my-module module in the acme namespace:

{
  "module_id": "acme:my-module",
  "visibility": "public",
  "url": "https://github.com/acme-co-example/my-module",
  "description": "An example custom module.",
  "models": [
    {
      "api": "rdk:component:generic",
      "model": "acme:demo:my-model"
    }
  ],
  "entrypoint": "run.sh"
}

See Upload a custom module and Update an existing module for a detailed walkthrough of the viam module commands.

See Modular resources for a conceptual overview of modules and the modular resource system at Viam.

organizations

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

viam organizations list
viam organizations api-key create --org-id <org-id> [--name <key-name>]

See create an organization API key for more information.

Command options

command optiondescriptionpositional arguments
listlist all organizations (name and id) that the authenticated session belongs to-
api-keycreate a new organization API key-
--helpreturn help-
Named arguments
argumentdescriptionapplicable commandsrequired
--org-idyour organization IDapi-keytrue
--nameoptional name for the organization API key. If omitted, a name will be auto-generated based on your login info and the current timeapi-keyfalse

robots

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

  • Listing all robots that you have access to, filtered by organization and location.
  • 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 robots list
viam robots status --organization=<org name> --location=<location name> --robot=<robot id>
viam robots logs --organization=<org name> --location=<location name> --robot=<robot id> [...named args]
viam robots part status --organization=<org name> --location=<location name> --robot=<robot id>
viam robots part run --organization=<org name> --location=<location name> --robot=<robot id> [--stream] --data <meth>
viam robots part shell --organization=<org name> --location=<location name> --robot=<robot id>

Examples:


# list all robots you have access to
viam robots list

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

# stream error level logs from a robot part
viam robots 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 robots 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
listlist all robots that the authenticated session has access to, filtered by organization and location.-
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 tolist, status, logs, parttrue
--locationlocation name that the robot belongs tolist, status, 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 stream data back at the specified interval.

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.

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