# 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](https://docs.viam.com/cli/overview/) for installation and authentication instructions. ## Find your IDs To find your organization ID and location IDs: ```sh viam organizations list ``` ```sh viam locations list ``` To find machine IDs and part IDs: ```sh viam machines list --organization= --location= ``` ```sh viam machines part list --machine= ``` ## List and monitor machines List all machines in a location: ```sh viam machines list --organization= --location= ``` List all machines across your organization: ```sh viam machines list --organization= --all ``` Check the status of a specific machine: ```sh viam machines status --machine= ``` ## View logs Stream logs from a machine: ```sh viam machines logs --machine= ``` Stream logs from a specific part: ```sh viam machines part logs --part= ``` Show only errors: ```sh viam machines part logs --part= --errors ``` Follow logs in real time: ```sh viam machines part logs --part= --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. ```sh viam machines part shell --part= ``` ## 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: ```sh viam machines part cp --part= local-file.txt machine:/home/user/ ``` Copy a file from a machine: ```sh viam machines part cp --part= machine:/home/user/remote-file.txt ./ ``` Copy a directory recursively: ```sh viam machines part cp --part= -r ./local-dir machine:/home/user/ ``` File permissions are preserved by default, respecting the destination `umask`. Use `--preserve` to also keep modification timestamps and force exact permission bits (overriding the destination `umask`): ```sh viam machines part cp --part= -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. ```sh viam machines part tunnel \ --part= \ --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: ```sh viam machines part run \ --part= \ --data='{"name": "my-sensor"}' \ rdk.component.sensor.v1.SensorService.GetReadings ``` Stream results at an interval: ```sh viam machines part run \ --part= \ --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`. ```sh viam packages upload \ --path=./my-package.tar.gz \ --name=my-control-logic \ --version=1.0.0 \ --type=archive \ --org-id= ``` For ML model packages, you must also specify the framework and model type: ```sh 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= ``` Download a package from the registry: ```sh viam packages export \ --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: ```sh viam machines part get-ftdc --part= ``` Parse an FTDC file locally: ```sh viam parse-ftdc --path=./ftdc-data ``` ## Work with traces Viam machines collect [OpenTelemetry](https://opentelemetry.io/) 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: ```sh viam traces print-remote --part= ``` Print traces from a local file: ```sh viam traces print-local ./traces-file ``` ### Download traces Download traces from a machine and save them to disk: ```sh viam traces get-remote --part= ``` By default, the file is saved to the current directory. Pass a target path to save elsewhere: ```sh viam traces get-remote --part= ./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: ```sh viam traces import-remote --part= --endpoint=localhost:4317 ``` ```sh viam traces import-local ./traces-file --endpoint=localhost:4317 ``` The `--endpoint` flag defaults to `localhost:4317` if omitted. #### Note Remote trace commands require the machine to have a shell service configured. ## Read metadata Read metadata attached to an organization, location, machine, or machine part. Specify at least one ID: ```sh viam metadata read --machine-id= ``` You can combine multiple IDs to read metadata at different levels: ```sh viam metadata read --org-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: ```sh viam machines api-key create --machine-id= ``` The CLI prints the key ID and key value. Save both immediately; the key value is only shown once. ```sh Successfully created key: Key ID: abcdef12-3456-7890-abcd-ef1234567890 Key Value: your-secret-key-value ```