> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-dpm-import.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# dpm (Daml Package Manager)

> Command reference and configuration for dpm, the primary CLI tool for Canton development.

`dpm` is the command-line interface for Canton development. It manages SDK installation, project scaffolding, compilation, testing, code generation, and local development environments. Most Canton development workflows start with a `dpm` command.

## Pre-requisites

Dpm runs on Windows, macOS and Linux.  For full functionality, you must have installed:

1. [VS Code download](https://code.visualstudio.com/download)
2. JDK 17 or greater, installed and part of your `JAVA_HOME`.  If you do not already have a JDK installed, try OpenJDK or [Eclipse Adoptium](https://adoptium.net/).
3. If you are on a Mac with Apple Silicon, you may need to install Rosetta 2 to run x86 binaries.  You can do this by running the following command in a terminal:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
softwareupdate --install-rosetta
```

## Installation

Installing `dpm` usually involves downloading a single binary and adding it to your `PATH`.

When installing `dpm` (any edition, on any platform), you can set the `DPM_HOME` environment variable to change the location where the SDK and any future updates are installed. The default is:

* `${HOME}/.dpm/` on Mac and Linux
* `%APPDATA%/.dpm/` on Windows

You should then add `${HOME}/.dpm/bin` to your `PATH`:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
export PATH="${HOME}/.dpm/bin:${PATH}"
```

or, if you used a custom install location:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
export PATH="${DPM_HOME}/bin:${PATH}"
```

To install the latest version:

### Mac/Linux Installation

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://get.digitalasset.com/install/install.sh | sh
```

### Windows Installation

Download and run the [windows installer](https://get.digitalasset.com/install/latest-windows.html), which will install the dpm sdk and set up the PATH variable for you.

### Manual Installation

If you prefer a more manual installation process, see [Manual Installation Instructions](#manual-installation-instructions).

### Installing dpm without an SDK

You can obtain the bare `dpm` binary — which does not have any SDK bundled with it — in two ways.

Download it from the [releases page](https://github.com/digital-asset/dpm/releases).

Or pull it directly from the public OCI repository using `oras` (or a similar tool):

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
## use the oras CLI to pull the correct platform image:
oras pull --platform darwin/arm64 europe-docker.pkg.dev/da-images/public/components/dpm:latest

## make the binary executable:
chmod +x dpm
```

The example above pulls the macOS Apple-silicon image. Substitute the `--platform` value for your machine: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, or `windows/amd64`.

Once you have the bare binary, you can run `dpm install` as described in [Project Management](#project-management): with no arguments it is an alias for `dpm install package`, installing the current project's dependencies; with a version argument (`dpm install <version>`) it installs that SDK version. Because the bare binary is not bundled with an SDK, you must set the registry manually — see [Registry and Edition](#registry-and-edition).

### Upgrading the SDK

You can upgrade to the latest version of an SDK by running:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm install latest
```

This installs the latest SDK of the same edition you already have installed. You will not be required to provide credentials again, since you should already be configured from installing the SDK the first time.

You can also install a specific version of the SDK in a similar way:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm install <version>
```

Note that outside of a Daml project, the active SDK is the latest version that is installed.

### Verifying the Installation

Once installed, verify the installation:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm --version
```

## Configuration Files

### daml.yaml

Every Daml project has a `daml.yaml` file at its root. If a `daml.yaml` file doesn't exist in your project, you can create one with:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm init
```

It specifies the SDK version, project metadata, source directory, and dependencies.

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
sdk-version: 3.4.0
name: my-project
source: daml
version: 1.0.0
dependencies:
  - daml-prim
  - daml-stdlib
build-options:
  - --target=3.4
```

Key fields:

* `sdk-version` -- The Daml SDK version to use. `dpm install` downloads this version.
* `name` -- The package name, used in the output DAR filename
* `source` -- Directory containing Daml source files (typically `daml`)
* `dependencies` -- List of Daml library dependencies
* `build-options` -- Compiler flags (e.g., target LF version)

### multi-package.yaml

For projects with multiple Daml packages, a `multi-package.yaml` at the project root lists all sub-packages:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
packages:
  - ./contracts
  - ./tests
  - ./scripts
```

Running `dpm build --all` from the root builds all listed packages in dependency order.

### dpm-config.yaml

The `dpm-config.yaml` file stores global `dpm` configuration such as SDK installation paths and registry settings. It is stored at `${DPM_HOME}/dpm-config.yaml` (where `${DPM_HOME}` is usually `~/.dpm`), is optional, and rarely needs manual editing.

`dpm` can be configured through this config file and through environment variables simultaneously. Environment variables take precedence over the corresponding fields in `dpm-config.yaml`, so they can be used to override configured values.

Typical uses include:

* **Registry URL** — Override the default OCI registry for SDK components.
* **Authentication** — Point to registry credentials.
* **Insecure registry** — Allow HTTP connections to a registry.

### Registry and Edition

For many of its built-in commands, `dpm` needs to know which OCI registry is in effect. If `dpm` was obtained as part of an SDK, the registry is set automatically in `${DPM_HOME}/dpm-config.yaml` (where `${DPM_HOME}` is usually `~/.dpm`).

However, if you are using the bare binary obtained directly from its OCI repository, this configuration might not be known. You can set it manually in `${DPM_HOME}/dpm-config.yaml`:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
registry: europe-docker.pkg.dev/da-images/public # or your desired OCI registry
```

or using the `DPM_REGISTRY` environment variable.

### Authentication

Authentication for pulling from and pushing to OCI registries is based on a file similar to `~/.docker/config.json`, though a Docker installation on the system isn't necessary.

`dpm` defaults to using Docker's auth. You can configure Docker to authenticate to the OCI registry (Google Artifact Registry), and `dpm` will use that:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
gcloud auth login
```

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
gcloud auth configure-docker europe-docker.pkg.dev
```

### Variable interpolation

Both `daml.yaml` and `dpm-config.yaml` support variable interpolation, which lets you avoid hardcoded values (such as registry URLs or credentials paths) and reference environment variables or other dynamic values.

## Command Reference

### Project Management

**`dpm init`** -- Initialize a new Daml project in the current directory. Creates a `daml.yaml` configuration file and a basic project structure.

You can manage SDK versions manually by using `dpm install`.  To install the SDK version specified in the daml.yaml, run:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm install
```

To install a specific SDK version, for example version `3.5.2`, run:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm install 3.5.2
```

To see the active SDK version:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm version --active
```

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
3.5.2
```

To list the installed SDK versions, including the currently active one (marked with `*`):

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm version
```

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
  3.5.1
* 3.5.2
```

To additionally list all the SDK versions that can be installed, as well as the installed versions:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm version --all
```

To get the list in a machine readable format:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm version --all -o json
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
 [
    {
        "version": "3.4.11",
        "installed": true,
        "remote": true
    },
    {
        "version": "3.5.1-rc3",
        "remote": true
    },
    {
        "version": "3.5.1-rc5",
        "remote": true
    },
    {
        "version": "3.5.1",
        "installed": true,
        "remote": true,
        "active": true
    },
    {
        "version": "3.5.2",
        "remote": true
    }
]
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm init
```

**`dpm new`** -- Create a new project from a template. Templates provide working examples that you can modify.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm new my-project --template daml-intro-contracts
```

### Building and Testing

**`dpm build`** -- Compile Daml source files into a DAR (Daml Archive) file. The output goes to `.daml/dist/`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm build
```

For multi-package projects, build all sub-packages:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm build --all
```

**`dpm test`** -- Run all Daml Script tests in the current package. Produces a summary with pass/fail status and coverage report.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm test
```

**`dpm install`** -- Download and install the Daml SDK version specified in `daml.yaml`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm install
```

### Code Generation

**`dpm codegen-js`** -- Generate TypeScript/JavaScript bindings from a compiled DAR file.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm codegen-js .daml/dist/my-project.dar -o generated-ts
```

**`dpm codegen-java`** -- Generate Java bindings from a compiled DAR file.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm codegen-java .daml/dist/my-project.dar -o generated-java
```

### Development Environment

**`dpm sandbox`** -- Start a local Canton sandbox node. This runs a single-participant Canton instance with an in-memory ledger for testing.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm sandbox
```

**`dpm studio`** -- Open Daml Studio (the VS Code extension) for the current project. This launches VS Code with the Daml extension activated.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm studio
```

### Exploration

Use `--help` on any command to see available options:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm --help
dpm build --help
dpm codegen-java --help
dpm inspect-dar --help
```

## Summary of `dpm` Commands

* `dpm build`:                    Build a Daml package or project

  This builds the Daml project according to the project config file `daml.yaml` (see [configuration files](#configuration-files)).

  In particular, it will use the dpm SDK (specified in the `sdk-version` field in `daml.yaml`) to resolve dependencies and compile the Daml project.

  Given a `daml.yaml` and `.daml` source files, the `dpm build` command will generate a .dar for this package. See [How to build Daml Archives](/appdev/reference/daml-language-reference#building-daml-archives) for how to define a package and build it to a DAR.

* `dpm test`:                     Test the current Daml project or the given files by running all test declarations.

  This runs all daml scripts defined within a package.

  Daml Scripts are top level values of type `Script ()`, from the `daml-script` package. This package mimics a Canton Ledger Client for quick iterative testing,
  and direct support within [Daml Studio](/sdks-tools/development-tools/daml-studio). The command runs these scripts against a reference Ledger called the IDE Ledger, which implements the core functionality of the Canton Ledger without the complexity of multi-participant setups.

  It is most useful for verifying the fundamentals of your ledger model, before moving onto integration testing via the Ledger API directly, or the Daml Codegen.  `dpm test` also provides code coverage information for templates and choices used.

* `dpm clean`:                    Clean a Daml package or project

  This removes any Daml artifact files created in your package during a daml build, including DARs.

| Command                 | Description                                                                  |
| ----------------------- | ---------------------------------------------------------------------------- |
| `dpm add`               | Add components and dars to project                                           |
| `dpm add component`     | Add a component to project                                                   |
| `dpm add dar`           | Add or update a dar in the project                                           |
| `dpm component init`    | Initialize a component in the current directory                              |
| `dpm component run`     | Pull down and run a remote component                                         |
| `dpm update`            | Update project dependencies                                                  |
| `dpm codegen-java`      | Daml to Java compiler                                                        |
| `dpm codegen-js`        | Daml to JavaScript compiler                                                  |
| `dpm canton-console`    | Canton console client                                                        |
| `dpm daml-shell`        | Daml-shell client for PQS                                                    |
| `dpm damlc`             | Compiler and IDE backend for the Daml programming language                   |
| `dpm docs`              | Generate documentation for a daml package from its documentation comments    |
| `dpm init`              | Initialize a `daml.yaml` project configuration file in the current directory |
| `dpm install`           | Install project's dependencies or specific dpm-sdk version                   |
| `dpm install package`   | Install the SDK(s), components and dars used by current project              |
| `dpm uninstall`         | Uninstall a dpm-sdk version                                                  |
| `dpm version`           | Show installed sdk versions                                                  |
| `dpm inspect-dar`       | Inspect a DAR archive                                                        |
| `dpm new`               | Create a new Daml package                                                    |
| `dpm publish`           | Commands for publishing artifacts                                            |
| `dpm publish component` | Publish a component to an OCI registry                                       |
| `dpm publish dar`       | Publish a dar to an OCI registry                                             |
| `dpm pqs`               | Participant query store                                                      |
| `dpm sandbox`           | Run full Canton installation in a single process                             |
| `dpm script`            | Daml Script Binary                                                           |
| `dpm studio`            | Launch Daml Studio                                                           |
| `dpm tags`              | List published tags of an artifact                                           |
| `dpm upgrade-check`     | Check upgrade validity between package versions                              |
| `dpm validate-dar`      | Validate a DAR archive                                                       |

Note: after installing a specific SDK version with `dpm install <version>`, update your [project config file](#project-management) to use the new version.

## Components

Components are artifacts that `dpm` (being primarily a *launcher*) wraps. Examples of components are `sandbox` and `scribe`. A component defines the commands it wants `dpm` to expose, as well as the binaries that back those commands.

A component is a directory that contains:

* a `component.yaml` file at its root. Its main purpose is to tell `dpm` how to import the component's commands and `exec` them.
* the binary or binaries (or JARs) that back the commands defined in `component.yaml`.
* optionally, additional arbitrary files and directories (if needed for the operation of the component, for example `lib` directories). When the component is published, `dpm` includes these in the artifact (see [Publishing Components to an OCI Repository](#publishing-components-to-an-oci-repository)).

Components — or rather the commands in them — can be backed by native binaries and/or JARs. This is a sample `component.yaml` defining two commands (`foo` and `bar`) backed by the same native binary:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
spec:
  commands:
    - path: ./foo-binary
      name: foo
      aliases: ["f"]
      desc: a command for foo'ing!
    - path: ./foo-binary
      name: bar
      aliases: ["b"]
      desc: a command for bar'ing!
      exec-args: ["--should-bar-instead-of-foo"]
```

When running `dpm --help`, you'll see the following in the help message:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
Usage:
  dpm [command]
...
...
Dpm-SDK Commands
  foo    a command for foo'ing!
  bar    a command for bar'ing!
...
```

The `exec-args` on the `bar` command tells `dpm` to supply additional args when running the binary backing the command, so it is executed as `./foo-binary --should-bar-instead-of-foo`.

### Dependency on other components

You can optionally declare dependencies of your component on other components:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
# component.yaml

dependency-paths:
  foo: CUSTOM_FOO_PATH
spec:
  commands:
    ...
```

In this example, the component expects a component named `foo` to be present when running `dpm`. `dpm` injects an environment variable named `CUSTOM_FOO_PATH` into this component's environment, pointing to the path of `foo` on the filesystem.

The dependency components must be present either as part of the installed SDK, or declared in `daml.yaml` or `multi-package.yaml`.

### component.yaml schema

See the [JSON schema](https://raw.githubusercontent.com/digital-asset/dpm/refs/heads/main/schema/component.v1.schema.json).

## Working with Components

### Initializing a component

Use `dpm component init` to scaffold a new component in the current directory:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm component init
```

This creates a starter `component.yaml` (and a `daml.yaml`) in the current directory. Pass `--force` to overwrite existing `component.yaml` and `daml.yaml` files:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm component init --force
```

### Running a remote component

Once a component has been published, you can pull it down and test-run it with `dpm component run`:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm component run <component name> <component version> [command] [args]
```

{/* COPIED_START source="dpm:docs-internal/src/faq.rst" hash="4696f289" */}

The registry to pull from is the one configured via the `DPM_REGISTRY` environment variable or `${DPM_HOME}/dpm-config.yaml`. This is handy for quickly sanity-checking a published component:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
export DPM_REGISTRY=europe-docker.pkg.dev/da-images/public
dpm component run canton-open-source 3.3.0-snapshot.20250429.15795.0.v6b2dcccb
```

`dpm` pulls the component into `~/.dpm/cache/components/`, and then runs the specified command of your component.

### Adding components and DARs to a project

Use `dpm add component` to add a published component to your project:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm add component <oci-uri>
```

| Option       | Description                                    |
| ------------ | ---------------------------------------------- |
| `--insecure` | Use HTTP instead of HTTPS for the OCI registry |

{/* COPIED_START source="dpm:docs-internal/src/cli/dpm_add_dar.rst" hash="9c6c12b4" */}

Use `dpm add dar` to add or update a DAR in your project. You must specify whether the DAR is a dependency or a data-dependency:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm add dar <oci-uri> <--dependencies | --data-dependencies>
```

| Option                | Description                                    |
| --------------------- | ---------------------------------------------- |
| `--dependencies`      | Add the DAR to the `dependencies` field        |
| `--data-dependencies` | Add the DAR to the `data-dependencies` field   |
| `--insecure`          | Use HTTP instead of HTTPS for the OCI registry |

## Publishing

### Publishing Components to an OCI Repository

<Note>
  This functionality is available in DPM version 1.0.14 or later (or bundled with SDK 3.5 or later).
</Note>

`dpm` fully handles packaging and publishing [components](#components). Components are published as [OCI](https://opencontainers.org/) artifacts to an OCI registry.

As a component developer, you can use the `dpm publish component` command to publish a component. Publishing is platform-aware, and the command requires the target platform(s) to be specified with `-p`/`--platform`:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
--platform darwin/arm64=<path to prepared directory containing the component for this platform>
```

Multiple platforms can be published in a single command by providing multiple `--platform` flags. For JAR components, you can use `--platform generic=<path to dir>`.

Here's a sample component `foo` laid out with one directory per platform:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
./
  darwin-arm64/
        component.yaml
        foo              # darwin/arm64 binary
        foo2             # another binary
        lib/...          # directory
        somefile.txt
  linux-amd64/
        component.yaml
        foo
        lib/...
```

The `component.yaml` file is required, and must be present at the root of each platform directory.

Publish it like this:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm publish component \
  oci://<full destination URI>:<version> \
  --platform darwin/arm64=./darwin-arm64 \
  --platform linux/amd64=./linux-amd64 \
  --extra-tags latest    # also push a 'latest' tag for this version of the component
```

This runs some validations, then publishes two [OCI images](https://specs.opencontainers.org/image-spec/manifest/#image-manifest) corresponding to the two platforms, and an [OCI index](https://specs.opencontainers.org/image-spec/image-index/?v=v1.0.1), plus the `latest` tag.

The published artifact for a given platform includes everything present in the given directory for that platform — all files and subdirectories (for example `lib`). You don't have to pre-bundle or zip up anything; just provide the raw directory. When pulling a component, `dpm` restores the artifact exactly as it was at publish time.

The component can now be imported (pulled) and run by `dpm`. See [Running a remote component](#running-a-remote-component) for how to pull components.

{/* COPIED_START source="dpm:docs-internal/src/cli/dpm_publish_component.rst" hash="cdc719f9" */}

#### Options

| Option                   | Description                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `-p, --platform`         | **REQUIRED.** `<os>/<arch>=<path-to-component>` or `generic=<path-to-component>`. May be given multiple times.                      |
| `-t, --extra-tags`       | Publish extra tags besides the semver.                                                                                              |
| `-a, --annotations`      | Annotations to include in the published OCI artifact (key/value pairs, may be given multiple times).                                |
| `-g, --include-git-info` | Include git info as annotations on the published manifest.                                                                          |
| `--auth`                 | Path to a config file similar to Docker's `config.json` for authenticating to the OCI registry. Defaults to Docker's `config.json`. |
| `-d, --dry-run`          | Don't actually push to the registry.                                                                                                |
| `--insecure`             | Use HTTP instead of HTTPS for the OCI registry.                                                                                     |

{/* COPIED_START source="dpm:docs-internal/src/components/publishing-components.rst" hash="5c3c35f8" */}

When publishing build artifacts you can also apply annotations to the entire image. The `-a`/`--annotations` flag can be used with a key/value pair multiple times to add annotations to the image being published. This is useful for attaching metadata such as the branch the build artifacts were built from, or the commit SHA related to the artifacts.

### Publishing DARs to an OCI Repository

<Note>
  This functionality is available in DPM version 1.0.20 or later (or bundled with SDK 3.5.2 or later).
</Note>

Similarly to components, you can publish DARs to an OCI repository for distribution:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm publish dar oci://example.com/my/dars/foo:1.0.0 \
    -f ./foo.dar \
    --extra-tags devnet    # optional
```

You should now be able to see the published version via `dpm tags`; see [Listing available tags and versions](#listing-available-tags-and-versions-in-an-oci-repository) below.

See the [Remote Dars](/appdev/modules/m5-environment-configuration#remote-dars) docs section to learn how to install `oci://` DARs in your project.

#### Options

| Option                   | Description                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --dar`              | **REQUIRED.** Path to the DAR file to publish. May be given multiple times.                                                         |
| `-l, --license`          | Path to the LICENSE file. A license file is required when publishing a DAR.                                                         |
| `--exclude-license`      | **For non-production use only.** Disable the license file requirement for DAR publishing.                                           |
| `-t, --extra-tags`       | Publish extra tags besides the semver.                                                                                              |
| `-a, --annotations`      | Annotations to include in the published OCI artifact (key/value pairs, may be given multiple times).                                |
| `-g, --include-git-info` | Include git info as annotations on the published manifest.                                                                          |
| `--auth`                 | Path to a config file similar to Docker's `config.json` for authenticating to the OCI registry. Defaults to Docker's `config.json`. |
| `-d, --dry-run`          | Don't actually push to the registry.                                                                                                |
| `--insecure`             | Use HTTP instead of HTTPS for the OCI registry.                                                                                     |

### Listing available tags and versions in an OCI repository

You can use the `dpm tags` command to view published versions and tags for a *specific* component or DAR:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm tags oci://example.com/my/dars/my-package
1.0.0
1.2.3
latest
```

| Option            | Description                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--registry-auth` | Path to a config file similar to Docker's `config.json` for authenticating to the OCI registry. Defaults to Docker's `config.json`. |

## Typical Workflow

A common development cycle with `dpm`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Set up the project
dpm new my-app --template daml-intro-contracts
cd my-app
dpm install

# 2. Write Daml code, then compile
dpm build

# 3. Run tests
dpm test

# 4. Start a local sandbox for integration testing
dpm sandbox

# 5. Generate bindings for your backend
dpm codegen-java .daml/dist/my-app.dar -o generated-java
dpm codegen-js .daml/dist/my-app.dar -o generated-ts
```

## `daml` assistant to `dpm` migration steps

This section provides a step-by-step guide for projects originally built with the Daml assistant.

## Migration steps

1. **Install Dpm**

   Follow the [installation instructions](#installation) above.

2. **Verify Dpm is in your PATH**

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm version
```

3. **Remove** `~/.daml/bin` **from your PATH**

   Edit your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`, `~/.profile`) and remove any line that adds `~/.daml/bin` to your `PATH`

4. **Remove the Daml assistant**

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
rm -rf ~/.daml
```

5. **Create a project configuration if needed**

   If a `daml.yaml` file doesn't already exist in your project, generate one:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm init
```

6. **Replace** `daml` **commands with** `dpm`

   Most commands map directly. See the [command migration table](/sdks-tools/cli-tools/dpm#command-migration-table) below.

   Six `daml` commands have been removed and replaced with Declarative API, Canton Console, JSON API, and/or gRPC API calls. See [removed command replacements](/sdks-tools/cli-tools/dpm#removed-command-replacements) for full details.

7. **Review project configuration**

   Review your `daml.yaml` to ensure it is compatible with dpm. Audit parent directories for stale `daml.yaml` files. Delete orphan or invalid files.

8. **Review global configuration** (optional)

   Review or create `${DPM_HOME}/dpm-config.yaml` if you need to customize registry, authentication, or other global settings.

9. **Set up variable interpolation** (optional)

   Use [variable interpolation](/sdks-tools/cli-tools/dpm#variable-interpolation) in your configuration files to avoid hardcoded values.

10. **Update CI/CD pipelines** (if applicable)

    Update any CI/CD pipeline scripts that reference `daml` commands to use the corresponding `dpm` commands instead.

## Command migration table

| daml command                   | dpm command                                                                            | purpose                           |
| ------------------------------ | -------------------------------------------------------------------------------------- | --------------------------------- |
| daml new                       | dpm new                                                                                | Create a new Daml project         |
| daml build                     | dpm build                                                                              | Compile the Daml project          |
| daml test                      | dpm test                                                                               | Run tests for the Daml project    |
| daml install                   | dpm install                                                                            | Install Daml SDK components       |
| daml codegen java              | dpm codegen-java                                                                       | Java code generation              |
| daml codegen js                | dpm codegen-js                                                                         | TypeScript code generation        |
| daml damlc                     | dpm damlc                                                                              | Invoke the daml compiler          |
| daml studio                    | dpm studio                                                                             | Open project in Visual Studio     |
| daml sandbox                   | dpm sandbox                                                                            | Launch a Daml Sandbox             |
| `daml ledger allocate-parties` | Use Declarative API – OR – JSON / gRPC API                                             | Allocate parties on a ledger      |
| `daml ledger list-parties`     | JSON / gRPC API                                                                        | list parties on a ledger          |
| `daml ledger upload-dar`       | Use Declarative API – OR – JSON / gRPC API                                             | Upload (and vet) dars on a ledger |
| `daml ledger fetch-dar`        | gRPC API                                                                               | Fetch a Dar from a ledger.        |
| `daml packages`                | JSON / gRPC API                                                                        | Package a Daml project            |
| `daml start`                   | `dpm sandbox` + `dpm build`; use Declarative API – OR – JSON / gRPC to upload/allocate | Start a local Daml Ledger         |

## Removed command replacements

The following `daml` commands have no direct `dpm` equivalent. Use the Declarative API, Canton Console, JSON API, or gRPC API instead.

### `daml ledger allocate-parties`

| Method          | Details                                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Declarative API | `canton.parameters.enable-alpha-state-via-config = yes` with `canton.participants.sandbox.alpha-dynamic { parties = [{ party = "Alice", synchronizers = ["mysync"] }, { party = "Bob" }] }` |
| Canton Console  | `ledger_api.parties.allocate(...)`                                                                                                                                                          |
| JSON API        | `POST /v2/parties/`                                                                                                                                                                         |
| gRPC            | `PartyManagementService.AllocateParty`                                                                                                                                                      |

### `daml ledger list-parties`

| Method         | Details                                        |
| -------------- | ---------------------------------------------- |
| Canton Console | `ledger_api.parties.list()`                    |
| JSON API       | `GET /v2/parties` or `GET /v2/parties/{party}` |
| gRPC           | `PartyManagementService.ListKnownParties`      |

### `daml ledger upload-dar`

| Method          | Details                                                                                                                                                                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Declarative API | `canton.parameters.enable-alpha-state-via-config = yes` with `canton.participants.sandbox.alpha-dynamic.dars = [{ location = "./my-asset.dar" }, { location = "https://path.to/repo/token.dar", request-headers = { AuthenticationToken : "mytoken" } }]` |
| Canton Console  | `ledger_api.packages.upload_dar(...)`                                                                                                                                                                                                                     |
| JSON API        | `POST /v2/dars/`                                                                                                                                                                                                                                          |
| gRPC            | `PackageManagementService.UploadDarFile`                                                                                                                                                                                                                  |

### `daml ledger fetch-dar`

| Method   | Details                         |
| -------- | ------------------------------- |
| JSON API | `GET /v2/packages/{package-id}` |
| gRPC     | `PackageService.GetPackage`     |

### `daml packages`

| Method         | Details                                                      |
| -------------- | ------------------------------------------------------------ |
| Canton Console | `ledger_api.packages.list()`                                 |
| JSON API       | `GET /v2/packages` or `GET /v2/packages/{package-id}/status` |
| gRPC           | `PackageService.ListPackages`                                |

### `daml start`

Replace with `dpm sandbox` combined with `dpm build`. Use the Declarative API or JSON/gRPC API to upload DARs and allocate parties as needed.

See `dpm sandbox` for details on running a local Canton installation.

## Related Pages

* [Daml SDK](/sdks-tools/sdks/daml-sdk) -- What the SDK includes and how versions work
* [Sandbox](/sdks-tools/development-tools/sandbox) -- Local testing environment started by `dpm sandbox`
* [Daml Studio](/sdks-tools/development-tools/daml-studio) -- VS Code extension launched by `dpm studio`
* [Daml Script](/sdks-tools/cli-tools/daml-script) -- Writing and running tests with `dpm test`

# Manual Installation Instructions

## Mac/Linux Installation

If you cannot / wish not to use the shell script to install for Linux or OSX, you can alternatively install dpm manually by running this set of commands in your terminal:

The latest stable release version can be found by hitting the following URL:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
VERSION="$(curl -sS "https://get.digitalasset.com/install/latest")"
```

And you can then use this to retrieve the tarball of the full installation, extract, and install, as outlined in the full instructions below.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
#! /usr/bin/env bash
set -xeuo pipefail

# get latest version number
VERSION="$(curl -sS "https://get.digitalasset.com/install/latest")"

# set your architecture to either amd64 | arm64
ARCH="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"

# set your OS to either darwin or linux
OS="$(uname | tr '[:upper:]' '[:lower:]')"

# pull down appropriate tarball for your OS and architecture
readonly TARBALL="dpm-${VERSION}-${OS}-${ARCH}.tar.gz"

# determine location of tarball to download
TARBALL_URL="https://get.digitalasset.com/install/dpm-sdk/${TARBALL}"

# make tmpdir
TMPDIR="$(mktemp -d)"

# download tarball
curl -SLf "${TARBALL_URL}" --output "${TMPDIR}/${TARBALL}" --progress-bar "$@"

# create directory to extract into
extracted="${TMPDIR}/extracted"
mkdir -p "${extracted}"

# untar to extracted directory
tar xzf "${TMPDIR}/${TARBALL}" -C "${extracted}" --strip-components 1

# bootstrap dpm
"${extracted}/bin/dpm" bootstrap "${extracted}"

# verify dpm version runs and does not return an error
if ! "${extracted}/bin/dpm" version; then
  echo "dpm version failed" >&2
  exit 1
fi

# cleanup tmpdir
rm -rf "${TMPDIR}"
```

## Windows Installation

Download and unpack the [windows dpm-sdk archive (.zip)](https://get.digitalasset.com/install/latest-windows-archive.html), then:

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Extract the downloaded zip ($ZIP_PATH) to temp directory ($EXTRACTED)
# Avoid using the system's temp directory as the user may not have rights to it
New-Item -ItemType Directory -Path $EXTRACTED | Out-Null
Expand-Archive -Path $ZIP_PATH -DestinationPath $EXTRACTED

# Optionally, override the TMP and DPM_HOME environment variable to point to directories other than the default,
# as the user might not have rights to the default directories.
# (You might also want to persist these variables as DPM uses them on every invocation)
$env:TMP = "<user-owned temporary directory>"
$env:DPM_HOME = "<user-owned directory>"

& "$EXTRACTED\windows-amd64\bin\dpm.exe" bootstrap $EXTRACTED\windows-amd64
```

## Unstable Version Manual Installation

Preview / unstable versions are also available for experimentation, though it is always recommended to use the stable versions listed above instead.

## Unstable Mac / Linux

Follow the `dpm-manual-installation-mac-linux` instructions to install an unstable version, but note the differences in VERSION and TARBALL\_URL.

The latest unstable release version can be found by hitting the following URL:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
VERSION="$(curl -sS "https://get.digitalasset.com/unstable/install/latest")"
```

The unstable tarball can be retrieved from the following URL:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# determine location of tarball to download
TARBALL_URL="https://get.digitalasset.com/unstable/install/dpm-sdk/${TARBALL}"
```

## Unstable Windows

Download and unpack the latest [windows unstable dpm-sdk archive (.zip)](https://get.digitalasset.com/unstable/install/latest-windows-archive.html), then follow `dpm-manual-installation-windows` instructions.