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 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. - 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 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
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
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!