Manage artifacts with the CLI¶

The dr artifact command group manages Workload artifacts, server-side image builds, and the local code that backs them, from your terminal. Commands are structured as follows:

dr artifact <command> [flags]

The group is split into three sub-command groups:

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

export DATAROBOT_CLI_FEATURE_WORKLOAD=true
dr auth login

The following is a typical code-to-Workload flow using these commands:

# Create the artifact on the server
dr artifact create --spec-file spec.json

# Link a local directory to it (use the printed ID)
dr artifact code init <artifact-id>

# Upload code and let sync fill in the codeRef
dr artifact code sync

# Build the container image server-side and wait for completion
dr artifact build create <artifact-id> --wait

# Lock the artifact for production
dr artifact lock <artifact-id>

For more information, see the detailed subcommand documentation in Subcommands.

Subcommands¶

dr artifact create¶

Create a Workload artifact from a JSON or YAML spec file.

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

Spec file format¶

The spec file defines the Workload artifact. JSON and YAML formats are both supported. To get started, see the examples below.

{
  "name": "my-agent",
  "spec": {
    "containerGroups": [{
      "containers": [{
        "imageUri": "nginx:latest",
        "port": 8080,
        "primary": true
      }]
    }]
  }
}

{
  "name": "my-agent",
  "spec": {
    "containerGroups": [{
      "containers": [{
        "primary": true,
        "port": 8080,
        "imageBuildConfig": { "dockerfile": { "source": "provided" } }
      }]
    }]
  }
}

{
  "name": "my-agent",
  "description": "Optional description shown in the DataRobot UI.",
  "spec": {
    "containerGroups": [{
      "containers": [{
        "primary": true,
        "port": 8080,
        "imageBuildConfig": {
          "dockerfile": { "source": "provided" },
          "codeRef": {
            "datarobot": {
              "catalogId": "67890abcdef1234567890abc",
              "catalogVersionId": "67890abcdef1234567890def"
            }
          }
        }
      }]
    }]
  }
}

Spec file validation¶

The following validation rules apply:

• Client-side: name must be non-empty; spec.containerGroups must contain at least one entry; each group's containers array must contain at least one entry.
• Server-side: the Workload API validates field-level shape and returns 422 with a JSON-path detail on a mismatch.
• Unknown fields are passed through to the server, so any field the server accepts is accepted here. The spec file is not parsed strictly.

Container lifecycles¶

The following container lifecycles are supported:

1. Prebuilt image—set imageUri (plus port and primary) on the entry container.
2. Build from a provided Dockerfile—set imageBuildConfig.dockerfile.source = "provided" to build from ./Dockerfile in your synced code.
3. Build from a generated Dockerfile—set imageBuildConfig.dockerfile.source = "generated" together with executionEnvironmentId, executionEnvironmentVersionId, and entrypoint to have the server generate a Dockerfile from a base image.

Examples¶

dr artifact create --spec-file spec.json

ID:          67890abcdef1234567890abc
Name:        my-agent
Status:      draft
Catalog ID:  —
Version ID:  —
Created:     2026-05-14 10:00 UTC
Updated:     2026-05-14 10:00 UTC

dr artifact create --spec-file spec.json --output-format json

{
  "id": "67890abcdef1234567890abc",
  "name": "my-agent",
  "status": "draft",
  "catalogId": "",
  "versionId": "",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

dr artifact list¶

List Workload artifacts with optional filtering.

dr artifact list [--limit <n>] [--status draft|locked] [--output-format text|json]

Examples¶

dr artifact list

╭──────────────────────────┬───────────┬────────┬──────────────────────────┬──────────────────────────┬──────────────────────╮
│ ARTIFACT ID              │ NAME      │ STATUS │ CATALOG ID               │ VERSION ID               │ UPDATED              │
├──────────────────────────┼───────────┼────────┼──────────────────────────┼──────────────────────────┼──────────────────────┤
│ 67890abcdef1234567890abc │ my-agent  │ draft  │ —                        │ —                        │ 2026-05-14 10:00 UTC │
│ 67890abcdef1234567890aaa │ chat-app  │ locked │ 67890abcdef1234567890cat │ 67890abcdef1234567890ver │ 2026-05-13 14:32 UTC │
╰──────────────────────────┴───────────┴────────┴──────────────────────────┴──────────────────────────┴──────────────────────╯

dr artifact list --status draft --output-format json

{
  "artifacts": [
    {
      "id": "67890abcdef1234567890abc",
      "name": "my-agent",
      "status": "draft",
      "catalogId": "",
      "versionId": "",
      "createdAt": "2026-05-14T10:00:00Z",
      "updatedAt": "2026-05-14T10:00:00Z"
    }
  ]
}

dr artifact get¶

Display details for a single Workload artifact by ID.

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

Examples¶

dr artifact get 67890abcdef1234567890abc

ID:          67890abcdef1234567890abc
Name:        my-agent
Status:      draft
Catalog ID:  —
Version ID:  —
Created:     2026-05-14 10:00 UTC
Updated:     2026-05-14 10:00 UTC

dr artifact get 67890abcdef1234567890abc --output-format json

{
  "id": "67890abcdef1234567890abc",
  "name": "my-agent",
  "status": "draft",
  "catalogId": "",
  "versionId": "",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

dr artifact delete¶

Delete a Workload artifact by ID. Two server-side rules apply: locked artifacts can never be deleted, and draft artifacts that are still referenced by a Workload cannot be deleted until the Workload is removed first.

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

dr artifact lock¶

Lock a draft artifact, making it immutable and eligible for production Workloads. Locking is irreversible—to iterate further, clone the artifact or create a new one.

dr artifact lock <artifact-id> [--output-format text|json]

dr artifact build create¶

Trigger a server-side image build for an artifact. The platform builds the container image from the artifact's current codeRef, pushes it to DataRobot's internal registry, and populates imageUri on the artifact. Only draft artifacts can be built.

dr artifact build create [<artifact-id>] [--wait] [--output-format text|json]

Prerequisites¶

• The artifact must be in draft status.
• The artifact must have a codeRef pointing to at least one synced catalog version. Run dr artifact code sync first if the artifact has no code.

Examples¶

# Trigger a build from a linked directory (no artifact-id needed)
dr artifact build create

# Trigger a build by artifact ID and return immediately
dr artifact build create 67890abcdef1234567890abc

# Trigger a build and wait for it to finish
dr artifact build create 67890abcdef1234567890abc --wait

dr artifact build get¶

Display details for a single build by ID.

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

dr artifact build list¶

List builds for an artifact, newest first.

dr artifact build list <artifact-id> [--limit <n>] [--output-format text|json]

dr artifact build logs¶

Print the build log for a specific build. When invoked with one positional argument, the artifact ID is read from .wapi/config.json in the current directory. When invoked with two, the first argument is the artifact ID.

dr artifact build logs [<artifact-id>] <build-id> [--level <level>] [--output-format text|json]

dr artifact code init¶

Link a project directory to an existing Workload artifact. Creates a .wapi/ state directory at the project root that records which artifact, catalog, and version the directory is bound to. Required before any other code command.

dr artifact code init [<artifact-id>] [--dir <path>] [-y|--yes] [--output-format text|json]

Prerequisites¶

• The artifact must already exist. Create it via dr artifact create or in the DataRobot UI.
• The artifact must be in draft status. Locked artifacts are immutable.

Examples¶

# Interactive: prompts for the directory
dr artifact code init 67890abcdef1234567890abc

# Non-interactive: link the current directory
dr artifact code init 67890abcdef1234567890abc --yes

# Link a sibling directory
dr artifact code init 67890abcdef1234567890abc --dir ./service

dr artifact code sync¶

Push local edits and pull remote changes between this directory and the linked artifact. Computes a three-way diff against the last known state, auto-resolves conflicts (remote wins; the local version is saved as a *.LOCAL.<timestamp> copy), and applies the resulting plan in a single versioned step.

dr artifact code sync [--dir <path>] [--dry-run | --diff] [-y|--yes] [--output-format text|json]

Prerequisites¶

The directory must already be linked via dr artifact code init. Otherwise the command returns not linked: run 'dr artifact code init <artifact-id>' first.

Conflict handling¶

When the same file has diverged on both sides, sync auto-resolves by taking the remote version and writing the local copy alongside as <path>.LOCAL.<timestamp>. In interactive mode the command pauses on conflicts so you can review the plan and abort; pass --yes to skip the prompt and apply unconditionally.

JSON mode¶

In JSON mode the plan is always emitted as the first document. If neither --dry-run nor --diff is set and the plan does not require explicit confirmation, the executed result is emitted as a second JSON document.

Examples¶

# Preview what would change
dr artifact code sync --dry-run

# Preview with per-file diffs
dr artifact code sync --diff

# Push and pull; prompt on conflicts
dr artifact code sync

# Push and pull non-interactively
dr artifact code sync --yes

dr artifact code versions¶

List the catalog version history for the artifact this project directory is linked to.

dr artifact code versions [--dir <path>] [--limit <n>] [--output-format text|json]

Output¶

The output marks the version that the artifact's codeRef currently points to with * and reports which version the local .wapi/ state was last synced to. This makes drift visible at a glance: a * next to a version other than the last-synced one means a sync would update local files.

Prerequisites¶

• The directory must be linked via dr artifact code init. Otherwise: not linked to an artifact. Run 'dr artifact code init <id>' first.
• At least one sync must have happened so the linked catalog has a version. Otherwise: no code has been synced yet. Run 'dr artifact code sync' first.

Examples¶

dr artifact code versions
dr artifact code versions --limit 10
dr artifact code versions --output-format json

dr artifact code checkout¶

Download a specific catalog version into .wapi/.checkouts/<version-id>/ for read-only inspection. The working directory and .wapi/ sync state are never modified.

dr artifact code checkout [<version-id>] [--dir <path>] [--clean] [-y|--yes] [--output-format text|json]

Examples¶

# Prompt for a version, then download
dr artifact code checkout

# Download a specific version (full ID or any unique prefix)
dr artifact code checkout abcdef12

# Download into a different project directory
dr artifact code checkout abcdef12 --dir ./service

# Remove all checkouts
dr artifact code checkout --clean

# Remove a single checkout
dr artifact code checkout abcdef12 --clean

Error handling¶

Exit codes¶