# refpoint run

> Execute a profile against one or more targets.

Source: https://refpoint.dev/docs/cli-reference/run

```
refpoint run PROFILE_PATH [flags]
```

Executes a profile against one or more targets. It takes exactly one path
argument. The path may be a single control file, a profile directory containing
`profile.rpp`, or a plain directory that is scanned for profile subdirectories
up to `scan_depth` levels.

## Connection flags

| Flag | Default | Description |
|------|---------|-------------|
| `--ssh-key PATH` | | SSH private key |
| `--ssh-password STRING` | | SSH password |
| `--ssh-known-hosts-file PATH` | `~/.ssh/known_hosts` | Also accepts `accept-new` and `insecure` |
| `--connect-retries N` | 0 | Extra SSH attempts on transient failures. Attempt N waits N times 2 seconds |
| `--winrm-password STRING` | | WinRM password |
| `--winrm-https` | false | Use HTTPS for WinRM on port 5986 |
| `--winrm-insecure` | false | Skip TLS verification for WinRM HTTPS. Prints a warning |
| `--winrm-allow-unencrypted` | false | Permit plain HTTP WinRM to a peer that cannot negotiate NTLM sealing |
| `--sudo` | false | Run commands under sudo on SSH and local Unix targets |
| `--sudo-password STRING` | | Password for `sudo -S`, or set `REFPOINT_SUDO_PASSWORD` |

## Target selection

| Flag | Default | Description |
|------|---------|-------------|
| `--targets LIST` | | Additional target addresses, repeatable and comma-separated |
| `--targets-file PATH` | | HCL inventory file |
| `--host-tag key=value` | | Select inventory targets by tag. Repeating a key ORs its values, distinct keys AND |
| `--target-parallelism N` | 16 | Max concurrent target scans. 0 means the default |

With no target given at all, the run defaults to `local`. A `--host-tag`
selector that matches nothing is an error, not a silent fall-through to local.

## Filtering

| Flag | Description |
|------|-------------|
| `--control LIST` | Only these control IDs |
| `--skip LIST` | Exclude these control IDs |
| `--tag key=value` | Filter controls by tag, repeatable |
| `--impact FLOAT` | Only controls with impact at or above this value, 0.0 to 1.0 |

## Variables and waivers

| Flag | Description |
|------|-------------|
| `--var key=value` | Override a profile variable, repeatable. Always a string |
| `--var-file PATH` | HCL file of overrides, native types preserved |
| `--waiver-file PATH` | HCL file declaring accepted exceptions |

`--var` wins over `--var-file`.

## Output

| Flag | Default | Description |
|------|---------|-------------|
| `--format FORMAT` | `terminal` | `terminal`, `json`, `junit`, `html`, `gha`, `gitlab`, `wazuh` |
| `--output PATH` | stdout | Report file, created 0600 |
| `--reporter format[:path]` | | Repeatable. Cannot be combined with `--format` or `--output`. At most one entry may write to stdout |
| `--audit-log PATH` | | Append an NDJSON trail of every transport operation, created 0600 |
| `--signing-key PATH` | | Ed25519 PEM key for report attestation |

## Execution

| Flag | Default | Description |
|------|---------|-------------|
| `--concurrency N` | 1 | Controls executed in parallel per target. Must be at least 1 |
| `--timeout DURATION` | `30s` | Per-control timeout, Go duration syntax |
| `--threshold FLOAT` | 0 | Exit 5 when the weighted score falls below this percentage, 0 to 100 |
| `--dry-run` | false | Print the execution plan and exit 0 |

`--dry-run` supports only the terminal and json formats and cannot be combined
with `--reporter`.

## Security

| Flag | Default | Description |
|------|---------|-------------|
| `--allowed-commands LIST` | empty | Executable basenames the `command` resource may run. Deny by default. `*` permits everything |
| `--allow-private-http` | false | Let `http` checks reach loopback, link-local and RFC1918 destinations |

## Examples

Run locally against the shipped example profile, which uses one `command`
check:

```shell
refpoint run profiles/example --allowed-commands uname
```

Write three reports from one run:

```shell
refpoint run baseline \
  --reporter terminal \
  --reporter junit:report.xml \
  --reporter html:report.html
```

Scan a tagged slice of an inventory and gate on the weighted score:

```shell
refpoint run baseline \
  --targets-file fleet.rptargets \
  --host-tag env=production \
  --host-tag role=web \
  --threshold 95 \
  --format json --output result.json
```

## Exit codes

| Code | Condition |
|------|-----------|
| 0 | Everything passed |
| 1 | At least one control failed, and either no threshold was set or the score met it |
| 2 | At least one target was unreachable or a control errored |
| 5 | Controls failed and the weighted score fell below `--threshold` |
| 130 | Interrupted by SIGINT or SIGTERM |