Export data

You can download machine data from cloud storage 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:

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 -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 -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

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:

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 in the Viam app.

Use the filters on the left side of the page to filter only 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:

viam data export --org-ids=<org-id> --data-type=<binary|tabular> --mime-types=<mime types> --destination=.

This command uses the Viam CLI to download the data onto your computer based on the search criteria you select in the Viam app.

By default, the command creates two new directories named data and metadata in the current directory and downloads the specified data into the data folder and metadata, like bounding box information and labels, in JSON format into the metadata folder. If you want to store the data in a different location, change the specified folder with the --destination flag.

Once the command has finished running and downloading the data, you can view and use the data locally.

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


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

Next steps

Other how-to guides for using and querying data include:

Train and deploy computer vision models
Train and deploy computer vision models

Use your image data to train a model, so your machines can make inferences about their environments.

Visualize and analyze sensor data
Visualize and analyze sensor data

Visualize sensor data from the Viam app using popular tools like Grafana.

Query sensor data with third-party tools
Query sensor data with third-party tools

Query sensor data that you have synced to the Viam app using the Viam app with SQL or MQL.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.