CLI reference¶

Every verb of helper, generated from the command definitions themselves so it cannot drift from what --help says. Verbs are grouped the way the tool groups them; each group's own --help lists its subcommands.

A few conventions hold across all of them:

Discovery is a read. discover <source> reads a source and prints what it saw; --persist writes it into the harness database and --dry-run previews that write.
Planners are reports. plan, bottlenecks and friends print a deterministic analysis; --narrate adds prose from a model, --persist records hits as findings with the standard lifecycle.
Execution is gated. exec run is the only path that changes the lab, and it runs through the trust gradient every time.

helper¶

homelab-helper - inventory, audit, and (eventually) recommendations.

Usage:

helper [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--install-completion`	boolean	Install completion for the current shell.	None
`--show-completion`	boolean	Show completion for the current shell, to copy it or customize the installation.	None
`--help`	boolean	Show this message and exit.	`False`

helper approvals¶

Phase 7 approval channel: configuration, what would ask you, who answered.

Usage:

helper approvals [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper approvals show¶

Channel status, what each pending proposal would get, and recent answers.

Usage:

helper approvals show [OPTIONS]

Options:

Name	Type	Description	Default
`--limit`	integer	Recent answers to show.	`10`
`--help`	boolean	Show this message and exit.	`False`

helper assert¶

Run and inspect configuration assertions.

Usage:

helper assert [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper assert list¶

List assertions with their latest run status.

Usage:

helper assert list [OPTIONS]

Options:

Name	Type	Description	Default
`--enabled` / `--all`	boolean	Show only enabled assertions (default), or every row.	`True`
`--help`	boolean	Show this message and exit.	`False`

helper assert load¶

Upsert ConfigurationAssertion rows from a YAML library file.

Idempotent: re-loading the same file twice produces no changes. Entries whose host: field references a hostname not in the harness DB are skipped with a reason (the loader is intentionally tolerant — land the library, then discover the hosts, then re-load).

Usage:

helper assert load [OPTIONS] PATH

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Parse and report what would change, but write nothing.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper assert run¶

Execute assertion(s) and persist AssertionRun rows + finding lifecycle.

Usage:

helper assert run [OPTIONS]

Options:

Name	Type	Description	Default
`--name`	text	Run a single assertion by name. Omit + use --all to run every enabled one.	None
`--all`	boolean	Run every enabled assertion.	`False`
`--include-disabled`	boolean	With --all, include assertions marked enabled=False.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper assert show¶

Show an assertion's definition and most-recent run evidence.

Usage:

helper assert show [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper audit¶

High-level lab audit roll-up.

Usage:

helper audit [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--top`, `-n`	integer range (between `0` and `50`)	Show this many most-recent open findings.	`5`
`--help`	boolean	Show this message and exit.	`False`

helper bottlenecks¶

Detect known bottleneck patterns and generate candidate mitigations.

Usage:

helper bottlenecks [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--persist`	boolean	Record hits as findings (reopen/resolve lifecycle).	`False`
`--narrate`	boolean	Narrate via the Planner agent.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper chat¶

Chat with the harness about your lab.

Usage:

helper chat [OPTIONS] [QUESTION] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--privacy`	text	Override the privacy policy (strict-local/prefer-local/open).	None
`--help`	boolean	Show this message and exit.	`False`

helper config¶

Show effective configuration and its sources.

Usage:

helper config [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper config init¶

Write a commented .env template to the per-user config directory.

Usage:

helper config init [OPTIONS]

Options:

Name	Type	Description	Default
`--force`	boolean	Overwrite an existing file.	`False`
`--path`	path	Write here instead of the config directory.	None
`--help`	boolean	Show this message and exit.	`False`

helper daemon¶

Run discovery, playbooks and the approval listener on a cadence.

Usage:

helper daemon [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper daemon run¶

Discovery → playbooks → listener, on cadences (or once with --once).

With a schedule file (--schedule or HOMELAB_HELPER_SCHEDULE) each probe and assertion runs on its own cadence from the same process.

Usage:

helper daemon run [OPTIONS]

Options:

Name	Type	Description	Default
`--sources`	text	Comma-separated discovery sources; default: every source `helper config` reports configured; '' to disable.	None
`--discovery-every`	integer	Minutes between discovery passes.	`60`
`--playbooks-every`	integer	Minutes between playbook passes.	`10`
`--listen-every`	integer	Minutes between listener passes.	`1`
`--ask` / `--no-ask`	boolean	Run the approval listener.	`True`
`--playbooks` / `--no-playbooks`	boolean	Run the playbooks.	`True`
`--digest` / `--no-digest`	boolean	Deliver the weekly digest when one is due.	`False`
`--digest-every`	integer	Minutes between digest checks (the window gates delivery).	`720`
`--schedule`	text	Probe/assertion cadence file (default: $HOMELAB_HELPER_SCHEDULE); '' to disable.	None
`--schedule-every`	integer	Minutes between checks for due probes and assertions (their cadences are in the file).	`5`
`--once`	boolean	One pass of each enabled job, then exit.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper db¶

Database management — init, status, migrations.

Usage:

helper db [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper db init¶

Upgrade the database to the latest revision and register shipped probes.

Usage:

helper db init [OPTIONS]

Options:

Name	Type	Description	Default
`--skip-probe-sync`	boolean	Skip probe entry-point sync after migration.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper db migrate¶

Generate a new Alembic migration. Equivalent to alembic revision.

Usage:

helper db migrate [OPTIONS] MESSAGE

Options:

Name	Type	Description	Default
`--autogenerate` / `--manual`	boolean	Use Alembic autogenerate (default) or scaffold a blank migration.	`True`
`--help`	boolean	Show this message and exit.	`False`

helper db reset¶

DESTRUCTIVE: drop all tables, then re-upgrade to head. Dev use only.

Usage:

helper db reset [OPTIONS]

Options:

Name	Type	Description	Default
`--yes`, `-y`	boolean	Confirm destructive reset without prompting.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper db status¶

Show the database's current Alembic revision and table count.

Usage:

helper db status [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper diff¶

Cross-source divergence (git desired-state vs live cluster).

Usage:

helper diff [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper diff git-vs-cluster¶

Report Argo CD git-vs-cluster drift; optionally record it as findings.

Usage:

helper diff git-vs-cluster [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Record drifted apps as DRIFT_CANDIDATE findings.	`False`
`--dry-run`	boolean	With --persist, preview + roll back.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper digest¶

Weekly summary of what changed, what is recommended, and what was done.

Usage:

helper digest [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper digest history¶

What was summarised, when, and whether it was delivered.

Usage:

helper digest history [OPTIONS]

Options:

Name	Type	Description	Default
`--limit`	integer	Most recent digests to show.	`10`
`--help`	boolean	Show this message and exit.	`False`

helper digest send¶

Deliver the digest and record its window.

A quiet window is recorded but not sent unless --quiet-ok: a weekly buzz that says "nothing happened" is the noise this slice exists to stop.

Usage:

helper digest send [OPTIONS]

Options:

Name	Type	Description	Default
`--days`	integer	Window in days; 0 means since the last digest.	`0`
`--quiet-ok`	boolean	Send even when nothing happened in the window.	`False`
`--out`	text	Also write the Markdown page to this path.	``
`--dry-run`	boolean	Render and report, but neither notify nor record.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper digest show¶

Render the digest page. Read-only — does not move the window.

Usage:

helper digest show [OPTIONS]

Options:

Name	Type	Description	Default
`--days`	integer	Window in days; 0 means since the last digest.	`0`
`--out`	text	Also write the Markdown page to this path.	``
`--help`	boolean	Show this message and exit.	`False`

helper discover¶

Run discovery probes against targets.

Usage:

helper discover [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover anomalies¶

Anomalies (Phase 10.3): guests and nodes outside their own usage baseline.

Usage:

helper discover anomalies [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover argocd¶

Read Argo CD Applications (read-only): git desired-state + sync/health drift.

Usage:

helper discover argocd [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover backups¶

Backup posture (Phase 8.2): uncovered, stale or unverified guests; orphans; capacity.

Usage:

helper discover backups [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover capacity¶

Capacity trends (Phase 10.2): filesystems filling, node memory and CPU crossing their lines.

Usage:

helper discover capacity [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover cloudflare¶

Read a Cloudflare zone's public DNS records (read-only) — the external half.

Usage:

helper discover cloudflare [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Reconcile external ServiceEndpoints from Cloudflare DNS.	`False`
`--dry-run`	boolean	With --persist, preview + roll back.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover hass¶

Read a Home Assistant instance (read-only): version, integrations, entities.

Usage:

helper discover hass [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Upsert the home-assistant Service (+ endpoint) into the harness DB.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover host¶

Discover a single host: run all registered host probes over SSH.

Usage:

helper discover host [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--ssh-user`, `-u`	text	SSH login user.	_required
`--ssh-key`, `-k`	path	Path to an SSH private key.	None
`--ssh-password-env`	text	Name of an env var holding the SSH password. (Never accept the password directly.)	None
`--primary-ip`	text	Override hostname for the SSH connection.	None
`--ssh-port`	integer	N/A	`22`
`--probe`	text	Restrict to these probe names. Default: every host probe.	None
`--no-sync`	boolean	Skip the probe-entry-point sync.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover import¶

Ingest an external host-scan CSV: upsert hosts + agentless coverage findings.

Usage:

helper discover import [OPTIONS] CSV_PATH

Options:

Name	Type	Description	Default
`--source`	text	Provenance label stored on imported hosts.	`network-scan`
`--dry-run`	boolean	Parse + classify and print the plan without writing.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover jetkvm¶

Read a JetKVM (read-only): device status, and the attached host's reachability + console.

Usage:

helper discover jetkvm [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Upsert the jetkvm Service; check the attached host and reconcile its findings.	`False`
`--dry-run`	boolean	With --persist, preview + roll back.	`False`
`--snapshot`	path	Also save one console frame (PNG) here. Needs the jetkvm extra.	None
`--help`	boolean	Show this message and exit.	`False`

helper discover k8s¶

Discover Kubernetes nodes as Host observations (INFERRED; kernel facts win).

Usage:

helper discover k8s [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover mikrotik¶

Read a MikroTik RouterOS 7 router (read-only): identity, interfaces, subnets, leases, static DNS.

Usage:

helper discover mikrotik [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Reconcile internal ServiceEndpoints from static DNS + stray-config from addresses/leases.	`False`
`--dry-run`	boolean	With --persist, preview + roll back.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover network¶

Scan a CIDR for live hosts; optionally fingerprint discovered services.

No SSH credentials needed — pure asyncio TCP connect-scan against a small panel of common ports. Observations are written to the harness DB; the reconciler treats the recorded network.* keys as evidence going forward. NetBox sync happens in a later slice (after NetBoxAdapter lands).

Usage:

helper discover network [OPTIONS] CIDR

Options:

Name	Type	Description	Default
`--ports`	text	Comma-separated port list. Default: a small panel of common services.	None
`--timeout`	float	Per-port connect timeout in seconds.	`0.8`
`--concurrency`	integer range (between `1` and `2000`)	Max concurrent TCP connects.	`200`
`--no-fingerprint`	boolean	Skip the per-host service fingerprint step.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover omv¶

Read an OpenMediaVault NAS (read-only): filesystems, disks, shares, services, stray exports.

Usage:

helper discover omv [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Record stray exports (nothing behind them) as STRAY_CONFIG findings.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover printwarden¶

Read print-warden's status (read-only): reachability, Moonraker, Klipper, telemetry age.

Usage:

helper discover printwarden [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Reconcile service-unhealthy findings for the warden and its printers.	`False`
`--dry-run`	boolean	With --persist, preview + roll back.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover proxmox¶

Read a Proxmox cluster's nodes + VMs/LXCs (read-only); persist and/or push to NetBox.

Usage:

helper discover proxmox [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Write the cluster + VMs into the harness DB.	`False`
`--netbox-sync`	boolean	Propose discovered VMs into NetBox (cluster must exist).	`False`
`--dry-run`	boolean	With --netbox-sync, preview writes.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover replay¶

Replay a synthetic lab (hosts + observations) — no hardware, no credentials.

Usage:

helper discover replay [OPTIONS] [FIXTURE]

Options:

Name	Type	Description	Default
`--no-assert`	boolean	Skip the fixture's bundled assertion library.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover show¶

Print the most recent observations for a host (debug helper).

Usage:

helper discover show [OPTIONS] HOSTNAME

Options:

Name	Type	Description	Default
`--limit`, `-n`	integer	N/A	`20`
`--help`	boolean	Show this message and exit.	`False`

helper discover storage¶

Storage efficiency (Phase 8.5): headroom trends, stale snapshots, clutter, released PVs.

Usage:

helper discover storage [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover suggestions¶

Service suggestions (Phase 8.7): idle capability and missing building blocks.

Usage:

helper discover suggestions [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover talos¶

Discover a Talos Linux node over the machine API (no SSH).

Usage:

helper discover talos [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--node`, `-N`	text	Talos API endpoint/IP. Defaults to NAME.	None
`--talosconfig`	path	Path to a talosconfig (default: talosctl's own).	None
`--probe`	text	Restrict to these probe names. Default: every talos probe.	None
`--no-sync`	boolean	Skip the probe-entry-point sync.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover unifi¶

Read a UniFi controller's DNS records, clients, and networks (read-only).

Usage:

helper discover unifi [OPTIONS]

Options:

Name	Type	Description	Default
`--persist`	boolean	Reconcile internal ServiceEndpoints from DNS + stray-config from networks/clients.	`False`
`--dry-run`	boolean	With --persist, preview + roll back.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper discover usage¶

Usage history (Phase 8.3): hourly/daily rollups from Proxmox RRD, backfilled, pruned.

Usage:

helper discover usage [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper discover versions¶

Version currency (Phase 8.1): package lag, mixed versions, OS end of life, HA updates.

Usage:

helper discover versions [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper exec¶

Execute action proposals through the trust gate (L2).

Usage:

helper exec [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper exec accept¶

Record that you applied a proposal by hand (the PROPOSE-rung evidence).

This is how a propose-only cell earns its first rung: each accepted proposal is one clean approval toward PROMOTION_STREAK.

Usage:

helper exec accept [OPTIONS] PROPOSAL_ID

Options:

Name	Type	Description	Default
`--note`	text	Why you accepted, for the record.	``
`--help`	boolean	Show this message and exit.	`False`

helper exec list¶

List pending, executable action proposals.

Usage:

helper exec list [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper exec receipts¶

List execution receipts, newest first.

Usage:

helper exec receipts [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper exec reject¶

Reject a proposal: breaks the cell's clean streak, never demotes it.

Usage:

helper exec reject [OPTIONS] PROPOSAL_ID

Options:

Name	Type	Description	Default
`--note`	text	Why you rejected, for the record.	``
`--help`	boolean	Show this message and exit.	`False`

helper exec rollback¶

Undo one executed action, using the state captured before it ran.

Operator-initiated and not gated by the trust gradient: the gradient governs what the framework does on its own, and a safety valve the policy could lock shut is not a safety valve. The undo writes its own receipt.

Usage:

helper exec rollback [OPTIONS] RECEIPT_ID

Options:

Name	Type	Description	Default
`--yes`	boolean	Skip the confirmation prompt.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper exec run¶

Run one pending action proposal through the trust gate.

--override crosses the soft-hard floors — the unverified-rollback degrade and a non-absolute host ceiling — for this one action. It never crosses an absolute floor, and it never makes a propose-only cell execute. The gesture is deliberately high-friction: you retype the cell key.

Usage:

helper exec run [OPTIONS] PROPOSAL_ID

Options:

Name	Type	Description	Default
`--yes`	boolean	Consent to THIS proposal up front instead of at the interactive prompt.	`False`
`--override`	boolean	Cross the soft-hard floors for THIS action (owner-only, logged).	`False`
`--override-reason`	text	Required with --override: why you accept it.	``
`--help`	boolean	Show this message and exit.	`False`

helper findings¶

View and triage reconciliation findings.

Usage:

helper findings [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper findings ack¶

Mark a finding as acknowledged (status → ACKNOWLEDGED).

Usage:

helper findings ack [OPTIONS] FINGERPRINT

Options:

Name	Type	Description	Default
`--by`	text	Acknowledger identity.	None
`--notes`	text	N/A	None
`--help`	boolean	Show this message and exit.	`False`

helper findings list¶

Tabular view of findings, filtered as requested.

Usage:

helper findings list [OPTIONS]

Options:

Name	Type	Description	Default
`--status`	text	Filter by status: open, acknowledged, resolved, suppressed, active (open+ack), or all.	`open`
`--severity`	text	N/A	None
`--kind`	text	N/A	None
`--host`	text	Filter to findings affecting this host id.	None
`--limit`, `-n`	integer range (between `1` and `500`)	N/A	`50`
`--help`	boolean	Show this message and exit.	`False`

helper findings narrate¶

Narrate findings as prose via the LLM router (Narrator agent).

Usage:

helper findings narrate [OPTIONS] [FINGERPRINTS]...

Options:

Name	Type	Description	Default
`--status`	text	Which findings to narrate when none are named.	`active`
`--help`	boolean	Show this message and exit.	`False`

helper findings resolve¶

Manually mark a finding as resolved.

On the next reconciler run, if the underlying condition is still observed, the auto-resolve gate will leave this row RESOLVED but emit a new finding with the same fingerprint (reopen-on-recurrence). Manual resolve is for cases the operator handled out-of-band.

Usage:

helper findings resolve [OPTIONS] FINGERPRINT

Options:

Name	Type	Description	Default
`--notes`	text	N/A	None
`--help`	boolean	Show this message and exit.	`False`

helper findings show¶

Print every field of one finding.

Usage:

helper findings show [OPTIONS] FINGERPRINT

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper findings suppress¶

Suppress this finding from default listings.

Honors the existing schema field suppressed_until. Without --until, suppression is open-ended; with one, the finding will surface again after that date. Suppression survives reopen — re-emitted fingerprints stay suppressed if their date is in the future.

Usage:

helper findings suppress [OPTIONS] FINGERPRINT

Options:

Name	Type	Description	Default
`--until`	text	ISO date (YYYY-MM-DD) when suppression auto-expires; default: forever.	None
`--notes`	text	N/A	None
`--help`	boolean	Show this message and exit.	`False`

helper host¶

Per-host views and operations.

Usage:

helper host [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper host intent¶

Show or set the operator's placement intent for a host.

Usage:

helper host intent [OPTIONS] HOSTNAME

Options:

Name	Type	Description	Default
`--no-new-guests`	boolean	Keep this host as it is: planners never propose moving or placing a guest onto it.	`False`
`--clear`	boolean	Remove the host's placement intent.	`False`
`--rationale`, `-r`	text	Why (recorded on the intent).	None
`--help`	boolean	Show this message and exit.	`False`

helper host retire¶

Mark a host decommissioned: record the intent, close its placements, resolve its findings.

Usage:

helper host retire [OPTIONS] HOSTNAME

Options:

Name	Type	Description	Default
`--rationale`, `-r`	text	Why (recorded on the intent).	None
`--yes`, `-y`	boolean	Skip the confirmation prompt.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper host show¶

Print everything the harness knows about a host.

Usage:

helper host show [OPTIONS] HOSTNAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper maintenance¶

One node's drain → update → reboot → return as a sequence of gated steps.

Usage:

helper maintenance [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper maintenance abort¶

Stop a planned or interrupted run; its remaining proposals are rejected.

Usage:

helper maintenance abort [OPTIONS] RUN_ID

Options:

Name	Type	Description	Default
`--reason`, `-r`	text	Why, for the record.	``
`--help`	boolean	Show this message and exit.	`False`

helper maintenance list¶

Every run, newest first.

Usage:

helper maintenance list [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper maintenance plan¶

Draft the run: one proposal per step, nothing executed.

Usage:

helper maintenance plan [OPTIONS] NODE

Options:

Name	Type	Description	Default
`--target`	text	Send every migratable guest to this node instead of the emptiest.	None
`--resume`	text	A stopped run (id or prefix) on this node whose drained guests this run brings back.	None
`--help`	boolean	Show this message and exit.	`False`

helper maintenance plan-talos¶

Draft a Talos cluster upgrade: one step per node, control planes first.

Usage:

helper maintenance plan-talos [OPTIONS] CONTROL_PLANE

Options:

Name	Type	Description	Default
`--to`	text	Talos release tag for every node, e.g. v1.14.2.	_required
`--kubernetes`	text	Also upgrade Kubernetes to this version last, e.g. 1.37.2.	None
`--talosconfig`	text	Path to a talosconfig (default: talosctl's own).	None
`--help`	boolean	Show this message and exit.	`False`

helper maintenance run¶

Execute the run's steps in order; stops at the first failure.

Usage:

helper maintenance run [OPTIONS] RUN_ID

Options:

Name	Type	Description	Default
`--yes`	boolean	Consent to every step up front.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper maintenance show¶

One run, step by step.

Usage:

helper maintenance show [OPTIONS] RUN_ID

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper mcp¶

Model Context Protocol server for Claude Desktop / Claude Code / Cursor.

Usage:

helper mcp [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper mcp serve¶

Serve the harness's MCP tools over stdio (blocking; launched by a client).

Usage:

helper mcp serve [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper mcp tools¶

List the MCP tools this server exposes (smoke check, no client needed).

Usage:

helper mcp tools [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper netbox¶

NetBox bridge: bootstrap custom fields and sync harness state.

Usage:

helper netbox [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper netbox bootstrap¶

Ensure the harness's custom fields exist on the configured NetBox.

Idempotent: lists existing CFs first, only creates the ones the harness needs that aren't already present. Safe to re-run after upstream NetBox upgrades.

Usage:

helper netbox bootstrap [OPTIONS]

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Report what would be created without making any API calls beyond list.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper netbox health¶

Ping NetBox at /api/status/ and print the version banner.

Usage:

helper netbox health [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper netbox sync-cluster¶

Sync a harness cluster's VirtualMachine rows into NetBox; write NetBox ids back.

Reads the cluster + VMs already persisted by helper discover proxmox --persist and upserts them into the matching NetBox cluster (which the operator owns — a missing one is reported, not created). The resulting netbox_cluster_id / netbox_vm_id are written back onto the harness rows so later syncs match by id. --dry-run previews and rolls back.

Usage:

helper netbox sync-cluster [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Preview NetBox writes; don't persist id write-back.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper netbox sync-host¶

Push a harness Host row's CF values + part placements onto NetBox.

Matches by Device.name == Host.hostname. The harness never creates Devices — operator owns Device creation in NetBox first. Missing Devices are reported with a clear "create the Device, then re-run" message.

By default this runs two passes:

custom_fields PATCH on the Device (power policy, arch, capabilities…).
InventoryItem sync — current open Placement rows are mirrored under the Device. Items with discovered=True not in the harness's active set are deleted; new placements create; matching slots with diverged fields update.

--skip-fields / --skip-inventory constrain either pass.

Usage:

helper netbox sync-host [OPTIONS] HOSTNAME

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Print what would happen without sending writes to NetBox.	`False`
`--skip-fields`	boolean	Skip the cf_* custom-field PATCH.	`False`
`--skip-inventory`	boolean	Skip the InventoryItem placement sync.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper onboard¶

Onboard a new host conversationally: interview → confirm → register.

Usage:

helper onboard [OPTIONS] [DESCRIPTION] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--probe`	boolean	After registration, run warm SSH discovery if credentials were collected.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper part¶

Physical-part identity: show and merge.

Usage:

helper part [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper part merge¶

Fold a duplicate part into its survivor: placements move, identity gaps fill, duplicate is deleted.

Usage:

helper part merge [OPTIONS] DUPLICATE

Options:

Name	Type	Description	Default
`--into`	text	The surviving part (id prefix, serial, or WWID).	_required
`--yes`, `-y`	boolean	Skip the confirmation prompt.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper part show¶

Print a part's identity and placement history.

Usage:

helper part show [OPTIONS] REF

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper plan¶

Placement recommendations from the workload library.

Usage:

helper plan [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper plan add-workload¶

Recommend where a new workload should run (AC2).

Usage:

helper plan add-workload [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--narrate`	boolean	Narrate via the Planner agent.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper plan path¶

Show the network path between two hosts and what it inherits (AC6).

Usage:

helper plan path [OPTIONS] HOST_A HOST_B

Options:

Name	Type	Description	Default
`--workload`	text	Judge the path for this workload's network class.	None
`--help`	boolean	Show this message and exit.	`False`

helper plan rebalance¶

Candidate rebalancing plans with tradeoffs (AC3). Proposals only.

Usage:

helper plan rebalance [OPTIONS]

Options:

Name	Type	Description	Default
`--narrate`	boolean	Narrate via the Planner agent.	`False`
`--basis`	text	allocated (default) or usage: load guests at observed p95 memory.	`allocated`
`--help`	boolean	Show this message and exit.	`False`

helper plan rightsize¶

Cores and memory recommendations from usage history (Phase 8.4). Changes nothing.

Usage:

helper plan rightsize [OPTIONS]

Options:

Name	Type	Description	Default
`--days`	integer	History window in days.	`30`
`--persist`	boolean	Record as rightsizing findings.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper plan surplus¶

Flag surplus capacity and propose reconfiguration options (AC5).

Usage:

helper plan surplus [OPTIONS]

Options:

Name	Type	Description	Default
`--narrate`	boolean	Narrate via the Planner agent.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper plan workloads¶

List the workload profile library.

Usage:

helper plan workloads [OPTIONS]

Options:

Name	Type	Description	Default
`--category`	text	Filter by category.	None
`--help`	boolean	Show this message and exit.	`False`

helper probes¶

Probe plugin inspection and registration.

Usage:

helper probes [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper probes list¶

List Probe rows registered in the DB.

Usage:

helper probes list [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper probes register¶

Re-sync probe entry points to the DB. Idempotent.

Usage:

helper probes register [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper schedule¶

Probe and assertion cadences: what is due, and when.

Usage:

helper schedule [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--file`	text	Schedule file (default: $HOMELAB_HELPER_SCHEDULE).	None
`--due`	boolean	Only what is due now.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper service¶

Service identity: resolver slices and the alias map.

Usage:

helper service [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper service aliases¶

Show the service alias map as loaded from HOMELAB_HELPER_SERVICE_ALIASES.

Usage:

helper service aliases [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper service resolvers¶

List every (scope, resolver) endpoint slice with its count.

Usage:

helper service resolvers [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper service retire-resolver¶

Delete every endpoint a resolver produced, plus the services left empty.

Usage:

helper service retire-resolver [OPTIONS] RESOLVER

Options:

Name	Type	Description	Default
`--scope`	text	internal	external (default: both).
`--yes`, `-y`	boolean	Skip the confirmation prompt.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper skills¶

Operator skill profile (inferred from chat; feeds future trust hints).

Usage:

helper skills [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper skills set¶

Pin a domain's level (manual overrides inference permanently).

Usage:

helper skills set [OPTIONS] DOMAIN LEVEL

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper status¶

One-screen status: findings, approvals, discovery, trust.

Usage:

helper status [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper status serve¶

Serve GET /status and GET /healthz over HTTP (blocking).

Usage:

helper status serve [OPTIONS]

Options:

Name	Type	Description	Default
`--host`	text	Bind address.	`127.0.0.1`
`--port`	integer	TCP port.	`8710`
`--help`	boolean	Show this message and exit.	`False`

helper status show¶

Print the status snapshot.

Usage:

helper status show [OPTIONS]

Options:

Name	Type	Description	Default
`--json`	boolean	Print the snapshot as JSON.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper trust¶

Trust gradient: show and grant per-cell action authority.

Usage:

helper trust [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper trust boundary¶

Cap one host's agent authority — the per-host ceiling.

--absolute is the "never under any circumstances" case: it becomes unreachable by any runtime gesture, and only a policy-config edit changes it.

Usage:

helper trust boundary [OPTIONS] HOSTNAME CEILING

Options:

Name	Type	Description	Default
`--absolute`	boolean	Window-proof: no elevation window or override lifts it, ever.	`False`
`--notes`	text	Why this host is capped.	``
`--help`	boolean	Show this message and exit.	`False`

helper trust grant¶

Grant one cell's authority level (recorded in TrustHistory).

Usage:

helper trust grant [OPTIONS] DOMAIN ACTION_KIND BLAST_RADIUS LEVEL

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper trust history¶

Print the append-only audit spine, newest first.

Usage:

helper trust history [OPTIONS]

Options:

Name	Type	Description	Default
`--limit`	integer	Most recent events to show.	`30`
`--help`	boolean	Show this message and exit.	`False`

helper trust show¶

Print domains, granted cells, boundaries, and windows.

Usage:

helper trust show [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper usage¶

Usage history: p95 and peak CPU/memory per host and guest.

Usage:

helper usage [OPTIONS] [SUBJECT] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--days`	integer	Window in days.	`30`
`--help`	boolean	Show this message and exit.	`False`

helper version¶

Print the installed homelab-helper version.

Usage:

helper version [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper view¶

Cross-source synthesized records for a service or host.

Usage:

helper view [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper view host¶

Synthesize a host record: identity + guests it runs + endpoints + findings.

Usage:

helper view host [OPTIONS] HOSTNAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper view service¶

Synthesize a service record across DNS endpoints, VMs, and hosts.

Usage:

helper view service [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper window¶

Elevation windows: scoped, expiring lifts of the soft-hard floors.

Usage:

helper window [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

helper window kill¶

Kill switch: revoke every open window at once.

In-flight autonomous work stops at its next checkpoint — the executor re-tests its window immediately before dispatch.

Usage:

helper window kill [OPTIONS]

Options:

Name	Type	Description	Default
`--yes`	boolean	Skip the confirmation prompt.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper window list¶

Show elevation windows, newest first.

Usage:

helper window list [OPTIONS]

Options:

Name	Type	Description	Default
`--all`	boolean	Include expired and revoked windows.	`False`
`--help`	boolean	Show this message and exit.	`False`

helper window open¶

Open a scoped, expiring window. At least one scope flag is required.

Usage:

helper window open [OPTIONS]

Options:

Name	Type	Description	Default
`--reason`	text	Why this window exists (audit record).	_required
`--minutes`	integer	Duration, max 480.	`60`
`--domain`	text	Scope to a trust domain.	`[]`
`--host`	text	Scope to a hostname.	`[]`
`--cell`	text	Scope to domain/action/blast.	`[]`
`--help`	boolean	Show this message and exit.	`False`

helper window revoke¶

Close one window now.

Usage:

helper window revoke [OPTIONS] WINDOW_ID

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`