Configure machines with the CLI

Create and configure machines, add and remove components and services, and apply configuration fragments from the command line.

Find your IDs

Many commands on this page require an organization ID, location ID, machine ID, or part ID.

A machine can have one or more parts, each running a separate instance of viam-server. Every machine has at least one part (the main part), which is created automatically when you create the machine. When you add resources, apply fragments, or restart, you target a specific part.

Find your organization ID and location ID:

viam organizations list

viam locations list

Find machine IDs and part IDs:

viam machines list --organization=<org-id> --location=<location-id>

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

Create a machine

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

On success, the CLI prints the new machine’s ID:

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

Save this ID for subsequent commands.

List machines

List all machines in a location:

viam machines list --organization=<org-id> --location=<location-id>

List all machines across your entire organization:

viam machines list --organization=<org-id> --all

Add a component or service

Add a resource to a machine part using its model triplet:

viam machines part add-resource \
  --part=<part-id> \
  --name=my-camera \
  --model-name=viam:camera:webcam

The model triplet follows the format namespace:type:model. Common model triplets:

Remove a component or service

viam machines part remove-resource \
  --part=<part-id> \
  --name=my-camera

Apply a fragment

Fragments are reusable configuration blocks. Add a fragment to a machine part by specifying its fragment ID:

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

If you omit the --fragment flag, the CLI prompts you to select a fragment interactively.

Remove a fragment:

viam machines part fragments remove --part=<part-id> --fragment=<fragment-id>

See Reuse machine configuration for details on creating and managing fragments.

Rename or move a machine

viam machines update \
  --machine=<machine-id> \
  --new-name=updated-name \
  --new-location=<new-location-id>

Delete a machine

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

Restart a machine part

viam machines part restart --part=<part-id>

Related pages

• Get started for setting up your first machine
• Configure hardware for component configuration with the Viam app
• Manage your fleet with the CLI for monitoring and remote access
• CLI reference for the complete machines command reference