> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-cli/harness-cli/harness-cli-commands/artifact-registry-commands.md).

# Artifact Registry

Harness Artifact Registry is a universal package store that hosts, proxies, and secures your build artifacts. The CLI (har module) lets you manage registries, push and pull packages in any supported format, inspect artifact versions, and trigger on-demand security scans without leaving your terminal.

This page covers every Artifact Registry resource and action available in the CLI.

***

### What you will learn in this topic <a href="#what-you-will-learn-in-this-topic" id="what-you-will-learn-in-this-topic"></a>

By the end of this page, you will know how to:

* List and create registries for different package types.
* Configure a local package-manager client to use a Harness registry.
* Push artifacts to a registry in any of the 18 supported package formats.
* Pull artifacts back to your local machine.
* Resolve dependencies from a Harness registry with the package-manager install helpers.
* Inspect artifact metadata, versions, and files.
* Delete artifacts individually or in bulk by name pattern.
* Trigger firewall scans and copy artifacts between registries.
* Migrate external registries into Harness Artifact Registry.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **Harness CLI installed and authenticated:** For setup steps, see [Install and upgrade](/harness-platform/use-harness-cli/harness-cli/install-and-upgrade.md) and [Authenticate](/harness-platform/use-harness-cli/harness-cli/authenticate.md).
* **Project scope configured:** Artifact Registry resources require `--org` and `--project`. Set them in your profile or pass them on each command.
* **Registry exists:** Most push and pull commands require a registry identifier. Create one first or use an existing registry.

***

### Registries <a href="#registries" id="registries"></a>

A registry is a named container that stores artifacts of a specific type (Docker, Helm, npm, Maven, Go, Python, or generic). Each registry belongs to a project and defines upstream proxies, cleanup policies, and access rules. You manage registries to organize artifacts by package format and control who can read or write packages.

#### List registries <a href="#list-registries" id="list-registries"></a>

View all registries in your current project scope to find the one you need for push or pull operations.

```sh
harness list registry
harness list registry --all --format json
harness list registry --search "<registry_name>"
```

#### Get registry details <a href="#get-registry-details" id="get-registry-details"></a>

Retrieve the full configuration of a specific registry, including its upstream sources, allowed actions, and cleanup rules.

```sh
harness get registry <registry>
harness get registry <registry> --format json
```

#### Create a registry <a href="#create-a-registry" id="create-a-registry"></a>

Create a new registry to start storing a specific package type. Each registry targets one format and supports either virtual (aggregation) or upstream (proxy) modes.

```sh
harness create registry \
  --set identifier=<registry_identifier> \
  --set name="<registry_name>" \
  --set packageType=<package_type> \
  --set type=<registry_type>
```

#### Delete a registry <a href="#delete-a-registry" id="delete-a-registry"></a>

Remove a registry and all artifacts stored within it. This action is irreversible.

```sh
harness delete registry <registry>
```

#### Configure a package-manager client <a href="#configure-a-package-manager-client" id="configure-a-package-manager-client"></a>

Point a local package-manager client at a Harness registry. The command writes the registry endpoint and credentials into the client configuration file for the registry's format, such as `.npmrc` for npm or `pip.conf` for Python.

```sh
harness configure registry <registry>
```

#### Registry metadata <a href="#registry-metadata" id="registry-metadata"></a>

Registry metadata stores extended properties like descriptions, labels, and upstream proxy configurations. Update metadata to change how the registry behaves without recreating it.

```sh
harness get registry_metadata <registry>
harness update registry_metadata <registry> --set description="<description>"
harness update registry_metadata <registry> --del <key>
```

***

### Push artifacts <a href="#push-artifacts" id="push-artifacts"></a>

The `push` action uploads a local artifact to a registry. Each package format has its own subcommand (`artifact:docker`, `artifact:helm`, `artifact:npm`, and so on) that handles format-specific upload logic. Use push commands to publish build outputs from CI pipelines or local development.

#### Supported push formats <a href="#supported-push-formats" id="supported-push-formats"></a>

The CLI supports 18 push formats. Each command targets a registry of the matching package type.

| Command                          | Uploads                             |
| -------------------------------- | ----------------------------------- |
| `harness push artifact:generic`  | One or more generic artifacts       |
| `harness push artifact:maven`    | A Maven artifact (`.jar` or `.war`) |
| `harness push artifact:npm`      | An npm package (`.tgz`)             |
| `harness push artifact:python`   | A Python package (`.whl`)           |
| `harness push artifact:nuget`    | A NuGet package (`.nupkg`)          |
| `harness push artifact:rpm`      | An RPM package                      |
| `harness push artifact:cargo`    | A Cargo crate (`.crate`)            |
| `harness push artifact:go`       | A Go module                         |
| `harness push artifact:conda`    | A Conda package                     |
| `harness push artifact:dart`     | A Dart package                      |
| `harness push artifact:composer` | A Composer package (`.zip`)         |
| `harness push artifact:ruby`     | A Ruby gem                          |
| `harness push artifact:swift`    | A Swift package                     |
| `harness push artifact:puppet`   | A Puppet module (`.tar.gz`)         |
| `harness push artifact:debian`   | A Debian package (`.deb` or `.dsc`) |
| `harness push artifact:conan`    | A Conan package                     |
| `harness push artifact:helm`     | A Helm chart                        |
| `harness push artifact:docker`   | A Docker image                      |

Every push command follows the same shape: the first argument is `<registry>/<artifact_name>` and the second is the local path or image reference.

```sh
harness push artifact:<format> <registry>/<artifact_name> <path_to_file>
```

#### Push a Docker image <a href="#push-a-docker-image" id="push-a-docker-image"></a>

Upload a tagged Docker image to a Docker-type registry. The first argument is `<registry>/<image_name>` and the second is the local image reference.

```sh
harness push artifact:docker <registry>/<image_name> <local_image>:<tag>
```

#### Push a Helm chart <a href="#push-a-helm-chart" id="push-a-helm-chart"></a>

Upload a packaged Helm chart archive to a Helm-type registry.

```sh
harness push artifact:helm <registry>/<chart_name> <path_to_chart>.tgz
```

#### Push a generic file <a href="#push-a-generic-file" id="push-a-generic-file"></a>

Upload any file type to a generic registry. Use this for build artifacts, binaries, or archives that do not fit a specific package format.

```sh
harness push artifact:generic <registry>/<artifact_name> <path_to_file>
```

#### Push a Maven artifact <a href="#push-a-maven-artifact" id="push-a-maven-artifact"></a>

Upload a JAR or POM file with Maven coordinates to a Maven-type registry.

```sh
harness push artifact:maven <registry>/<artifact_name> <path_to_jar>
```

#### Push an npm package <a href="#push-an-npm-package" id="push-an-npm-package"></a>

Upload a packed npm tarball to an npm-type registry.

```sh
harness push artifact:npm <registry>/<package_name> <path_to_tarball>.tgz
```

#### Push a Python package <a href="#push-a-python-package" id="push-a-python-package"></a>

Upload a source distribution or wheel to a Python-type registry.

```sh
harness push artifact:python <registry>/<package_name> <path_to_dist>
```

#### Push a Debian package <a href="#push-a-debian-package" id="push-a-debian-package"></a>

Upload a `.deb` or `.dsc` file to a Debian-type registry. Debian pushes require `--distribution` and `--component`, because the registry indexes packages by both values.

```sh
harness push artifact:debian <registry>/<package_name> <path_to_package>.deb \
  --distribution <distribution> \
  --component <component>
```

***

### Resolve dependencies from a registry <a href="#resolve-dependencies-from-a-registry" id="resolve-dependencies-from-a-registry"></a>

The install helpers run your package manager against a Harness registry, so a build resolves dependencies from Harness without you editing the client configuration by hand.

```sh
harness execute artifact:npm_install
harness execute artifact:npm_ci
harness execute artifact:pip_install
harness execute artifact:mvn_install
harness execute artifact:dotnet_restore
```

* **`artifact:npm_install`:** Runs `npm install` against a Harness npm registry.
* **`artifact:npm_ci`:** Runs `npm ci` against a Harness npm registry.
* **`artifact:pip_install`:** Runs `pip install` against a Harness PyPI registry.
* **`artifact:mvn_install`:** Runs Maven dependency resolution against a Harness Maven registry.
* **`artifact:dotnet_restore`:** Runs `dotnet restore` against a Harness NuGet registry.

***

### Pull artifacts <a href="#pull-artifacts" id="pull-artifacts"></a>

The `pull` action downloads an artifact from a registry to your local machine. Use this to retrieve specific versions for debugging, deployment, or local testing. Pass the full path as `<registry>/<artifact_name>/<version>`.

```sh
harness pull artifact <registry>/<artifact_name>/<version>
harness pull artifact <registry>/<artifact_name>/<version> -o <output_directory>
```

***

### Artifacts <a href="#artifacts" id="artifacts"></a>

An artifact represents a stored package within a registry. It groups all versions of a single logical package under one name. Use artifact commands to browse what exists in a registry, check metadata, or remove outdated packages.

#### List artifacts in a registry <a href="#list-artifacts-in-a-registry" id="list-artifacts-in-a-registry"></a>

View all artifacts stored in a specific registry. Pass the registry identifier as a positional argument.

```sh
harness list artifact <registry>
harness list artifact <registry> --all --format json
harness list artifact <registry> --search "<artifact_name>"
```

#### Get artifact details <a href="#get-artifact-details" id="get-artifact-details"></a>

Retrieve the full metadata for a specific artifact using the `<registry>/<artifact_name>` format.

```sh
harness get artifact <registry>/<artifact_name>
harness get artifact <registry>/<artifact_name> --format json
```

#### Delete an artifact <a href="#delete-an-artifact" id="delete-an-artifact"></a>

Remove an artifact and all its versions from the registry. This action is irreversible and frees the associated storage.

```sh
harness delete artifact <registry>/<artifact_name>
```

#### Delete artifacts in bulk <a href="#delete-artifacts-in-bulk" id="delete-artifacts-in-bulk"></a>

Delete every artifact whose name matches a pattern. `--registry` is required. Narrow the match with `--version`, preview the result with `--dry-run`, and skip the confirmation prompt with `--force`.

```sh
harness delete artifact:bulk <pattern> --registry <registry> --dry-run
harness delete artifact:bulk <pattern> --registry <registry> --version <version>
harness delete artifact:bulk <pattern> --registry <registry> --force
```

{% hint style="warning" %}
Run a bulk delete with `--dry-run` first. The command removes every matching artifact and all of its versions, and the deletion cannot be undone.
{% endhint %}

#### Artifact metadata <a href="#artifact-metadata" id="artifact-metadata"></a>

Artifact metadata stores labels, annotations, and custom properties. Update metadata to tag artifacts for tracking, filtering, or policy enforcement without modifying the artifact content.

```sh
harness get artifact_metadata <registry>/<artifact_name>
harness update artifact_metadata <registry>/<artifact_name> --set labels.team=platform
```

***

### Artifact versions <a href="#artifact-versions" id="artifact-versions"></a>

Each push to an artifact creates a new version. Versions are immutable records that track the exact content, digest, and upload timestamp. You use version commands to audit what was published, compare changes across releases, or clean up old builds.

#### List versions <a href="#list-versions" id="list-versions"></a>

View all versions of a specific artifact to see the full release history. Pass the path as `<registry>/<artifact_name>`.

```sh
harness list artifact_version <registry>/<artifact_name>
harness list artifact_version <registry>/<artifact_name> --format json
```

#### Get version details <a href="#get-version-details" id="get-version-details"></a>

Retrieve the full metadata for a specific version, including its content digest, size, and upload time.

```sh
harness get artifact_version <registry>/<artifact_name>/<version>
harness get artifact_version <registry>/<artifact_name>/<version> --format json
```

#### Delete a version <a href="#delete-a-version" id="delete-a-version"></a>

Remove a specific version from an artifact. Other versions remain intact.

```sh
harness delete artifact_version <registry>/<artifact_name>/<version>
```

#### Version metadata <a href="#version-metadata" id="version-metadata"></a>

Version metadata stores per-version labels and annotations. Use it to mark versions as verified, approved, or flagged for review without altering the immutable content.

```sh
harness get artifact_version_metadata <registry>/<artifact_name>/<version>
harness update artifact_version_metadata <registry>/<artifact_name>/<version> \
  --set labels.verified=true
```

***

### Copy an artifact version <a href="#copy-an-artifact-version" id="copy-an-artifact-version"></a>

Copy a specific version from one registry to another without re-uploading from your local machine. Use this to promote artifacts between staging and production registries.

```sh
harness execute artifact_version:copy <registry>/<artifact_name>/<version> \
  --set targetRegistry=<target_registry>
```

***

### List artifact files <a href="#list-artifact-files" id="list-artifact-files"></a>

View the individual files that make up an artifact version (layers for Docker, files for generic archives). Use this to inspect what a version contains without downloading the full artifact.

```sh
harness list artifact_file <registry>/<artifact_name>/<version>
```

***

### Security scans <a href="#security-scans" id="security-scans"></a>

Harness Artifact Registry includes a built-in firewall that scans artifacts for known vulnerabilities. Use on-demand scans to check packages before promoting them to production or after a new CVE is disclosed.

#### Scan all artifacts in a registry <a href="#scan-all-artifacts-in-a-registry" id="scan-all-artifacts-in-a-registry"></a>

Trigger a full scan across every artifact and version in a registry.

```sh
harness execute registry:firewall_scan <registry>
```

#### Scan a specific version <a href="#scan-a-specific-version" id="scan-a-specific-version"></a>

Trigger a targeted scan on a single artifact version when you need results fast.

```sh
harness execute artifact_version:firewall_scan <version> \
  --registry <registry> --artifact <artifact_name>
```

***

### Migrate a registry <a href="#migrate-a-registry" id="migrate-a-registry"></a>

Import artifacts from an external registry (Docker Hub, ECR, GCR, Artifactory) into Harness Artifact Registry. Use migration to consolidate scattered package stores into a single managed location. Describe the source registry in a config file and pass it with `-f`.

```sh
harness execute registry:migrate <registry> -f <migration_config>.yaml
```

***

### Related articles <a href="#related-articles" id="related-articles"></a>

* [Continuous Delivery](/harness-platform/use-harness-cli/harness-cli/harness-cli-commands/cd-and-pipeline-commands.md): Manage pipelines and deployment resources.
* [Infrastructure as Code Management](/harness-platform/use-harness-cli/harness-cli/harness-cli-commands/iacm-commands.md): Manage Terraform and OpenTofu workspaces.
* [Code Repository](/harness-platform/use-harness-cli/harness-cli/harness-cli-commands/code-repository-commands.md): Manage repositories and pull requests.