Automate with scripts

Combine CLI commands into shell scripts, CI/CD pipelines, and provisioning workflows to automate common Viam operations.

Authenticate in scripts

Interactive viam login opens a browser, which does not work in headless environments. Use API key authentication instead:

viam login api-key --key-id=$VIAM_API_KEY_ID --key=$VIAM_API_KEY

Store credentials in environment variables or your CI/CD system’s secret manager, not in the script itself. To create an API key, see Manage API keys.

Use profiles for non-interactive auth

If a script needs to operate across multiple organizations, set up profiles in advance:

viam profiles add --profile-name=production --key-id=$PROD_KEY_ID --key=$PROD_KEY
viam profiles add --profile-name=staging --key-id=$STAGING_KEY_ID --key=$STAGING_KEY

Then use --profile on each command, or set VIAM_CLI_PROFILE_NAME to activate a profile for the entire script:

export VIAM_CLI_PROFILE_NAME=production
viam machines list --all

CI/CD: upload a module on release

A GitHub Actions workflow that builds and uploads a module when you push a version tag:

# .github/workflows/upload-module.yml
name: Upload module
on:
  push:
    tags:
      - "v*"

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Viam CLI
        run: |
          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

      - name: Authenticate
        run: viam login api-key --key-id=${{ secrets.VIAM_KEY_ID }} --key=${{ secrets.VIAM_KEY }}

      - name: Build
        run: viam module build local

      - name: Upload
        run: |
          VERSION=${GITHUB_REF_NAME#v}
          viam module upload --version=$VERSION --platform=linux/amd64 dist/archive.tar.gz

CI/CD: retrain a model on new data

A script that creates a fresh dataset from recent data and submits a training job.

Set these environment variables before running:

  • VIAM_KEY_ID and VIAM_KEY: your API key credentials (see Manage API keys)
  • ORG_ID: your organization ID (run viam organizations list)
#!/bin/bash
set -euo pipefail

viam login api-key --key-id=$VIAM_KEY_ID --key=$VIAM_KEY

# Create a dataset from the last 7 days of labeled images.
# The create command prints: "Created dataset <name> with dataset ID: <uuid>"
DATASET_ID=$(viam dataset create --org-id=$ORG_ID --name="weekly-$(date +%F)" \
  | grep -oE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}')

# date -v is macOS; date -d is Linux. Adjust for your platform.
START=$(date -u -v-7d +%FT%TZ 2>/dev/null || date -u -d '7 days ago' +%FT%TZ)
END=$(date -u +%FT%TZ)

viam dataset data add filter \
  --dataset-id=$DATASET_ID \
  --org-ids=$ORG_ID \
  --tags=labeled \
  --start=$START \
  --end=$END

# Submit a managed training job
viam train submit managed \
  --dataset-id=$DATASET_ID \
  --model-org-id=$ORG_ID \
  --model-name=defect-detector-$(date +%F) \
  --model-type=object_detection \
  --model-framework=tflite \
  --model-labels=defective,good

Schedule this as a cron job or a weekly CI/CD trigger.

Batch fleet operations

List all machines

Set ORG_ID to your organization ID (run viam organizations list).

#!/bin/bash
set -euo pipefail

viam login api-key --key-id=$VIAM_KEY_ID --key=$VIAM_KEY

# List all machines across all locations
viam machines list --organization=$ORG_ID --all

Provisioning: create and configure a machine

Script that creates a machine and applies a standard configuration fragment.

Set these environment variables before running:

  • VIAM_KEY_ID and VIAM_KEY: your API key credentials
  • ORG_ID: your organization ID
  • LOCATION_ID: your location ID (run viam locations list)

The script takes two arguments: the machine name and the fragment ID.

#!/bin/bash
set -euo pipefail

MACHINE_NAME=$1
FRAGMENT_ID=$2

viam login api-key --key-id=$VIAM_KEY_ID --key=$VIAM_KEY

# Create the machine.
# Output format: "created new machine with id <uuid>"
CREATE_OUTPUT=$(viam machines create --name=$MACHINE_NAME --location=$LOCATION_ID)
MACHINE_ID=$(echo "$CREATE_OUTPUT" | grep -oE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}')

# Get the part ID from the part list.
# Output includes lines like "  ID: <uuid>"
PART_ID=$(viam machines part list --machine=$MACHINE_ID | grep 'ID:' | head -1 | awk '{print $2}')

# Apply the configuration fragment
viam machines part fragments add --part=$PART_ID --fragment=$FRAGMENT_ID

echo "Machine $MACHINE_NAME ($MACHINE_ID) created with fragment $FRAGMENT_ID applied."

Bulk data export

Export all images from a fleet for offline analysis. Set ORG_ID to your organization ID.

#!/bin/bash
set -euo pipefail

viam login api-key --key-id=$VIAM_KEY_ID --key=$VIAM_KEY

# date -v is macOS; date -d is Linux. Adjust for your platform.
START=$(date -u -v-30d +%FT%TZ 2>/dev/null || date -u -d '30 days ago' +%FT%TZ)
END=$(date -u +%FT%TZ)

viam data export binary filter \
  --destination=./fleet-data \
  --org-ids=$ORG_ID \
  --mime-types=image/jpeg,image/png \
  --start=$START \
  --end=$END \
  --parallel=20

The --parallel flag controls how many concurrent downloads run (default: 100). Increase it for faster exports on high-bandwidth connections, or decrease it to reduce load.

Tips for scripting

  • Use --quiet (-q) to suppress non-essential output when parsing command results
  • Use --debug (-vvv) when troubleshooting a script
  • Set defaults with viam defaults set-org to avoid passing --org-id on every command
  • All timestamps use ISO-8601 format: 2026-01-15T00:00:00Z
  • Exit codes are non-zero on failure, so set -e works as expected

Related pages

Previous

Administer your organization

Next

CLI reference