Workload API > Workload interfaces > Workload CLI > Manage Workloads with the CLI

Manage Workloads with the CLI¶

Preview

The Workload API is a preview feature, on by default.

Feature flag: Enable Access to Workload API Experimental Features

The dr workload command group creates and operates Workloads from your terminal. Commands are structured as follows:

dr workload <command> [flags]

The group covers the full Workload runtime lifecycle:

Subcommand	Description
CRUD	`create`, `get`, `list`, `delete`
Lifecycle	`start`, `stop`, `status`
Invoke	`endpoint`
Observe	`logs`

Before you begin, enable the command group and authenticate. dr workload and dr artifact are hidden by default; a single environment variable enables both:

export DATAROBOT_CLI_FEATURE_WORKLOAD=true
dr auth login

The following is a typical end-to-end flow using these commands alongside dr artifact:

# Build and lock the artifact (see dr artifact)
dr artifact build create <artifact-id> --wait
dr artifact lock <artifact-id>

# Create the Workload
dr workload create --spec-file workload.yaml

# Check it's running
dr workload status <workload-id>

# Get the invoke URL
dr workload endpoint <workload-id>

# Tail logs
dr workload logs <workload-id> --follow

# Tear it down when done
dr workload delete <workload-id>

Subcommands¶

Subcommand	Description
`dr workload create`	Create a Workload from a YAML or JSON spec file.
`dr workload get`	Display details for a single Workload by ID.
`dr workload list`	List Workloads with optional filtering.
`dr workload delete`	Delete a Workload by ID.
`dr workload start`	Start a stopped Workload.
`dr workload stop`	Stop a running Workload without deleting it.
`dr workload status`	Display the current status of a Workload.
`dr workload endpoint`	Print the invoke URL for a Workload.
`dr workload logs`	Print or stream runtime logs for a Workload.

`dr workload create`¶

Create a Workload from a YAML or JSON spec file.

dr workload create --spec-file <path> [--output-format text|json]

Argument/Flag	Description
`--spec-file <path>`	Path to a YAML or JSON spec file. Required.
`--output-format <text\\|json>`	Output format. Defaults to `text`.

Spec file format¶

The spec file describes the Workload and provides either an artifact reference or an inline artifact spec. See Two ways to create a Workload for a description of both modes.

Create from an existing artifactCreate with an inline artifact spec

name: my-api-service
artifactId: 67890abcdef1234567890abc   # locked artifact
importance: low
runtime:
  containerGroups:
    - name: default
      replicaCount: 1
      containers:
        - name: main
          resourceAllocation:
            cpu: 1
            memory: "512Mi"

name: my-api-service
importance: low
artifact:
  name: my-api-service-artifact
  spec:
    containerGroups:
      - containers:
          - imageUri: ghcr.io/my-org/my-app:latest
            port: 8000
            primary: true
            readinessProbe:
              path: /readyz
              port: 8000
              initialDelaySeconds: 10
            livenessProbe:
              path: /healthz
              port: 8000
              initialDelaySeconds: 30
runtime:
  containerGroups:
    - name: default
      replicaCount: 1
      containers:
        - name: main
          resourceAllocation:
            cpu: 1
            memory: "512Mi"

Examples¶

Create with default human-readable outputCreate with machine-parseable JSON output

Command

dr workload create --spec-file workload.yaml

Output

ID:           67890abcdef1234567890wld
Name:         my-api-service
Status:       launching
Endpoint:     —
Type:         service
Importance:   low
Artifact ID:  67890abcdef1234567890abc
Created:      2026-05-14 10:00 UTC
Updated:      2026-05-14 10:00 UTC

Command

dr workload create --spec-file workload.yaml --output-format json

Output

{
  "id": "67890abcdef1234567890wld",
  "name": "my-api-service",
  "status": "launching",
  "importance": "low",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

`dr workload get`¶

Display details for a single Workload by ID.

dr workload get <workload-id> [--output-format text|json]

Argument/Flag	Description
`<workload-id>`	The Workload ID. Required.
`--output-format <text\\|json>`	Output format. Defaults to `text`.

Examples¶

Command

dr workload get 67890abcdef1234567890wld

Output

ID:           67890abcdef1234567890wld
Name:         my-api-service
Status:       running
Endpoint:     https://app.datarobot.com/api/v2/workloads/67890abcdef1234567890wld/
Type:         service
Importance:   low
Artifact ID:  67890abcdef1234567890abc
Created:      2026-05-14 10:00 UTC
Updated:      2026-05-14 10:05 UTC

`dr workload list`¶

List Workloads with optional filtering.

dr workload list [--limit <n>] [--status <status>] [--output-format text|json]

Argument/Flag	Description
`--limit <n>`	Maximum number of Workloads to return. Defaults to `100`.
`--status <status>`	Filter by lifecycle status. Accepts a single value or multiple values (repeatable flag or comma-separated, for example `--status running` or `--status running,errored`). Optional.
`--output-format <text\\|json>`	Output format. Defaults to `text`.

Examples¶

List all WorkloadsFilter by status with JSON output

Command

dr workload list

Renders as a bordered table:

Output

╭──────────────────────────┬────────────────┬─────────┬─────────┬────────────┬──────────────────────╮
│ WORKLOAD ID              │ NAME           │ STATUS  │ TYPE    │ IMPORTANCE │ UPDATED              │
├──────────────────────────┼────────────────┼─────────┼─────────┼────────────┼──────────────────────┤
│ 67890abcdef1234567890wld │ my-api-service │ running │ service │ low        │ 2026-05-14 10:05 UTC │
╰──────────────────────────┴────────────────┴─────────┴─────────┴────────────┴──────────────────────╯

When no Workloads match, the text output is No workloads found. and the JSON output is {"workloads": []}.

Command

dr workload list --status running --output-format json

Output

{
  "workloads": [
    {
      "id": "67890abcdef1234567890wld",
      "name": "my-api-service",
      "status": "running",
      "type": "service",
      "importance": "low",
      "artifactId": "67890abcdef1234567890abc",
      "endpoint": "https://app.datarobot.com/api/v2/workloads/67890abcdef1234567890wld/",
      "createdAt": "2026-05-14T10:00:00Z",
      "updatedAt": "2026-05-14T10:05:00Z"
    }
  ]
}

`dr workload delete`¶

Delete a Workload by ID. The Workload is stopped if it is running, and all associated protons are torn down. The backing artifact is not deleted.

dr workload delete <workload-id> [-y|--yes]

Argument/Flag	Description
`<workload-id>`	The Workload ID. Required.
`-y, --yes`	Skip the confirmation prompt.

`dr workload start`¶

Start a stopped Workload. Has no effect on a Workload that is already running or launching.

dr workload start <workload-id> [--output-format text|json]

Argument/Flag	Description
`<workload-id>`	The Workload ID. Required.
`--output-format <text\\|json>`	Output format. Defaults to `text`.

`dr workload stop`¶

Stop a running Workload without deleting it. Protons are scaled to zero; the Workload identity and endpoint URL are preserved. Use dr workload start to restart.

dr workload stop <workload-id> [--output-format text|json]

Argument/Flag	Description
`<workload-id>`	The Workload ID. Required.
`--output-format <text\\|json>`	Output format. Defaults to `text`.

`dr workload status`¶

Print the current lifecycle status of a Workload as a bare string. The value is directly usable in scripts. Use dr workload get for the full detail view.

dr workload status <workload-id> [--output-format text|json]

Argument/Flag	Description
`<workload-id>`	The Workload ID. Required.
`--output-format <text\\|json>`	Output format. Defaults to `text`.

For a description of all status values, see Lifecycle states.

Examples¶

Status of a running WorkloadStatus while launchingUse in a script

Command

dr workload status 67890abcdef1234567890wld

Output

running

Command

dr workload status 67890abcdef1234567890wld

Output

launching

Command

STATUS=$(dr workload status 67890abcdef1234567890wld)
echo "Workload is: $STATUS"

`dr workload endpoint`¶

Print the invoke URL for a Workload. Only available when the Workload is in running status.

dr workload endpoint <workload-id>

Argument/Flag	Description
`<workload-id>`	The Workload ID. Required.

Examples¶

Commands

# Print the endpoint
dr workload endpoint 67890abcdef1234567890wld

# Store the endpoint in a variable and invoke it
# Note: the URL ends with a trailing slash; append sub-paths without a leading slash
ENDPOINT=$(dr workload endpoint 67890abcdef1234567890wld)
curl -sS "${ENDPOINT}predict" \
  -H "Authorization: Bearer $DATAROBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "hello"}'

`dr workload logs`¶

Print or stream runtime logs for a Workload.

dr workload logs <workload-id> [--level <level>] [--limit <n>] [--follow] [--output-format text|json]

Argument/Flag	Description
`<workload-id>`	The Workload ID. Required.
`--level <level>`	Minimum log level to show: `debug`, `info`, `warn`, `warning`, `error`, `critical`. Optional; if omitted, all levels are returned.
`--limit <n>`	Maximum number of log lines to return. Defaults to `100`.
`--follow`	Stream logs continuously (like `tail -f`). Press `Ctrl`+`C` to stop.
`--output-format <text\\|json>`	Output format. Defaults to `text`.

Examples¶

Commands

# Print the last 100 log lines
dr workload logs 67890abcdef1234567890wld

# Filter to errors only
dr workload logs 67890abcdef1234567890wld --level error --limit 100

# Stream logs continuously
dr workload logs 67890abcdef1234567890wld --follow

# Capture logs as JSON for further processing
dr workload logs 67890abcdef1234567890wld --output-format json | jq '.[] | select(.level == "error")'

Error handling¶

Error	Cause and resolution
`not authenticated`	Run `dr auth login` first; every `dr workload` command requires authentication.
`workload <id> not found`	The Workload ID does not exist. Check the ID with `dr workload list`.
`invalid spec: required field 'name' is missing or empty`	The spec file's `name` is missing or empty. Add a non-empty string.
`invalid spec: exactly one of 'artifact' or 'artifactId' must be set`	Supply either an inline `artifact` block or an `artifactId`, not both and not neither.
`artifact <id> not found`	The `artifactId` does not exist. Check the ID with `dr artifact list`.
`artifact must be locked to create a persistent Workload`	The referenced artifact is still in `draft` status. Lock it with `dr artifact lock` first, or use an inline `artifact` block for a draft Workload with an 8-hour TTL.
`workload limit reached`	The organization has hit its concurrent Workload cap. Delete unused Workloads and try again; or contact your DataRobot administrator.
`workload <id> has no endpoint URL`	The Workload has no endpoint assigned. Check status with `dr workload status`; the endpoint is only available once the Workload is running.

Exit codes¶

Code	Meaning
`0`	Success.
`1`	Error (validation failed, API error, not authenticated, etc.).
`130`	Interrupted (`Ctrl`+`C`).

Manage Workloads with the CLI¶

Subcommands¶

dr workload create¶

Spec file format¶

Examples¶

dr workload get¶

Examples¶

dr workload list¶

Examples¶

dr workload delete¶

dr workload start¶

dr workload stop¶

dr workload status¶

Examples¶

dr workload endpoint¶

Examples¶

dr workload logs¶

Examples¶

Error handling¶

Exit codes¶

`dr workload create`¶

`dr workload get`¶

`dr workload list`¶

`dr workload delete`¶

`dr workload start`¶

`dr workload stop`¶

`dr workload status`¶

`dr workload endpoint`¶

`dr workload logs`¶