# Harness CLI — Command Reference

> Complete list of every command supported by the Harness CLI, grouped by module.
> **327 commands across 95 nouns × 11 public modules.**

The grammar is **`harness <verb> <noun> [identifier] [flags]`** — the verb always comes first. A small set of self-management commands (`auth`, `install`, `version`, `debug`) sit outside the verb/noun grammar because they operate on the tool itself rather than a Harness resource.

If you are an AI agent reading this file: every row below is a valid invocation. Placeholders in angle brackets (`<id>`, `<repo>/<pr_number>`) are the only free variables. Prefer `harness list noun --matrix` and `harness <verb> <noun> --help` for the live source of truth — this document mirrors the spec files under [`pkg/spec/`](pkg/spec/) but is regenerated by hand and may lag by a release.

| Module       | Commands | Notes                                                                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `core`       | 22       | Auth (PAT + browser SSO via `--sso`), install/upgrade (core + plugins from GitHub/tarball/`all`), version, discovery (`list/get module`, `list/get plugin`, `list/get noun`), debug helpers |
| `platform`   | 48       | Orgs, projects, users, roles, connectors, secrets, settings, delegates, delegate tokens, Harness Worker Agents, entity usage |
| `pipeline`   | 45       | Pipelines, executions (abort/retry/retry_history), logs (live viewer), triggers CRUD, input sets CRUD, templates + versions, approvals, freeze windows |
| `cd`         | 20       | Services, environments, infrastructure definitions, service overrides                                                     |
| `iacm`       | 13       | IaCM workspaces (Terraform/OpenTofu) plus Ansible hosts/inventories/playbooks and the module/provider registries          |
| `har`        | 47       | Artifact Registry — push (18 formats), pull, registries, artifact/version metadata, firewall scans, migrate, package-manager install helpers |
| `code`       | 51       | Harness Code — repos, PRs (`pr:mine`, `pr:review_pending`, review/merge/reopen/ready/edit, labels), review insights, reviewers/codeowners, branches, commits, tags, comments, checks |
| `rt`         | 41       | Resilience Testing — JMeter/Locust/k6 load tests, runs (follow/stop/rerun), templates, scripts, composite tests, usage     |
| `gitops`     | 27       | GitOps agents, applications (sync/refresh), clusters, repositories, ApplicationSets                                       |
| `governance` | 11       | OPA policies, policy sets, policy evaluations                                                                             |
| `audit`      |  2       | Read-only audit trail across every Harness resource                                                                       |

Use `harness list noun --matrix` for the live noun × verb matrix. Use `harness <verb> <noun> --help` for full flag details on any command.

---

## Contents

- [Global conventions](#global-conventions)
- [Core (management & discovery)](#core-management--discovery)
- [Platform](#platform)
- [Pipelines / CI-CD](#pipelines--ci-cd)
- [CD (Continuous Delivery)](#cd-continuous-delivery)
- [IaCM (Infrastructure as Code & Ansible)](#iacm-infrastructure-as-code--ansible)
- [Artifact Registry (HAR)](#artifact-registry-har)
- [Code (Harness Code)](#code-harness-code)
- [Resilience Testing (RT)](#resilience-testing-rt)
- [GitOps](#gitops)
- [Harness Worker Agents](#harness-worker-agents)
- [Governance](#governance)
- [Audit](#audit)
- [Interactive TUI (`--ui`)](#interactive-tui---ui)
- [Cheat sheet for AI agents](#cheat-sheet-for-ai-agents)

---

## Global conventions

These apply to every command and are not repeated in each module.

- **`<id>`** — the resource identifier (e.g. pipeline ID, project ID, secret ID).
- **Compound IDs** — code, pipeline-execution, PR-comment, and GitOps resources use `<parent>/<child>` forms (e.g. `<repo>/<pr_number>`, `<pipeline>/<execution_id>`, `<agent>/<app>`, `<repo>/<pr_number>/<comment_id>`). The CLI accepts the same form everywhere a parent is required.
- **Qualified nouns** — `noun:variant` distinguishes sub-operations on the same resource (`execute pr:merge`, `list pr:mine`, `list pr:review_pending`, `execute pr:review`, `execute pr:label`, `get pr:insight`, `get pipeline:summary`, `execute loadtest:sync`, `list kg:type`, `execute execution:abort`).
- **`--set` / `--del`** — `create` and `update` commands accept `--set key=value` (repeatable) and, on update, `--del key` to clear a field. Nested paths use dots: `--set variables.region=us-east-1`.
- **YAML I/O (`-f`)** — `create` and `update` on most resources accept `-f file.yaml` (or `-f -` for stdin) to send the body from a file instead of using `--set`. `get` prints YAML by default; add `--yaml` to force YAML on commands where another format is the default.
- **Output format** — `--format table|text|csv|tsv|json|yaml` (plus `jsonl`/`markdown` where supported). Defaults: `table` for `list`, `text` for `get`/other verbs. `--json` / `--yaml` are shorthands. Pick the right shape:
  - `table` / `csv` / `tsv` (list) — projected columns only (shaped by `--columns`); `table` prints the paging footer; `tsv` is best for shell/awk.
  - `json` (any verb) — raw API response (full object + envelope); ignores `--columns`. Use when a field isn't a column, or to inspect create/update/execute results.
  - `yaml` (get) — data object with envelope stripped; the body that round-trips through `update -f` / `create -f`.
  - `text` — default human-readable summary for non-list verbs.
- **Paging** — every `list` supports `--limit`, `--offset` (or `--page`), `--all`, and `--count` where the underlying API supports it.
- **Scope** — `--account`, `--org`, `--project` override profile scope per-invocation. Multi-level nouns also accept `--level account|org|project` to switch scope.
- **`--ui`** — many list and select commands support an interactive TUI (see [Interactive TUI](#interactive-tui---ui)). Requires a TTY.
- **`--profile`** — pick a non-default auth profile for one invocation. Equivalent to setting `HARNESS_PROFILE`.

---

## Core (management & discovery)

Source: [`pkg/spec/core.spec.yaml`](pkg/spec/core.spec.yaml).

### Authentication

| Command                    | One-line description                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| `harness auth login`       | Save credentials to a named profile. Interactive PAT wizard by default; pass `--api-url` + `--api-token` for non-interactive login. Add `--sso` for browser OAuth2 (tokens stored in the OS keychain where available). |
| `harness auth sso_refresh` | Refresh the SSO access token using the stored refresh token.                               |
| `harness auth sso_status`  | Show SSO token expiry and refresh status for the active profile.                           |
| `harness auth setscope`    | Set the default org and/or project on a profile.                                           |
| `harness auth logout`      | Remove a profile and its stored credentials.                                               |
| `harness auth profiles`    | List all configured authentication profiles.                                               |
| `harness auth status`      | Show the current auth profile and validate credentials.                                    |
| `harness auth env`         | Print env vars for the current auth context (use with `--export` for `eval`-friendly output). |
| `harness auth token`       | Print the active API token to stdout (useful for piping into other tooling).               |

### Version & install

| Command                          | One-line description                                                            |
| -------------------------------- | ------------------------------------------------------------------------------- |
| `harness version`                | Print the Harness CLI version.                                                  |
| `harness install cli`            | Install or upgrade the `harness` binary **and** any installed modules in one shot (`--version`, `--install-dir`, `--force`, `--check`, `--core-only`). Errors if `--install-dir` does not match the current executable path. |
| `harness install module <name>`  | Install or upgrade a single CLI module binary (e.g. `har`).                     |
| `harness install plugin <ref>`   | Install or upgrade a plugin. `<ref>` may be a plugin name (`har`), `owner/repo` (GitHub latest release), `owner/repo/prefix` (prefixed tags), a tarball URL, a local tarball/binary, or `all` to upgrade every installed registry plugin. `--version`, `--force`, `--check`, `--github-token`. |

### Discovery

| Command                     | One-line description                                                              |
| --------------------------- | --------------------------------------------------------------------------------- |
| `harness list module`       | List all loaded CLI modules (builtin + external).                                 |
| `harness get module <name>` | Show the domain model and nouns for a module (`--matrix` for noun × verb table).  |
| `harness list plugin`       | List installed external plugin binaries.                                          |
| `harness get plugin <name>` | Show metadata for an installed plugin.                                            |
| `harness list noun`         | List all registered nouns with their module and supported verbs (`--matrix`).     |
| `harness get noun <noun>`   | Show fields and supported commands for a specific noun.                           |

### Debug

| Command                       | One-line description                                                         |
| ----------------------------- | ---------------------------------------------------------------------------- |
| `harness debug miscfg`        | Trigger a misconfigured command (dev-only registry self-test).               |
| `harness debug update_check`  | Probe the release manifest and report what an in-place upgrade would do.     |
| `harness debug sso-log`       | Emit SSO auth debug events (for troubleshooting browser login flows).          |

---

## Platform

Source: [`pkg/spec/platform.spec.yaml`](pkg/spec/platform.spec.yaml).

### Account, Organizations & Projects

| Command                          | One-line description                                                  |
| -------------------------------- | --------------------------------------------------------------------- |
| `harness get account`            | Get details for the current account.                                  |
| `harness list organization`      | List organizations in the account.                                    |
| `harness get organization <id>`  | Get an organization by identifier.                                    |
| `harness create organization`    | Create a new organization (`--set` fields or `-f org.yaml`).          |
| `harness update organization`    | Update an organization (get-then-put via `--set`/`--del`, or `-f`).   |
| `harness delete organization`    | Delete an organization by identifier.                                 |
| `harness list project`           | List projects in an organization.                                     |
| `harness get project <id>`       | Get a project by identifier.                                          |
| `harness create project`         | Create a new project (`--set` fields or `-f project.yaml`).           |
| `harness update project`         | Update a project (`--set`/`--del`, or `-f`).                          |
| `harness delete project`         | Delete a project by identifier.                                       |

### Users, Groups & Service Accounts

| Command                              | One-line description                                |
| ------------------------------------ | --------------------------------------------------- |
| `harness list user`                  | List users in the account.                          |
| `harness get user <id>`              | Get a user by identifier.                           |
| `harness list user_group`            | List user groups in the account.                    |
| `harness get user_group <id>`        | Get a user group by identifier.                     |
| `harness list service_account`       | List service accounts in the account.               |
| `harness get service_account <id>`   | Get a service account by identifier.                |

### Roles, Permissions & Resource Groups

| Command                              | One-line description                                          |
| ------------------------------------ | ------------------------------------------------------------- |
| `harness list role`                  | List roles in scope.                                          |
| `harness get role <id>`              | Get a role by identifier.                                     |
| `harness list role_assignment`       | List role assignments in scope.                               |
| `harness get role_assignment <id>`   | Get a role assignment by identifier.                          |
| `harness list resource_group`        | List resource groups in scope.                                |
| `harness get resource_group <id>`    | Get a resource group by identifier.                           |
| `harness list permission`            | List all available permissions.                               |
| `harness get permission <id>`        | Get a permission by identifier.                               |

### Settings

| Command                       | One-line description                                  |
| ----------------------------- | ----------------------------------------------------- |
| `harness list setting`        | List platform settings.                               |
| `harness get setting <id>`    | Get a setting value by identifier.                    |

### Connectors & Secrets

| Command                               | One-line description                                                                    |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| `harness list connector`              | List connectors (multi-level via `--level`).                                            |
| `harness get connector <id>`          | Get a connector by identifier.                                                          |
| `harness create connector <id>`       | Create a connector (`--set` fields or `-f connector.yaml`).                             |
| `harness update connector <id>`       | Update a connector (`--set`/`--del`, or `-f`).                                          |
| `harness delete connector <id>`       | Delete a connector by identifier.                                                       |
| `harness execute connector:test <id>` | Run a connectivity test against a connector and return the structured result.           |
| `harness list secret`                 | List secrets (metadata only — values are never returned).                               |
| `harness get secret <id>`             | Get a secret by identifier (metadata only).                                             |
| `harness create secret <id>`          | Create a secret (`--set` fields or `-f secret.yaml`; secret values are redacted in echo). |
| `harness update secret <id>`          | Update a secret (`--set`/`--del`, or `-f`).                                             |
| `harness delete secret <id>`          | Delete a secret by identifier.                                                          |

### Delegates & Delegate Tokens

| Command                              | One-line description                                                           |
| ------------------------------------ | ------------------------------------------------------------------------------ |
| `harness list delegate`              | List delegates in scope (multi-level).                                         |
| `harness get delegate <id>`          | Get a delegate by identifier.                                                  |
| `harness list delegate_token`        | List delegate tokens.                                                          |
| `harness create delegate_token <id>` | Create a delegate token (token value is returned **once** at creation time).   |
| `harness delete delegate_token <id>` | Revoke (delete) a delegate token.                                              |

### Entity Usage

| Command                                       | One-line description                                                                                            |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `harness list entity_usage connector/<id>`    | List every place a given entity is referenced. Pass the target as `<entity_type>/<id>` (e.g. `connector/git-hub`). |

---

## Pipelines / CI-CD

Source: [`pkg/spec/pipeline.spec.yaml`](pkg/spec/pipeline.spec.yaml).

### Pipelines

| Command                                     | One-line description                                                                                         |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `harness list pipeline`                     | List pipelines in a project.                                                                                 |
| `harness get pipeline <id>`                 | Get a pipeline's YAML definition (`--format json` to convert; `--raw` for the full envelope).                |
| `harness create pipeline`                   | Create a pipeline — inline (`-f pipeline.yaml`) or Git-backed (`--connector`/`--repo`/`--file-path`).        |
| `harness update pipeline`                   | Update a pipeline's YAML definition (`-f file.yaml` or `-f -` for stdin).                                    |
| `harness delete pipeline <id>`              | Delete a pipeline by identifier.                                                                             |
| `harness get pipeline:summary <id>`         | Get a lightweight pipeline summary (without full YAML).                                                      |
| `harness get runtime_input_template <id>`   | Get the runtime input template for a pipeline (shows every `<+input>` placeholder).                          |
| `harness list pipeline_v1`                  | List v1-schema pipelines in a project (legacy API compatibility).                                            |
| `harness get pipeline_v1 <id>`              | Get a v1-schema pipeline by identifier.                                                                      |

### Executions

| Command                                          | One-line description                                                                                              |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `harness execute pipeline <id>`                  | Trigger a pipeline execution (`--input key=val` repeatable, `--input-set`, `--input-file`, `--branch`, `--follow`). |
| `harness execute pipeline:dynamic <id>`          | Execute a pipeline whose YAML is validated dynamically (uses the validators endpoint before running).             |
| `harness execute pipeline:input_set <id>`        | Execute using the inputSetList endpoint (input sets are merged server-side).                                      |
| `harness execute execution:abort <[pipeline/]id>`| Abort a running pipeline execution (`--interrupt-type AbortAll\|Abort\|Pause\|Resume\|StageRollback\|ExpireAll\|Retry`). |
| `harness execute execution:retry <pipeline/execution-id>` | Retry a failed pipeline execution (`--retry-stages`, `--only-failed-stages`, `--input`, `--input-file`, `--follow`). |
| `harness get execution:retry_history <[pipeline/]id>` | Show retry history and retryable stages for a pipeline execution. |
| `harness list execution`                         | List pipeline executions in a project (`--status`, `--branch`, `--module`; optional pipeline scope).              |
| `harness get execution <[pipeline/]id>`          | Get a pipeline execution by ID (`--no-graph` to skip the stage/step graph).                                       |
| `harness list execution_step <[pipeline/]id>`    | List expanded execution steps (including loop/matrix iterations) for an execution.                                |
| `harness list execution_log <[pipeline/]id>`     | List all log keys for a pipeline execution.                                                                       |
| `harness get execution_log <key>`                | Fetch logs for a log key. Passing `<[pipeline/]execId>` returns every log stream for the execution. `--follow` streams live, `--ui` launches the interactive log viewer, `--save` writes the log to a file. |

### Triggers, Input Sets & Templates

| Command                                                | One-line description                                                                                                              |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `harness list trigger`                                 | List triggers for a pipeline (`--search` for a name filter).                                                                      |
| `harness get trigger <pipeline/id>`                    | Get a trigger by identifier.                                                                                                      |
| `harness create trigger <pipeline_id>`                 | Create a trigger from a YAML body (`-f trigger.yaml`; the file carries the full trigger definition).                              |
| `harness update trigger <[pipeline/]id>`               | Update a trigger's YAML definition (`-f trigger.yaml` or `-f -`).                                                                 |
| `harness delete trigger <[pipeline/]id>`               | Delete a trigger by identifier (interactive confirm; use `-y` to skip).                                                           |
| `harness list input_set`                               | List input sets for a pipeline.                                                                                                   |
| `harness get input_set <pipeline/id>`                  | Get an input set by identifier.                                                                                                   |
| `harness create input_set <pipeline_id>`               | Create an input set from a YAML body (`-f input-set.yaml`).                                                                       |
| `harness update input_set <pipeline/id>`               | Update an input set's YAML definition (`-f input-set.yaml` or `-f -`).                                                            |
| `harness delete input_set <pipeline/id>`               | Delete an input set by identifier (interactive confirm; use `-y` to skip).                                                        |
| `harness list template`                                | List templates in a project.                                                                                                      |
| `harness get template <id>`                            | Get a template's stable version by identifier.                                                                                    |
| `harness create template`                              | Create a template from a YAML body (`-f template.yaml`).                                                                          |
| `harness list template_version <template_id>`          | List all versions of a template.                                                                                                  |
| `harness get template_version <template/version>`      | Get a specific template version.                                                                                                  |
| `harness update template_version <template/version>`   | Update a template version from YAML (`-f template.yaml`).                                                                         |
| `harness delete template_version <template/version>`   | Delete a template version (interactive confirm; use `-y` to skip).                                                                |
| `harness update template_version:set-stable <template/version>` | Mark a template version as the stable version.                                                                           |

### Approvals & Freezes

| Command                                                    | One-line description                                                        |
| ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| `harness list approval_instance`                           | List approval instances for a pipeline execution.                           |
| `harness get approval_instance <id>`                       | Get an approval instance by identifier.                                     |
| `harness execute approval_instance:approve <id>`           | Approve a waiting Harness approval instance (`--comment`, `--approver-input key=value` repeatable). |
| `harness execute approval_instance:reject <id>`            | Reject a waiting Harness approval instance (`--comment`).                   |
| `harness list freeze_window`                               | List deployment freeze windows (multi-level via `--level`).                 |
| `harness get freeze_window <id>`                           | Get a deployment freeze window by identifier.                               |
| `harness get global_freeze`                                | Get the global deployment freeze status.                                    |

---

## CD (Continuous Delivery)

Source: [`pkg/spec/cd.spec.yaml`](pkg/spec/cd.spec.yaml).

The CD module covers the four primary deployment resources: **services** (what you deploy), **environments** (where you deploy), **infrastructure** definitions (how you deploy), and **service overrides** (per-environment service config).

### Services

| Command                          | One-line description                                                  |
| -------------------------------- | --------------------------------------------------------------------- |
| `harness list service`           | List services in a project.                                           |
| `harness get service <id>`       | Get a service by identifier.                                          |
| `harness create service <id>`    | Create a service (`--set name=<name> [description=…]` or `-f service.yaml`). |
| `harness update service <id>`    | Update a service's name, description, or tags.                        |
| `harness delete service <id>`    | Delete a service by identifier.                                       |

### Environments

| Command                              | One-line description                                                              |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| `harness list environment`           | List environments in a project.                                                   |
| `harness get environment <id>`       | Get an environment by identifier.                                                 |
| `harness create environment <id>`    | Create an environment (`--set name=<name> type=Production\|PreProduction` or `-f env.yaml`). |
| `harness update environment <id>`    | Update an environment's name, type, description, or tags.                         |
| `harness delete environment <id>`    | Delete an environment by identifier.                                              |

### Infrastructure

| Command                                 | One-line description                                                                          |
| --------------------------------------- | --------------------------------------------------------------------------------------------- |
| `harness list infrastructure --env <e>` | List infrastructure definitions inside an environment.                                        |
| `harness get infrastructure <id>`       | Get an infrastructure definition (`--env <environment_id>` required).                         |
| `harness create infrastructure <id>`    | Create an infrastructure definition (`--set name=<name> environmentRef=<env>` or `-f infra.yaml`). |
| `harness update infrastructure <id>`    | Update an infrastructure definition.                                                          |
| `harness delete infrastructure <id>`    | Delete an infrastructure definition (`--env <environment_id>` required).                      |

### Service Overrides

| Command                                    | One-line description                                                                                     |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `harness list service_override --env <e>`  | List service overrides for an environment.                                                               |
| `harness get service_override <id>`        | Get a service override by identifier.                                                                    |
| `harness create service_override <id>`     | Create a service override (`--set environmentRef=<env> type=ENV_GLOBAL_OVERRIDE\|ENV_SERVICE_OVERRIDE`). |
| `harness update service_override <id>`     | Update a service override.                                                                               |
| `harness delete service_override <id>`     | Delete a service override.                                                                               |

---

## IaCM (Infrastructure as Code & Ansible)

Source: [`pkg/spec/iacm.spec.yaml`](pkg/spec/iacm.spec.yaml).

IaCM manages Terraform/OpenTofu workspaces, tracks Ansible inventories and playbooks, and provides a private Terraform module and provider registry. Workspace `create`/`update`/`delete` land in v3.1; today, workspaces are provisioned via the UI or REST and are fully driveable from the CLI thereafter.

### Terraform Workspaces

| Command                          | One-line description                                          |
| -------------------------------- | ------------------------------------------------------------- |
| `harness list workspace`         | List IaCM workspaces in a project.                            |
| `harness get workspace <id>`     | Get an IaCM workspace by identifier.                          |
| `harness execute workspace <id>` | Execute a remote Terraform plan. The workspace ID may be omitted if `.harness/workspace.yaml` is present (`--target`, `--replace`, `--force`). |

### Ansible — Hosts, Inventories, Playbooks

| Command                          | One-line description                                                     |
| -------------------------------- | ------------------------------------------------------------------------ |
| `harness list host`              | List Ansible hosts (`--search`, `--inventory`, `--status`).              |
| `harness get host <id>`          | Get an Ansible host by identifier.                                       |
| `harness list inventory`         | List Ansible inventories in a project.                                   |
| `harness get inventory <id>`     | Get an Ansible inventory by identifier.                                  |
| `harness list playbook`          | List Ansible playbooks in a project.                                     |
| `harness get playbook <id>`      | Get an Ansible playbook by identifier.                                   |

### Module & Provider Registries

| Command                                 | One-line description                                              |
| --------------------------------------- | ----------------------------------------------------------------- |
| `harness list registry_module`          | List Terraform/OpenTofu modules published to the IaCM registry.   |
| `harness get registry_module <id>`      | Get a registry module by identifier.                              |
| `harness list provider`                 | List Terraform providers registered with IaCM.                    |
| `harness get provider <id>`             | Get a provider by identifier.                                     |

---

## Artifact Registry (HAR)

Source: [`pkg/spec/har.spec.yaml`](pkg/spec/har.spec.yaml). Ships as a separate `harness-har` binary and is dispatched transparently from `harness`.

### Registries

| Command                                | One-line description                                                                            |
| -------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `harness list registry`                | List artifact registries in a project.                                                          |
| `harness get registry <id>`            | Get an artifact registry by identifier.                                                         |
| `harness create registry`              | Create a new artifact registry.                                                                 |
| `harness delete registry <id>`         | Delete an artifact registry by identifier.                                                      |
| `harness configure registry <id>`      | Configure a local package-manager client (e.g. `.npmrc`, `pip.conf`) to use a Harness registry. |

### Registry metadata

| Command                                | One-line description                                                        |
| -------------------------------------- | --------------------------------------------------------------------------- |
| `harness get registry_metadata <id>`   | Get metadata for an artifact registry.                                      |
| `harness update registry_metadata`     | Update metadata on an artifact registry (`--set key=value`, `--del key`).   |

### Artifacts — push (per-format)

| Command                                | One-line description                                          |
| -------------------------------------- | ------------------------------------------------------------- |
| `harness push artifact:generic`        | Push one or more generic artifacts to a Harness registry.     |
| `harness push artifact:maven`          | Push a Maven artifact (`.jar`/`.war`) to a Harness registry.  |
| `harness push artifact:npm`            | Push an npm package (`.tgz`) to a Harness registry.           |
| `harness push artifact:python`         | Push a Python package (`.whl`) to a Harness registry.         |
| `harness push artifact:nuget`          | Push a NuGet package (`.nupkg`) to a Harness registry.        |
| `harness push artifact:rpm`            | Push an RPM package to a Harness registry.                    |
| `harness push artifact:cargo`          | Push a Cargo crate (`.crate`) to a Harness registry.          |
| `harness push artifact:go`             | Push a Go module to a Harness registry.                       |
| `harness push artifact:conda`          | Push a Conda package to a Harness registry.                   |
| `harness push artifact:dart`           | Push a Dart package to a Harness registry.                    |
| `harness push artifact:composer`       | Push a Composer package (`.zip`) to a Harness registry.       |
| `harness push artifact:ruby`           | Push a Ruby gem to a Harness registry.                        |
| `harness push artifact:swift`          | Push a Swift package to a Harness registry.                   |
| `harness push artifact:puppet`         | Push a Puppet module (`.tar.gz`) to a Harness registry.       |
| `harness push artifact:debian`         | Push a Debian package (`.deb`/`.dsc`; `--distribution`/`--component` required). |
| `harness push artifact:conan`          | Push a Conan package to a Harness registry.                   |
| `harness push artifact:helm`           | Push a Helm chart to a Harness registry.                      |
| `harness push artifact:docker`         | Push a Docker image to a Harness registry.                    |

### Artifacts — pull / list / get / delete

| Command                                | One-line description                                          |
| -------------------------------------- | ------------------------------------------------------------- |
| `harness pull artifact <registry>`     | Pull a generic artifact from a Harness registry.              |
| `harness list artifact <registry>`     | List artifacts in a registry.                                 |
| `harness get artifact <id>`            | Get artifact metadata by registry and name.                   |
| `harness delete artifact <id>`         | Delete an artifact and all its versions.                      |
| `harness delete artifact:bulk <pattern>` | Bulk-delete artifacts matching a name pattern (`--registry` required; `--version`, `--dry-run`, `--force`). |

### Artifact versions

| Command                                                | One-line description                                                |
| ------------------------------------------------------ | ------------------------------------------------------------------- |
| `harness list artifact_version`                        | List versions of an artifact.                                       |
| `harness get artifact_version <id>`                    | Get artifact-version metadata.                                      |
| `harness delete artifact_version <id>`                 | Delete a specific artifact version.                                 |
| `harness list artifact_file`                           | List files inside a specific artifact version.                      |
| `harness execute artifact_version:copy <id>`           | Copy a specific artifact version to another registry.               |
| `harness execute artifact_version:firewall_scan <id>`  | Evaluate firewall policy for a specific artifact version.           |

### Package-manager install helpers

| Command                                   | One-line description                                                          |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| `harness execute artifact:npm_install`    | Run `npm install` against a Harness npm registry.                           |
| `harness execute artifact:npm_ci`         | Run `npm ci` against a Harness npm registry.                                |
| `harness execute artifact:pip_install`    | Run `pip install` against a Harness PyPI registry.                            |
| `harness execute artifact:mvn_install`    | Run Maven dependency resolution against a Harness Maven registry.             |
| `harness execute artifact:dotnet_restore` | Run `dotnet restore` against a Harness NuGet registry.                        |

### Artifact / version metadata

| Command                                       | One-line description                                                          |
| --------------------------------------------- | ----------------------------------------------------------------------------- |
| `harness get artifact_metadata <id>`          | Get metadata for an artifact.                                                 |
| `harness update artifact_metadata`            | Update metadata on an artifact (`--set key=value`, `--del key`).              |
| `harness get artifact_version_metadata <id>`  | Get metadata for an artifact version.                                         |
| `harness update artifact_version_metadata`    | Update metadata on an artifact version (`--set key=value`, `--del key`).      |

### Registry-level execute verbs

| Command                                       | One-line description                                                                |
| --------------------------------------------- | ----------------------------------------------------------------------------------- |
| `harness execute registry:firewall_scan`      | Audit lock-file dependencies against firewall policies for a registry.              |
| `harness execute registry:migrate`            | Migrate artifacts from a source registry into Harness using a config file (`-f`).   |

---

## Code (Harness Code)

Source: [`pkg/spec/code.spec.yaml`](pkg/spec/code.spec.yaml).

Built-in git hosting. Repositories are top-level. PRs, branches, commits, tags, and labels live inside a repo. Compound IDs use `<repo>/<pr_number>`, `<repo>/<branch>`, `<repo>/<sha>`, `<repo>/<key>` (labels), `<repo>/<pr_number>/<reviewer_id>`, and `<repo>/<pr_number>/<comment_id>` where noted below.

### Repositories

| Command                              | One-line description                                                                                              |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `harness list repository`            | List code repositories (multi-level — supports account/org/project scope).                                        |
| `harness get repository <id>`        | Get a repository by identifier.                                                                                   |
| `harness create repository <id>`     | Create a new repository (`--set identifier=<name> [default_branch=main] [description=…] [is_public=true]`).       |
| `harness update repository <id>`     | Update a repository (`description`, `default_branch`, `is_public`).                                               |
| `harness delete repository <id>`     | Delete a repository by identifier.                                                                                |

### Pull Requests

| Command                                          | One-line description                                                                                                        |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `harness list pr <repo>`                         | List pull requests for a repository (`--state`, `--author <email\|uid\|id>`, `--search`, `--created-after`, `--sort`, `--order`). |
| `harness list pr:mine`                           | List pull requests **you authored** across every repo in scope (`--state`, `--created-after`, `--created-before`).          |
| `harness list pr:review_pending`                 | List pull requests **awaiting your review** across every repo in scope (`--state`, `--created-after`, `--created-before`).  |
| `harness get pr <repo>/<pr_number>`              | Get pull request details (rich text output via workflow formatter).                                                         |
| `harness create pr <repo>`                       | Create a pull request (`--set title=… source_branch=… target_branch=…`; `-f desc.md` for the description body).             |
| `harness update pr <repo>/<pr_number>`           | Update a pull request (`--set title=… description=… is_draft=…`, etc.).                                                     |
| `harness execute pr:merge <repo>/<pr_number>`    | Merge a pull request (`--method merge\|squash\|rebase\|fast-forward`, `--delete-branch`, `--dry-run`).                      |
| `harness execute pr:close <repo>/<pr_number>`    | Close a pull request without merging.                                                                                       |
| `harness execute pr:reopen <repo>/<pr_number>`   | Reopen a closed pull request.                                                                                               |
| `harness execute pr:ready <repo>/<pr_number>`    | Mark a draft pull request as ready for review.                                                                              |
| `harness execute pr:edit <repo>/<pr_number>`     | Edit a pull request's title and/or description (`--title`, `--description`).                                                |
| `harness execute pr:review <repo>/<pr_number>`   | Submit a review decision (`--decision approve\|changereq`).                                                                 |

### Review insights (Harness Code AI review)

| Command                                                  | One-line 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 (formatted for terminal output).            |
| `harness list pr_suggested_reviewer <repo>/<pr_number>`  | List AI-suggested reviewers for a pull request.                                      |
| `harness list pr_suggested_label <repo>/<pr_number>`     | List AI-suggested labels for a pull request.                                         |
| `harness list pr_success_criterion <repo>/<pr_number>`   | List AI review success-criteria results for a pull request.                          |

### Reviewers & codeowners

| Command                                                          | One-line description                                                                 |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `harness list code_principal`                                    | List Code principals (users/service accounts) in scope (`--search`).                 |
| `harness list pr_reviewer <repo>/<pr_number>`                    | List reviewers on a pull request (decision, type, added-by).                         |
| `harness create pr_reviewer <repo>/<pr_number>`                  | Add a reviewer (`--reviewer <email\|uid\|id>` — resolved automatically).            |
| `harness delete pr_reviewer <repo>/<pr_number>/<reviewer_id>`    | Remove a reviewer from a pull request.                                               |
| `harness list pr_codeowner <repo>/<pr_number>`                   | List codeowners evaluated on a pull request (pattern, owner, decision).              |

### Labels

| Command                                                          | One-line description                                                                 |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `harness list repo_label <repo>`                                 | List labels defined on a repository (`--search`).                                    |
| `harness create repo_label <repo>`                               | Define a repo-level label (`--key` required; `--color`, `--type static\|dynamic`, `--description`). |
| `harness update repo_label <repo>/<key>`                         | Update a repo-level label (`--new-key`, `--color`, `--type`, `--description`).       |
| `harness delete repo_label <repo>/<key>`                         | Delete a repo-level label.                                                           |
| `harness list pr_label <repo>/<pr_number>`                       | List labels assignable to a pull request (`--assignable`, `--search`).               |
| `harness execute pr:label <repo>/<pr_number>`                    | Assign a label to a pull request (`--label <label_id>`).                             |
| `harness execute pr:unlabel <repo>/<pr_number>`                  | Remove a label from a pull request (`--label <label_id>`).                           |

### Branches, Commits & Tags

| Command                                  | One-line description                                                       |
| ---------------------------------------- | -------------------------------------------------------------------------- |
| `harness list branch <repo>`             | List branches in a repository (`--search`).                                |
| `harness get branch <repo>/<branch>`     | Get branch details.                                                        |
| `harness create branch <repo>`           | Create a branch (`--set name=<branch> target=<sha_or_branch>`).            |
| `harness delete branch <repo>/<branch>`  | Delete a branch by name.                                                   |
| `harness list commit <repo>`             | List commits (`--branch <ref>`, `--path <file>`).                          |
| `harness list pr_commit <repo>/<pr_number>` | List commits in a pull request.                                         |
| `harness get commit <repo>/<sha>`        | Get commit details.                                                        |
| `harness list tag <repo>`                | List tags in a repository (`--search`).                                    |
| `harness create tag <repo>`              | Create a tag (`--set name=<tag> target=<sha>`).                            |
| `harness delete tag <repo>/<tag>`        | Delete a tag by name.                                                      |

### PR activity, comments & checks

| Command                                                  | One-line description                                                                       |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `harness list pr_activity <repo>/<pr_number>`            | List PR activity timeline (comments, reviews, state changes; `--kind`, `--type`).          |
| `harness list pr_comment <repo>/<pr_number>`             | List comments on a pull request.                                                           |
| `harness create pr_comment <repo>/<pr_number>`           | Post a comment (`-f <file>` or stdin; `--reply-to <id>` for threaded replies).             |
| `harness update pr_comment <repo>/<pr_number>/<id>`      | Edit an existing PR comment's text (`--text`).                                             |
| `harness delete pr_comment <repo>/<pr_number>/<id>`      | Delete a PR comment by identifier.                                                         |
| `harness list pr_check <repo>/<pr_number>`               | List status checks on a PR (includes pipeline ID, execution ID, and stage when reported).  |
| `harness list commit_check <repo>/<sha>`                 | List status checks on a specific commit SHA (`--search`).                                  |

---

## Resilience Testing (RT)

Source: [`pkg/spec/rt.spec.yaml`](pkg/spec/rt.spec.yaml).

Resilience Testing is how Harness verifies how a service holds up under stress. Load testing is the feature area available today: run JMeter, Locust, and k6 tests against your services. `rt` is the module; `loadtest` is the noun you type.

A **loadtest** is a reusable definition (tool, script, infrastructure, environment, tunables). Creating one does not run anything. `create loadtest <id> -f test.yaml` is the usual path — every tool type requires a `toolConfig` block that `--set` cannot express. Export with `get loadtest <id> --yaml -o test.yaml` and apply edits with `update loadtest <id> -f test.yaml`.

### Load tests

| Command | One-line description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `harness list loadtest` | List RT load tests (`--search`, `--tool JMeter\|Locust\|K6`, `--status`, `--environment`, `--tag`). |
| `harness get loadtest <id>` | Get an RT load test definition (`--yaml` for a body you can edit and send back with `update -f`). |
| `harness create loadtest <id>` | Create an RT load test from a YAML body (`-f test.yaml` required for `toolConfig`). |
| `harness create loadtest:from_json <id>` | Create an RT load test from a declarative endpoint spec (`-f request.json`; spec under `jsonSpec`). |
| `harness create loadtest:from_template <id>` | Instantiate an RT load test from a template (`--template`; REFERENCE vs LOCAL copy). |
| `harness update loadtest <id>` | Update an RT load test from YAML (`-f test.yaml`). |
| `harness update loadtest:json_spec <id>` | Update the JSON endpoint spec on a JSON-backed RT load test (`-f request.json`). |
| `harness delete loadtest <id>` | Delete an RT load test. |
| `harness list loadtest:variables <id>` | List variables and runtime inputs the test accepts (override these with `--set` on execute). |
| `harness execute loadtest:sync <id>` | Re-pull a REFERENCE (template-backed) test after its template changes. |
| `harness execute loadtest <id>` | Start a run (`--set targetUsers=50` for this run only; `--follow` streams until terminal). |

### Runs

| Command | One-line description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `harness list loadtest_run` | List runs (`list loadtest_run` across the project, or `list loadtest_run <loadtest-id>` for one test; `--status`, `--search`). |
| `harness get loadtest_run <run-id>` | Get a run (`--follow` to stay attached while it is live). |
| `harness update loadtest_run <run-id>` | Retarget a live run (`--set target_users=200`). |
| `harness execute loadtest_run:stop <run-id>` | Stop a live run early. |
| `harness execute loadtest_run:rerun <run-id>` | Start a fresh run of the same load test with the same shape. |
| `harness get loadtest_run:summary <run-id>` | Headline result numbers for a run. |
| `harness list loadtest_run:metrics <run-id>` | Time-series metrics for a run. |
| `harness list loadtest_run:graph <run-id>` | Render-ready chart series for a run. |
| `harness list loadtest_run:requests <run-id>` | Sampled individual requests from a run. |
| `harness list loadtest_run:endpoints <run-id>` | Per-endpoint breakdown for a run. |

### Scripts

| Command | One-line description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `harness get loadtest_script <loadtest-id>` | Show the script currently attached to a load test. |
| `harness update loadtest_script <loadtest-id>` | Upload a new script (`-f test.jmx` or stdin; optional `--description` on the revision). |
| `harness list loadtest_script:revisions <loadtest-id>` | List script revisions. |
| `harness get loadtest_script:revision <loadtest-id>` | Get one script revision (`--revision`). |

### Templates

Templates live in hubs. `list loadtest_template` spans every hub unless you pass `--hub`. Other template commands target one hub — pass `--hub` when the template is not in the default (unhubbed) one. Revisions use `<template-id>/<rev>`.

| Command | One-line description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `harness list loadtest_template` | List RT load test templates (`--hub` to narrow). |
| `harness get loadtest_template <id>` | Get a template. |
| `harness create loadtest_template <id>` | Create a template (`-f`). |
| `harness update loadtest_template <id>` | Update a template (`-f`). |
| `harness delete loadtest_template <id>` | Delete a template. |
| `harness list loadtest_template:variables <id>` | List variables a template exposes. |
| `harness get loadtest_template:yaml <id>` | Export a template as YAML. |
| `harness list loadtest_template_revision <id>` | List revisions of a template. |
| `harness create loadtest_template_revision <id>/<rev>` | Add a template revision. |
| `harness get loadtest_template_revision <id>/<rev>` | Get a template revision. |
| `harness delete loadtest_template_revision <id>/<rev>` | Delete a template revision. |

### Composite tests & usage

A **composite_loadtest** runs RT load tests and chaos probes together as stages. Identifiers must not contain hyphens — use underscores. **loadtest_usage** is account-wide and ignores `--org` / `--project`.

| Command | One-line description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `harness list composite_loadtest` | List composite RT load tests (`--search`). |
| `harness create composite_loadtest <id>` | Create a composite test (`--loadtest` and `--probe` required; `--probe-infra`, `--probe-duration`). |
| `harness list loadtest_usage` | Break account load-testing usage down by service (`--from`, `--to`; e.g. `30d`). |
| `harness get loadtest_usage` | Show total account load-testing usage (`--from`, `--to`). |
| `harness get loadtest_usage:report` | Export the account usage report (`--from`, `--to`, `--format csv`). |

---

## GitOps

Source: [`pkg/spec/gitops.spec.yaml`](pkg/spec/gitops.spec.yaml).

Argo CD–backed GitOps: agents (control plane in your cluster), applications, destination clusters, source repositories, and ApplicationSets. Compound IDs use `<agent>/<name>` (applications, clusters, repositories) or `<agent>/<uuid>` (ApplicationSets).

### Agents

| Command | One-line description |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `harness list gitops_agent` | List GitOps agents (`--type`, `--scope`, `--health-status`, `--connected-status`, `--search`). |
| `harness get gitops_agent <id>` | Get a GitOps agent by identifier. |
| `harness create gitops_agent <id>` | Create a GitOps agent record (`--set name=… namespace=…`, or `-f agent.yaml`). Does not install into a cluster. |
| `harness delete gitops_agent <id>` | Delete a GitOps agent. |
| `harness execute gitops_agent:install <id>` | Fetch Helm override values or a kubectl manifest for installing an agent (`--method helm\|yaml`, `--output_file` required; optional `-f install.yaml`). Does not run helm/kubectl for you. |

### Applications

| Command | One-line description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `harness list gitops_application` | List GitOps applications (`--search`). |
| `harness get gitops_application <agent/app>` | Get a GitOps application (YAML via `--yaml` is the Argo app spec). |
| `harness create gitops_application <agent>` | Create an application (`-f app.yaml` required; `--cluster` required; `--repo` or `--skip-repo-validation`). |
| `harness update gitops_application <agent/app>` | Update an application (`-f app.yaml`; optional `--cluster`/`--repo`). |
| `harness delete gitops_application <agent/app>` | Delete an application (`--propagation-policy`, `--no-cascade`, `--remove-finalizers`, `--app-namespace`). |
| `harness execute gitops_application:sync <agent/app>` | Sync an application (`--revision`, `--prune`, `--dry-run`). |
| `harness execute gitops_application:refresh <agent/app>` | Refresh an application (`--hard` invalidates manifest caches). |

### Clusters

| Command | One-line description |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `harness list gitops_cluster` | List GitOps clusters (`--search`, `--agent`). |
| `harness get gitops_cluster <agent/cluster_id>` | Get a GitOps cluster by identifier. |
| `harness create gitops_cluster <agent/cluster_id>` | Register a cluster on an agent (`-f cluster.yaml`; `--upsert`). |
| `harness update gitops_cluster <agent/cluster_id>` | Update a cluster (`-f cluster.yaml`; `--force-update`). |
| `harness delete gitops_cluster <agent/cluster_id>` | Delete a cluster (`--force-delete`, `--query-name`). |

### Repositories

| Command | One-line description |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `harness list gitops_repository` | List GitOps repositories (`--search`, `--agent`). |
| `harness get gitops_repository <agent/repo_id>` | Get a GitOps repository by identifier. |
| `harness create gitops_repository <agent/repo_id>` | Register a Git repo on an agent (`-f repo.yaml`; `--upsert`, `--repo-creds-id`). |
| `harness update gitops_repository <agent/repo_id>` | Update a repository (`-f repo.yaml`). |
| `harness delete gitops_repository <agent/repo_id>` | Delete a repository (`--force-delete`, `--query-repo`). |

### ApplicationSets

| Command | One-line description |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `harness list gitops_application_set` | List GitOps ApplicationSets (`--search`, `--agent`). |
| `harness get gitops_application_set <agent/uuid>` | Get an ApplicationSet by agent + UUID. |
| `harness create gitops_application_set <agent>` | Create an ApplicationSet (`-f appset.yaml`; `--upsert`, `--dry-run`). |
| `harness update gitops_application_set <agent/uuid>` | Update an ApplicationSet (`-f appset.yaml`; `--upsert`, `--dry-run`). |
| `harness delete gitops_application_set <agent/uuid>` | Delete an ApplicationSet. |

---
## Harness Worker Agents

Source: [`pkg/spec/platform.spec.yaml`](pkg/spec/platform.spec.yaml) — noun `agent`.

Harness Worker Agents are Harness-managed automation workers, defined by a wrapper YAML whose `spec` key carries the agent pipeline definition. The commands live under the `platform` module.

| Command                              | One-line description                                                                                                                              |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `harness list agent`                 | List Harness Worker Agents.                                                                                                                       |
| `harness get agent <id>`             | Get a Harness Worker Agent's definition (`-o yaml` produces a valid wrapper for editing).                                                         |
| `harness create agent <id>`          | Create a Harness Worker Agent from a wrapper YAML (`-f agent.yaml`). The wrapper carries `name`, `description`, and the agent `spec` string.      |
| `harness update agent <id>`          | Update a Harness Worker Agent from a wrapper YAML.                                                                                                |

---

## Governance

Source: [`pkg/spec/governance.spec.yaml`](pkg/spec/governance.spec.yaml).

OPA (Open Policy Agent) policies authored in Rego, grouped into **policy sets** that are evaluated on pipeline runs and resource changes.

### Policies

| Command                              | One-line description                                                      |
| ------------------------------------ | ------------------------------------------------------------------------- |
| `harness list policy`                | List governance policies.                                                 |
| `harness get policy <id>`            | Get a policy's details (including its Rego source).                       |
| `harness create policy <id>`         | Create a policy (`--set name=<name> rego='package main…'` or `-f policy.yaml`). |
| `harness update policy <id>`         | Update a policy's name or Rego source.                                    |
| `harness delete policy <id>`         | Delete a policy by identifier.                                            |

### Policy Sets

| Command                              | One-line description                                                                                              |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `harness list policy_set`            | List policy sets.                                                                                                 |
| `harness get policy_set <id>`        | Get a policy set's details.                                                                                       |
| `harness create policy_set <id>`     | Create a policy set (`--set name=<name> type=pipeline action=onrun enabled=true`).                                |
| `harness update policy_set <id>`     | Update a policy set (name, enabled, member policies).                                                             |
| `harness delete policy_set <id>`     | Delete a policy set by identifier.                                                                                |

### Policy Evaluations

| Command                              | One-line description                                                              |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| `harness list policy_evaluation`     | List recorded policy-set evaluations against resources.                           |

---

## Audit

Source: [`pkg/spec/audit.spec.yaml`](pkg/spec/audit.spec.yaml).

Read-only access to the audit trail across **every** Harness module. Every create/update/delete produces an `audit_event`.

| Command                          | One-line description                                                                                                                     |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `harness list audit_event`       | List audit-trail events (defaults to the last 7 days; filter with `--from`, `--to`, `--resource-type`, `--action`, `--principal`).       |
| `harness get audit_event <id>`   | Get a single audit event with the YAML diff of the change.                                                                               |

---

## Interactive TUI (`--ui`)

Many commands support a `--ui` flag that launches an interactive terminal UI (Bubble Tea). It requires a TTY on both stdin and stdout — running under a pipe, in CI, or with output redirected fails with `--ui requires an interactive terminal (TTY)`.

Three flavors:

- **Paged list browser** — auto-enabled on every `list` command whose API supports paging. Scroll, search, and drill into rows. Wired in [`pkg/registry/registry.go`](pkg/registry/registry.go) at the `list`+paging branch.
- **Resource picker / detail view** — opt-in on selected `get` commands via `ui: true` in the spec. Used to interactively pick or inspect a single resource.
- **Live log viewer** — `harness get execution_log <[pipeline/]execId> --ui` streams logs step-by-step in real time, shows the graph on the left, and offers Details/Inputs/Outputs tabs. Left/right scrolling, spinner, and save-to-file are built in.

### `list` commands with `--ui`

| Module       | Commands                                                                                                                                                                                                                                       |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core`       | `auth profiles`, `list module`, `list noun`                                                                                                                                                                                                    |
| `platform`   | `list organization`, `list project`, `list user`, `list user_group`, `list service_account`, `list role`, `list role_assignment`, `list resource_group`, `list permission`, `list setting`, `list connector`, `list secret`, `list delegate`, `list delegate_token`, `list agent`, `list entity_usage` |
| `pipeline`   | `list pipeline`, `list pipeline_v1`, `list execution`, `list execution_step`, `list execution_log`, `list trigger`, `list input_set`, `list template`, `list approval_instance`, `list freeze_window`                                          |
| `cd`         | `list service`, `list environment`, `list infrastructure`, `list service_override`                                                                                                                                                             |
| `iacm`       | `list workspace`, `list host`, `list inventory`, `list playbook`, `list registry_module`, `list provider`                                                                                                                                      |
| `har`        | `list registry`, `list artifact`, `list artifact_version`, `list artifact_file`                                                                                                                                                                |
| `code`       | `list repository`, `list pr`, `list pr:mine`, `list pr:review_pending`, `list branch`, `list commit`, `list pr_commit`, `list tag`, `list pr_activity`, `list pr_comment`, `list pr_check`, `list commit_check`, `list pr_reviewer`, `list pr_codeowner`, `list pr_label`, `list repo_label`, `list pr_suggested_reviewer`, `list pr_suggested_label`, `list pr_success_criterion`, `list code_principal` |
| `rt`         | `list loadtest`, `list loadtest:variables`, `list loadtest_run`, `list loadtest_run:metrics`, `list loadtest_run:graph`, `list loadtest_run:requests`, `list loadtest_run:endpoints`, `list loadtest_script:revisions`, `list loadtest_template`, `list loadtest_template:variables`, `list loadtest_template_revision`, `list composite_loadtest`, `list loadtest_usage` |
| `gitops`      | `list gitops_agent`, `list gitops_application`, `list gitops_cluster`, `list gitops_repository`, `list gitops_application_set` |
| `governance` | `list policy`, `list policy_set`, `list policy_evaluation`                                                                                                                                                                                     |
| `audit`      | `list audit_event`                                                                                                                                                                                                                             |

### `get` commands with `--ui`

| Command                              | What `--ui` does                                                                              |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `harness get project --ui`           | Interactive project picker (org-aware).                                                       |
| `harness get workspace --ui`         | Interactive IaCM workspace picker.                                                            |
| `harness get artifact_version --ui`  | Interactive artifact + version picker.                                                        |
| `harness get execution_log --ui`     | Live log viewer for a pipeline execution — tails steps in real time, supports navigation, tab views, and save. Use the `<[pipeline/]execId>` form (not a full log key) and don't pair with `--stage` or `--step`. |

### Notes

- `--ui` is mutually exclusive with `--format`, `--out`, and stream redirection — pick one.
- For `list` commands with `--ui`, paging flags (`--limit`, `--offset`, `--all`, `--count`) are ignored; the TUI handles paging itself.
- When a new noun is added to a spec with a paged list endpoint, `--ui` is wired automatically — no extra spec changes needed.

---

## Cheat sheet for AI agents

Rules the CLI is guaranteed to follow — safe to build on top of without extra probing.

1. **Grammar is strict:** every non-management command is `harness <verb> <noun> [id] [flags]`. Never `harness <noun> <verb>`. When in doubt, run `harness list noun --matrix`.
2. **Every `list` accepts `--limit`, `--offset` (or `--page`), `--all`, and `--count`.** For unbounded pulls prefer `--all`; for size probes use `--count`.
3. **Pick the right `--format`:** `table`/`csv`/`tsv` on `list` are projected columns only (not the full object). `json` is the raw API response + envelope (any verb). `yaml` on `get` is the envelope-stripped body for `update -f` / `create -f`. For automation prefer `--format json` (or `jsonl` when available); `--json` / `--yaml` are shorthands.
4. **IDs vs compound IDs.** Any command whose ID label reads `<parent>/<child>` (e.g. `<repo>/<pr_number>`, `<[pipeline/]exec_id>`) accepts that exact form as its positional argument. Slashes are meaningful and are NOT URL-encoded.
5. **`--set key=value` on `create`/`update` is repeatable and supports dot paths** (`--set variables.region=us-east-1`). `--del key` clears fields on `update`.
6. **`-f file.yaml` reads the body from a file** on create/update (or `-f -` for stdin). It is mutually compatible with `--set` — `--set` overrides matching keys from the file.
7. **`--ui` needs a TTY.** In non-interactive contexts (CI, headless agents) never pass `--ui`; use `--follow` for streaming and `--format jsonl` for iteration instead.
8. **Auth is per-profile.** Default profile is used unless `--profile` or `HARNESS_PROFILE` is set. `harness auth env --export` prints the env vars needed to talk to the same account outside the CLI.
9. **Discovery, not memorization.** If you don't know a flag or a field name, `harness <verb> <noun> --help` and `harness get noun <noun>` are always available.
10. **Idempotency signals.** `create` is not idempotent — it errors if the resource exists. `update` uses get-then-put semantics (safe to re-run with the same `--set`). `delete` is idempotent-safe with `--ignore-not-found`.

Live source of truth for anything below (never trust a stale doc when the CLI can answer):

```sh
harness list noun --matrix        # every noun × verb combo
harness get noun pipeline         # fields and supported verbs for one noun
harness get module code           # domain model, nouns, and commands for a module
harness <verb> <noun> --help      # full flag list for any command
```