Global Flags

Overview

Global flags (also called persistent flags) are available to all hc commands. They control authentication, API endpoints, and output formatting. These flags override values from your saved configuration file and environment variables.

Configuration Precedence

Configuration values are resolved in the following order (highest precedence first):

Command-line flags - Flags passed directly to the command
Environment variables - Shell environment variables
Config file - Saved authentication configuration (~/.harness/auth.json)

Each level overrides the previous levels.

Command-line flags always take precedence. Use them to temporarily override your saved configuration without modifying the config file.

Available Global Flags

Authentication Flags

--api-url

string

Base URL for the Harness API. This is typically https://app.harness.io for SaaS or your self-hosted Harness URL.Environment variable: HARNESS_API_URLConfig file field: base_url

# SaaS
hc registry list --api-url https://app.harness.io

# Self-hosted
hc registry list --api-url https://harness.company.com

Don’t include a trailing slash in the URL.

--token

string

Authentication token (API key) for authenticating with Harness. You can generate an API key in the Harness UI under Account Settings → Access Control → API Keys.Environment variable: HARNESS_API_KEYConfig file field: token

hc registry list --token sat.abc123.xyz789...

Keep your token secure. Don’t commit it to version control or share it publicly.

--account

string

Harness account identifier. This is automatically extracted from your authentication token when you run hc auth login, but you can override it with this flag.Environment variable: None (automatically derived from token)Config file field: account_id

hc registry list --account myAccountId

Scope Flags

--org

string

Organization identifier. Required for operations that are scoped to an organization. Some commands (like IACM) have a separate --org-id flag that takes precedence.Environment variable: HARNESS_ORG_IDConfig file field: org_id

hc registry list --org engineering

--project

string

Project identifier. Required for operations that are scoped to a project. Some commands (like IACM) have a separate --project-id flag that takes precedence.Environment variable: HARNESS_PROJECT_IDConfig file field: project_id

hc registry list --project infrastructure

Output Flags

--format

string

default:"table"

Format for command output. Determines how results are displayed.Supported values:

table - Human-readable table format (default)
json - JSON output for parsing
Other formats may be supported by specific commands

Config file field: None (always defaults to table)

# Table format (default)
hc registry list --format table

# JSON format
hc registry list --format json

Use --format json when piping output to other tools like jq for processing.

--verbose

boolean

Enable verbose logging to console. Shows detailed debug information including HTTP requests, responses, and timing information.Config file field: None (always defaults to false)

# Short form
hc registry list -v

# Long form
hc registry list --verbose

Verbose output is sent to stderr, while normal output goes to stdout. This allows you to redirect results while still seeing debug logs.

Examples

Using Saved Configuration

After running hc auth login, your configuration is saved:

# Uses saved config from ~/.harness/auth.json
hc registry list

Overriding with Flags

# Override org and project for one command
hc registry list --org different-org --project different-project

# Your saved config remains unchanged

Using Environment Variables

export HARNESS_API_URL=https://app.harness.io
export HARNESS_API_KEY=sat.abc123.xyz789...
export HARNESS_ORG_ID=engineering
export HARNESS_PROJECT_ID=backend

# Commands now use these values
hc registry list
hc iacm plan --workspace-id prod

Combining Methods

# Environment variables provide defaults
export HARNESS_ORG_ID=engineering
export HARNESS_PROJECT_ID=backend

# Flag overrides environment variable for this command only
hc iacm plan --workspace-id staging --project frontend

# Next command uses environment variable again
hc registry list  # Uses project=backend from env

Different Environments

# Production
hc registry list \
  --api-url https://app.harness.io \
  --token $PROD_TOKEN \
  --org production \
  --project core

# Staging  
hc registry list \
  --api-url https://app.harness.io \
  --token $STAGING_TOKEN \
  --org staging \
  --project core

# Self-hosted
hc registry list \
  --api-url https://harness.company.com \
  --token $INTERNAL_TOKEN \
  --org internal \
  --project infrastructure

Debugging with Verbose Mode

# See detailed HTTP requests and responses
hc iacm plan --workspace-id prod --verbose

# Output includes:
# - Request URLs and headers
# - Response status codes
# - Response bodies
# - Timing information

JSON Output for Automation

# Parse output with jq
hc registry list --format json | jq '.[] | select(.name == "my-registry")'

# Save output to file
hc registry list --format json > registries.json

# Use in scripts
REGISTRY_COUNT=$(hc registry list --format json | jq 'length')
echo "Found $REGISTRY_COUNT registries"

Configuration File

The configuration file is stored at ~/.harness/auth.json:

{
  "base_url": "https://app.harness.io",
  "token": "sat.abc123.xyz789...",
  "account_id": "myAccountId",
  "org_id": "engineering",
  "project_id": "infrastructure"
}

This file contains sensitive credentials. Ensure it has appropriate permissions:

chmod 600 ~/.harness/auth.json

Creating Config File

The easiest way to create the config file is with hc auth login:

hc auth login
# Follow the prompts to authenticate

Alternatively, create it manually:

mkdir -p ~/.harness
cat > ~/.harness/auth.json <<EOF
{
  "base_url": "https://app.harness.io",
  "token": "your-token-here",
  "account_id": "your-account-id",
  "org_id": "your-org",
  "project_id": "your-project"
}
EOF
chmod 600 ~/.harness/auth.json

Updating Config File

You can update the config file in several ways:

Run hc auth login again - Re-authenticates and updates the file
Edit manually - Open ~/.harness/auth.json in a text editor
Use environment variables - Override without modifying the file

Environment Variables Reference

HARNESS_API_URL

string

Overrides base_url from config file. Sets the API base URL.

export HARNESS_API_URL=https://app.harness.io

HARNESS_API_KEY

string

Overrides token from config file. Sets the authentication token.

export HARNESS_API_KEY=sat.abc123.xyz789...

HARNESS_ORG_ID

string

Overrides org_id from config file. Sets the default organization.

export HARNESS_ORG_ID=engineering

HARNESS_PROJECT_ID

string

Overrides project_id from config file. Sets the default project.

export HARNESS_PROJECT_ID=infrastructure

Resolution Examples

Here’s how different configuration methods interact:

Example 1: Flag Overrides Everything

# Config file
cat ~/.harness/auth.json
# { "org_id": "production", ... }

# Environment
export HARNESS_ORG_ID=staging

# Command with flag
hc registry list --org development

# Result: Uses org=development (flag wins)

Example 2: Environment Overrides Config

# Config file
cat ~/.harness/auth.json
# { "org_id": "production", ... }

# Environment
export HARNESS_ORG_ID=staging

# Command without flag
hc registry list

# Result: Uses org=staging (environment wins)

Example 3: Config as Fallback

# Config file
cat ~/.harness/auth.json
# { "org_id": "production", ... }

# No environment variable set
# Command without flag
hc registry list

# Result: Uses org=production (config is used)

Example 4: Partial Override

# Config file has both org and project
cat ~/.harness/auth.json
# { "org_id": "production", "project_id": "backend", ... }

# Override only org
hc registry list --org staging

# Result: Uses org=staging, project=backend
# (only org is overridden, project comes from config)

Best Practices

Security

Use config file for development: Store credentials securely in ~/.harness/auth.json
Use environment variables for CI/CD: Set HARNESS_API_KEY and other vars in your CI system
Never commit tokens: Add auth.json to .gitignore
Rotate tokens regularly: Generate new API keys periodically
Use service accounts: Create dedicated service accounts for automation

Organization

Set defaults in config: Put your most-used org/project in the config file
Override with flags when needed: Use flags for one-off commands in different scopes
Use environment variables for scripts: Set env vars at the top of scripts for clarity

Debugging

Enable verbose mode: Use --verbose when troubleshooting API issues
Check precedence: Remember flags > env vars > config file
Verify config file: Check ~/.harness/auth.json if authentication fails

Troubleshooting

Not logged in. Please run 'hc auth login' first

Authentication failed / Invalid token

Your token may have expired or been revoked:

Generate a new API key in Harness UI
Run hc auth login with the new token
Or update ~/.harness/auth.json manually

Organization/Project not found

Verify the org/project identifiers are correct:

# Check what you're using
cat ~/.harness/auth.json

# Try with explicit flags
hc registry list --org correct-org --project correct-project

Identifiers are case-sensitive and must match exactly.

Config file not being used

Check that:

File exists: ls -la ~/.harness/auth.json
File is valid JSON: cat ~/.harness/auth.json | jq
Environment variables aren’t overriding it: env | grep HARNESS

Environment variable not working

Make sure the variable is exported:

# Wrong - only sets for current command
HARNESS_ORG_ID=engineering hc registry list

# Correct - exports for all subsequent commands
export HARNESS_ORG_ID=engineering
hc registry list

Authentication

Registry

Artifact

Infrastructure as Code

Global Options

Utility Commands

Overview

Configuration Precedence

Available Global Flags

Authentication Flags

Scope Flags

Output Flags

Examples

Using Saved Configuration

Overriding with Flags

Using Environment Variables

Combining Methods

Different Environments

Debugging with Verbose Mode

JSON Output for Automation

Configuration File

Creating Config File

Updating Config File

Environment Variables Reference

Resolution Examples

Example 1: Flag Overrides Everything

Example 2: Environment Overrides Config

Example 3: Config as Fallback

Example 4: Partial Override

Best Practices

Security

Organization

Debugging

Troubleshooting

See Also

Build docs developers (and LLMs) love

Authentication

Registry

Artifact

Infrastructure as Code

Global Options

Utility Commands

​Overview

​Configuration Precedence

​Available Global Flags

​Authentication Flags

​Scope Flags

​Output Flags

​Examples

​Using Saved Configuration

​Overriding with Flags

​Using Environment Variables

​Combining Methods

​Different Environments

​Debugging with Verbose Mode

​JSON Output for Automation

​Configuration File

​Creating Config File

​Updating Config File

​Environment Variables Reference

​Resolution Examples

​Example 1: Flag Overrides Everything

​Example 2: Environment Overrides Config

​Example 3: Config as Fallback

​Example 4: Partial Override

​Best Practices

​Security

​Organization

​Debugging

​Troubleshooting

​See Also

Build docs developers (and LLMs) love

Overview

Configuration Precedence

Available Global Flags

Authentication Flags

Scope Flags

Output Flags

Examples

Using Saved Configuration

Overriding with Flags

Using Environment Variables

Combining Methods

Different Environments

Debugging with Verbose Mode

JSON Output for Automation

Configuration File

Creating Config File

Updating Config File

Environment Variables Reference

Resolution Examples

Example 1: Flag Overrides Everything

Example 2: Environment Overrides Config

Example 3: Config as Fallback

Example 4: Partial Override

Best Practices

Security

Organization

Debugging

Troubleshooting

See Also