> 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/global-flags-and-output-formats.md).

# Global flags and output formats

Reference for the global flags, output formats, pagination, environment variables, and exit codes shared across all Harness CLI commands.

Learn how to use global flags to control scope, output format, pagination, and behavior across all Harness CLI commands.

The Harness CLI provides a set of flags that work consistently across commands. Use these flags to control scope, output formatting, pagination, and command behavior. This page serves as a reference for the shared flags available throughout the CLI.

***

## What you will learn in this topic

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

* Control the account, organization, and project scope of commands.
* Switch between supported output formats.
* Customize which fields appear in command output.
* Paginate through large result sets or retrieve all results.
* Configure the CLI using environment variables.
* Interpret CLI exit codes in scripts and CI pipelines.

***

## Before you begin

* **Harness CLI installed and authenticated**: Go to [Install and upgrade](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/overview.md) and [Authenticate](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/authenticate-the-harness-cli.md) for setup steps.

***

## Scope flags

Use scope flags to control which account, organization, and project a command operates against. The CLI resolves scope in the following order: command-line flags, profile defaults, and then environment variables.

| Flag                            | Description                                                   |
| ------------------------------- | ------------------------------------------------------------- |
| `--profile <name>`              | Use a specific authentication profile.                        |
| `--org <id>`                    | Override the organization defined in the active profile.      |
| `--project <id>`                | Override the project defined in the active profile.           |
| `--level account\|org\|project` | Specify the scope for resources that support multiple levels. |

```shell
harness list secret --level account 
harness list pipeline --org platform --project production 
harness list connector --level org --org platform --profile prod
```

***

## Output formats for list commands

By default, `list` commands display results in a table. You can use the `--format` flag to produce machine-readable output or export data for external tools.

| Format     | Use case                                 | Notes                              |
| ---------- | ---------------------------------------- | ---------------------------------- |
| `table`    | Interactive terminal use                 | Default format for `list` commands |
| `json`     | Integration with tools that consume JSON | Returns a formatted JSON array     |
| `jsonl`    | Streaming and line-based processing      | Outputs one JSON object per line   |
| `csv`      | Spreadsheet and reporting tools          | Includes a header row              |
| `tsv`      | Tab-delimited processing                 | Includes a header row              |
| `markdown` | Documentation, pull requests, and wikis  | Renders output as a Markdown table |

```shell
harness list pipeline --format json 
harness list pipeline --format jsonl | jq -r '.id' 
harness list pipeline --format csv > pipelines.csv 
harness list pipeline --json
```

### Customize columns

You can use `--columns` flag to control which columns appear in list output.

Run the `--list-columns` command to view the available columns for a resource.

```shell
harness list pipeline --list-columns 
harness list pipeline --columns "name,id,project,lastRun" 
harness list pipeline --columns "+lastRun" 
harness list pipeline --columns "Name:it.name"
```

***

## Output formats for get, create, and update commands

Commands that operate on a single resource default to human-readable text output. Use the following flags to change the format or save output to a file.

| Flag                        | Description                                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--format text\|json\|yaml` | Output format. Default is `text`.                                                                                                     |
| `--json`                    | Shorthand for `--format json`.                                                                                                        |
| `--yaml`                    | Shorthand for `--format yaml`.                                                                                                        |
| `--fields <names>`          | Print only the specified comma-separated field names, tab-separated on output. Run `--list-fields` to discover available field names. |
| `--list-fields`             | Display available field identifiers and exit.                                                                                         |
| `--raw`                     | Return the complete API response envelope (JSON output only).                                                                         |
| `-o`, `--out <path>`        | Write output to a file instead of standard output.                                                                                    |

```shell
harness get pipeline my-pipeline --format json 
harness get pipeline my-pipeline --raw --format json 
harness get pipeline my-pipeline -o pipeline.yaml
```

***

## Pagination flags

List commands return paginated results by default. Use these flags to control how many records are returned.

These options are mutually exclusive. Use either `--all`, `--limit` and `--offset`, or `--count`.

| Flag           | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| `--all`        | Retrieve all available results.                                |
| `--limit <N>`  | Return up to N results.                                        |
| `--offset <N>` | Skip the first 'N' results.                                    |
| `--count`      | Return the total number of results without retrieving records. |

```shell
harness list pipeline --count 
harness list pipeline --all --format jsonl 
harness list pipeline --limit 25 --offset 50
```

***

## Behavior flags

These flags modify how a command runs and are available on every command.

| Flag                  | Description                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--debug`             | Enable debug logging                                                                                             |
| `--timeout <seconds>` | Abort after N seconds; accepts decimals (`1.5`); `0` = no timeout; exits `124` on timeout                        |
| `--ui`                | Launch an interactive TUI - browse lists, pick resources, or open the live execution log viewer (requires a TTY) |
| `-h`, `--help`        | Help for the current command                                                                                     |

```shell
harness list pipeline --debug 
harness execute pipeline deploy-prod --timeout 300 
harness get execution_log my-pipeline/exec-123 --ui
```

***

## Exit codes

| Code  | Meaning                                                             |
| ----- | ------------------------------------------------------------------- |
| `0`   | Success                                                             |
| `1`   | Generic failure: validation error, API error, or resource not found |
| `2`   | Usage error: invalid flags or unknown command                       |
| `124` | Timed out: `--timeout` duration exceeded                            |
| `130` | Interrupted by the user (Ctrl+C)                                    |

`--follow` is specific to `execute` commands. When you run `execute pipeline --follow`, the CLI exits with the terminal status of the pipeline execution, not `0`.

Use exit codes in scripts to gate downstream work:

```shell
if ! harness list pipeline --search deploy-prod --json | jq -e 'length > 0'; then 
  echo "no matching pipelines" 
  exit 1 
fi
```

***

## Environment variables

Environment variables override saved profile settings and are the preferred authentication method in CI pipelines, Docker containers, and scripted environments.

| Variable              | Description                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HARNESS_API_KEY`     | API token. Takes precedence over saved profile credentials.                                                                                       |
| `HARNESS_ACCOUNT`     | Account ID. Used 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_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.                                                                  |
| `HARNESS_DEBUG`       | Set to `1` to enable debug logging without passing `--debug`.                                                                                     |
| `HARNESS_NO_COLOR`    | Set to `1` to disable ANSI colors. `NO_COLOR` is also respected.                                                                                  |
| `HARNESS_CLI_COLUMNS` | Per-noun default `--columns` overrides. Semicolon-separated `noun=cols` pairs, for example `pipeline=id,name,status;execution=id,status,started`. |
| `HARNESS_CLI_HOME`    | Override the location of `~/.harness/`.                                                                                                           |

```shell
export HARNESS_API_KEY=pat.xxxxxxxxxxxxxxxxxx 
export HARNESS_ACCOUNT=ZJL7VBAhRq6Pf9G4f5OqLg 
harness list pipeline
```

***

## Troubleshooting

**A command exits with code `2`.** The CLI received an unknown flag or an invalid combination of flags. Run the command with `-h` to review the supported flags for that command.

**Pagination flags conflict with each other.** `--all`, `--limit`/`--offset`, and `--count` are mutually exclusive. Use only one of these approaches per command.

**Environment variable authentication is not taking effect.** Confirm `HARNESS_API_KEY` and `HARNESS_ACCOUNT` are both exported in the current shell session; environment variables take precedence over a saved profile only when both are set.

Go to [Troubleshooting](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/troubleshooting.md) for more common CLI errors and their resolutions.

## Related articles

These pages provide further reference material for working with the Harness CLI:

* [Platform](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/harness-cli-commands/platform.md): Review detailed examples of platform resource operations.
* [Troubleshooting](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/troubleshooting.md): Resolve common CLI errors.
