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
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.
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.hyp recommendation list --status open,in_progress
hyp recommendation list --standalonehyp recommendation get
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.
hyp recommendation get hyprec-0123456789abcdef## 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/912hyp recommendation publish
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.
hyp recommendation publish ./recommendation-no-python3.mdpublished hyprec-0123456789abcdef (standalone)
view: hyp recommendation get hyprec-0123456789abcdefhyp recommendation mark
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.
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"marked hyprec-0123456789abcdef [applied] Batch the retries
reason: Landed in hyparam/hypaware#912
link: https://github.com/hyparam/hypaware/pull/912hyp recommendation delete
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.
hyp recommendation delete hyprec-0123456789abcdefhyp fix
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.
hyp fix hyprec-0123456789abcdef
hyp fix --kind usage-review