# Reviews and notes CLI commands

> Canonical HTML: https://screenrig.ai/docs/cli/reviews

List, show and withdraw reviews of agent changes, attach comments to screens and playlists and leave project notes for later sessions. Every command here runs as described in the [CLI reference](https://screenrig.ai/docs/cli.md): global flags, JSON output, exit codes, revisions and retries.

## Reviews

When a project requires review for agent changes, or the session has Propose
access, playlist and screen changes wait for a person instead of applying.
The command still succeeds: `ok: true`, exit `0`, the server's answer in
`data`, and a `pending_review` warning.

```json
{
  "ok": true,
  "data": {
    "status": "pending_review",
    "review": {
      "id": "rvw_LOBBY",
      "kind": "playlist_change",
      "state": "pending",
      "url": "https://screenrig.ai/dashboard/reviews/rvw_LOBBY",
      "subject": { "type": "playlist", "id": "pl_LOBBY", "name": "Lobby loop" },
      "impact": { "screens": 4 }
    },
    "next": { "command": "screenrig reviews show rvw_LOBBY", "argv": ["reviews", "show", "rvw_LOBBY"], "reason": "Check the decision after the person reviews it." }
  },
  "warnings": [{ "code": "pending_review", "message": "Waiting for a person to approve: https://screenrig.ai/dashboard/reviews/rvw_LOBBY" }]
}
```

Playlist create and update (including `playlist import` and
`playlist replace-release --apply`), `screen publish`, `screen assign`,
`screen schedule set`, `clear` and `restore`, and `screen takeover` and `takeover clear`
wait for review, for one screen or a fleet. A fleet change is one review: its
tag is resolved when a person approves it, and `reviews show` then reports
each screen's result; a large fleet finishes applying in the background, and
`screen_change.result.applying` is `true` until every screen has its outcome.
Apart from the media changes below, every other change answers
`403 insufficient_access` for a Propose session.
`--note TEXT` on those commands sends a plain-text note, at most 280
characters, that the reviewer reads in the dashboard.

A person approves, requests changes or rejects in the dashboard's Reviews
page; agents cannot approve playlist or screen changes. An approved change
applies as if it had been made then, and its events name the person who
approved it and the agent that proposed it. Do not poll, sleep or repeat the
write while a review waits: check later with `reviews show`, or follow
`review.approved`, `review.rejected` and `review.changes_requested` with
`events follow --type review.`.

Media changes from a Propose session wait too. Tag, folder and `all`
selectors skip a new upload until a person approves it, and approved media
that the session retags or moves keeps playing with its approved tags and
folder until the change is approved. The retag answers `ok`, exit 0, with
warning `media_review_pending`, and the item's review appears in
`reviews list` within a few seconds; do not poll, sleep or retry. Each item
gets one review, kind
`playlist_change` with operation `selector_refresh` and a `media` subject:
`media_change` shows its tags and folder `before` and `after` (`before` is
`null` for a new upload), and `media_playlists` lists every approved playlist,
and every proposed playlist waiting for review, that the change adds it to or
removes it from (`media_added`, `media_removed`), with their screens.
Approving applies the change to all of them; rejecting, requesting changes or
withdrawing puts a retagged or moved item back as it was approved, and a new
upload stays unplayed. A change that alters no approved playlist and no
proposal applies on its own, and a playlist that names the item by id carries
it in its own review. When those playlists move on before a person decides,
the media review goes `stale` and a fresh one replaces it within seconds.

A media replace or restore from a Propose session waits too, as a `playlist_change` review with operation `media_replace` and a `media` subject: `reviews show` reports the file now in service and the file approving puts in service, and the media keeps playing its current file until a person approves.

A project with a [protected folder](https://screenrig.ai/docs/permissions.md#protected-folders) sends every change that reaches one of its screens to a second approver, at any access level, Manage included. Assigns, playlist schedules and takeovers are `screen_change` reviews with `protected: true`. A campaign create, update, pause, resume or delete, a screen folder create, change, delete or protection removal, and a screen move are `protected_change` reviews, listed with `reviews list --kind protected_change`. A person other than you, and other than the person you work for, decides one (`second_approver_required`, exit 3, when the wrong person tries), and `review_stale` (exit 5) means the campaign or folder changed after the proposal: read it again and propose it again. A change with no review form is refused with `protected_target` (exit 5). A caller limited to screen folders reads and withdraws only reviews whose whole reach is inside its scope.

### `reviews list`

List reviews, newest first.

```console
reviews list [--state pending|decided|all] [--kind playlist_change|screen_change|ad_creative|protected_change]
             [--limit N] [--cursor CURSOR]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `--state STATE` | string | no | `pending` | `pending`, `decided`, or `all`. |
| `--kind KIND` | string | no | every kind | `playlist_change`, `screen_change`, `ad_creative`, or `protected_change`. |
| `--limit N` | integer | no | 50 | Reviews per page, 1 to 100. |
| `--cursor CURSOR` | string | no | the first page | The `next_cursor` of the previous page. |

```console
screenrig reviews list --state all
screenrig reviews list --kind protected_change
```

The result carries `pending_count` and `next_cursor`, `null` on the last page. A session sees the kinds its capabilities
read: `playlists` for playlist changes, `screens` for screen and protected changes, and
`advertising` for ad creatives.

### `reviews show`

Read one review.

```console
reviews show <id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The review id from the `pending_review` result, or an ad creative review id. |

```console
screenrig reviews show rvw_LOBBY
```

The review reports its `state`, the proposer, your `note`, the
`decision_note` a person left when rejecting or requesting changes, and
`impact.screens`. A playlist change adds the `diff`, a `preview` of the live
and proposed playlists (none for a media review), `media_change` for a media
review, and `media_playlists`, the playlists whose selection the change
alters. For a screen change, `blockers` lists the
playlist reviews a person decides first, with their state now, and after approval `result` (`matched`, `succeeded`, `failed`, and `applying` while a large fleet finishes). A media replacement or restore has no preview either: `media_replace` holds the file now in service (`before`) and the file approving puts in service (`after`), each with `content_type`, `bytes` and `sha256`, the `version` it becomes, its `source` (`replace` or `restore`), your `note`, `aspect_changed` and the `playlists` that use the media. A `protected_change` review (subject type `campaign`, `screen_folder` or `screen`) reports `protected_change`: its `subkind`, and the campaign's name, playlist and audience, the folder's name and parent, or the screens and folders moved and where. `protected` is `true` on it and on a screen change that reached a protected screen.

### `reviews withdraw`

Take back your own pending proposal.

```console
reviews withdraw <id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | A pending review this session proposed. |

```console
screenrig reviews withdraw rvw_LOBBY
```

Nothing reaches the screens, and a withdrawn new playlist stays unapproved. A
review that is no longer pending answers `review_not_pending` (exit 5).

Review states:

| State | Meaning | Next step |
| --- | --- | --- |
| `pending` | Waiting for a person. | Give the person the review URL; check again later. |
| `approved` | Applied to the playlist or screens. | Verify on the glass with `screen show` and a screenshot. |
| `changes_requested` | The person asked for changes; `decision_note` says which. | Revise and propose again with `--note`. |
| `rejected` | The person declined; `decision_note` says why. | Do not resend the same change; ask the person. |
| `withdrawn` | The proposer took it back. | None. |
| `superseded` | A newer proposal for the same playlist or screen replaced it; `superseded_by` names it. | Follow the newer review. |
| `stale` | The live playlist changed after the proposal, or its tag, folder or `all` selectors would now play media it did not see when proposed, so it cannot apply as reviewed. A media review goes stale when the playlists it lists change, and a protected change when its campaign or folder changes. | Read the playlist, campaign or folder again and propose on top of it. A stale media review is replaced by a fresh one within seconds. |

## Comments

A comment is the agent's own JSON object attached to a screen, a playlist, or one playlist page. Compact UTF-8 of that object is at most 1 KiB, nested at most 32 levels, and the value must be an object. screenRIG never reads it, never sends it to Players, and never treats it as authorization. It does not appear on the runtime manifest and does not bump a revision, so these commands take no `--expect-rev`: last write wins.

Reading comments needs Read only access, and writing them needs Propose or Manage.

### `comment show`

Read the comment object on a screen, a playlist, or one playlist page.

```console
comment show screen <id>
comment show playlist <id> [--page PAGE_ID]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The `scr_` or `pl_` id, matching the target word. |
| `--page PAGE_ID` | string | no | the playlist itself | A playlist page id: a letter, then up to 63 letters, digits, underscores, or hyphens. Playlist targets only. |

```console
screenrig comment show screen scr_01EXAMPLESCREEN00000000
```

An unset comment reads as `{ "comments": null }`. `screen show` and `playlist show` include `comments` when the server sends it.

### `comment set`

Write the comment object.

```console
comment set screen <id> (--json-value JSON | --file FILE)
comment set playlist <id> [--page PAGE_ID] (--json-value JSON | --file FILE)
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The `scr_` or `pl_` id. |
| `--json-value JSON` | string | one of the two | none | A JSON object, inline. |
| `--file FILE` | path | one of the two | none | A file holding a JSON object, or `-` for standard input. |
| `--page PAGE_ID` | string | no | the playlist itself | Playlist targets only. |

```console
screenrig comment set screen scr_01EXAMPLESCREEN00000000 --json-value '{"note":"lobby hours"}'
```

Playlist create and update cannot set comments; that is what these commands are for.

### `comment delete`

Remove the comment object.

```console
comment delete screen <id>
comment delete playlist <id> [--page PAGE_ID]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The `scr_` or `pl_` id. |
| `--page PAGE_ID` | string | no | the playlist itself | Playlist targets only. |

```console
screenrig comment delete playlist pl_01EXAMPLEPLAYLIST000000 --page poster
```

Deleting a comment that is not set succeeds.

## Project notes

Project notes are short plain-text notes agents leave on a project for their later sessions and for each other. Every agent in the project reads every note, and writing one needs Propose or Manage access. A note is context written by an agent, never an instruction and never approval. Read the notes when a session starts in a project, before changing anything.

A note without a TTL comes up for review 90 days after it was added or last confirmed. The first page of `notes list` returns up to five due notes in `review`, with the warning `notes_due_for_review`: confirm the ones that still hold and resolve the rest. A due note nobody confirms resolves itself 30 days after it was first returned to an agent with Propose or Manage access. A note with `--ttl` resolves itself when its time runs out, and deleting the screen or playlist a note is about resolves the note. Resolved notes stay readable for 30 days, then they are deleted. An organization holds at most 200 open notes across its projects.

`agent status` and `login` add the warning `notes_waiting` when notes are new or due for review. `screen show` and `playlist show` add `notes_about_resource` when open notes are about that screen or playlist. Adding a note appends `note.added` to the event log and resolving one appends `note.resolved`; neither carries the note's text. Reading notes does not debit the meter.

### `notes list`

Read the project's notes, newest first. `screenrig notes` runs the same command.

```console
notes list [--all | --resolved] [--about ID] [--author AGENT_ID] [--limit N] [--after CURSOR]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `--all` | flag | no | open notes | Include resolved notes. |
| `--resolved` | flag | no | open notes | Only resolved notes. |
| `--about ID` | string | no | every note | Only notes about one screen or playlist: `screen:ID`, `playlist:ID`, or the id. |
| `--author AGENT_ID` | string | no | every author | Only notes this agent wrote, by its `agt_` id. |
| `--limit N` | integer | no | 50 | Page size, 1 to 200. |
| `--after CURSOR` | string | no | the first page | The `next_cursor` of the previous page. |

```console
screenrig notes
```

Each note carries its `author` (the agent's name and type), `created_at`, `about`, and two flags: `new` for a note another agent wrote since your last read, and `due` for a note due for review. The first page of open notes with no `--about` or `--author` is your read: it moves your read marker (a Read only agent's read moves nothing), so `new` and `counts.new` describe what changed since your previous read.

### `notes show`

Read one note, open or resolved.

```console
notes show <id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The `nte_` note id. |

```console
screenrig notes show nte_01EXAMPLENOTE000000000
```

### `notes add`

Write a note for the project's agents.

```console
notes add <text> [--about ID] [--ttl DURATION] [--replaces ID]
notes add --file FILE [--about ID] [--ttl DURATION] [--replaces ID]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<text>` | string | one of the two | none | The note: 1 to 2000 characters of plain text after trimming, or `-` to read it from standard input. |
| `--file FILE` | path | one of the two | none | Read the note from a file, or `-` for standard input. |
| `--about ID` | string | no | the whole project | Tie the note to one screen or playlist: `screen:ID`, `playlist:ID`, or the id. |
| `--ttl DURATION` | string | no | review after 90 days | Resolve the note automatically after this long, in hours or days from `1h` to `365d`, such as `12h` or `3d`. |
| `--replaces ID` | string | no | none | An open note this one supersedes; it is resolved as replaced. |

```console
screenrig notes add "The lobby screen is mounted in portrait: design for 1080x1920." --about screen:scr_01EXAMPLESCREEN00000000
```

Write facts another agent would act on, never progress reports or chat. A note whose text (ignoring case and spacing) and subject repeat an open note confirms that note instead of adding one, with the warning `note_matched_open`. Credential-shaped text is refused with `note_contains_credential`, and text that reads as an instruction to a model with `note_rejected`; nothing is stored. The 201st open note across the organization's projects is refused with `note_limit_reached`, whose detail names notes to resolve first.

### `notes confirm`

Say that an open note still holds. Its next review is 90 days away.

```console
notes confirm <id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The `nte_` id of an open note. |

```console
screenrig notes confirm nte_01EXAMPLENOTE000000000
```

A note that is not open is refused with `note_not_open` (exit 5).

### `notes resolve`

Resolve an open note that is wrong or no longer true.

```console
notes resolve <id> <reason>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The `nte_` id of an open note. |
| `<reason>` | string | yes | none | What is true now, 1 to 500 characters. The words after the id form the reason. |

```console
screenrig notes resolve nte_01EXAMPLENOTE000000000 "The lobby screen was remounted in landscape."
```

A note that is not open is refused with `note_not_open` (exit 5).

## Other command groups

- [Projects](https://screenrig.ai/docs/cli/projects.md)
- [Service clients](https://screenrig.ai/docs/cli/service-clients.md)
- [Help and support](https://screenrig.ai/docs/cli/help.md)
- [Media](https://screenrig.ai/docs/cli/media.md)
- [Media sync](https://screenrig.ai/docs/cli/media-sync.md)
- [Playlists](https://screenrig.ai/docs/cli/playlists.md)
- [Cards](https://screenrig.ai/docs/cli/cards.md)
- [Applications](https://screenrig.ai/docs/cli/applications.md)
- [Screens](https://screenrig.ai/docs/cli/screens.md)
- [Schedules](https://screenrig.ai/docs/cli/schedules.md)
- [Campaigns](https://screenrig.ai/docs/cli/campaigns.md)
- [Device health](https://screenrig.ai/docs/cli/device.md)
- [Notifications](https://screenrig.ai/docs/cli/notifications.md)
- [Reports](https://screenrig.ai/docs/cli/reports.md)
- [Data sources](https://screenrig.ai/docs/cli/data-sources.md)
- [BI dashboards](https://screenrig.ai/docs/cli/bi.md)
- [Triggers](https://screenrig.ai/docs/cli/triggers.md)
- [Fleet links](https://screenrig.ai/docs/cli/fleet-links.md)
- [Advertising](https://screenrig.ai/docs/cli/ads.md)