# 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](https://docs.viam.com/cli/configure-machines/) |
| Data management | Export, tag, and delete captured data; configure database access | [Manage data](https://docs.viam.com/cli/manage-data/) |
| Datasets and ML training | Create datasets, submit training jobs, run inference | [Datasets and training](https://docs.viam.com/cli/datasets-and-training/) |
| Data pipelines | Create and manage scheduled MQL aggregation pipelines | [Data pipelines](https://docs.viam.com/cli/data-pipelines/) |
| Module development | Scaffold, build, upload, and version modules | [Build and deploy modules](https://docs.viam.com/cli/build-and-deploy-modules/) |
| Fleet operations | Monitor status, stream logs, shell into machines, copy files | [Manage your fleet](https://docs.viam.com/cli/manage-your-fleet/) |
| Organization admin | Manage API keys, configure OAuth, set up billing | [Administer your organization](https://docs.viam.com/cli/administer-your-organization/) |
| Scripting and CI/CD | Authenticate in scripts, automate common workflows | [Automate with scripts](https://docs.viam.com/cli/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](https://docs.viam.com/build-apps/hosting/), 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

- [macOS](https://docs.viam.com/cli/overview/#tabset-clioverview-1-0)
- [Linux aarch64](https://docs.viam.com/cli/overview/#tabset-clioverview-1-1)
- [Linux x86_64](https://docs.viam.com/cli/overview/#tabset-clioverview-1-2)
- [Windows](https://docs.viam.com/cli/overview/#tabset-clioverview-1-3)
- [Source](https://docs.viam.com/cli/overview/#tabset-clioverview-1-4)

To download the Viam CLI on a macOS computer, install [brew](https://brew.sh/) and run the following commands:

```sh
brew tap viamrobotics/brews
brew install viam
```

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

```sh
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:

```sh
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](https://brew.sh/) on Linux `amd64` (Intel `x86_64`):

```sh
brew tap viamrobotics/brews
brew install viam
```

[Download the binary](https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-windows-amd64.exe) and run it directly to use the Viam CLI on a Windows computer.

If you have [Go installed](https://go.dev/doc/install), you can build the Viam CLI directly from source using the `go install` command:

```sh
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:

```sh
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc
```

Verify the installation:

```sh
viam version
```

To update the CLI to the latest version:

```sh
viam update
```

## Authenticate

- [Personal access token](https://docs.viam.com/cli/overview/#tabset-clioverview-2-0)
- [API key](https://docs.viam.com/cli/overview/#tabset-clioverview-2-1)

```sh
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:

```sh
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:

```sh
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:

```sh
viam logout
```

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

```sh
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:

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

To create an API key, see [Manage API keys](https://docs.viam.com/cli/administer-your-organization/#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`:

```sh
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.

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

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

To find your organization ID:

```sh
viam organizations list
```

To find location IDs within your organization:

```sh
viam locations list
```

Clear defaults when you need to work across organizations:

```sh
viam defaults clear-org
```

```sh
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.

```sh
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:

```sh
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:

```sh
viam machines list --all --profile=production
```

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

```sh
export VIAM_CLI_PROFILE_NAME=production
viam machines list --all
```

List and remove profiles:

```sh
viam profiles list
```

```sh
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:

```sh
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.

- [bash](https://docs.viam.com/cli/overview/#tabset-clioverview-3-0)
- [zsh](https://docs.viam.com/cli/overview/#tabset-clioverview-3-1)
- [fish](https://docs.viam.com/cli/overview/#tabset-clioverview-3-2)
- [PowerShell](https://docs.viam.com/cli/overview/#tabset-clioverview-3-3)

Add to your `~/.bashrc`:

```sh
source <(viam completion bash)
```

Add to your `~/.zshrc`:

```sh
source <(viam completion zsh)
```

```sh
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`:

```powershell
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:

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