Skip to main content

Manage Artifacts and Registries

Last updated on

This guide covers the essential commands for working with the Artifact Registry from the command line. This will require installation of the Harness CLI and authentication to your Harness account.

Registry Management​

The hc registry (or hc reg) command allows you to manage your Artifact Registry registries.

List Registries​

View all registries in your project:

hc registry list --org devrel --project sd1

You can also use the short alias:

hc reg list --org devrel --project sd1
Registry List

This displays a table with your registries, including their identifiers, package types, and other details provided that your authentication is at account level.

Get Registry Details​

Retrieve detailed information about a specific registry:

hc registry get [?name] [flags]

Available flags:

  • --package-type string package type
  • --page int32 page number (zero-indexed)
  • --page-size int32 number of items per page (default 10)

Go to the Artifact Registry documentation for a comprehensive list of supported package types.

You can also use global flags to override the org and project, to know more about global flags, refer to the Global Flags section.

Configure Package Manager Clients​

Configure your package manager clients to work with supported Harness Artifact Registries, such as npm. The hc registry configure command automatically sets up the necessary configuration files with the correct registry URLs and authentication.

Configure npm Client​

Configure your npm client to use a Harness Artifact Registry virtual npm registry. This command updates your .npmrc file with the appropriate registry URL and authentication token.

hc registry configure npm [flags]

Required flags:

  • --registry string: Registry identifier
  • --pkg-url string: Package registry base URL (e.g., https://pkg.harness.io)

Flags:

  • --scope string: NPM scope (e.g., @myorg) - configures scoped registry. If not provided, configures the default registry
  • --global: Configure globally for the user (modifies ~/.npmrc)
  • --project-level: Configure at project level (creates/modifies .npmrc in current directory)

Example - Configure default registry:

hc registry configure npm --registry npmproxy --pkg-url https://pkg.harness.io

Example - Configure scoped registry:

hc registry configure npm --registry npmproxy --pkg-url https://pkg.harness.io --scope @myorg

Example - Configure globally:

hc registry configure npm --registry npmproxy --pkg-url https://pkg.harness.io --global

Example - Configure at project level:

hc registry configure npm --registry npmproxy --pkg-url https://pkg.harness.io --project-level

Manage Registry Metadata​

Attach custom key-value pairs to registries for better organization and tracking.

Set Metadata​

hc registry metadata set [flags]

Required flags:

  • --registry string: Registry identifier
  • --metadata string: Metadata in key:value,key:value format

Example:

hc registry metadata set --registry my-docker-reg --metadata "env:prod,region:us"

Get Metadata​

hc registry metadata get [flags]

Required flags:

  • --registry string: Registry identifier

Example:

hc registry metadata get --registry my-docker-reg

Delete Metadata​

hc registry metadata delete [flags]

Required flags:

  • --registry string: Registry identifier
  • --metadata string: Metadata in key:value,key:value format

Example:

hc registry metadata delete --registry my-docker-reg --metadata "env:prod"

Delete a Registry​

Remove a registry from your project:

hc registry delete [name] [flags]

Example:

hc registry delete my-docker-registry
Permanent Action

Deleting a registry will remove all artifacts stored within it. This action cannot be undone. Make sure to back up any important artifacts before deletion.

Audit Dependencies from Lock Files​

The hc registry fw audit (or hc registry firewall audit) command parses and evaluates dependencies from package manager lock files against your registry's firewall policies to identify which packages are allowed, blocked, or flagged with warnings.

hc registry fw audit [flags]

Required flags:

  • -f, --file string: Path to dependency file
    • NPM: package.json, package-lock.json, pnpm-lock.yaml, yarn.lock
    • Java: pom.xml, build.gradle, build.gradle.kts
    • Python: requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock
  • --registry string: Registry name

Example:

hc registry fw audit --file package-lock.json --registry npmproxy --org Devrel --project sd1

Sample output:

  > Fetching registry details for: npmproxy...
  Found registry: d991f9d1-1cda-4a66-a13b-83dd2d9e0b82 (type: NPM)
  Parsing dependency file: package-lock.json...
  Found 15 dependencies in package-lock.json
  > Initiating bulk scan evaluation for registry: npmproxy...
  Bulk scan evaluation completed successfully

  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    |
| ...          | ...     | ...     |
└──────────────────────────────────┘

Get Firewall Status for an Artifact Version​

The hc registry fw explain command gets detailed firewall and scan status information for a specific artifact version already stored in your registry.

hc registry fw explain [flags]

Required flags:

  • --registry string: Registry name
  • --package string: Package name
  • --version string: Package version

Example:

hc registry fw explain --registry npmproxy --package express --version 4.18.2 --org Devrel --project sd1

Sample output:

  Fetching registry details for: npmproxy...
  Found registry UUID: d991f9d1-1cda-4a66-a13b-83dd2d9e0b82
  > Initiating scan evaluation for express@4.18.2...
  Scan evaluation completed successfully

  > Scan Result...
   Package:     express
   Version:     4.18.2
   Scan Status: ALLOWED
   Scan ID:     0e2ed1a8-3977-481a-8bb7-1ccc7b0f399c

  This artifact version is ALLOWED by the firewall

  > Fetching detailed scan information...

Scan Details:
============================================================
Last Evaluated: 2026-02-18 11:18:06 IST

Possible scan statuses:

  • ALLOWED: The artifact passes all firewall policies and is safe to use
  • BLOCKED: The artifact violates firewall policies and should not be used
  • WARN: The artifact has potential issues but is not blocked

Artifact Management​

The hc artifact (or hc art) command allows you to manage artifacts within your registries.

List Artifacts​

The list command is hierarchical and can show different levels of detail depending on the arguments provided.

List Artifacts​

hc artifact list [flags]

Shows all available artifacts in your project.

List All Artifacts in a Registry​

This will show all artifacts in the specified registry.

hc artifact list --registry <registry> --org <org> --project <project>

Example:

hc artifact list --registry hub01 --org devrel --project sd1
Get Artifact from Registry

Pagination Options​

For large result sets, control the output with pagination:

hc artifact list --registry <registry> --page 0 --page-size 20

Available flags:

  • --page: Page number (zero-indexed)
  • --page-size: Number of items per page (default: 10)
  • --registry: Name of the registry

Push Artifacts​

Push artifacts to your registry using the appropriate subcommand for your package type.

General syntax:

hc artifact push [command]

Available commands:

  • generic
  • go
  • conda
  • cargo
  • composer
  • dart
  • nuget
  • python
  • rpm
  • npm

Pick the appropriate command based on your package type. Use the -h flag to get help and understand the necessary flags for each command.

Example: Push a generic artifact

hc artifact push go my-go-registry v1.2.3

Pull Artifacts​

Download artifacts from your registry to your local machine.

General syntax:

 hc artifact pull [command]

Available commands:

  • generic

Pick the appropriate command based on your package type. Use the -h flag to get help and understand the necessary flags for each command.

Example with package URL:

hc artifact pull generic image cli-arti/latest/package.json ./dummy --pkg-url https://pkg.harness.io
Pull Generic Artifact

This downloads the specified artifact to the destination path on your local machine.

Manage Artifact Metadata​

Attach custom key-value pairs to packages or specific versions for better organization, tracking, and automation workflows.

Package vs Version Level Metadata

Metadata can be applied at two levels:

  • Package-level: Applies to the entire package (omit --version flag)
  • Version-level: Applies to a specific version (include --version flag)

Set Metadata​

hc artifact metadata set [flags]

Required flags:

  • --registry string: Registry identifier
  • --package string: Package name
  • --metadata string: Metadata in key:value,key:value format

Optional flags:

  • --version string: Version (for version-level metadata)

Example - Package-level metadata:

hc artifact metadata set --registry r1 --package nginx --metadata "owner:team-a"

Example - Version-level metadata:

hc artifact metadata set --registry r1 --package nginx --version 1.2.3 --metadata "approved:true"

Get Metadata​

hc artifact metadata get [flags]

Required flags:

  • --registry string: Registry identifier
  • --package string: Package name

Optional flags:

  • --version string: Version (for version-level metadata)

Example - Package-level:

hc artifact metadata get --registry r1 --package nginx

Example - Version-level:

hc artifact metadata get --registry r1 --package nginx --version 1.2.3

Delete Metadata​

hc artifact metadata delete [flags]

Required flags:

  • --registry string: Registry identifier
  • --package string: Package name
  • --metadata string: Metadata in key:value,key:value format

Optional flags:

  • --version string: Version (for version-level metadata)

Example - Package-level:

hc artifact metadata delete --registry r1 --package nginx --metadata "owner:team-a"

Example - Version-level:

hc artifact metadata delete --registry r1 --package nginx --version 1.2.3 --metadata "approved:true"

Delete Artifacts​

Delete a specific version of an artifact or all versions of an artifact from the Harness Artifact Registry.

hc artifact delete [artifact-name] [flags]

Required flags:

  • --registry string: Name of the registry

Optional flags:

  • --version string: Specific version to delete (if not provided, deletes all versions)

Example - Delete a specific version:

hc artifact delete my-app --registry my-docker-registry --version 1.0.0

Example - Delete all versions:

Omit the --version flag to delete the entire artifact and all its versions:

hc artifact delete my-app --registry my-docker-registry
Permanent Deletion

Deleting artifacts is permanent and cannot be undone. Ensure you have backups or are certain about the deletion before proceeding.

Copy Artifacts​

Copy a specific version of an artifact package from one registry to another within your Harness Artifact Registry.

hc artifact copy <SRC_REGISTRY>/<PACKAGE_NAME>/<VERSION> <DEST_REGISTRY> [flags]

Optional flags:

  • --artifact-type string: Artifact type (e.g., model or dataset)

Example:

hc artifact copy source-registry/nginx/1.2.3 destination-registry

Example with artifact type:

hc artifact copy ml-registry/my-model/v2.0 prod-registry --artifact-type model

Tips and Best Practices​

1. Use Command Aliases

Save time with short aliases:

  • hc reg instead of hc registry
  • hc art instead of hc artifact

2. Get Help Anytime

Use the --help flag to see all available options:

hc [command] --help
hc registry list --help

3. Pagination for Large Datasets

Control output when working with many artifacts:

hc artifact list my-registry --page-size 50

4. Scripting and Automation

Use JSON or YAML format for parsing in scripts:

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

5. Work Across Projects

Use global flags to work with different projects without changing configuration:

hc registry list --project dev-project
hc registry list --project prod-project

6. Audit Dependencies for Security

Use firewall audit to check your dependencies before deployment:

hc registry fw audit --file package-lock.json --registry npmproxy

7. Configure Package Managers Once

Set up your package manager client configuration once, then use standard commands:

hc registry configure npm --registry npmproxy --pkg-url https://pkg.harness.io --project-level

After configuration, use standard npm commands like npm install and npm publish without additional setup.