Cortex References

Global Options

These flags work across most commands and can be placed before or after subcommands.

Prop

Type

voltra --help
voltra -v
voltra --json status
voltra --local-time --json workout list --start 2026-06-01 --end 2026-06-23
voltra --command-timeout-ms 60000 connect <DEVICE_ID>

Quick Start

voltra doctor                              # 1. Diagnose environment
voltra config set-api-key <API_KEY>        # 2. Configure API key (required for device/training commands)
voltra whoami                             #    Verify identity
voltra scan                               # 3. Scan for devices
voltra connect <DEVICE_ID>                # 4. Connect (starts background session)
voltra status                             # 5. Check device status
voltra set-mode weight-training           # 6. Set mode + parameters
voltra set-weight 20 --unit lbs
voltra config accept-physical-risk        #    Accept physical risk (required once before load)
voltra load                               # 7. Load resistance
voltra unload                             # 8. Unload
voltra finish-training                    #    End training session
voltra disconnect                         #    Disconnect

API key required: All device/training commands that go through the background session (scan, connect, set-mode, load, etc.) require a persisted API key (voltra config set-api-key). Without a key, these commands exit with an error. Cloud commands (workout, actions, session, custom-curve, etc.) also support the --api-key flag for temporary override.

API Errors for Agents

Cloud API commands return a non-zero exit code when the backend reports an error. Add --json to receive a structured error on stdout instead of a human-only message on stderr:

{
  "error": {
    "status": 200,
    "code": 10154,
    "key": "SESSION_TITLE_ALREADY_EXISTED",
    "message": "Session title already existed",
    "meaning": "A Session with this title already exists for the account.",
    "recommendedAction": "Choose a different Session title or update the existing Session.",
    "retryable": false,
    "method": "POST",
    "endpoint": "/agent/workout/me/custom-session/v2"
  }
}

Agents should use key, meaning, and recommendedAction to decide what to do. backendMessage and raw preserve the backend response for diagnostics. Validation failures may also include path, rule, and detail. Unknown backend codes are returned without being replaced by a generic success or retry instruction.

10207 is one shared SERVER_BUSY code. It can be caused by the global Sentinel QPS limit, the AI user rate limit, or Session update lock contention. The wire response is identical, so the endpoint only provides request context and cannot identify the actual cause. Treat it as retryable and use backoff.

Authentication failures use HTTP 401 with wire code: 401; the semantic key is determined from msg. Backend enum values 40800, 40801, and 40803 are not sent as the wire code:

Message	Semantic key	Default action
`AI access token is missing`	`AI_TOKEN_MISSING`	Supply an AI access token.
`AI access token is invalid or expired`	`AI_TOKEN_INVALID`	Refresh or reissue the token.
`AI access token scope does not match Source header`	`AI_TOKEN_SCOPE_MISMATCH`	Use a token with the required Source scope.

Common Agent workout codes include:

Code	Meaning	Default action
`10152`	Custom action limit (200) reached	Reuse an action or remove one with user confirmation.
`10153`	Custom action name already exists	Choose another name or update the existing action.
`10154`	Session title already exists	Choose another title or update the existing Session.
`10166`	Custom curve name already exists	Choose another name or update the existing curve.
`10172`	Session missing or inaccessible	Verify the Session ID and account.
`10201`	AI token maps to no user	Check account mapping or issue a new token.
`10206`	Request validation failed	Correct the request using `path`, `rule`, and `detail`.
`10207`	Global QPS limit, user rate limit, or Session update lock	Wait and retry with backoff when `retryable` is `true`.
`10801`	Workout record missing or inaccessible	Verify the workout ID and account.
`40300`	Operation forbidden	Check ownership and permissions.
`401`	AI token missing, invalid, expired, or scope mismatch	Inspect `msg`, then supply or refresh the AI access token.

Cortex References

Global Options

Quick Start

API Errors for Agents

On this page