Skip to main content

​
General Questions

Harness CLI is a command-line interface tool that provides unified access to Harness services. It follows a consistent, resource-based command structure for interacting with Harness Artifact Registry, Infrastructure as Code Management (IaCM), and other Harness platform services.The CLI enables automation, scripting, and integration with CI/CD pipelines.
Currently, the CLI supports:
  • Authentication: Login, logout, and session management
  • Artifact Registry (AR): Manage registries and artifacts
  • Infrastructure as Code Management (IaCM): Terraform operations
  • Projects and Organizations: Resource management (coming soon)
  • API Passthrough: Direct REST API access for power users (coming soon)
The CLI is built with Go and supports:
  • Linux: x86_64, ARM64
  • macOS: Intel and Apple Silicon (M1/M2)
  • Windows: x86_64
The installation script automatically detects your OS and architecture.
Yes! Harness CLI is open source under the MIT License. You can:
  • View the source code on GitHub
  • Contribute improvements and bug fixes
  • Report issues and request features
See the Contributing guide for more details.

​
Installation and Setup

Quick Install (Recommended):
curl -fsSL https://raw.githubusercontent.com/harness/harness-cli/v2/install | sh
Alternative Methods:
  • Download binary from releases page
  • Build from source: make build
  • Custom installation directory: 
    curl -fsSL https://raw.githubusercontent.com/harness/harness-cli/v2/install | INSTALL_DIR=$HOME/.local/bin sh
Configuration is stored at:
$HOME/.harness/auth.json
This file contains:
  • API base URL
  • Authentication token
  • Account ID
  • Default organization and project (optional)
The file has restricted permissions (0600) for security.
Currently, the CLI supports one authenticated session at a time. To switch accounts:
hc auth logout
hc auth login --api-token <new-token> --account <new-account-id>
For advanced use cases, you can:
  • Use different tokens via command-line flags: 
    hc registry list --token <token> --account <account-id>
  • Maintain multiple configuration files and swap them manually
No. After running hc auth login, your credentials are saved and automatically used for subsequent commands.You only need to re-authenticate if:
  • Your token expires
  • You logout explicitly
  • You switch accounts
  • You want to override saved credentials with command-line flags

​
Authentication

To create an API token:
  1. Log into the Harness platform (https://app.harness.io)
  2. Navigate to your profile settings
  3. Go to “API Keys” or “Personal Access Tokens”
  4. Click “Create Token” or “New API Key”
  5. Give it a name and select appropriate scopes
  6. Copy the generated token (you won’t see it again)
Then use it with the CLI:
hc auth login --api-token <your-token>
The CLI expects tokens in the format:
pat.AccountID.RandomString.RandomString
The CLI automatically extracts the Account ID from this format. If your token format is different, you’ll need to provide the Account ID explicitly:
hc auth login --api-token <token> --account <account-id>
Environment variable support is coming soon. Currently, you can:
  1. Save credentials via hc auth login (recommended)
  2. Use command-line flags: 
    hc registry list --token <token> --account <account-id>
  3. Script token passing: 
    TOKEN=$(cat token.txt)
hc registry list --token $TOKEN --account <account-id>
Use the status command:
hc auth status
This displays:
  • Current authentication state
  • API URL
  • Account ID
  • Organization ID (if set)
  • Project ID (if set)

​
Usage

All CLI commands follow this pattern:
hc [global-flags] <command> <subcommand> [args] [flags]
Examples:
hc auth login
hc registry list --format json
hc artifact push generic my-registry ./file.tar.gz --version 1.0.0
hc artifact list --registry my-registry
See the Command Reference for all available commands.
Add --help or -h to any command:
hc --help                    # All commands
hc registry --help           # Registry commands
hc artifact push --help      # Push command details
Yes! Use the --format flag:
hc registry list --format json
hc artifact list --registry my-reg --format json
This is useful for:
  • Scripting and automation
  • Parsing with tools like jq
  • Integration with other systems
Default format is table for human-readable output.
Use global flags to set scope:
hc registry list --org <org-id> --project <project-id>
You can set defaults during login:
hc auth login --org <org-id> --project <project-id>
Command-line flags always override saved defaults.
Yes! Several commands have shorter aliases:
  • hc reg = hc registry
  • hc art = hc artifact
  • hc proj = hc project
  • hc org = hc organisation
Example:
hc reg list        # Same as: hc registry list
hc art list        # Same as: hc artifact list

​
Artifact Registry

Harness Artifact Registry supports:
  • Docker / OCI containers
  • Generic (any file type)
  • Go modules
  • npm (Node.js)
  • Maven (Java)
  • Python (PyPI)
  • NuGet (.NET)
  • Cargo (Rust)
  • Composer (PHP)
  • Conda (Python/R)
  • Dart (Pub)
  • RPM (Red Hat)
See Package Types for detailed documentation.
Use the artifact push command with the appropriate package type:
# Generic artifacts
hc artifact push generic <registry> <file-path> \
  --name <artifact-name> \
  --version <version>

# Go modules
hc artifact push go <registry> <module-path>

# Other package types
hc artifact push maven <registry> <pom-file>
hc artifact push npm <registry> <package-directory>
See the Artifact Management guide for examples.
Yes! The CLI includes a migration tool for moving artifacts from:
  • JFrog Artifactory
  • Sonatype Nexus
  • Other registries
Create a migration configuration file and run:
hc registry migrate --config migrate-config.yaml
See the Registry Migration guide for details.
To delete all versions of an artifact:
hc artifact delete <artifact-name> --registry <registry-name>
To delete a specific version:
hc artifact delete <artifact-name> \
  --registry <registry-name> \
  --version <version>
Deletions are permanent and cannot be undone. Use with caution.
Yes! Use the configure command for supported package types:
# Configure npm
hc registry configure npm <registry-name>

# More package types coming soon
This updates your local package manager configuration to point to Harness registries.

​
Troubleshooting

Use the --log-file flag to save detailed logs:
hc registry list --log-file debug.log
This captures:
  • API requests and responses
  • Error details
  • Timing information
Useful for diagnosing issues or reporting bugs.
Common causes:
  1. Token expired - Re-authenticate with hc auth login
  2. Invalid token - Verify token in Harness platform
  3. Insufficient permissions - Check token scopes
  4. Wrong account/org/project - Verify with hc auth status
See Troubleshooting - Authentication Errors for detailed solutions.
Possible causes:
  • Network connectivity issues
  • Large artifact transfers
  • High migration concurrency
Solutions:
  • Check network connection to Harness endpoints
  • Reduce migration concurrency: 
    hc registry migrate --config migrate.yaml --concurrency 5
  • Split large operations into smaller batches
See Troubleshooting - Connection Issues.
Resources:

​
Development and Contributing

We welcome contributions! Here’s how:
  1. Fork the repository on GitHub
  2. Create a feature branch
  3. Make your changes
  4. Run tests: make test
  5. Submit a pull request
See the Contributing guide for detailed instructions.
Requirements:
  • Go 1.21 or later
  • Make
Steps:
git clone https://github.com/harness/harness-cli.git
cd harness-cli
make build
The binary will be created as ./hc.
Run the test suite:
make test
Run linter:
make lint
Format code:
make format

harness-cli/
├── api/              # OpenAPI specs for each service
├── cmd/              # CLI commands implementation
│   ├── hc/           # Main CLI entry point
│   ├── auth/         # Authentication commands
│   ├── registry/     # Registry management
│   ├── artifact/     # Artifact management
│   └── ...
├── config/           # Configuration handling
├── internal/         # Internal packages and API clients
├── module/           # Service-specific modules
├── tools/            # Development tools
└── util/             # Utility functions
See the Contributing guide for more details.

​
Still Have Questions?

Contact Support

Check the troubleshooting guide or reach out to the community for help.

Build docs developers (and LLMs) love

Get started for freeTalk to us