Skip to main content

​
Synopsis

Manage key-value metadata pairs on packages and specific versions in Harness Artifact Registry. Metadata can be used for categorization, approval tracking, ownership, and custom tagging. 
hc artifact metadata <subcommand> [flags]

​
Subcommands

get

Retrieve metadata

set

Add or update metadata

delete

Remove metadata

​
Metadata Levels

Metadata can be applied at two levels:
  1. Package Level - Metadata applies to the entire package across all versions
  2. Version Level - Metadata applies to a specific version only
Use --version flag to specify version-level metadata. Omit it for package-level metadata.

​
Get Metadata

Retrieve metadata key-value pairs from a package or specific version.

​
Usage

hc artifact metadata get --registry <registry> --package <package> [--version <version>]

​
Options

​
--registry
string
required
Registry identifier
​
--package
string
required
Package name
​
--version
string
Specific version (optional, for version-level metadata)

​
Examples

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

​
Output

Displays metadata in table format: 
Fetching metadata... ✓
Metadata fetched

Key            Value
owner          team-a
approved       true
environment    production
scanned        2024-03-15
If no metadata exists: 
No metadata found

​
Set Metadata

Set or update metadata key-value pairs on a package or specific version.

​
Usage

hc artifact metadata set --registry <registry> --package <package> --metadata <key:value,...> [--version <version>]

​
Options

​
--registry
string
required
Registry identifier
​
--package
string
required
Package name
​
--metadata
string
required
Metadata in key:value,key:value format
​
--version
string
Specific version (optional, for version-level metadata)

​
Metadata Format

Metadata must be provided in comma-separated key:value pairs: 
key1:value1,key2:value2,key3:value3

​
Examples

hc artifact metadata set \
  --registry docker-registry \
  --package nginx \
  --metadata "owner:team-a,environment:production"

​
Output

Parsing metadata... ✓
Metadata parsed
Updating metadata... ✓
Metadata updated successfully

​
Delete Metadata

Delete specific metadata key-value pairs from a package or version.

​
Usage

hc artifact metadata delete --registry <registry> --package <package> --metadata <key:value,...> [--version <version>]

​
Options

​
--registry
string
required
Registry identifier
​
--package
string
required
Package name
​
--metadata
string
required
Metadata to delete in key:value,key:value format
​
--version
string
Specific version (optional, for version-level metadata)
Value matching required - You must provide both key and value to delete metadata. This prevents accidental deletion.

​
Examples

hc artifact metadata delete \
  --registry docker-registry \
  --package nginx \
  --metadata "old-key:old-value"

​
Output

Parsing metadata... ✓
Metadata parsed
Deleting metadata... ✓
Metadata deleted successfully

​
Common Use Cases

# Mark version as approved
hc artifact metadata set \
  --registry docker-registry \
  --package myapp \
  --version 1.0.0 \
  --metadata "approved:true,approved-by:security-team,approved-date:2024-03-15"
Track which versions have been approved for production deployment.
# Set package owner
hc artifact metadata set \
  --registry npm-registry \
  --package @myorg/shared-lib \
  --metadata "owner:platform-team,contact:[email protected]"
Identify which team owns and maintains a package.
# Tag package for environment
hc artifact metadata set \
  --registry docker-registry \
  --package myapp \
  --metadata "environment:production,region:us-east-1"
Organize artifacts by deployment environment and region.
# Record security scan
hc artifact metadata set \
  --registry docker-registry \
  --package myapp \
  --version 2.1.0 \
  --metadata "scanned:true,scan-date:2024-03-15,vulnerabilities:0,scanner:trivy"
Store security scanning results and dates.
# Mark as deprecated
hc artifact metadata set \
  --registry npm-registry \
  --package old-package \
  --metadata "deprecated:true,reason:security-vulnerability,replacement:new-package"
Flag deprecated packages with replacement information.
# Store build metadata
hc artifact metadata set \
  --registry docker-registry \
  --package myapp \
  --version 3.2.0 \
  --metadata "build-id:12345,git-commit:abc123def,build-date:2024-03-15,builder:jenkins"
Track build provenance and CI/CD information.

​
Metadata Patterns

Use clear, consistent naming conventions:
  • owner - Team or person responsible
  • approved - Approval status (true/false)
  • environment - Target environment
  • deployed - Deployment status
  • scanned - Security scan status
  • deprecated - Deprecation flag
  • critical - Business criticality

​
Date Format

Use ISO 8601 format for dates: 
--metadata "scanned:2024-03-15,deployed-at:2024-03-15T10:30:00Z"

​
Boolean Values

Use lowercase true/false: 
--metadata "approved:true,deprecated:false"

​
Error Handling

Error: Failed to parse metadata: invalid format
Ensure metadata is in key:value,key:value format with no extra spaces.
Error: not found: package does not exist
Verify the package name and registry are correct using hc artifact get.
Error: not found: version does not exist
Check available versions with hc artifact get <package>.

​
Tips

List before update - Use metadata get to see existing metadata before adding or deleting.
Metadata is additive - Using set with new keys adds them to existing metadata. It doesn’t replace all metadata.
Automate with CI/CD - Integrate metadata commands in your pipelines to automatically tag artifacts with build info.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us