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

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