> 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/artifact-registry/3.0/reference/cli.md).

# CLI

Full command reference for the Harness CLI (hc): managing registries, artifacts, and Dependency Firewall from the terminal or a CI pipeline.

The Harness CLI (`hc`) lets you manage Artifact Registry resources from the terminal or a CI pipeline. Use it to create and configure registries, push and pull artifacts, audit dependencies against firewall policies, and automate registry operations.

## Install and authenticate

**Install on macOS or Linux**:

```bash
curl https://raw.githubusercontent.com/harness/harness-cli/v2/install | sh
```

Confirm the installation and add `hc` to your PATH as prompted, then verify:

```bash
hc version
```

To upgrade to the latest version:

```bash
hc upgrade
```

**Authenticate interactively**:

```bash
hc auth login
```

You are prompted for your Harness URL (`https://app.harness.io`), API token, and account ID. Optionally scope the session to a default org and project. Credentials are stored locally after a successful login.

**Authenticate non-interactively (CI)**:

```bash
hc auth login \
  --api-url https://app.harness.io \
  --api-token $HARNESS_API_TOKEN \
  --account $HARNESS_ACCOUNT_ID
```

## Global flags

These flags apply to every `hc` command and override the values stored from `hc auth login`.

| Flag            | Description                                                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--account`     | Account ID                                                                                                                                                    |
| `--api-url`     | Base Harness API URL                                                                                                                                          |
| `--org`         | Organization ID                                                                                                                                               |
| `--project`     | Project ID                                                                                                                                                    |
| `--token`       | Authentication token (overrides stored credentials). `hc auth login` uses `--api-token` instead; go to [Install and authenticate](#install-and-authenticate). |
| `--format`      | Output format: `table` (default), `json`, `yaml`                                                                                                              |
| `-v, --verbose` | Verbose console output                                                                                                                                        |
| `-h, --help`    | Help for the current command                                                                                                                                  |

**Short aliases**: `hc reg` = `hc registry` · `hc art` = `hc artifact`

***

## hc registry

The `hc registry` command group manages registries in Harness Artifacts.

### hc registry list

List all registries in a project.

```bash
hc registry list [flags]
```

| Flag        | Description                            |
| ----------- | -------------------------------------- |
| `--org`     | Organization ID                        |
| `--project` | Project ID                             |
| `--format`  | Output format: `table`, `json`, `yaml` |

**Example**:

```bash
hc registry list --org my-org --project my-project
```

**Extract identifiers for scripting**:

```bash
hc registry list --format json | jq '.[] | .identifier'
```

### hc registry get

Retrieve details about a registry: type, configuration, and artifact count.

```bash
hc registry get [name] [flags]
```

| Flag             | Description                           |
| ---------------- | ------------------------------------- |
| `--package-type` | Filter by package type                |
| `--page`         | Page number, zero-indexed (default 0) |
| `--page-size`    | Results per page (default 10)         |

**Example**:

```bash
hc registry get my-docker-registry
```

### hc registry configure

Configure a package manager client to authenticate and route traffic through a Harness Artifacts. The command writes the registry URL and credentials to your package manager's config file: `.npmrc` for npm, `~/.m2/settings.xml` for Maven, and so on. After running this, use your native package manager commands directly.

```bash
hc registry configure <package-manager> --registry <name> [flags]
```

**Supported package managers**: `npm` · `maven` · `pip` · `nuget`

{% tabs %}
{% tab title="npm" %}

| Flag              | Required | Description                                                    |
| ----------------- | -------- | -------------------------------------------------------------- |
| `--registry`      | Yes      | Registry identifier                                            |
| `--pkg-url`       | No       | Package host URL (default: `https://pkg.harness.io`)           |
| `--scope`         | No       | npm scope, for example, `@myorg`; configures a scoped registry |
| `--global`        | No       | Write to `~/.npmrc` (user-global)                              |
| `--project-level` | No       | Write `.npmrc` in the current directory                        |

```bash
# Default registry
hc registry configure npm --registry my-npm-registry

# Scoped registry
hc registry configure npm --registry my-npm-registry --scope @myorg

# Project-level config
hc registry configure npm --registry my-npm-registry --project-level
```

{% endtab %}

{% tab title="Maven" %}
Writes the registry URL and credentials to `~/.m2/settings.xml`.

```bash
hc registry configure maven --registry my-maven-registry
```

{% endtab %}

{% tab title="pip" %}
Configures pip to resolve packages from the registry.

```bash
hc registry configure pip --registry my-pypi-registry
```

{% endtab %}

{% tab title="NuGet" %}
Configures the NuGet / dotnet client.

```bash
hc registry configure nuget --registry my-nuget-registry
```

{% endtab %}
{% endtabs %}

### hc registry metadata

Attach custom key-value labels to a registry for organization, search, and automation.

**Set**:

```bash
hc registry metadata set --registry <name> --metadata "key:value,key:value"
```

**Get**:

```bash
hc registry metadata get --registry <name>
```

**Delete**:

```bash
hc registry metadata delete --registry <name> --metadata "key:value"
```

**Example**:

```bash
hc registry metadata set --registry prod-docker --metadata "env:prod,region:us-east-1"
hc registry metadata get --registry prod-docker
hc registry metadata delete --registry prod-docker --metadata "region:us-east-1"
```

### hc registry fw audit

Evaluate a dependency manifest or lock file against your registry's Dependency Firewall policies. Use this locally before a PR or in CI before deployment to surface blocked and flagged packages before they reach production.

```bash
hc registry fw audit --file <path> --registry <name> [flags]
```

| Flag         | Required | Description                   |
| ------------ | -------- | ----------------------------- |
| `-f, --file` | Yes      | Path to manifest or lock file |
| `--registry` | Yes      | Registry name                 |
| `--org`      | No       | Organization ID               |
| `--project`  | No       | Project ID                    |

**Input files and what they audit**:

| Input file                                                         | Audit scope                            |
| ------------------------------------------------------------------ | -------------------------------------- |
| `package.json`                                                     | Direct dependencies only               |
| `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`                 | Direct and all transitive dependencies |
| `pom.xml`, `build.gradle`, `requirements.txt`, and other manifests | Per package manager resolution         |

{% hint style="info" %}
Pass a lock file to audit the full resolved dependency graph, including transitive packages. Pass `package.json` to audit direct dependencies only.
{% endhint %}

**Examples**:

{% tabs %}
{% tab title="npm (direct)" %}

```bash
hc registry fw audit --file package.json --registry my-npm-registry
```

{% endtab %}

{% tab title="npm (full graph)" %}

```bash
hc registry fw audit --file package-lock.json --registry my-npm-registry
```

{% endtab %}

{% tab title="Yarn" %}

```bash
hc registry fw audit --file yarn.lock --registry my-npm-registry
```

{% endtab %}

{% tab title="pnpm" %}

```bash
hc registry fw audit --file pnpm-lock.yaml --registry my-npm-registry
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If lock files are not stored in source control, generate one before auditing:

```bash
npm install --package-lock-only
hc registry fw audit --file package-lock.json --registry my-npm-registry
```

For other package managers: `yarn install`, `pnpm install --lockfile-only`, or the equivalent for your tool.
{% endhint %}

**Sample output**:

```
Parsing dependency file: package-lock.json...
Found 15 dependencies

Scan Results for 15 dependencies:
  Warnings: 2  Allowed: 13

┌──────────────────────────────────┐
| Package Name | Version | Status  |
| body-parser  | 1.20.1  | WARN    |
| express      | 4.18.2  | ALLOWED |
| lodash       | 4.17.20 | WARN    |
└──────────────────────────────────┘
```

### hc registry fw explain

Get the Dependency Firewall verdict and scan details for a specific artifact version already stored in a registry. Use this to investigate why a package was allowed, blocked, or flagged.

```bash
hc registry fw explain --registry <name> --package <name> --version <version> [flags]
```

| Flag         | Required | Description     |
| ------------ | -------- | --------------- |
| `--registry` | Yes      | Registry name   |
| `--package`  | Yes      | Package name    |
| `--version`  | Yes      | Package version |

**Example**:

```bash
hc registry fw explain \
  --registry my-npm-registry \
  --package express \
  --version 4.18.2
```

**Possible statuses**: `ALLOWED` · `BLOCKED` · `WARN`

### hc registry migrate

Migrate artifacts from an external registry to Harness Artifacts using a YAML config file. Supported source types: `NEXUS`, `JFROG`.

```bash
hc registry migrate --config <path> [flags]
```

| Flag            | Description                         | Default       |
| --------------- | ----------------------------------- | ------------- |
| `-c, --config`  | Path to migration config file       | `config.yaml` |
| `--concurrency` | Concurrent operations               | `1`           |
| `--dry-run`     | Preview file list without uploading | `false`       |
| `--overwrite`   | Overwrite existing artifacts        | `false`       |
| `-v, --verbose` | Verbose logging                     | `false`       |

Go to [Migrate from JFrog Artifactory](https://developer.harness.io/artifact-registry/3.0/get-started/migrate-to-harness-artifacts/from-jfrog-artifactory.md) and [Migrate from Amazon ECR](https://developer.harness.io/artifact-registry/3.0/get-started/migrate-to-harness-artifacts/from-amazon-ecr.md) for complete migration guides including config file structure and step-by-step walkthroughs.

### hc registry delete

Delete a registry and all artifacts within it.

```bash
hc registry delete <name>
```

**Example**:

```bash
hc registry delete my-docker-registry
```

{% hint style="warning" %}
Deleting a registry removes all artifacts stored within it. This action cannot be undone. Back up important artifacts before deleting.
{% endhint %}

***

## hc artifact

The `hc artifact` command group manages artifacts within your registries.

### hc artifact list

List artifacts in a registry, with optional pagination.

```bash
hc artifact list [flags]
```

| Flag          | Description                   |
| ------------- | ----------------------------- |
| `--registry`  | Registry name                 |
| `--page`      | Page number, zero-indexed     |
| `--page-size` | Results per page (default 10) |

**Examples**:

```bash
# All artifacts in a registry
hc artifact list --registry my-docker-registry

# Paginated
hc artifact list --registry my-docker-registry --page 0 --page-size 50
```

### hc artifact push

Push an artifact to a registry. Use the subcommand for your package type.

```bash
hc artifact push <package-type> [args] [flags]
```

**Supported package types**: `generic` · `go` · `conda` · `cargo` · `composer` · `dart` · `nuget` · `python` · `rpm` · `npm` · `swift`

Use `-h` on any subcommand for its full flag list:

```bash
hc artifact push generic --help
```

**Example: generic artifact**

```bash
hc artifact push generic my-registry build.tar.gz \
  --name my-app \
  --version 1.2.3
```

{% hint style="info" %}
For single-file uploads (Generic, Composer, RPM, Python, Dart), the CLI automatically sends a checksum digest with the request. The registry rejects uploads where the bytes do not match and returns **409 Conflict**. No configuration is required.
{% endhint %}

### hc artifact pull

Download an artifact from a registry to your local machine.

```bash
hc artifact pull <package-type> [args] [flags]
```

**Supported package types**: `generic`

**Example**:

```bash
hc artifact pull generic \
  my-registry/my-app/1.2.3/build.tar.gz \
  ./downloads \
  --pkg-url https://pkg.harness.io
```

### Install wrappers with Dependency Firewall tracking

These commands wrap your native package manager's install to add Dependency Firewall evaluation and dependency graph upload. After the install, the Dependency Firewall dashboard shows which packages were blocked and which pipelines are affected.

| Command                      | Wraps            |
| ---------------------------- | ---------------- |
| `hc artifact npm install`    | `npm install`    |
| `hc artifact npm ci`         | `npm ci`         |
| `hc artifact mvn install`    | `mvn install`    |
| `hc artifact pip install`    | `pip install`    |
| `hc artifact dotnet restore` | `dotnet restore` |

**Prerequisites**: Authenticate with `hc auth login` and configure your package manager with `hc registry configure`. Dependency Firewall must be enabled on the registry.

**Example: npm**

```bash
hc registry configure npm --registry my-npm-registry --global
hc artifact npm install
```

**Example output**:

```
✅ Found HAR registry: my-npm-registry
⚡ Running npm install...
✅ Firewall evaluation completed (15 packages)

  ❌ BLOCKED  lodash@4.18.1
    Policy Set: Firewall | Category: License

  ✅ PASSED   express@4.18.2

✅ Build info uploaded (15 nodes)
```

Go to [Dependency Firewall](https://developer.harness.io/artifact-registry/3.0/dependency-firewall/overview.md) for dashboard details and pipeline tracking.

### hc artifact metadata

Attach custom key-value labels to an artifact package or a specific version.

**Set**:

```bash
hc artifact metadata set \
  --registry <name> \
  --package <name> \
  --metadata "key:value,key:value" \
  [--version <version>]
```

**Get**:

```bash
hc artifact metadata get \
  --registry <name> \
  --package <name> \
  [--version <version>]
```

**Delete**:

```bash
hc artifact metadata delete \
  --registry <name> \
  --package <name> \
  --metadata "key:value" \
  [--version <version>]
```

Omit `--version` to operate at package level. Include `--version` to operate on a specific version.

**Examples**:

```bash
# Package-level
hc artifact metadata set --registry my-registry --package nginx \
  --metadata "owner:platform-team"

# Version-level
hc artifact metadata set --registry my-registry --package nginx \
  --version 1.25.0 --metadata "approved:true"
```

### hc artifact delete

Delete an artifact or specific versions from a registry. Supports wildcard patterns for bulk operations.

```bash
hc artifact delete <artifact-name> --registry <name> [flags]
```

| Flag         | Required | Description                                                      | Default      |
| ------------ | -------- | ---------------------------------------------------------------- | ------------ |
| `--registry` | Yes      | Registry name                                                    | None         |
| `--version`  | No       | Version to delete; supports glob patterns (for example, `1.0.*`) | All versions |
| `--dry-run`  | No       | Preview without deleting                                         | `true`       |
| `--force`    | No       | Permanent delete; omit for soft delete                           | `false`      |

{% hint style="info" %}
`--dry-run` defaults to `true`. Pass `--dry-run=false` when you are ready to execute; without it, the command only previews what would be deleted.
{% endhint %}

**Examples**:

```bash
# Delete a specific version (soft delete)
hc artifact delete my-app --registry my-registry --version 1.0.0 --dry-run=false

# Delete all versions of an artifact
hc artifact delete my-app --registry my-registry --dry-run=false

# Preview bulk delete matching a wildcard pattern
hc artifact delete "my-app-*" --registry my-registry

# Execute bulk delete
hc artifact delete "my-app-*" --registry my-registry --dry-run=false

# Permanent delete: cannot be recovered
hc artifact delete "temp-*" --registry my-registry --dry-run=false --force
```

{% hint style="warning" %}
Wildcard bulk deletion is supported for Generic, Maven, npm, Python, NuGet, Go, Conda, Composer, Swift, and Dart registries. Docker and Helm registries do not support bulk delete.
{% endhint %}

### hc artifact copy

Copy a specific artifact version from one registry to another within the same Harness account.

```bash
hc artifact copy <src-registry>/<package>/<version> <dest-registry> [flags]
```

| Flag              | Description                                      |
| ----------------- | ------------------------------------------------ |
| `--artifact-type` | Artifact type, for example, `model` or `dataset` |

**Example**:

```bash
hc artifact copy my-source-registry/nginx/1.25.0 my-dest-registry
```

***

## Use the CLI in CI

### Jenkins

Install the [Harness plugin](https://plugins.jenkins.io/harness/) for Jenkins. The plugin installs and authenticates `hc` on the agent. Configure the CLI tool under **Manage Jenkins** > **Tools** and store your API token under **Manage Jenkins** > **System**.

```groovy
pipeline {
    agent any
    tools { harnessCli 'harness-cli' }
    stages {
        stage('Push to Harness Artifacts') {
            steps {
                hc 'artifact push generic my-registry target/myapp-1.0.jar'
            }
        }
    }
}
```

### GitHub Actions

Use the [Setup Harness CLI](https://github.com/marketplace/actions/setup-harness-cli) action. Store your credentials as GitHub secrets.

```yaml
- uses: harness/setup-harness-cli@v1
  with:
    api-url: ${{ secrets.HARNESS_URL }}
    account: ${{ secrets.HARNESS_ACCOUNT_ID }}
    token: ${{ secrets.HARNESS_PAT_TOKEN }}

- run: |
    hc artifact push generic my-registry build.tar.gz \
      --name my-app \
      --version ${{ github.sha }}
```

The action logs out at job end, even on failure, so the token is not left on self-hosted runners.

***

## Troubleshooting

<details>

<summary>hc auth login fails or returns 401</summary>

Verify your API token is valid and has not expired. Confirm the account ID matches the account associated with the token. Pass `--api-url https://app.harness.io` explicitly if the stored URL is incorrect.

</details>

<details>

<summary>hc registry list returns no results</summary>

Confirm `--org` and `--project` match where your registries are created. Run `hc auth login` to refresh your session if the token has expired.

</details>

<details>

<summary>Push returns 409 Conflict</summary>

A 409 from a single-file push means the uploaded content did not match the declared checksum. Re-upload the file. If the error persists, verify the file was not modified during transfer.

</details>

<details>

<summary>hc registry fw audit shows no results</summary>

Confirm the input file format is supported: `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` for npm; `pom.xml` or `build.gradle` for Maven; `requirements.txt` or `Pipfile.lock` for Python. Dependency Firewall must be enabled on the registry.

</details>

<details>

<summary>Does the CLI support yarn install or npm audit?</summary>

`hc artifact npm install` does not wrap `yarn install`. To audit yarn dependencies against Dependency Firewall, run `hc registry fw audit --file yarn.lock --registry <name>`. For `npm audit`, the npm client handles that natively against the registry; those results show vulnerability advisory data, not Dependency Firewall decisions.

</details>

## Next steps

* [Install the Harness CLI](https://developer.harness.io/harness-platform/use-harness-platform/automation/cli/install)
* [Migrate from JFrog Artifactory](https://developer.harness.io/artifact-registry/3.0/get-started/migrate-to-harness-artifacts/from-jfrog-artifactory.md)
* [Migrate from Amazon ECR](https://developer.harness.io/artifact-registry/3.0/get-started/migrate-to-harness-artifacts/from-amazon-ecr.md)
* [Dependency Firewall](https://developer.harness.io/artifact-registry/3.0/dependency-firewall/overview.md)
* [REST API reference](https://developer.harness.io/artifact-registry/3.0/reference/rest-api.md)

{% @harness-feedback/feedback %}
