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.

Prerequisites
You need the Viam CLI installed and authenticated. See Viam CLI overview for installation and authentication instructions.

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. The --type flag specifies the package type: archive, ml_model, module, slam_map, or ml_training.

viam packages upload \
  --path=./my-package.tar.gz \
  --name=my-control-logic \
  --version=1.0.0 \
  --type=archive \
  --org-id=<org-id>

For ML model packages, you must also specify the framework and model type:

viam packages upload \
  --path=./my-model.tar.gz \
  --name=my-detector \
  --version=1.0.0 \
  --type=ml_model \
  --model-framework=tflite \
  --model-type=object_detection \
  --org-id=<org-id>

Download a package from the registry:

viam packages export \
  --org-id=<org-id> \
  --name=my-detector \
  --version=latest \
  --type=ml_model \
  --destination=./downloaded

If you omit --version, the CLI downloads the latest version. If you omit --destination, the package is saved to the current directory.

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

Work with traces

Viam machines collect OpenTelemetry traces that record the timing and context of operations. Use the viam traces commands to retrieve and inspect these traces for debugging performance issues.

Print traces to the console

Print traces from a remote machine:

viam traces print-remote --part=<part-id>

Print traces from a local file:

viam traces print-local ./traces-file

Download traces

Download traces from a machine and save them to disk:

viam traces get-remote --part=<part-id>

By default, the file is saved to the current directory. Pass a target path to save elsewhere:

viam traces get-remote --part=<part-id> ./my-traces

Import traces to an OTLP endpoint

If you run a tracing backend like Jaeger or Grafana Tempo, import traces directly from a machine or a local file:

viam traces import-remote --part=<part-id> --endpoint=localhost:4317

viam traces import-local ./traces-file --endpoint=localhost:4317

The --endpoint flag defaults to localhost:4317 if omitted.

Read metadata

Read metadata attached to an organization, location, machine, or machine part. Specify at least one ID:

viam metadata read --machine-id=<machine-id>

You can combine multiple IDs to read metadata at different levels:

viam metadata read --org-id=<org-id> --location-id=<location-id>

Available flags: --org-id, --location-id, --machine-id, --part-id.

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