VOLTRA Getting Started

This skill covers the happy path from zero to first successful training session. For installation failures, use voltra-cli-troubleshooting. For device control after initial setup, use voltra-device-training. For completed workout data, use voltra-workout-data. For live telemetry analysis, use voltra-live-stream.

Step 1: Verify Installation

Check that voltra is available and working:

where.exe voltra
voltra --version
voltra -v

If the command is not found, load voltra-cli-troubleshooting.

Step 2: Configure API Key (Required for Workout Data)

To fetch training history and analytics, set your VOLTRA API Key. You can obtain one from the Beyond+ mobile app (Cortex beta section), not a web dashboard.

Option A — Environment variable (recommended for CI/scripts):

$env:VOLTRA_API_KEY="bp_ai_xxx"

export VOLTRA_API_KEY="bp_ai_xxx"

Option B — Local config (persists across sessions):

voltra config set-api-key "<VOLTRA API Key>"

Verify the key works:

voltra workout auth-check --json

Expected output:

{ "valid": true }

If authentication fails, check that the key was copied correctly and has not expired. Cortex can only store and use keys; key creation, revocation, and expiration management are handled in the Beyond+ mobile app (Cortex beta section), not on a web dashboard.

Skip this step if the user only needs BLE device control without workout data.

Step 2.5: Accept Physical Risk (Required for Device Control)

The voltra load command engages the VOLTRA motor and applies physical force. You must explicitly accept the physical risk once before using any load command:

voltra config accept-physical-risk --json

Or set the environment variable for scripting / CI:

$env:VOLTRA_ACCEPT_PHYSICAL_RISK="true"

export VOLTRA_ACCEPT_PHYSICAL_RISK=true

Expected output:

{ "accepted": true, "source": "config" }

This is a one-time acceptance stored locally. Skip this step if the user only needs read-only commands (status, scan, list-known, workout data).

Step 3: Scan for Devices

Ensure Bluetooth is enabled and the VOLTRA device is powered on and nearby:

voltra scan --json

This returns a list of nearby VOLTRA devices with their IDs and names. If scanning fails, check:

• Bluetooth is enabled on your computer
• The VOLTRA device is powered on and in range
• On Linux, you may need additional permissions; run voltra doctor or voltra ble doctor for guidance

Step 4: Connect to a Device

Choose a device from the scan results:

voltra connect <device-id-or-name> --json

Verify the connection:

voltra status --json

You should see the connected device name/id and live device parameters. Use voltra disconnect --json to end the session.

Step 5: Inspect Device State

Before training, check the device is ready:

voltra refresh <scope> --json   # e.g. all, epStatus
voltra status --json
voltra check-cable-zero --json

For detailed state interpretation, load voltra-device-status.

Step 6: Start Training

Enter a training mode and set up the device. For example, a simple weight training session:

voltra set-mode <mode> --json    # e.g. weightTraining
voltra set-weight <lbs> --json
voltra load --json
voltra status --json

For all training modes and controls, load voltra-device-training.

Step 7: End the Session

When done:

voltra unload --json
voltra finish-training --json
voltra disconnect --json

Managing Skills

AI skills can be installed, updated, and removed:

voltra skills list --json
voltra skills add --json                          # install from default CDN
voltra skills add <url> --name <skill> --json     # install specific skill from custom source
voltra skills add --target pi --target claude --json  # target specific agents
voltra skills update --check --json               # check for updates
voltra skills update --json                       # update all installed skills
voltra skills remove <name> -y --json             # remove a skill

For the full skills management reference, see voltra-device-training/references/command-reference.md.

What's Next

• Device issues? → voltra-cli-troubleshooting
• All training modes? → voltra-device-training
• Check device state? → voltra-device-status
• View workout history? → voltra-workout-data
• Analyze live training telemetry? → voltra-live-stream

Guardrails

• Do not issue training commands unless the user explicitly asked.
• Do not store or display the full VOLTRA API Key in logs or responses.
• If the device blocks a command (dock, cable-zero, mode), report the reason and stop.
• Do not infer device state from local cached files (.voltra storage). Always use live Cortex output.