HypAware
View as Markdown

Work with recommendations

A recommendation is one proposed change with the evidence for it. It is either a page of a published report or published on its own; both kinds are listed together and share one id form. hyp rec is a short alias for hyp recommendation. The forms these commands replace still run: hyp report recommend, hyp report mark, hyp report list --recommendations and a lone recommendation id given to hyp report get or hyp report delete.

hyp recommendation list

Usage
hyp recommendation list [--status <state,...>] [--standalone] [--kind <kind>] [--period <period>] [--limit <n>] [--before <publishedAt>] [--org <org>] [--json] [--remote <target>]

Lists the recommendations themselves, flat, newest first, from the remote's recommendation index: id, state in brackets (shown only when the remote supplies one), the publish time (the parent report's, or the recommendation's own for one published with hyp recommendation publish), the parent report as kind/period/id (or standalone for one published with hyp recommendation publish), and the title, with the thesis below. It has no coverage notice, because the recommendation index does not carry the report's coverage; hyp report list shows it. --status <state,...> filters by state; an unknown state is refused before any request. --standalone lists only the ones published on their own. A remote that predates the recommendation index returns 1 and says so. --kind and --period filter on the parent report, so with either one, a recommendation stored on its own is not listed. One published before the remote stored them that way is a report of kind recommendation, so --kind recommendation still lists it, as standalone. --limit and --before apply to every row. --json prints the remote's recommendation rows whole.

Usage
  hyprec-fedcba9876543210	[open]	2026-10-03T09:00:00.000Z	standalone	No python3 on the runner
  hyprec-0123456789abcdef	[in_progress]	2026-08-24T09:00:00.000Z	usage-review/2026-W34/REPORT_ID	Batch the retries
      Every retry is its own call, 506 times a month. One queue fixes it.
Terminal
hyp recommendation list --status open,in_progress
hyp recommendation list --standalone

hyp recommendation get

Usage
hyp recommendation get <id> [--output <file>] [--org <org>] [--remote <target>]

Takes a recommendation id (hyprec- and its token, like hyprec-qcyx22sjav, as hyp recommendation list prints it). It resolves the id to its page, in its report or on its own, and prints that page (Markdown, or HTML when the report was published without it) with a Citations from the report record tail: the turns the page cites as evidence:N, numbered to match, and the queries the report ran to reach the recommendation, verbatim in sql blocks, and then a Status section: the current state with its reason, links, who recorded it and when, followed by the history one line per event, oldest first. A recommendation nobody has marked reads State: open (never marked). This is the read to make from inside an AI client session when asked to fix a recommendation by id.

Ten-character ids like hyprec-qcyx22sjav need HypAware 1.51.0 or newer. An older hyp refuses one: fix and recommendation mark say it is "not a recommendation id", and report get <id> prints its usage line. The id is fine; run hyp update (see updating and recovery) and try again.

Terminal
hyp recommendation get hyprec-0123456789abcdef
Usage
## Status

State: applied
Reason: Landed in hyparam/hypaware#912
Link: https://github.com/hyparam/hypaware/pull/912
By: email:dev@example.com (via cli)
At: 2026-10-03T18:21:07.000Z

History, oldest first:

- 2026-10-01T09:00:00.000Z  in_progress  by email:dev@example.com  via dashboard
- 2026-10-03T18:21:07.000Z  applied  by email:dev@example.com  via cli: Landed in hyparam/hypaware#912 https://github.com/hyparam/hypaware/pull/912

hyp recommendation publish

Usage
hyp recommendation publish <file.md> [--title <title>] [--org <org>] [--remote <target>]

Publishes one recommendation page on its own, with no report around it, for an analysis that yields a single recommendation. The file must be .md or .markdown and is written like a recommendation-<slug>.md page inside a report: the first # heading is the title (--title overrides it) and the bold paragraph under it is the thesis. A page with no heading and no --title is refused before upload. The remote stores the page as a recommendation of its own, with no report around it, mints the hyprec- id, and renders it. hyp recommendation list lists it as standalone, and hyp recommendation get <id> serves the page. A repeat upload of the same content on the same UTC day answers with the existing id (already published). A recommendation published before the remote stored them this way stays a report of kind recommendation whose period is its publish date, and hyp report get recommendation <period> <id> still serves it. A remote that predates the standalone route returns 1 and says so. Requires the publisher role, like publish.

Terminal
hyp recommendation publish ./recommendation-no-python3.md
Usage
published hyprec-0123456789abcdef (standalone)
  view: hyp recommendation get hyprec-0123456789abcdef

hyp recommendation mark

Usage
hyp recommendation mark <id> <open|in_progress|applied|dismissed> [--reason <text>] [--link <url>]... [--org <org>] [--remote <target>]

Records what became of a recommendation. The id is the one hyp recommendation list prints (the legacy rec- spelling is accepted). The state is the remote's vocabulary: open, in_progress, applied, or dismissed; any state may follow any other, so reopening is the same verb. --reason (one line, up to 2000 characters) is required for dismissed and optional otherwise; a dismissal without one is refused with exit 2 before any request. --link is repeatable and takes absolute http(s) URLs, the pull request that landed the change most of all (up to 8; a value with a literal comma is split on it, so percent-encode one). An empty --link is refused with exit 2 rather than recorded as no link. The event is appended on the remote with via: cli; nothing is kept locally. The receipt is the new state line with the reason and links as recorded. An unknown id, or a remote that predates the status route, returns 1 and names both readings. Requires the publisher role, like publish.

Terminal
hyp recommendation mark hyprec-0123456789abcdef applied --reason "Landed in hyparam/hypaware#912" --link https://github.com/hyparam/hypaware/pull/912
hyp recommendation mark hyprec-0123456789abcdef dismissed --reason "The retry loop was removed in 1.39"
Usage
marked hyprec-0123456789abcdef [applied]	Batch the retries
  reason: Landed in hyparam/hypaware#912
  link: https://github.com/hyparam/hypaware/pull/912

hyp recommendation delete

Usage
hyp recommendation delete <id> [--yes] [--org <org>] [--remote <target>]

Warning: This permanently deletes a recommendation published on its own, for every member of the organization. It prompts on a terminal; a non-interactive call without --yes refuses with exit code 2.

The id is as hyp recommendation list prints it. A recommendation that is a page of a report is not deleted, including a standalone one that a remote from before standalone records published as a one-page report. The command says a report is deleted whole, prints the hyp report delete <kind> <period> <id> command for that report, and returns 1. An unknown id deletes nothing and returns 1.

Terminal
hyp recommendation delete hyprec-0123456789abcdef

hyp fix

Usage
hyp fix [id] [--kind <kind>] [--period <period>] [--limit <n>] [--org <org>] [--remote <target>]

Starts a recorded AI client on one recommendation, in the current directory. The id is the one hyp recommendation list prints. HypAware resolves it to its report (or, for one stored on its own, to its own page), checks the recommendation page still exists, and starts the client with instructions to read it through hyp recommendation get <id> and make the change in the current repository. Nothing is written to disk. The client takes over the terminal and nothing is pre-authorized: the client asks before running the read. The instructions end by telling the client to record the outcome: hyp recommendation mark <rec-id> applied --reason "<one line>" --link <PR url> once the change is landed, or hyp recommendation mark <rec-id> dismissed --reason "<why>" if the recommendation should not be done, with the run's --org and --remote carried along.

With no id on a terminal, it asks in two steps: first which report, newest first, each with its publish date and how many recommendations it carries (a report with none is not offered). Recommendations stored on their own are in no report, so they come last as one group, "Standalone recommendations". Then it asks which of that report's recommendations, labeled by the page's title and described by its thesis when the remote lists them, else by the page name. Escape on the second list returns to the first. --kind, --period and --limit narrow which reports are offered; --limit also bounds the standalone group, and with --kind or --period the group is not offered. Without a terminal, or with HYP_NO_TUI=1, the id is required and omitting it there returns 2. The client offer set is the recorded one hyp report generate draws on, without the skill requirement: attached, or configured with no attach marker to write, and with its CLI on PATH. If more than one such client could be started, it asks which; a run given an id that cannot prompt takes the first of that set, in the order hyp ask uses: ascending client id. That pick is also time-bounded on a terminal: unanswered for 10 seconds, it takes the first of that set and says so on stdout (No answer at the client prompt - starting the first one.), and the first keypress lifts the deadline. The report and recommendation listings above each have their own 10-second deadline, which starts when that list is shown and is lifted by the first keypress on it; going back to the first list starts a fresh one. A listing left unanswered picks nothing and starts nothing: it prints hyp fix: no answer at the picker - nothing started. with the usage line to stderr and returns 2. A declined pick succeeds, as does a listing that carries no recommendations. A malformed id returns 2. An unknown id, a recommendation page the report no longer carries, a standalone recommendation with no page, no launchable client, or a process-start failure returns 1.

Terminal
hyp fix hyprec-0123456789abcdef
hyp fix --kind usage-review
Was this page useful?

↑↓ navigate↵ openesc close