Harbourmaster command-line interface

The harbourmaster-ai-review executable supports GitHub pull request review. The package script ai-review builds the executable before running it.

Invocation

From the EOS repository root, the package-script form is:

text

pnpm --filter @eos/harbourmaster ai-review -- [options]

GitHub mode

text

harbourmaster-ai-review --repo OWNER/NAME --pull-number NUMBER [options]

Option	Environment fallback	Default	Description
`--repo`	`GITHUB_REPOSITORY`	none	Repository in `owner/name` form. Required.
`--pull-number`	`PR_NUMBER`	none	Positive pull request number. Required.
`--head-sha`	`HEAD_SHA`	none	Expected pull request head SHA. A mismatch causes a neutral skip in the runner; the action requires a value and also verifies the workspace checkout.
`--mode`	`AI_REVIEW_MODE`	`comment`	Run mode: `silent`, `check-only`, `comment`, or `blocking`.
`--workspace-root`	`GITHUB_WORKSPACE`	current directory	Canonical checkout that the code-quality reviewer can inspect alongside the staged diff.
`--workspace-boundary`	`GITHUB_WORKSPACE`	current directory	Canonical directory boundary that must contain the workspace root.
`--config-path`	`OPENCODE_CONFIG_PATH`	bundled config when called by the action	Trusted OpenCode configuration directory.
`--strict-runtime`	`HARBOURMASTER_STRICT_RUNTIME`	`false`	Fails when runtime degradation prevents real review execution.
`--debug`	`DEBUG`	`false`	Enables runner outcome details.

GitHub authentication is read from GITHUB_AUTH_MODE and its corresponding credential variables before Octokit is created. The runner masks the resolved credentials and removes them from its environment before OpenCode starts.

Variable	Required when	Description
`GITHUB_AUTH_MODE`	No	`github_token` (default) or `github_app`.
`GITHUB_TOKEN`	`github_token`	Token used to create Octokit.
`GITHUB_APP_ID`	`github_app`	GitHub App ID.
`GITHUB_APP_PRIVATE_KEY`	`github_app`	PEM private key.
`GITHUB_APP_INSTALLATION_ID`	`github_app`	Installation ID.

Variable	Description
`HARBOURMASTER_OPENCODE_EVENT_LOG_PATH`	Optional path for the raw OpenCode JSON event log. The Action sets this to a job artifact file.

GitHub mode streams raw OpenCode standard output and emits Effect logfmt telemetry to standard output. Raw OpenCode standard error is also forwarded unchanged. Fatal CLI parsing or startup errors are emitted as a redacted cli_error logfmt record on standard error.

Dashboard command

The dashboard has a separate package entry point:

text

pnpm --filter @eos/harbourmaster dashboard:build -- \
  --input INPUT.log --output OUTPUT [--format FORMAT]

--input and --output are required. --format accepts markdown, html, or json. Without --format, .html selects HTML, .json selects JSON, and all other extensions select Markdown.

Exit codes

Code	Meaning
`0`	Successful, skipped, check-only, or allowed degraded outcome.
`10`	Harbourmaster or OpenCode configuration error.
`20`	GitHub, model-provider, or diff-provider error.
`30`	OpenCode or internal runtime error.
`40`	Model context or structured-output validation error.
`50`	GitHub publication error.

Argument validation errors outside the classified runner contract exit with code 1.