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
- 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 Harness account: Access to a project that contains at least one code repository. For steps to create one, see Create a repository.
- A supported operating system: macOS or Linux on
amd64orarm64. 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.
- An API key (optional): Required only for CI pipelines and automated scripts. For steps to create one, see Manage API keys.
curlavailable on yourPATH: The install step usescurlto download the installer.
Command overview
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.
| Task | Commands |
|---|---|
| Repositories | list repository, get repository, create repository, update repository, delete repository |
| 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 | list code_principal, list pr_reviewer, create pr_reviewer, delete pr_reviewer, list pr_codeowner |
| AI review insights | get pr:insight, get pr:review_group, list pr_suggested_reviewer, list pr_suggested_label, list pr_success_criterion |
| 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 | 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
Install the CLI, log in, and set the org and project that your commands target by default.
# 1. Install the CLI
curl -fsSL https://raw.githubusercontent.com/harness/cli/main/install.sh | sh
# 2. Confirm the install
harness version
# 3. Log in
harness auth login
# 4. Set the scope your commands target
harness auth setscope --org <org-id> --project <project-id>
# 5. Confirm your profile, account, and token state
harness auth status
Windows is not supported. Use WSL (Windows Subsystem for Linux) if you are on Windows.
For CI pipelines and automated scripts, set the HARNESS_API_KEY environment variable instead of running an interactive login. Interactive login requires a TTY.
Enable tab completion so the CLI resolves repository names, branch names, and pull request numbers against the live Harness API as you type.
- Zsh
- Bash
source <(harness completion zsh)
source <(harness completion bash)
For installer flags, profile management, token expiry, and the full authentication precedence order, see Install and upgrade and Authenticate.
Resource identifiers
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.
Manage repositories
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:
harness list repository
harness list repository --level org --org my-org
harness get repository my-service
Create a repository and set its default branch:
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:
harness update repository my-service --set description="Billing and invoicing service"
harness update repository my-service --set default_branch=develop
Work with pull requests
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
Two qualified nouns work across every repository in scope, which makes them a good start to your day:
harness list pr:mine
harness list pr:review_pending
Both accept --state, --created-after, and --created-before.
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:
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
Set the title and the source and target branches with --set. Pass a Markdown file with -f to supply the description body.
harness create pr my-service \
--set title="Add retry to billing client" source_branch=feature/retry target_branch=main
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
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
Submit a decision with --decision. Use approve to approve, or changereq to request changes.
harness execute pr:review my-service/42 --decision approve
harness execute pr:review my-service/42 --decision changereq
Merge or close a pull request
Choose the merge method explicitly. Add --delete-branch to clean up the source branch, and --dry-run to check mergeability first.
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.
Run the merge with --dry-run first. The command reports whether the pull request is mergeable and what would happen, without changing the branch.
Manage reviewers and codeowners
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:
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:
harness delete pr_reviewer my-service/42/alice
harness list pr_codeowner my-service/42
Review insights from Harness Code AI
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:
harness get pr:insight my-service/42
harness get pr:review_group my-service/42
Check the suggestions, then act on them:
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.
Manage branches, commits, and tags
| 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:
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:
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:
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
| 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:
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:
echo "Verified against staging. Approving." | harness create pr_comment my-service/42 -f -
Reply in a thread, edit a comment, or remove it:
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:
harness list pr_check my-service/42
harness list commit_check my-service/a1b2c3d
Append --help at any level to list the available verbs, nouns, and flags, for example harness execute pr:merge --help.
Example: review and merge from the terminal
The following sequence covers a full review pass without opening the UI.
# 1. Find what is waiting on you
harness list pr:review_pending --state open
# 2. Triage the change by risk
harness get pr:insight my-service/42
harness get pr:review_group my-service/42
# 3. Confirm checks passed
harness list pr_check my-service/42
# 4. Leave a comment and approve
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
harness execute pr:merge my-service/42 --method squash --delete-branch
Troubleshooting
harness: command not found after installing the Harness CLI
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.
harness auth login fails or hangs with no interactive prompt in Harness CLI
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.
harness list repository returns no repositories or an empty result in Harness Code Repository
Your default org and project may be unset or pointing at the wrong scope. Run harness auth setscope --org <org-id> --project <project-id>, and add --level org or --level account if the repository lives above project scope.
Harness CLI reports a resource not found error for a pull request or branch in Harness Code Repository
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.
harness execute pr:merge fails with a permission or mergeability error in Harness Code Repository
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.
Related articles
For the full command reference and the UI workflows that these commands map onto, see the following topics.
- Code Repository command reference: Review every Code Repository command, flag, and output option.
- Supported resources and actions: Confirm which actions each resource supports before you script against it.
- Create a pull request: Compare the CLI flow with the equivalent UI workflow.
- Review a pull request: Understand review decisions, approvals, and branch rules.