Edit

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

The Viam app is the fastest way to configure a single machine, browse your data, or train a model interactively. The CLI is the better choice when you need to:

Automate repeatable workflows. Script machine provisioning, module deployment, data export, or model retraining in shell scripts or CI/CD pipelines.
Work in headless environments. Configure machines, view logs, or shell into a device from a terminal without a browser.
Operate at fleet scale. List all machines across locations, apply fragments in batch, or export data across an entire organization with a single command.
Build tools and integrations. AI coding assistants, chatbots, and custom tooling can parse and execute CLI commands directly.

The CLI and the Viam app are not exclusive. Most users work in both: the app for visual configuration and testing, the CLI for automation, scripting, and remote access.

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 scaffolding (viam module generate) creates a new module project with boilerplate code and a build script.
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.
OAuth setup (viam organizations auth-service) configures end-user authentication.
Billing setup (viam organizations billing-service) enables white-label billing.
Module hot-reload (viam module reload-local) reloads a module during development 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

For more information see install the Viam CLI.

Verify the installation:

viam version

To update the CLI to the latest version:

viam update

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

Interactive login opens a browser, which does not work in headless environments. Use API key authentication instead:

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

To create an API key, see Manage API keys.

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

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!