Skip to main content
This guide will take you from zero to running your first successful commands with the Harness CLI. You’ll install the tool, authenticate with Harness, and execute common operations.
This quickstart takes approximately 5 minutes to complete.

​
Prerequisites

Before you begin, make sure you have:
  • A Harness account (sign up at app.harness.io)
  • A Harness API token (you’ll generate this during authentication)
  • Terminal access on Linux, macOS, or Windows

​
Step 1: Install the CLI

Install the Harness CLI using our quick install script: 
curl -fsSL https://raw.githubusercontent.com/harness/harness-cli/v2/install | sh
For Windows or other installation methods, see our complete installation guide.
Verify the installation: 
hc version
You should see output showing the version and Go build information: 
hc version 2.0.0
Built with go1.21.0

​
Step 2: Authenticate with Harness

The CLI needs to authenticate with your Harness account. You can do this interactively or with flags. Run the login command and follow the prompts: 
hc auth login
You’ll be prompted for:
1

API URL

Press Enter to use the default (https://app.harness.io) or enter your custom Harness instance URL.
API URL [https://app.harness.io]:
2

API Token

Enter your Harness API token. To generate one:
  1. Go to app.harness.io
  2. Click your profile icon → My API Keys
  3. Click + API Key → + Token
  4. Give it a name and click Generate Token
  5. Copy the token (it won’t be shown again)
API Token: ****************************************
The token format is pat.AccountID.Random.Random. The CLI automatically extracts your account ID from the token.
3

Organization and Project (optional)

If you work within a specific organization or project, you can set defaults:
Organization ID (optional): my-org
Project ID (optional): my-project
These can be overridden per command with --org and --project flags.
The CLI validates your credentials and saves the configuration: 
Validating credentials...
✓ Credentials validated successfully
Successfully logged into Harness
API URL:      https://app.harness.io
Account ID:   abc123xyz
Your credentials are saved to ~/.harness/auth.json with permissions set to 0600 (owner read/write only) for security.

​
Non-interactive authentication

For automation and CI/CD pipelines, you can provide credentials via flags: 
hc auth login \
  --api-url https://app.harness.io \
  --api-token pat.abc123.xyz789.def456 \
  --account abc123 \
  --non-interactive
Or use environment variables: 
export HARNESS_API_URL="https://app.harness.io"
export HARNESS_API_KEY="pat.abc123.xyz789.def456"

hc auth login --non-interactive

​
Verify authentication

Check your authentication status: 
hc auth status
This shows your current configuration and validates that your credentials are working.

​
Step 3: Run your first commands

Now that you’re authenticated, let’s explore what you can do with the CLI.

​
List artifact registries

See all registries in your account: 
hc registry list
Example output: 
+-----------------+--------------+----------+---------------+
| Registry        | Package Type | Size     | Registry Type |
+-----------------+--------------+----------+---------------+
| docker-prod     | DOCKER       | 12.5 GB  | VIRTUAL       |
| npm-internal    | NPM          | 2.3 GB   | HOSTED        |
| maven-releases  | MAVEN        | 8.7 GB   | VIRTUAL       |
+-----------------+--------------+----------+---------------+
Use --format=json to get machine-readable output for scripting:
hc registry list --format=json

​
Get registry details

View detailed information about a specific registry: 
hc registry get docker-prod

​
List artifacts

See all artifacts across registries: 
hc artifact list
Or filter by registry: 
hc artifact list --registry docker-prod
Example output: 
+------------------+---------+--------------+-------------+
| Artifact         | Version | Package Type | Registry    |
+------------------+---------+--------------+-------------+
| myapp/backend    | 1.2.3   | DOCKER       | docker-prod |
| myapp/frontend   | 1.2.3   | DOCKER       | docker-prod |
| shared-library   | 2.0.1   | NPM          | npm-internal|
+------------------+---------+--------------+-------------+

​
Push an artifact

Upload a generic artifact to a registry: 
hc artifact push generic my-registry ./app.zip \
  --name myapp \
  --version 1.0.0 \
  --pkg-url https://app.harness.io/har/api/v1
The --pkg-url flag is required for push operations. It points to your Harness package API endpoint.
The CLI shows a progress bar during upload: 
Uploading file: ./app.zip
Uploading generic file 'app.zip' to path 'app.zip' (version '1.0.0') in registry 'my-registry'...
[████████████████████████████████] 100% (2.3 MB/2.3 MB)
Successfully uploaded generic file 'app.zip' to path 'app.zip' (version '1.0.0') in registry 'my-registry'

​
Using different output formats

All list and get commands support table (default) or JSON output: 
hc registry list --format=table
JSON output is useful for scripting and automation: 
# Get registry count
hc registry list --format=json | jq '.data.itemCount'

# Extract registry identifiers
hc registry list --format=json | jq -r '.data.registries[].identifier'

​
Common workflows

Now that you know the basics, here are some common workflows: 
# List all registries
hc registry list

# Filter by package type
hc registry list --package-type DOCKER

# Get detailed information
hc registry get my-registry

# Delete a registry
hc registry delete my-registry

# List artifacts in a specific registry
hc artifact list --registry my-registry

# Get artifact details
hc artifact get myapp --registry my-registry

# Delete an artifact (all versions)
hc artifact delete myapp --registry my-registry

# Delete a specific version
hc artifact delete myapp --registry my-registry --version 1.0.0
The CLI supports multiple package types. Here are some examples:
hc artifact push generic my-registry ./file.zip \
  --name myapp \
  --version 1.0.0 \
  --pkg-url https://app.harness.io/har/api/v1

# Pull a generic artifact
hc artifact pull generic my-registry myapp/1.0.0/app.zip ./downloads

# The file will be saved to ./downloads/app.zip

​
Using global flags

All commands support global flags that override your saved configuration: 
# Override account for a single command
hc registry list --account different-account

# Use a different organization
hc artifact list --org another-org --project another-project

# Get JSON output
hc registry list --format=json

# Enable verbose logging for debugging
hc registry list --verbose
Configuration precedence (highest to lowest):
  1. Command-line flags
  2. Environment variables
  3. Configuration file (~/.harness/auth.json)

​
Troubleshooting

If you see “Not logged in. Please run ‘hc auth login’ first”:
  1. Run hc auth login to authenticate
  2. Or provide credentials via environment variables or flags
Check your authentication:
hc auth status
If credential validation fails:
  1. Verify your API token is still valid in the Harness UI
  2. Check that you’re using the correct API URL
  3. Ensure your token has the necessary permissions
Generate a new token if needed:
hc auth logout
hc auth login
If you get “command not found: hc”:
  1. Verify installation: which hc
  2. Check that /usr/local/bin is in your PATH
  3. Try reinstalling or installing to a custom directory
Add to PATH if needed:
export PATH="/usr/local/bin:$PATH"
For detailed debugging information, use the --verbose flag:
hc registry list --verbose
This shows HTTP requests, responses, and internal operations.

​
Next steps

You’re now ready to explore the full power of the Harness CLI:

Authentication concepts

Learn about advanced authentication methods and security best practices.

Configuration guide

Configure the CLI for your workflow with profiles and environment variables.

Registry migration

Migrate artifacts from external registries to Harness.

Command reference

Explore the complete command reference with all options and examples.
Need help? Check our troubleshooting guide or FAQ.

Build docs developers (and LLMs) love

Get started for freeTalk to us