# Manage Workloads with the CLI

> Manage Workloads with the CLI - dr workload commands for creating, operating, and observing
> Workloads from your terminal.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-07-09T05:46:40.355776+00:00` (UTC).

## Primary page

- [Manage Workloads with the CLI](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [Subcommands](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#subcommands): In-page section heading.
- [dr workload create](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-create): In-page section heading.
- [Spec file format](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#workload-spec-file-format): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#workload-create-examples): In-page section heading.
- [dr workload get](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-get): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#workload-get-examples): In-page section heading.
- [dr workload list](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-list): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#workload-list-examples): In-page section heading.
- [dr workload delete](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-delete): In-page section heading.
- [dr workload start](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-start): In-page section heading.
- [dr workload stop](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-stop): In-page section heading.
- [dr workload status](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-status): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#workload-status-examples): In-page section heading.
- [dr workload endpoint](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-endpoint): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#workload-endpoint-examples): In-page section heading.
- [dr workload logs](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#dr-workload-logs): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#workload-logs-examples): In-page section heading.
- [Error handling](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#error-handling): In-page section heading.
- [Exit codes](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/workload-cli.html.md#exit-codes): In-page section heading.

## Related documentation

- [Workload API](https://docs.datarobot.com/en/docs/workload-api/index.html.md): Linked from this page.
- [Workload interfaces](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/index.html.md): Linked from this page.
- [Workload CLI](https://docs.datarobot.com/en/docs/workload-api/workload-interfaces/workload-cli/index.html.md): Linked from this page.
- [Two ways to create a Workload](https://docs.datarobot.com/en/docs/workload-api/get-started-workloads/index.html.md#two-ways-to-create-a-workload): Linked from this page.
- [Lifecycle states](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#lifecycle-states): Linked from this page.

## Documentation content

> [!NOTE] 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](https://docs.datarobot.com/en/docs/workload-api/get-started-workloads/index.html.md#two-ways-to-create-a-workload) for a description of both modes.

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

**Create with an inline artifact spec:**
```
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 output:**
```
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
```

**Create with machine-parseable JSON output:**
```
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> [--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 Workloads:**
```
dr workload list
```

Renders as a bordered table:

```
╭──────────────────────────┬────────────────┬─────────┬─────────┬────────────┬──────────────────────╮
│ 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": []}`.

**Filter by status with JSON output:**
```
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.

```
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](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#lifecycle-states).

#### Examples

**Status of a running Workload:**
```
dr workload status 67890abcdef1234567890wld
```

```
running
```

**Status while launching:**
```
dr workload status 67890abcdef1234567890wld
```

```
launching
```

**Use in a script:**
```
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). |