Skip to main content
Harness CLI uses API tokens to authenticate with Harness services. Authentication credentials are stored locally and used for all subsequent commands.

​
Authentication Methods

The CLI supports three ways to provide authentication credentials, in order of precedence:
1

Command-line flags

Flags override all other configuration sources
2

Environment variables

Environment variables override the config file
3

Configuration file

Stored credentials from hc auth login

​
Configuration File

When you run hc auth login, credentials are saved to ~/.harness/auth.json: 
{
  "base_url": "https://app.harness.io",
  "token": "pat.account_id.random.random",
  "account_id": "your_account_id",
  "org_id": "optional_org_id",
  "project_id": "optional_project_id"
}
The config file is created with 0600 permissions (read/write for owner only) to protect your credentials.

​
Authentication Commands

​
Login

Authenticate with Harness and save credentials: 
# Prompts for all required information
hc auth login
The login command:
  1. Validates credentials by calling the Harness API
  2. Extracts the account ID from the token (format: pat.AccountID.Random.Random)
  3. Saves the configuration to ~/.harness/auth.json

​
Check Status

Verify your authentication status: 
hc auth status
Example output: 
Checking authentication status...
Authentication Status: ✓ Authenticated
API URL:      https://app.harness.io
Account ID:   my_account_id
Org ID:       my_org
Project ID:   my_project

​
Logout

Remove saved credentials: 
hc auth logout
This deletes the ~/.harness/auth.json file and clears the session.

​
Environment Variables

You can override configuration file values using environment variables:
Environment VariableDescriptionConfig File Field
HARNESS_API_URLBase URL for the APIbase_url
HARNESS_API_KEYAuthentication tokentoken
HARNESS_ORG_IDOrganization identifierorg_id
HARNESS_PROJECT_IDProject identifierproject_id
export HARNESS_API_URL="https://app.harness.io"
export HARNESS_API_KEY="pat.account.xxx.xxx"
export HARNESS_ORG_ID="my_org"
export HARNESS_PROJECT_ID="my_project"

​
Command-line Flags

Flags provide the highest precedence and override both environment variables and the config file: 
hc registry list \
  --api-url https://app.harness.io \
  --token pat.account.xxx.xxx \
  --account my_account_id \
  --org my_org \
  --project my_project
Available flags (on all commands):
  • --api-url: Base URL for the API
  • --token: Authentication token
  • --account: Account identifier
  • --org: Organization identifier
  • --project: Project identifier

​
Precedence Order

When the CLI loads configuration, it follows this precedence (highest to lowest):
If no authentication is configured through any method, the CLI will display:
Not logged in. Please run 'hc auth login' first.

​
Token Format

Harness personal access tokens follow this format: 
pat.{AccountID}.{Random}.{Random}
The CLI automatically extracts the account ID from the token, so you typically don’t need to provide the --account flag during login.

​
API Validation

During login, the CLI validates credentials by making a GET request to: 
{api_url}/ng/api/accounts/{account_id}
The request includes:
  • Header: x-api-key: {token}
  • Timeout: 10 seconds
If validation fails, you’ll see an error message: 
authentication failed with status 401. Please check your credentials

​
CI/CD Usage

For CI/CD pipelines, use environment variables instead of hc auth login: 
env:
  HARNESS_API_URL: https://app.harness.io
  HARNESS_API_KEY: ${{ secrets.HARNESS_TOKEN }}
  HARNESS_ACCOUNT_ID: ${{ secrets.HARNESS_ACCOUNT }}

steps:
  - name: List registries
    run: hc registry list
Store tokens as secrets in your CI/CD platform. Never commit tokens to version control.

​
Security Best Practices

  1. Protect your config file: The CLI sets ~/.harness/auth.json with 0600 permissions
  2. Use environment variables in CI/CD: Don’t save credentials to files in automated environments
  3. Rotate tokens regularly: Generate new API tokens periodically
  4. Use minimal permissions: Create tokens with only the permissions needed
  5. Never commit credentials: Add .harness/ to your .gitignore

​
Troubleshooting

Run hc auth login to authenticate, or set environment variables:
export HARNESS_API_KEY="your_token"
export HARNESS_API_URL="https://app.harness.io"
Your token may be invalid or expired. Generate a new token from the Harness UI:
  1. Go to Account Settings → Access Control → API Keys
  2. Create a new Personal Access Token
  3. Run hc auth login with the new token
Your token format is invalid. Harness tokens should follow the format: pat.{AccountID}.{Random}.{Random}
Run with the --verbose flag to see configuration details:
hc auth status --verbose

Build docs developers (and LLMs) love

Get started for freeTalk to us