# Work with recommendations

Canonical: https://hypaware.ai/docs/cli-reference/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`

```text
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.

```text
  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.
```

```sh
hyp recommendation list --status open,in_progress
hyp recommendation list --standalone
```

## `hyp recommendation get`

```text
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](https://hypaware.ai/docs/cli/index.md#update-hypaware)) and try
again.

```sh
hyp recommendation get hyprec-0123456789abcdef
```

```text
## 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`

```text
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`.

```sh
hyp recommendation publish ./recommendation-no-python3.md
```

```text
published hyprec-0123456789abcdef (standalone)
  view: hyp recommendation get hyprec-0123456789abcdef
```

## `hyp recommendation mark`

```text
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`.

```sh
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"
```

```text
marked hyprec-0123456789abcdef [applied]	Batch the retries
  reason: Landed in hyparam/hypaware#912
  link: https://github.com/hyparam/hypaware/pull/912
```

## `hyp recommendation delete`

```text
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`.

```sh
hyp recommendation delete hyprec-0123456789abcdef
```

## `hyp fix`

```text
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`.

```sh
hyp fix hyprec-0123456789abcdef
hyp fix --kind usage-review
```

