Manage your fleet with the CLI

Monitor machine status, stream logs, connect to remote machines with a shell, copy files, and deploy software packages across your fleet.

Find your IDs

To find your organization ID and location IDs:

viam organizations list

viam locations list

To find machine IDs and part IDs:

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

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

List and monitor machines

List all machines in a location:

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

List all machines across your organization:

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

Check the status of a specific machine:

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

View logs

Stream logs from a machine:

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

Stream logs from a specific part:

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

Show only errors:

viam machines part logs --part=<part-id> --errors

Follow logs in real time:

viam machines part logs --part=<part-id> --tail

Shell into a machine

Open an interactive shell on a remote machine part. The connection uses Viam’s secure WebRTC channel, not direct SSH. The machine must have a shell service configured.

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

Copy files to and from machines

File copy uses the same secure connection as shell access, not SSH or SCP. Use the machine: prefix for remote paths.

Copy a file to a machine:

viam machines part cp --part=<part-id> local-file.txt machine:/home/user/

Copy a file from a machine:

viam machines part cp --part=<part-id> machine:/home/user/remote-file.txt ./

Copy a directory recursively:

viam machines part cp --part=<part-id> -r ./local-dir machine:/home/user/

Preserve file permissions and timestamps:

viam machines part cp --part=<part-id> -r --preserve ./local-dir machine:/home/user/

Create a tunnel

Forward a local port to a port on a remote machine. This is useful for accessing web UIs, databases, or other services running on machines that are not directly reachable from your network.

viam machines part tunnel \
  --part=<part-id> \
  --local-port=8080 \
  --destination-port=8080

Run component and service methods

Call a gRPC method on a component or service directly from the CLI, like curl for Viam’s API:

viam machines part run \
  --part=<part-id> \
  --data='{"name": "my-sensor"}' \
  rdk.component.sensor.v1.SensorService.GetReadings

Stream results at an interval:

viam machines part run \
  --part=<part-id> \
  --stream=500ms \
  --data='{"name": "my-camera"}' \
  rdk.component.camera.v1.CameraService.GetImage

Deploy software packages

Upload a package to the Viam registry for deployment to machines:

viam packages upload \
  --path=./my-package.tar.gz \
  --name=my-control-logic \
  --version=1.0.0 \
  --type=ml_model

Export a package:

viam packages export --type=ml_model

Export diagnostics

Export FTDC (Full-Time Diagnostic Data Capture) metrics from a machine:

viam machines part get-ftdc --part=<part-id>

Parse an FTDC file locally:

viam parse-ftdc --path=./ftdc-data

Create API keys for machines

Create an API key scoped to a specific machine:

viam machines api-key create --machine-id=<machine-id>

The CLI prints the key ID and key value. Save both immediately; the key value is only shown once.

Successfully created key:
Key ID: abcdef12-3456-7890-abcd-ef1234567890
Key Value: your-secret-key-value

Related pages

• Monitor machine status for monitoring with the Viam app
• Troubleshoot for debugging machine issues
• Deploy software for deploying with fragments
• CLI reference for the complete machines command reference