Manage Workloads with the CLI¶

The dr workload command group deploys and operates Workloads from your terminal. It is also available under the alias dr wl. Commands are structured as follows:

dr workload <command> [flags]

The group covers the full Workload lifecycle:

Before you begin, authenticate with dr auth login.

There are two ways to get a Workload running.

# Write .datarobot.yaml (a wizard on a terminal, flags otherwise)
dr workload config

# Plan, then deploy; later runs apply only the difference
dr workload up

# Every other command finds the Workload from .datarobot.yaml
dr workload status
dr workload logs --follow

# Lock the version that is running
dr workload promote

# Tear it down, with everything the deploy created
dr workload delete --purge

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

Working in a project directory¶

Inside a project folder, you can leave out <workload-id> from any command that takes one. The CLI finds the ID for you:

1. It looks for .datarobot.yaml in the current directory, or in the directory you pass with --dir.
2. If it doesn't find one, it checks each parent directory in turn.
3. It reads the Workload ID from the workloadId key in the first .datarobot.yaml it finds.

The command prints the Workload it picked to stderr, so you can confirm it's the right one:

cd my-app
dr workload status          # instead of dr workload status 67890abcdef1234567890wld
dr workload logs --follow

dr workload up adds workloadId to .datarobot.yaml automatically after the first deploy.

If you created the Workload another way, such as with dr workload create, you can add the ID yourself. Create a .datarobot.yaml file in the project's root folder that contains this one line, using the ID that dr workload create printed:

workloadId: 67890abcdef1234567890wld

If you pass a Workload ID in the command, the CLI uses that ID and ignores the one in .datarobot.yaml.

The CLI searches only the current directory and its parents, never subfolders or folders beside it. To use a project in another folder, pass its path with --dir.

Because stop, start, delete, and promote change something, they ask for confirmation when the ID comes from the manifest rather than the command line. Pass --yes to skip the prompt in a script; a typed ID is never prompted. stop and start also accept DATAROBOT_CLI_NON_INTERACTIVE=true in place of --yes. delete and promote do not when the ID comes from the manifest: that variable is usually set once across a whole pipeline, and deleting or locking something nobody named is not what it was set for.

Subcommands¶

dr workload config¶

Write the .datarobot.yaml that describes a project. On a terminal it is a short wizard: bind to an existing Workload or name a new one, confirm the image source and port read from the Dockerfile, pick the sizing, and carry the variables in .env into the file. Every question has a flag, so the same file is written without prompts in CI. The file is the Workload create spec plus a workloadId the CLI manages; see Workload manifest.

dr workload config [--dir <path>] [--name <name> | --workload-id <id>] [--build-mode dockerfile|generated|image] [--port <n>] [--health <path>] [--cpu <n>] [--memory <size>] [--replicas <n>] [--importance <level>] [--skip-env] [--spec-file <path>] [--sync-env] [--dry-run] [-y|--yes] [--output-format text|json]

config leaves an existing manifest alone; the only edit it makes to one is --sync-env.

Examples¶

The following commands write a manifest interactively, from flags, and from a spec you already have.

# On a terminal: the wizard
dr workload config

# In CI: a project with a Dockerfile needs nothing but a name
dr workload config --yes --name my-app

# A published image
dr workload config --yes --name my-app --build-mode image --image registry.example.com/app:v1

# From a Workload spec you already hold; asks only what it leaves open
dr workload config --spec-file workload.yaml --name my-app

# After editing .env: reconcile the manifest's variables
dr workload config --sync-env

dr workload up¶

Deploy the project. The command compares .datarobot.yaml and your project files with what's currently running, prints a plan of what it will change, and then makes those changes.

If nothing has changed, it prints Already up to date and exits with code 0.

dr workload up [--dir <path>] [--dry-run] [--detach] [--force-build] [--promote] [--sync-env] [--spec-file <path>] [--poll-timeout <duration>] [-y|--yes] [--output-format text|json]

What a run does depends on what changed. The following table summarizes the rules; see Workload manifest for more detail.

A rollout never changes the endpoint, and the generation already serving keeps serving until the new one is ready. Only fields the manifest mentions are managed: a setting the file never names survives every deploy, and a value changed in the UI that the file does name is put back on the next run, and the run says so.

If the project doesn't have a .datarobot.yaml file yet, dr workload up first runs the same setup as dr workload config. It creates .datarobot.yaml, tells you it did, and then deploys.

With --yes, the setup runs without prompts and fills in the settings from your project files. If the CLI can't work out a setting (for example, because there's no Dockerfile), the command stops and lists the dr workload config flags you can use to provide it.

Examples¶

The following commands deploy interactively, preview, deploy unattended, and recover a lost image.

# Plan, then deploy
dr workload up

# Plan and stop
dr workload up --dry-run

# In CI: deploy asking nothing, with a JSON result
dr workload up --yes --output-format json

# Deploy and lock the result
dr workload up --promote

# Rebuild the image the registry lost
dr workload up --force-build

my-app (67890abc), running

  + artifact   new version, 1 spec change; keeps the running image, so no rebuild
      env GREETING: changed
  ~ runtime    containerGroups[default].replicaCount: 1 -> 3
  ✓ Creating the new version (100ms)
  ✓ Rolling out the new version (300ms)
  ✓ Waiting for the rollout (11s)
  ✓ Waiting for the new version to serve (1m2s)
  ✓ Checking the endpoint (200ms)
  Endpoint check: an authenticated GET answered HTTP 200 OK.

dr workload promote¶

Make the version a Workload is running permanent. The draft artifact it is serving is locked in place and given a version number; the Workload keeps running it, and nothing is rebuilt or rolled. This is the CLI form of promoting a Workload to production.

dr workload promote [<workload-id>] [--dir <path>] [-y|--yes] [--output-format text|json]

Locking can't be undone. After you promote a Workload, the next dr workload up that changes something creates a new version instead of editing the locked one, and locks the new version too. A promoted Workload always deploys locked versions.

The command fails, and shows the reason from DataRobot, if the Workload:

• Is already running a locked version.
• Has no running version.
• Is in the middle of a rollout.

Only the artifact's owner can promote a Workload.

To deploy and promote in one step, run dr workload up --promote.

dr workload create¶

Create a Workload from a YAML or JSON spec file.

dr workload create --spec-file <path> [--use-case-id <id>] [--enclave <name>] [--output-format text|json]

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.

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¶

dr workload create --spec-file workload.yaml

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

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

{
  "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>] [--dir <path>] [--output-format text|json]

Examples¶

dr workload get 67890abcdef1234567890wld

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>] [--offset <n>] [--status <status>] [--enclave <name>] [--output-format text|json]

Examples¶

dr workload list

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

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

{
  "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 unless you pass --purge.

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

After deleting the Workload, the command updates the project it found with --dir (the current directory by default):

• Workload ID: If .datarobot.yaml points to the deleted Workload, the command removes the workloadId line. The next dr workload up from that project creates a new Workload.
• Environment variables: .datarobot.yaml keeps its environment variables. Any variable that referred to a credential deleted by --purge is reset to a placeholder. The next --sync-env run, with dr workload up or dr workload config, replaces the placeholder with a new credential.

Locked artifacts are kept. A locked artifact can't be deleted, so --purge leaves it in place and says so in its output. It also keeps the artifact's credentials, because anything that runs the artifact might still need them.

Examples¶

The following commands delete by ID, from a project, and with everything the deploy created.

# Delete by ID; the artifact stays
dr workload delete 67890abcdef1234567890wld

# From a project: the Workload named in .datarobot.yaml, after confirming
dr workload delete

# Everything the deploy created, asking nothing
dr workload delete --purge --yes

dr workload start¶

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

dr workload start [<workload-id>] [--dir <path>] [-y|--yes] [--output-format text|json]

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>] [--dir <path>] [-y|--yes] [--output-format text|json]

dr workload settings¶

Show or change how much a Workload runs with, including replicas, autoscaling, resource bundles, and the CPU and memory of each container.

These are the same settings that dr workload up applies from .datarobot.yaml. Use this command to check or resize a Workload that doesn't have a .datarobot.yaml file, such as one created with dr workload create.

For conceptual information, see Runtime settings.

dr workload settings [<workload-id>] [--dir <path>] [--output-format text|json]
dr workload settings [<workload-id>] --replicas <n> [--group <name>] [--wait] [-y|--yes]
dr workload settings [<workload-id>] --spec-file <path> [--wait] [-y|--yes]

When you change settings, DataRobot replaces the Workload's containers gradually. It starts new containers with the new settings, then shuts down the old ones. The endpoint keeps responding the whole time.

• One change at a time: If a previous change is still rolling out, the command fails. Wait for the rollout to finish, then try again.
• Stopped Workloads: Changing settings on a stopped Workload also starts it.
• Waiting for the change: By default, the command returns as soon as DataRobot accepts the change. Add --wait to wait until the rollout finishes. If you don't use --wait, run dr workload settings again to see whether the rollout is still in progress.

Examples¶

The following commands read the settings, scale, and apply an edited body.

# Current settings, one row per container
dr workload settings

# Scale to three replicas and wait for them
dr workload settings --replicas 3 --wait

# Save the settings, edit them, send them back
dr workload settings --output-format json > settings.json
dr workload settings --spec-file settings.json --wait

╭─────────┬──────────┬──────────────────────────────────┬────────────┬───────────┬─────┬────────────┬─────╮
│ GROUP   │ REPLICAS │ AUTOSCALING                      │ BUNDLE     │ CONTAINER │ CPU │ MEMORY     │ GPU │
├─────────┼──────────┼──────────────────────────────────┼────────────┼───────────┼─────┼────────────┼─────┤
│ default │ auto     │ 0-3 on httpRequestsConcurrency=2 │ cpu.xlarge │ primary   │ 1   │ 2147483648 │ -   │
╰─────────┴──────────┴──────────────────────────────────┴────────────┴───────────┴─────┴────────────┴─────╯

dr workload status¶

Print the current lifecycle status of a Workload as a bare string. The value is directly usable in scripts. An errored status is a valid answer, so the command still exits 0. Use dr workload get for the full detail view, and dr workload diagnose for why.

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

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

Examples¶

dr workload status 67890abcdef1234567890wld

running

dr workload status 67890abcdef1234567890wld

launching

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

dr workload diagnose¶

Explain why a Workload is in its current state. status says errored and stops there, and logs can be empty for a container that never started. This command reads the platform's per-replica status details for every container generation of the Workload and prints the overall verdict, then a table of each replica and container with its state, reason, restart count, readiness, and how its last run ended. Anything that stands out is listed as a finding: CrashLoopBackOff, ImagePullBackOff, ErrImagePull, OOMKilled, a non-zero exit code, restarts.

dr workload diagnose [<workload-id>] [--dir <path>] [--output-format text|json]

An errored Workload is the answer, not a command failure, so the command exits 0, like status.

Examples¶

dr workload diagnose

Workload 67890abcdef1234567890wld (my-api-service) is errored

Generation 67890abcdef1234567890gen · errored · active  artifact 67890abcdef1234567890abc
  Workload is in state errored based on pod states
  ╭─────────────────────────────┬───────────┬─────────┬──────────────────┬──────────┬───────┬────────────────────╮
  │ REPLICA                     │ CONTAINER │ STATE   │ REASON           │ RESTARTS │ READY │ LAST EXIT          │
  ├─────────────────────────────┼───────────┼─────────┼──────────────────┼──────────┼───────┼────────────────────┤
  │ 6945b6ddd7-6mhh8 (running)  │ primary   │ waiting │ CrashLoopBackOff │ 3        │ no    │ exit 0 (Completed) │
  ╰─────────────────────────────┴───────────┴─────────┴──────────────────┴──────────┴───────┴────────────────────╯
  Findings:
    ⚠ primary: CrashLoopBackOff; last run exited 0 (Completed)

dr workload endpoint¶

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

dr workload endpoint [<workload-id>] [--dir <path>]

Examples¶

# 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. By default it prints the most recent --limit lines oldest-first.

dr workload logs [<workload-id>] [--dir <path>] [--level <level>] [--limit <n>] [--grep <text>]... [--exclude <text>]... [--trace-id <id>] [--span-id <id>] [--since <time>] [--until <time>] [--follow] [--output-format text|json]

Examples¶

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

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

# Search the last hour, from inside a project
dr workload logs --grep "connection refused" --since 1h

# Stream errors, dropping health-check noise
dr workload logs --level error --exclude healthz --follow

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

dr workload events¶

Shows the events DataRobot recorded for a Workload, including what changed, when, and who made the change. Events include:

• Settings changes that rolled out.
• Rollouts that failed, and why.
• Starts and stops.

Use dr workload events to see what DataRobot did to the Workload. Use dr workload logs to see what the container itself wrote.

The command prints the 100 most recent events, oldest first. To change how many it prints, use --limit.

dr workload events [<workload-id>] [--dir <path>] [--limit <n>] [--type <text>]... [--since <time>] [--until <time>] [--proton-id <id>] [--output-format text|json]

Examples¶

# The recent trail, from inside a project
dr workload events

# Both outcomes of a rollout
dr workload events --type errored --type completed

# Everything from yesterday, with details
dr workload events --since 1d --output-format json

Error handling¶

Exit codes¶