Configuration

Harness CLI uses a combination of configuration files, environment variables, and command-line flags to manage settings. Understanding the configuration hierarchy helps you control CLI behavior effectively.

Configuration Structure

The CLI maintains global configuration that applies to all commands:

type GlobalFlags struct {
    APIBaseURL string
    AuthToken  string
    AccountID  string
    OrgID      string
    ProjectID  string
    Format     string
}

Configuration File Location

Authentication and default settings are stored in:

~/.harness/auth.json

The directory is created automatically with 0755 permissions when you first run hc auth login.

Configuration File Format

{
  "base_url": "https://app.harness.io",
  "token": "pat.account_id.random.random",
  "account_id": "my_account",
  "org_id": "my_org",
  "project_id": "my_project"
}

The org_id and project_id fields are optional. If not specified, you can provide them via flags or environment variables when needed.

Configuration Precedence

Configuration values are loaded in this order (later sources override earlier ones):

Default Values

Hard-coded defaults in the application

API URL: https://app.harness.io
Format: table

Configuration File

Values from ~/.harness/auth.json

Environment Variables

Environment variables override config file values

Command-line Flags

Flags have the highest precedence and override everything

Precedence Example

Given this configuration file:

~/.harness/auth.json

{
  "base_url": "https://app.harness.io",
  "account_id": "default_account",
  "org_id": "default_org"
}

And these environment variables:

export HARNESS_ORG_ID="env_org"
export HARNESS_PROJECT_ID="env_project"

This command:

hc registry list --account override_account

Will use:

account_id: override_account (from flag)
org_id: env_org (from environment)
project_id: env_project (from environment)
base_url: https://app.harness.io (from config file)

Global Flags

These flags are available on all commands (except auth, version, and upgrade):

Flag	Type	Description	Default
`--api-url`	string	Base URL for the API	`https://app.harness.io`
`--token`	string	Authentication token	-
`--account`	string	Account identifier	-
`--org`	string	Organization identifier	-
`--project`	string	Project identifier	-
`--format`	string	Output format (`table` or `json`)	`table`
`--verbose`, `-v`	boolean	Enable verbose logging	`false`

Flag Binding

The CLI binds persistent flags directly to the global configuration:

rootCmd.PersistentFlags().StringVar(&config.Global.APIBaseURL, "api-url", "",
    "Base URL for the API (overrides saved config)")
rootCmd.PersistentFlags().StringVar(&config.Global.AuthToken, "token", "",
    "Authentication token (overrides saved config)")
rootCmd.PersistentFlags().StringVar(&config.Global.AccountID, "account", "", 
    "Account (overrides saved config)")
rootCmd.PersistentFlags().StringVar(&config.Global.OrgID, "org", "", 
    "Org (overrides saved config)")
rootCmd.PersistentFlags().StringVar(&config.Global.ProjectID, "project", "", 
    "Project (overrides saved config)")
rootCmd.PersistentFlags().StringVar(&config.Global.Format, "format", "table", 
    "Format of the result")

Environment Variables

The CLI checks these environment variables during startup:

Core Configuration

API Configuration
Authentication
Scope

# Override API endpoint
export HARNESS_API_URL="https://app.harness.io"

# Use a different environment
export HARNESS_API_URL="https://app.eu.harness.io"

# Provide API key via environment
export HARNESS_API_KEY="pat.account.xxx.xxx"

# Set organization context
export HARNESS_ORG_ID="my_org"

# Set project context
export HARNESS_PROJECT_ID="my_project"

Environment Variable Loading

The CLI loads environment variables after the config file:

// Check environment variables (override auth config, flags will override during Execute)
if envVal := os.Getenv("HARNESS_API_URL"); envVal != "" {
    config.Global.APIBaseURL = envVal
}
if envVal := os.Getenv("HARNESS_API_KEY"); envVal != "" {
    config.Global.AuthToken = envVal
}
if envVal := os.Getenv("HARNESS_ORG_ID"); envVal != "" {
    config.Global.OrgID = envVal
}
if envVal := os.Getenv("HARNESS_PROJECT_ID"); envVal != "" {
    config.Global.ProjectID = envVal
}

Scope Configuration

Harness resources are organized hierarchically:

Account
  └── Organization
        └── Project
              └── Resources (Registries, Pipelines, etc.)

Account-level Resources

For account-level operations, only account_id is required:

hc registry list --account my_account

Organization-level Resources

For org-level operations, provide both account_id and org_id:

hc registry list --account my_account --org my_org

Project-level Resources

For project-level operations, provide all three identifiers:

hc registry list \
  --account my_account \
  --org my_org \
  --project my_project

You can save default scope in the config file during hc auth login to avoid repeating these flags.

Output Format Configuration

Control output format globally or per-command:

Global Setting

# Set default format in config file
hc auth login  # During setup, or edit ~/.harness/auth.json

# Use environment variable
export HARNESS_FORMAT="json"

# Use flag on every command
hc registry list --format json

Format Options

Table Format

Human-readable boxed tables (default)

--format table

JSON Format

Machine-readable JSON output

--format json

See Output Formats for detailed examples.

Configuration Loading Flow

Configuration for Different Environments

Development
Production
Europe

# Set up for development environment
export HARNESS_API_URL="https://app.dev.harness.io"
export HARNESS_API_KEY="$DEV_TOKEN"

hc registry list

# Set up for production environment
export HARNESS_API_URL="https://app.harness.io"
export HARNESS_API_KEY="$PROD_TOKEN"

hc registry list

# Set up for European instance
export HARNESS_API_URL="https://app.eu.harness.io"
export HARNESS_API_KEY="$EU_TOKEN"

hc registry list

Verbose Logging

Enable detailed logging for troubleshooting:

hc registry list --verbose

When verbose mode is enabled:

Logs are written to stderr in console format
HTTP requests and responses are logged
Timestamps are included (RFC3339 format)
Errors include stack traces

The logging implementation:

if verbose {
    logWriter := zerolog.ConsoleWriter{
        Out:        os.Stderr,
        TimeFormat: time.RFC3339,
        NoColor:    false,
    }
    log.Logger = log.Output(logWriter)
} else {
    // Disable logging when verbose is not enabled
    log.Logger = zerolog.Nop()
}

Command-specific Configuration

Some commands have additional configuration stored in the global config:

type GlobalFlags struct {
    // ... common flags ...
    
    // Command-specific configurations
    Registry RegistryConfig
}

type RegistryConfig struct {
    PkgURL string
    Migrate MigrateConfig
    Status StatusConfig
}

These are typically set via command-specific flags.

Best Practices

Use Config File for Defaults

Save your most common settings in ~/.harness/auth.json to avoid repetitive flags.

Use Environment Variables for CI/CD

Set credentials and settings via environment variables in automated pipelines.

Use Flags for Overrides

Use command-line flags when you need to temporarily override settings.

Separate Environments

Use different environment variable sets or config files for different Harness environments.

Troubleshooting

Which configuration is being used?

Run any command with --verbose to see the configuration values being used:

hc registry list --verbose

Configuration file not found

If the config file doesn’t exist, run:

hc auth login

This creates ~/.harness/auth.json with your credentials.

Settings not taking effect

Remember the precedence order:

Flags (highest)
Environment variables
Config file
Defaults (lowest)

Check if a higher-precedence source is overriding your setting.

How to reset configuration?

Remove the configuration file:

rm ~/.harness/auth.json

Then run hc auth login to create a fresh configuration.

Get Started

Core Concepts

Guides

Configuration Structure

Configuration File Location

Configuration File Format

Configuration Precedence

Precedence Example

Global Flags

Flag Binding

Environment Variables

Core Configuration

Environment Variable Loading

Scope Configuration

Account-level Resources

Organization-level Resources

Project-level Resources

Output Format Configuration

Global Setting

Format Options

Table Format

JSON Format

Configuration Loading Flow

Configuration for Different Environments

Verbose Logging

Command-specific Configuration

Best Practices

Use Config File for Defaults

Use Environment Variables for CI/CD

Use Flags for Overrides

Separate Environments

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Configuration Structure

​Configuration File Location

​Configuration File Format

​Configuration Precedence

​Precedence Example

​Global Flags

​Flag Binding

​Environment Variables

​Core Configuration

​Environment Variable Loading

​Scope Configuration

​Account-level Resources

​Organization-level Resources

​Project-level Resources

​Output Format Configuration

​Global Setting

​Format Options

Table Format

JSON Format

​Configuration Loading Flow

​Configuration for Different Environments

​Verbose Logging

​Command-specific Configuration

​Best Practices

Use Config File for Defaults

Use Environment Variables for CI/CD

Use Flags for Overrides

Separate Environments

​Troubleshooting

Build docs developers (and LLMs) love

Configuration Structure

Configuration File Location

Configuration File Format

Configuration Precedence

Precedence Example

Global Flags

Flag Binding

Environment Variables

Core Configuration

Environment Variable Loading

Scope Configuration

Account-level Resources

Organization-level Resources

Project-level Resources

Output Format Configuration

Global Setting

Format Options

Configuration Loading Flow

Configuration for Different Environments

Verbose Logging

Command-specific Configuration

Best Practices

Troubleshooting