Set up machines with the CLI

Create and connect a machine to the Viam platform from the command line, instead of clicking through the Viam app.

You’ll need:

1. Install and authenticate the CLI

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

brew tap viamrobotics/brews
brew trust viamrobotics/brews
brew install viam

On Debian-based distributions (Debian, Ubuntu, Raspberry Pi OS 64-bit), install the Viam CLI from Viam’s apt repository so apt upgrade keeps it up to date:

curl -fsSL https://us-apt.pkg.dev/doc/repo-signing-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/viam.gpg
echo "deb [signed-by=/usr/share/keyrings/viam.gpg] https://us-apt.pkg.dev/projects/static-file-server-310021 viam main" | sudo tee /etc/apt/sources.list.d/viam.list
sudo apt update && sudo apt install viam-cli

The package is named viam-cli; the installed command is viam (a viam-cli alias also works).

On other distributions, download the binary directly:

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

On Debian-based distributions (Debian, Ubuntu), install the Viam CLI from Viam’s apt repository so apt upgrade keeps it up to date:

curl -fsSL https://us-apt.pkg.dev/doc/repo-signing-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/viam.gpg
echo "deb [signed-by=/usr/share/keyrings/viam.gpg] https://us-apt.pkg.dev/projects/static-file-server-310021 viam main" | sudo tee /etc/apt/sources.list.d/viam.list
sudo apt update && sudo apt install viam-cli

The package is named viam-cli; the installed command is viam (a viam-cli alias also works).

On other distributions, download the binary directly:

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

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 from source. Clone the repository and build it with make:

git clone --depth 1 https://github.com/viamrobotics/rdk.git
cd rdk
make cli
sudo cp "bin/$(go env GOOS)-$(go env GOARCH)/viam-cli" /usr/local/bin/viam

To confirm viam is installed and ready to use, run viam version from your terminal.

For more information see install the Viam CLI.

In a script, authenticate with an API key:

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

2. Create the machine

viam machines create --name=my-first-machine --location=<location-id>

The CLI prints the new machine’s ID:

created new machine with id abc12345-1234-abcd-5678-ef1234567890

To find your location ID:

viam locations list

3. Get the part ID

Every machine has at least one part. To install viam-agent on the device, you need the part ID:

viam machines part list --machine=<machine-id>

4. Install viam-agent on the device

On the compute device that will run the machine, run:

sudo /bin/sh -c "VIAM_API_KEY_ID=<key-id> VIAM_API_KEY=<key> VIAM_PART_ID=<part-id>; $(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)"

The install script downloads viam-agent, fetches the machine’s cloud config to /etc/viam.json using the credentials above, and starts the agent service.

5. Verify the machine is online

viam machines status --machine=<machine-id>

If the machine is connected, the CLI prints its part list and status. If not, see Troubleshoot problems.

6. Apply a baseline configuration (optional)

If you have a fragment defining your standard component setup, attach it to the machine’s main part:

viam machines part fragments add --part=<part-id> --fragment=<fragment-name-or-id>

See Reuse machine configuration for the fragment authoring workflow.

Set up multiple machines

The pattern above handles one machine. To do this for many machines, wrap steps 2-6 in a script. See Automate with scripts for a complete provisioning script.

What’s next