> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/authenticate-the-harness-cli.md).

# Authenticate the Harness CLI

Authenticate the Harness CLI interactively, with SSO, with environment variables for CI, or with named profiles.

Log in to the Harness CLI, manage named profiles, set up authentication for CI, and enable shell completions.

The Harness CLI must be authenticated before it can access Harness resources. You can authenticate interactively for local development, use environment variables in automated environments, or manage multiple accounts and environments with named profiles.

### What you will learn in this topic

By the end of this page, you will know how to:

* Log in and create your first profile.
* Log in through your browser with single sign-on (SSO), and refresh or inspect an SSO token.
* Pass credentials through environment variables for CI and scripts.
* Create, list, switch, and remove named profiles.
* Set a default organization and project for a profile.
* Print the active auth context and API token for use in other tooling.
* Enable tab-completion for Bash and Zsh.
* Troubleshoot a browser login flow with SSO debug logging.

### Before you begin

* **Harness CLI installed:** To install the CLI, review [Install and upgrade](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/overview.md).
* **API key:** A Harness Personal Access Token (PAT) or Service Account token. Generate one from **My Profile** > **API Keys** or from a Service Account in the Harness UI.

### Log in

Run the login command to authenticate your CLI:

```shell
harness auth login
```

This command launches an interactive TUI wizard to collect your API URL, PAT or SAT token, account ID, and optional default organization and project. The CLI stores credentials and profile configuration locally for future use.

Confirm your authentication:

```shell
harness auth status
```

To authenticate through a browser with SSO instead of a PAT or SAT token, review [Login with SSO (single sign-on)](#login-with-sso).

### Named profiles

To create a profile for a different account or environment, pass the `--profile` flag:

```shell
harness auth login --profile staging 
harness auth login --profile prod
```

### Non-interactive login

Log in without an interactive prompt by passing all values as flags. This is the recommended approach for CI pipelines:

```shell
harness auth login \ 
  --profile ci \ 
  --api-url  app.harness.io \ 
  --api-token "$HARNESS_API_KEY" \ 
  --account "$HARNESS_ACCOUNT" \ 
  --org default \ 
  --project my_project
```

For a fully non-interactive login, pass the API URL and token together:

```shell
harness auth login --api-url "$HARNESS_API_URL" --api-token "$HARNESS_API_KEY"
```

The CLI resolves credentials in the following order: `--profile`, `HARNESS_API_KEY`, `HARNESS_PROFILE`, CI runner auto-detection, and the default profile in `~/.harness/config.yaml`. The first valid source is used.

### Login with SSO

Add `--sso` to authenticate through your browser with OAuth2 instead of pasting a token. Where the operating system provides a keychain, the CLI stores the resulting tokens there rather than on disk.

```shell
harness auth login --sso 
harness auth login --sso --profile prod
```

### Check SSO token status

Show the token expiry and refresh status for the active profile.

```shell
harness auth sso_status --profile prod
```

### Refresh SSO token

Exchange the stored refresh token for a new access token. Run this when an SSO access token has expired but the session is still valid.

```shell
harness auth sso_refresh
```

### Troubleshooting

If a browser login does not complete, emit SSO auth debug events and retry the login.

```shell
harness debug sso-log
```

### Set environment variables

For CI pipelines, Docker containers, and automated scripts, set these environment variables instead of logging in interactively:

| Variable                  | Description                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------- |
| `HARNESS_API_KEY`         | API token. Takes precedence over any saved profile.                                 |
| `HARNESS_ACCOUNT`         | Account ID. Required together with `HARNESS_API_KEY` for environment variable auth. |
| `HARNESS_PROFILE`         | Name of the saved profile to use. Same effect as `--profile <name>`.                |
| `HARNESS_ORG`             | Default org for commands that need one. Overridden by `--org`.                      |
| `HARNESS_DEFAULT_PROJECT` | Default project for commands that need one. Overridden by `--project`.              |
| `HARNESS_API_URL`         | Override the API URL. Typically only needed for self-hosted Harness deployments.    |

When `HARNESS_API_KEY` is set, it takes precedence over any saved profile. To review the full list of environment variables including output and behavior controls, review [Global flags and output](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/global-flags-and-output-formats.md#environment-variables).

Environment variables are typically the preferred authentication method for CI/CD pipelines and other automated environments because they avoid storing credentials on disk.

```shell
export HARNESS_API_KEY=pat.xxxxxxxxxxxxxxxxxx 
export HARNESS_ACCOUNT=ZJL7VBAhRq6Pf9G4f5OqLg 
export HARNESS_ORG=default 
export HARNESS_PROJECT=my_project 

harness list pipeline
```

### Manage profiles

A profile is a named set of credentials and default organization and project settings. Most teams maintain separate profiles for development, staging, and production environments.

#### List and inspect

```shell
harness auth profiles                       # List every saved profile 
harness auth status                         # Show the active profile 
harness auth status --profile staging       # Inspect a specific profile
```

#### Switch between profiles

Use a profile for a single command:

```shell
harness list pipeline --profile prod
```

Pin a profile for the entire shell session:

```shell
export HARNESS_PROFILE=prod 
harness list pipeline   # Uses the prod profile
```

### Set a default organization and project

Set the default organization and project for a profile so you do not need to pass them on every command:

```shell
harness auth setscope --org my-org --project my-project 
harness auth setscope --org my-org --project my-project --profile staging
```

Run `harness auth setscope` without flags to launch an interactive picker.

### Log out

Remove a profile and its stored credentials:

```shell
harness auth logout 
harness auth logout --profile staging
```

### Export the auth context

Two commands print the active credentials so that other tooling can consume them.

#### Print environment variables

Print the environment variables for the current auth context. Add `--export` to produce output you can pass to `eval`.

```shell
harness auth env 
eval "$(harness auth env --export)"
```

#### Print the API token

Print the active API token to stdout. Use this to pipe the token into another tool, such as `curl`.

{% hint style="warning" %}
`harness auth token` writes a live credential to stdout. Do not log its output or store it in a file that is committed to version control.
{% endhint %}

```shell
harness auth token 
curl -H "x-api-key: $(harness auth token)" <harness_api_url>
```

### Configuration files

The CLI stores its configuration in two local files.

* The `~/.harness/config.yaml` file stores profiles, account IDs, default org and project.
* The `~/.harness/credentials` file stores API tokens per profile. These tokens are never logged or printed.

Override the config directory with the `HARNESS_CONFIG_HOME` environment variable.

### Shell completions

Tab-completion covers actions, resources, flags, and live identifiers fetched from the API.

#### Zsh

```shell
source <(harness completion zsh)
```

Add to `.zshrc` for persistence:

```shell
echo 'source <(harness completion zsh)' >> ~/.zshrc
```

#### Bash

```shell
source <(harness completion bash)
```

Add to `.bashrc` for persistence:

```shell
echo 'source <(harness completion bash)' >> ~/.bashrc
```

Shell completion supports actions, resources, identifiers, flags, and valid flag values. Resource identifiers are retrieved dynamically from the Harness API.

### Related articles

Continue with the following pages to go deeper on CLI usage.

* [Supported resources and actions](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/supported-resources-and-actions.md): Review every supported resource and action.
* [Global flags and output](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/global-flags-and-output-formats.md): Understand output formats, filtering, and pagination.
