# gnhf CLI reference

**This file is a cache, not the source of truth.** Verify with `gnhf --help` before relying on a
flag; the roster and options change between releases. Captured against **gnhf v0.1.49**.

Normally you should not call `gnhf` directly — use `scripts\start-run.ps1`, which adds the preflight
checks and the guaranteed finalize step. This reference exists for reading the flags the wrapper
passes and for diagnosing a run.

## Install

The skill **vendors its own copy** — you should not need a global install:

```powershell
npm install gnhf --prefix "$env:USERPROFILE\.scout\m-skills\lights-out\vendor"
```

That produces `vendor\node_modules\gnhf\dist\cli.mjs`, which the scripts run via `node`. Only `node`
needs to be on PATH; the npm-generated `gnhf` / `gnhf.cmd` / `gnhf.ps1` shims are irrelevant here
(they are 28-line launchers that resolve paths relative to their own location, so they cannot be
moved or copied anywhere useful).

Resolution order is `$env:LIGHTS_OUT_GNHF` → vendored → `gnhf` on PATH.

On this machine, `registry.npmjs.org` is TLS-intercepted and fails with
`ERR_SSL_SSL/TLS_ALERT_HANDSHAKE_FAILURE`. Use the configured Microsoft proxy registry — that is the
default, so a plain `npm install` works; do **not** pass `--registry=https://registry.npmjs.org`.

A global `npm install -g gnhf` still works as a fallback, but nothing in the skill requires it.

## Flags

| Flag | Notes |
|---|---|
| `--agent <agent>` | `claude`, `codex`, `rovodev`, `opencode`, `copilot`, `pi`, `cursor`, or `acp:<target-or-command>` |
| `--model <model>` | Overrides `agentModel.<agent>` from config |
| `--max-iterations <n>` | Abort after N iterations |
| `--max-tokens <n>` | Abort after N total input+output+cache tokens |
| `--max-rate-limit-wait <dur>` | Abort after this much cumulative usage-limit wait (`30m`, `2h`, `0`) |
| `--fallback-model <model>` | Retry a Claude usage-limit rejection with this model instead of waiting |
| `--stop-when <condition>` | Natural-language completion condition; survives resume. `""` clears it |
| `--prevent-sleep <on\|off>` | Keep the machine awake. Always `on` for overnight runs |
| `--worktree` | Run in a separate git worktree, enabling parallel runs on one repo |
| `--current-branch` | Commit on the current branch instead of creating `gnhf/<runId>` |
| `--push` | Push after each successful iteration |
| `--meteor-frequency <0-5>` | TUI meteors. The wrapper sets `0` (no TTY, so it is only log noise) |
| `--mock` | **TUI demo only.** Replays canned iterations, does no git work, does not exit. Never use it to validate a real run |

## Run identity

Deterministic, derived from the prompt — so a run is findable months later without guessing:

```
slug   = prompt.toLowerCase()
           .replace(/[^a-z0-9]+/g,'-')
           .replace(/^-+|-+$/g,'')
           .slice(0,20)
           .replace(/-+$/,'')
hash   = sha256(prompt).hex.slice(0,6)
runId  = "<slug>-<hash>"
branch = "gnhf/<runId>"
```

On collision gnhf appends `-1`, `-2`, …, so the predicted id may not be the final one.
`Resolve-LightsOutRunDir` in `scripts\lib.ps1` handles that.

## Artifacts

Per run, in `<repo>\.gnhf\runs\<runId>\` (gitignored by gnhf, so it never pollutes the branch):

| File | Contents |
|---|---|
| `prompt.md` | The objective as given |
| `notes.md` | The agent's own iteration log — **claims, not evidence** |
| `end-state.json` | `status`, `stopCondition`, `agentError`, `iterations`, `successCount`, `failCount`, `endedAt` |
| `gnhf.log` | JSONL lifecycle log with timings and full `error.cause` chains |
| `iteration-<n>.jsonl` | Raw agent stream per iteration. Large; never copied to the vault |
| `base-commit` | Commit the run branched from |
| `stop-when` | Persisted stop condition |

## Behaviors that break unattended runs

Both are enforced by the wrapper's preflight; know them when diagnosing a failure.

1. **Launching from a `gnhf/*` branch** prompts interactively to overwrite/continue, and hard-fails
   when stdin is not a TTY: *"Cannot show the overwrite prompt because stdin is not interactive."*
2. **An empty prompt with a non-TTY stdin** makes gnhf read the prompt *from* stdin and block
   forever.

Also: gnhf requires a clean working tree, never force-pushes, never auto-pulls, and commits each
successful iteration separately so a night can be reviewed or reverted one change at a time.

## Docs

Upstream project: <https://github.com/kunchenguid/gnhf> (`README.md`, `VISION.md`).

The vendored package also ships its own README locally — no network needed:
`vendor\node_modules\gnhf\README.md`.

This skill does **not** depend on a local clone of the gnhf source repo.