> 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/code-repository/3.0/use-harness-code/code-repository-cli-commands/harness-cli.md).

# Harness CLI for Code Repository

The **Harness CLI** is the unified command-line interface for Harness. It uses one consistent grammar across every module, so the way you install, authenticate, and run commands for Code Repository matches the rest of the Harness platform. This guide shows you how to install the CLI, log in, set your scope, and manage repositories, pull requests, reviews, branches, and tags from your terminal.

***

### What you will learn in this topic <a href="#what-you-will-learn-in-this-topic" id="what-you-will-learn-in-this-topic"></a>

* How to install the Harness CLI and verify the installation
* How to authenticate and set your default org and project scope
* How to create and inspect repositories from the terminal
* How to open, review, and merge pull requests without leaving your shell
* How to manage reviewers, codeowners, branches, tags, comments, and status checks

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **A Harness account:** Access to a project that contains at least one code repository. For steps to create one, see [Create a repository](/code-repository/3.0/use-harness-code/manage-repositories/create-repo.md).
* **A supported operating system:** macOS or Linux on `amd64` or `arm64`. Windows is not supported. Use WSL (Windows Subsystem for Linux) if you are on Windows. The installer downloads the matching binary automatically.
* **Code Repository permissions:** You need **View** on repositories, plus **Edit** to create or update them and **Push** to merge pull requests. For the full list, see the [Permissions reference](/harness-ai/use-harness-platform/platform-access-control/permissions-reference.md#code-repository).
* **An API key (optional):** Required only for CI pipelines and automated scripts. For steps to create one, see [Manage API keys](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md).
* **`curl` available on your `PATH`:** The install step uses `curl` to download the installer.

***

### Command overview <a href="#command-overview" id="command-overview"></a>

Every command follows the `harness <verb> <noun> [identifier] [flags]` grammar. The following table lists all 41 Code Repository commands, grouped by task. For the full syntax and flags for each one, see the [Code Repository command reference](/code-repository/use-harness-code/code-repository-cli-commands/command-reference.md).

| Task                                                                  | Commands                                                                                                                                             |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Repositories](#manage-repositories)                                  | `list repository`, `get repository`, `create repository`, `update repository`, `delete repository`                                                   |
| [Pull requests](#work-with-pull-requests)                             | `list pr`, `list pr:mine`, `list pr:review_pending`, `get pr`, `create pr`, `update pr`, `execute pr:merge`, `execute pr:close`, `execute pr:review` |
| [Reviewers and codeowners](#manage-reviewers-and-codeowners)          | `list code_principal`, `list pr_reviewer`, `create pr_reviewer`, `delete pr_reviewer`, `list pr_codeowner`                                           |
| [AI review insights](#review-insights-from-harness-code-ai)           | `get pr:insight`, `get pr:review_group`, `list pr_suggested_reviewer`, `list pr_suggested_label`, `list pr_success_criterion`                        |
| [Branches, commits, and tags](#manage-branches-commits-and-tags)      | `list branch`, `get branch`, `create branch`, `delete branch`, `list commit`, `get commit`, `list pr_commit`, `list tag`, `create tag`, `delete tag` |
| [Activity, comments, and checks](#track-activity-comments-and-checks) | `list pr_activity`, `list pr_comment`, `create pr_comment`, `update pr_comment`, `delete pr_comment`, `list pr_check`, `list commit_check`           |

***

### Set up the CLI <a href="#set-up-the-cli" id="set-up-the-cli"></a>

Install the CLI, log in, and set the org and project that your commands target by default.

```bash
# 1. Install the CLI <a href="#1-install-the-cli" id="1-install-the-cli"></a>
curl -fsSL https://raw.githubusercontent.com/harness/cli/main/install.sh | sh

# 2. Confirm the install <a href="#2-confirm-the-install" id="2-confirm-the-install"></a>
harness version

# 3. Log in <a href="#3-log-in" id="3-log-in"></a>
harness auth login

# 4. Set the scope your commands target <a href="#4-set-the-scope-your-commands-target" id="4-set-the-scope-your-commands-target"></a>
harness auth setscope --org <org-id> --project <project-id>

# 5. Confirm your profile, account, and token state <a href="#5-confirm-your-profile-account-and-token-state" id="5-confirm-your-profile-account-and-token-state"></a>
harness auth status
```

Windows is not supported. Use WSL (Windows Subsystem for Linux) if you are on Windows.

{% hint style="info" %}
**NON-INTERACTIVE AUTHENTICATION**

For CI pipelines and automated scripts, set the `HARNESS_API_KEY` environment variable instead of running an interactive login. Interactive login requires a TTY.
{% endhint %}

Enable tab completion so the CLI resolves repository names, branch names, and pull request numbers against the live Harness API as you type.

{% tabs %}
{% tab title="Zsh" %}

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

{% endtab %}

{% tab title="Bash" %}

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

{% endtab %}
{% endtabs %}

For installer flags, profile management, token expiry, and the full authentication precedence order, see [Install and upgrade](/harness-ai/use-harness-cli/harness-cli/install-and-upgrade.md) and [Authenticate](/harness-ai/use-harness-cli/harness-cli/authenticate.md).

***

### Resource identifiers <a href="#resource-identifiers" id="resource-identifiers"></a>

The Harness CLI grammar is `harness <verb> <noun> [identifier] [flags]`. Repositories are top level, and everything else lives inside a repository, so Code Repository nouns use compound identifiers built with slashes.

| Identifier form                    | Used by                                                          | Example                  |
| ---------------------------------- | ---------------------------------------------------------------- | ------------------------ |
| `<repo>`                           | Repositories, and the list commands scoped to a repository       | `my-service`             |
| `<repo>/<pr_number>`               | Pull requests, reviewers, codeowners, comments, activity, checks | `my-service/42`          |
| `<repo>/<branch>`                  | Branches                                                         | `my-service/release-1.2` |
| `<repo>/<sha>`                     | Commits and commit checks                                        | `my-service/a1b2c3d`     |
| `<repo>/<pr_number>/<reviewer_id>` | Reviewer removal                                                 | `my-service/42/alice`    |
| `<repo>/<pr_number>/<comment_id>`  | Comment updates and deletion                                     | `my-service/42/108`      |

Leave the slash in a compound identifier unencoded. For the `--set`, `--del`, `-f`, `--format`, paging, and scope conventions that apply to every command on this page, see [Global flags and output](/harness-ai/use-harness-cli/harness-cli/global-flags-and-output.md).

***

### Manage repositories <a href="#manage-repositories" id="manage-repositories"></a>

Repositories support the full create, read, update, and delete cycle. The `list` command is multi-level, so `--level` targets account, org, or project scope.

| Command                            | Description                                                           |
| ---------------------------------- | --------------------------------------------------------------------- |
| `harness list repository`          | List repositories in scope. Supports `--level account\|org\|project`. |
| `harness get repository <repo>`    | Get a repository by identifier.                                       |
| `harness create repository <repo>` | Create a repository with `--set`.                                     |
| `harness update repository <repo>` | Update `description`, `default_branch`, or `is_public`.               |
| `harness delete repository <repo>` | Delete a repository by identifier.                                    |

List the repositories in your project, then look at one:

```bash
harness list repository
harness list repository --level org --org my-org
harness get repository my-service
```

Create a repository and set its default branch:

```bash
harness create repository my-service \
  --set identifier=my-service default_branch=main description="Billing service" is_public=false
```

Update the description and switch the default branch:

```bash
harness update repository my-service --set description="Billing and invoicing service"
harness update repository my-service --set default_branch=develop
```

***

### Work with pull requests <a href="#work-with-pull-requests" id="work-with-pull-requests"></a>

Pull requests are the core of the CLI workflow for Code Repository. You can open a pull request, track it, review it, and merge it without opening the UI.

| Command                                        | Description                                                               |
| ---------------------------------------------- | ------------------------------------------------------------------------- |
| `harness list pr <repo>`                       | List pull requests for a repository.                                      |
| `harness list pr:mine`                         | List pull requests you authored across every repository in scope.         |
| `harness list pr:review_pending`               | List pull requests awaiting your review across every repository in scope. |
| `harness get pr <repo>/<pr_number>`            | Get pull request details.                                                 |
| `harness create pr <repo>`                     | Create a pull request.                                                    |
| `harness update pr <repo>/<pr_number>`         | Update the title, description, or draft state.                            |
| `harness execute pr:merge <repo>/<pr_number>`  | Merge a pull request.                                                     |
| `harness execute pr:close <repo>/<pr_number>`  | Close a pull request without merging.                                     |
| `harness execute pr:review <repo>/<pr_number>` | Submit a review decision.                                                 |

#### Find the pull requests that need you <a href="#find-the-pull-requests-that-need-you" id="find-the-pull-requests-that-need-you"></a>

Two qualified nouns work across every repository in scope, which makes them a good start to your day:

```bash
harness list pr:mine
harness list pr:review_pending
```

Both accept `--state`, `--created-after`, and `--created-before`.

```bash
harness list pr:mine --state open
harness list pr:review_pending --created-after 2026-08-01
```

To scope to a single repository, pass the repository identifier and filter as needed:

```bash
harness list pr my-service --state open
harness list pr my-service --author alice@example.com --sort created --order desc
harness list pr my-service --search "rate limit"
```

`--author` accepts an email address, a user ID, or a numeric principal ID.

#### Create a pull request <a href="#create-a-pull-request" id="create-a-pull-request"></a>

Set the title and the source and target branches with `--set`. Pass a Markdown file with `-f` to supply the description body.

```bash
harness create pr my-service \
  --set title="Add retry to billing client" source_branch=feature/retry target_branch=main
```

```bash
harness create pr my-service \
  --set title="Add retry to billing client" source_branch=feature/retry target_branch=main \
  -f pr-description.md
```

#### Update a pull request <a href="#update-a-pull-request" id="update-a-pull-request"></a>

```bash
harness get pr my-service/42
harness update pr my-service/42 --set title="Add retry and backoff to billing client"
harness update pr my-service/42 --set is_draft=false
```

#### Review a pull request <a href="#review-a-pull-request" id="review-a-pull-request"></a>

Submit a decision with `--decision`. Use `approve` to approve, or `changereq` to request changes.

```bash
harness execute pr:review my-service/42 --decision approve
harness execute pr:review my-service/42 --decision changereq
```

#### Merge or close a pull request <a href="#merge-or-close-a-pull-request" id="merge-or-close-a-pull-request"></a>

Choose the merge method explicitly. Add `--delete-branch` to clean up the source branch, and `--dry-run` to check mergeability first.

```bash
harness execute pr:merge my-service/42 --method squash --delete-branch
harness execute pr:merge my-service/42 --method merge --dry-run
harness execute pr:close my-service/42
```

`--method` accepts `merge`, `squash`, `rebase`, and `fast-forward`.

{% hint style="info" %}
**VERIFY BEFORE YOU MERGE**

Run the merge with `--dry-run` first. The command reports whether the pull request is mergeable and what would happen, without changing the branch.
{% endhint %}

***

### Manage reviewers and codeowners <a href="#manage-reviewers-and-codeowners" id="manage-reviewers-and-codeowners"></a>

Add and remove reviewers from the terminal, and check how codeowner rules evaluated against a pull request.

| Command                                                       | Description                                                                       |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `harness list code_principal`                                 | List Code principals (users and service accounts) in scope. Supports `--search`.  |
| `harness list pr_reviewer <repo>/<pr_number>`                 | List reviewers with their decision, type, and who added them.                     |
| `harness create pr_reviewer <repo>/<pr_number>`               | Add a reviewer with `--reviewer`.                                                 |
| `harness delete pr_reviewer <repo>/<pr_number>/<reviewer_id>` | Remove a reviewer.                                                                |
| `harness list pr_codeowner <repo>/<pr_number>`                | List codeowners evaluated on the pull request, with pattern, owner, and decision. |

Find a principal, add them as a reviewer, then confirm:

```bash
harness list code_principal --search alice
harness create pr_reviewer my-service/42 --reviewer alice@example.com
harness list pr_reviewer my-service/42
```

`--reviewer` resolves an email address, user ID, or numeric principal ID automatically.

Remove a reviewer, and review which codeowner rules applied:

```bash
harness delete pr_reviewer my-service/42/alice
harness list pr_codeowner my-service/42
```

***

### Review insights from Harness Code AI <a href="#review-insights-from-harness-code-ai" id="review-insights-from-harness-code-ai"></a>

Harness Code AI produces risk summaries, review groupings, and suggestions on a pull request. The CLI reads all of them, which is useful for triaging a large pull request before you open the diff.

| Command                                                 | Description                                      |
| ------------------------------------------------------- | ------------------------------------------------ |
| `harness get pr:insight <repo>/<pr_number>`             | Get the risk summary insight for a pull request. |
| `harness get pr:review_group <repo>/<pr_number>`        | Get risk-bucketed file groups for review.        |
| `harness list pr_suggested_reviewer <repo>/<pr_number>` | List AI-suggested reviewers.                     |
| `harness list pr_suggested_label <repo>/<pr_number>`    | List AI-suggested labels.                        |
| `harness list pr_success_criterion <repo>/<pr_number>`  | List AI review success-criteria results.         |

Triage a pull request by risk before you read the code:

```bash
harness get pr:insight my-service/42
harness get pr:review_group my-service/42
```

Check the suggestions, then act on them:

```bash
harness list pr_suggested_reviewer my-service/42
harness list pr_suggested_label my-service/42
harness list pr_success_criterion my-service/42
```

For more information about the AI review capabilities behind these commands, see [AI agents](/code-repository/use-harness-code/pull-requests/ai-agents.md).

***

### Manage branches, commits, and tags <a href="#manage-branches-commits-and-tags" id="manage-branches-commits-and-tags"></a>

| Command                                     | Description                                                        |
| ------------------------------------------- | ------------------------------------------------------------------ |
| `harness list branch <repo>`                | List branches. Supports `--search`.                                |
| `harness get branch <repo>/<branch>`        | Get branch details.                                                |
| `harness create branch <repo>`              | Create a branch with `--set name=<branch> target=<sha_or_branch>`. |
| `harness delete branch <repo>/<branch>`     | Delete a branch by name.                                           |
| `harness list commit <repo>`                | List commits. Supports `--branch <ref>` and `--path <file>`.       |
| `harness get commit <repo>/<sha>`           | Get commit details.                                                |
| `harness list pr_commit <repo>/<pr_number>` | List the commits in a pull request.                                |
| `harness list tag <repo>`                   | List tags. Supports `--search`.                                    |
| `harness create tag <repo>`                 | Create a tag with `--set name=<tag> target=<sha>`.                 |
| `harness delete tag <repo>/<tag>`           | Delete a tag by name.                                              |

Create a release branch off `main`, then confirm it exists:

```bash
harness create branch my-service --set name=release-1.2 target=main
harness get branch my-service/release-1.2
harness list branch my-service --search release
```

Inspect history, including the commits on a single file:

```bash
harness list commit my-service --branch main
harness list commit my-service --path src/billing/client.go
harness get commit my-service/a1b2c3d
harness list pr_commit my-service/42
```

Tag a release, then clean up an old branch:

```bash
harness create tag my-service --set name=v1.2.0 target=a1b2c3d
harness list tag my-service
harness delete branch my-service/feature/retry
```

***

### Track activity, comments, and checks <a href="#track-activity-comments-and-checks" id="track-activity-comments-and-checks"></a>

| Command                                                     | Description                                                                                                 |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `harness list pr_activity <repo>/<pr_number>`               | List the activity timeline, including comments, reviews, and state changes. Supports `--kind` and `--type`. |
| `harness list pr_comment <repo>/<pr_number>`                | List comments on a pull request.                                                                            |
| `harness create pr_comment <repo>/<pr_number>`              | Post a comment from a file or stdin. Supports `--reply-to <id>`.                                            |
| `harness update pr_comment <repo>/<pr_number>/<comment_id>` | Edit an existing comment with `--text`.                                                                     |
| `harness delete pr_comment <repo>/<pr_number>/<comment_id>` | Delete a comment.                                                                                           |
| `harness list pr_check <repo>/<pr_number>`                  | List status checks on a pull request, including pipeline and execution IDs.                                 |
| `harness list commit_check <repo>/<sha>`                    | List status checks on a commit SHA. Supports `--search`.                                                    |

Read the timeline, then post a comment:

```bash
harness list pr_activity my-service/42
harness list pr_comment my-service/42
harness create pr_comment my-service/42 -f review-notes.md
```

Pass `-` to read the comment body from stdin, which works well in scripts:

```bash
echo "Verified against staging. Approving." | harness create pr_comment my-service/42 -f -
```

Reply in a thread, edit a comment, or remove it:

```bash
harness create pr_comment my-service/42 --reply-to 108 -f follow-up.md
harness update pr_comment my-service/42/108 --text "Corrected: this affects only the retry path."
harness delete pr_comment my-service/42/108
```

Check pipeline status before you merge:

```bash
harness list pr_check my-service/42
harness list commit_check my-service/a1b2c3d
```

{% hint style="info" %}
**DISCOVER ANY COMMAND**

Append `--help` at any level to list the available verbs, nouns, and flags, for example `harness execute pr:merge --help`.
{% endhint %}

***

### Example: review and merge from the terminal <a href="#example-review-and-merge-from-the-terminal" id="example-review-and-merge-from-the-terminal"></a>

The following sequence covers a full review pass without opening the UI.

```bash
# 1. Find what is waiting on you <a href="#1-find-what-is-waiting-on-you" id="1-find-what-is-waiting-on-you"></a>
harness list pr:review_pending --state open

# 2. Triage the change by risk <a href="#2-triage-the-change-by-risk" id="2-triage-the-change-by-risk"></a>
harness get pr:insight my-service/42
harness get pr:review_group my-service/42

# 3. Confirm checks passed <a href="#3-confirm-checks-passed" id="3-confirm-checks-passed"></a>
harness list pr_check my-service/42

# 4. Leave a comment and approve <a href="#4-leave-a-comment-and-approve" id="4-leave-a-comment-and-approve"></a>
echo "Retry logic looks correct. Approving." | harness create pr_comment my-service/42 -f -
harness execute pr:review my-service/42 --decision approve

# 5. Merge and clean up <a href="#5-merge-and-clean-up" id="5-merge-and-clean-up"></a>
harness execute pr:merge my-service/42 --method squash --delete-branch
```

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>harness: command not found after installing the Harness CLI</summary>

The install directory is not on your PATH. Add \~/.local/bin to your PATH (export PATH="$HOME/.local/bin:$PATH"), then restart your shell or re-run the installer and accept the PATH update prompt.

</details>

<details>

<summary>harness auth login fails or hangs with no interactive prompt in Harness CLI</summary>

Interactive login requires a TTY. In CI or a non-interactive shell, set the HARNESS\_API\_KEY environment variable instead of running harness auth login.

</details>

<details>

<summary>harness list repository returns no repositories or an empty result in Harness Code Repository</summary>

Your default org and project may be unset or pointing at the wrong scope. Run harness auth setscope --org --project , and add --level org or --level account if the repository lives above project scope.

</details>

<details>

<summary>Harness CLI reports a resource not found error for a pull request or branch in Harness Code Repository</summary>

Code Repository nouns use compound identifiers. Pass the repository with the resource, for example my-service/42 for a pull request and my-service/release-1.2 for a branch, and leave the slash unencoded.

</details>

<details>

<summary>harness execute pr:merge fails with a permission or mergeability error in Harness Code Repository</summary>

Merging requires Push permission on the repository, and the pull request must satisfy its branch rules. Run the command with --dry-run to see what blocks the merge, and check harness list pr\_check for failing status checks.

</details>

***

### Related articles <a href="#related-articles" id="related-articles"></a>

For the full command reference and the UI workflows that these commands map onto, see the following topics.

* [Code Repository command reference](/code-repository/use-harness-code/code-repository-cli-commands/command-reference.md): Review every Code Repository command, flag, and output option.
* [Supported resources and actions](/harness-ai/use-harness-cli/harness-cli/supported-resources-and-actions.md): Confirm which actions each resource supports before you script against it.
* [Create a pull request](/code-repository/use-harness-code/pull-requests/create-pr.md): Compare the CLI flow with the equivalent UI workflow.
* [Review a pull request](/code-repository/use-harness-code/pull-requests/review-pr.md): Understand review decisions, approvals, and branch rules.