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

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 the troubleshooting tips on Set up your first machine.

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