Viam CLI overview | Viam Documentation

Viam CLI overview

The Viam CLI is a single binary that gives you command-line access to the Viam platform. Everything you can do in the Viam app, and several things you can only do from the command line, are available as CLI commands.

When to use the CLI

If you prefer working in a terminal, the CLI covers the same operations as the Viam app. You can use whichever interface you prefer, or both.

The CLI is particularly well-suited for tasks that are awkward or impossible in a browser:

Scripting and automation. Create machines, export data, upload modules, or submit training jobs from shell scripts and CI/CD pipelines.
Headless environments. Authenticate with an API key, view logs, and shell into a remote machine without a browser.
Bulk operations. List all machines across an organization, or export binary data filtered by location, machine, or component type.
Operations only available through the CLI. Scaffold new modules, transfer files to and from machines, tunnel ports, and hot-reload modules during development.

What the CLI covers

Area	What you can do	Guide
Machine configuration	Create machines, add components and services, apply fragments	Configure machines
Data management	Export, tag, and delete captured data; configure database access	Manage data
Datasets and ML training	Create datasets, submit training jobs, run inference	Datasets and training
Data pipelines	Create and manage scheduled MQL aggregation pipelines	Data pipelines
Module development	Scaffold, build, upload, and version modules	Build and deploy modules
Fleet operations	Monitor status, stream logs, shell into machines, copy files	Manage your fleet
Organization admin	Manage API keys, configure OAuth, set up billing	Administer your organization
Scripting and CI/CD	Authenticate in scripts, automate common workflows	Automate with scripts

CLI-only operations

Some operations are only available through the CLI:

Module and app scaffolding (viam module generate) creates a new module, Viam application, or combined module+app project with boilerplate code and a build script. Use viam module add-model and viam module add-app to extend existing modules.
Shell access (viam machines part shell) opens an interactive terminal on a remote machine.
File transfer (viam machines part cp) copies files to and from machines.
Port tunneling (viam machines part tunnel) forwards a local port to a remote machine.
Module hot-reload (viam module reload) builds a module and syncs it to a running machine without restarting the machine.

Install

To download the Viam CLI on a macOS computer, install brew and 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 --compressed -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 --compressed -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

Download the binary and run it directly to use the Viam CLI on a Windows computer.

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

Verify the installation:

viam version

To update the CLI to the latest version:

viam update

Authenticate

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.

Use your organization, location, or machine part API key and corresponding API key ID in the following command:

viam login api-key --key-id <api-key-id> --key <organization-api-key-secret>

Authentication tokens refresh automatically. You do not need to re-authenticate between sessions unless your token is revoked.

To check who you are authenticated as:

viam whoami

This prints your email if you logged in interactively, or key-<uuid> if you authenticated with an API key.

To end your session:

viam logout

To print your current access token (for piping into other tools, only works with interactive login, not API keys):

viam login print-access-token

Authenticate in scripts and CI/CD

Scripts and CI/CD pipelines cannot complete an interactive login. Use API key authentication instead:

viam login api-key --key-id=<key-id> --key=<key>

To create an API key, see Manage API keys.

Authenticate on a machine without a local browser

Interactive login normally opens a browser on the current machine. To log in on a machine without a local browser (for example, over SSH), pass --no-browser:

viam login --no-browser

The CLI prints an authentication URL. Open it in a browser on any machine to complete login.

Set defaults

If you work primarily within one organization or location, set defaults to avoid passing --org-id or --location-id on every command. The CLI validates that the org or location exists and is accessible before saving. Defaults are scoped to the active profile, so each profile can have its own default org and location.

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

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

To find your organization ID:

viam organizations list

To find location IDs within your organization:

viam locations list

Clear defaults when you need to work across organizations:

viam defaults clear-org

viam defaults clear-location

Manage authentication profiles

If you work across multiple organizations or use both personal and service accounts, profiles let you switch between saved credentials without re-authenticating. Each profile stores an API key and maintains its own default org and location independently.

viam profiles add --profile-name=production --key-id=<key-id> --key=<key>

profiles add errors if the name already exists. Use profiles update to overwrite an existing profile:

viam profiles update --profile-name=production --key-id=<new-key-id> --key=<new-key>

Use a profile for a single command with the --profile global flag:

viam machines list --all --profile=production

Or set the VIAM_CLI_PROFILE_NAME environment variable to activate a profile for an entire shell session:

export VIAM_CLI_PROFILE_NAME=production
viam machines list --all

List and remove profiles:

viam profiles list

viam profiles remove --profile-name=staging

Global flags

Every command accepts these flags:

Flag	Description
`--profile`	Use a saved authentication profile
`--config`, `-c`	Path to a CLI config file
`--debug`, `--vvv`	Enable debug logging
`--quiet`, `-q`	Suppress non-essential output
`--disable-profiles`	Ignore all saved profiles for this command

Get help

Every command supports the --help flag:

viam --help
viam machines --help
viam machines part shell --help

Enable shell completion

The CLI supports tab completion for commands, subcommands, and flag names. If you installed the CLI with Homebrew, completions are set up automatically. Otherwise, load the completion script for your shell.

Add to your ~/.bashrc:

source <(viam completion bash)

Add to your ~/.zshrc:

source <(viam completion zsh)

mkdir -p ~/.config/fish/completions
viam completion fish > ~/.config/fish/completions/viam.fish

Save the script as viam.ps1 and dot-source it from your $PROFILE:

viam completion pwsh > "$(Split-Path $PROFILE)/viam.ps1"
Add-Content $PROFILE ". $(Split-Path $PROFILE)/viam.ps1"

The generated script uses its filename to register completion for the viam command, so the file must be named viam.ps1.

After loading the script, press Tab to complete commands and flags:

viam <Tab>             # lists all commands
viam machines <Tab>    # lists subcommands of machines
viam data export <Tab> # lists subcommands of export