Export data

You can download machine data to your computer with the Viam CLI.

If you prefer to manage your data with code, see the data client API documentation.

Prerequisites

Install the Viam CLI and authenticate

Install the Viam CLI using the option below that matches your system architecture:

• macOS
• Linux aarch64
• Linux x86_64
• Windows
• Source

To download the Viam CLI on a macOS computer, install brew and run the following commands:

brew tap viamrobotics/brews
brew install viam

To download the Viam CLI on a Linux computer with the aarch64 architecture, run the following commands:

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:

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 on Linux amd64 (Intel x86_64):

brew tap viamrobotics/brews
brew install viam

Download the binary and run it directly to use the Viam CLI on a Windows computer.

If you have Go installed, you can build the Viam CLI directly from source using the go install command:

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:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

For more information see install the Viam CLI.

Then authenticate your CLI session with Viam using one of the following options:

• Personal access token
• API key

viam login

This will open a new browser window with a prompt to start the authentication process. If a browser window does not open, the CLI will present a URL for you to manually open in your browser. Follow the instructions to complete the authentication process.

Use your organization, location, or machine part API key and corresponding API key ID in the following command:

viam login api-key --key-id <api-key-id> --key <organization-api-key-secret>

Export data with the Viam CLI

To export your data from the cloud using the Viam CLI:

1. Filter the data you want to download
   Navigate to the DATA page.
   Use the filters on the left side of the page to filter the data you wish to export.

2. Copy the export command from the DATA page
   In the upper right corner of the DATA page, click the Export button.
   Click Copy export command.
   This copies the command, including your org ID and the filters you selected, to your clipboard.

3. Run the command
   Run the copied command in a terminal:

• Binary data
  • Tabular data

viam data export binary filter --org-ids=<org-id> --destination=.

By default, the command creates two new directories named data and metadata in the destination directory.
It downloads binary files into the data folder and metadata (bounding box information, labels) in JSON format into the metadata folder.

Since data is downloaded in parallel, the order is not guaranteed to be chronological. Sort your files by filename to see them in chronological order.

viam data export tabular --destination=. --part-id=<part-id> --resource-name=<resource-name> --resource-subtype=<resource-subtype> --method=<method>

The tabular export command writes a single data.ndjson file in NDJSON (newline-delimited JSON) format to the destination directory.

If you want to store the data in a different location, change the destination with the --destination flag.

You can see more information about exporting data in the Viam CLI documentation.