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

- An organization and a location in the Viam app. New to Viam? Use [Set up your first machine](https://docs.viam.com/set-up-a-machine/first-machine/) to create them, then come back.
- An API key for the CLI. See [Manage API keys](https://docs.viam.com/cli/administer-your-organization/#manage-api-keys).
- A Linux or macOS device to run `viam-agent`. For Windows or ESP32, use [Set up your first machine](https://docs.viam.com/set-up-a-machine/first-machine/).

## 1\. Install and authenticate the CLI

- [macOS](https://docs.viam.com/set-up-a-machine/with-cli/#tabset-set-up-a-machinewith-cli-1-0)
- [Linux aarch64](https://docs.viam.com/set-up-a-machine/with-cli/#tabset-set-up-a-machinewith-cli-1-1)
- [Linux x86\_64](https://docs.viam.com/set-up-a-machine/with-cli/#tabset-set-up-a-machinewith-cli-1-2)
- [Windows](https://docs.viam.com/set-up-a-machine/with-cli/#tabset-set-up-a-machinewith-cli-1-3)
- [Source](https://docs.viam.com/set-up-a-machine/with-cli/#tabset-set-up-a-machinewith-cli-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="$(go env GOPATH)/bin:$PATH"' >> ~/.bashrc
```

For more information see [install the Viam CLI](https://docs.viam.com/cli/).

In a script, authenticate with an API key:

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

## 2\. Create the machine

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

The CLI prints the new machine’s ID:

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

To find your location ID:

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

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

## 4\. Install viam-agent on the device

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

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

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

If the machine is connected, the CLI prints its part list and status. If not, see [Troubleshoot problems](https://docs.viam.com/monitor/troubleshoot/).

## 6\. Apply a baseline configuration (optional)

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

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

See [Reuse machine configuration](https://docs.viam.com/fleet/reuse-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](https://docs.viam.com/cli/automate-with-scripts/#provisioning-create-and-configure-a-machine) for a complete provisioning script.

## What’s next

- [Configure hardware](https://docs.viam.com/hardware/configure-hardware/) to add components and services.
- [Reuse machine configuration](https://docs.viam.com/fleet/reuse-configuration/) to author the fragments your machines apply.
- [Automate with scripts](https://docs.viam.com/cli/automate-with-scripts/) for bulk operations and CI/CD.