> ## Documentation Index
> Fetch the complete documentation index at: https://docs.observal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# observal inbox

View and update the signed-in user's work and event feed. Inbox items cover reviews, decisions, teamspace activity, update notices, completed insights, and system notices.

The Inbox is self-only. There is no option for reading another user's items.

## List items

The direct and explicit list forms are equivalent:

```bash theme={null}
observal inbox --output json
observal inbox list --state open --action-required --output json
observal inbox list --subject-type mcp --search postgres --sort oldest --output json
```

| Option | Description |
| - | - |
| `--state`, `-s` | Filter by `open`, `done`, or `dismissed` |
| `--kind`, `-k` | Filter by event kind |
| `--action-required` / `--no-action-required` | Filter by whether the item requires action |
| `--unread` / `--read` | Filter by read state |
| `--subject-type` | Filter by the related object type, such as `agent`, `mcp`, `skill`, `team`, or `insight_report` |
| `--search`, `-q` | Search titles, bodies, namespaces, and slugs |
| `--sort` | Sort by `newest` or `oldest` |
| `--page`, `-p` | Select a page, starting at 1 |
| `--page-size` | Return 1 through 100 items |
| `--output`, `-o` | Table or JSON output |

Supported kinds are:

* `review_requested`
* `review_approved`
* `review_rejected`
* `review_comment`
* `change_requested`
* `team_join_requested`
* `team_join_decided`
* `team_created_pending`
* `ownership_transfer`
* `update_available`
* `insight_ready`
* `system_notice`

JSON returns the direct paginated server object:

```json theme={null}
{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 25
}
```

An empty `items` array is successful. Continue with `--page N` while the returned page range is below `total`.

## Count items

```bash theme={null}
observal inbox count --output json
observal inbox count --facets --facet-state open --output json
```

The basic result includes `unread`, `action_required`, `open`, `done`, and `dismissed`. `--facets` also returns `by_kind` and `by_subject_type`; `--facet-state` restricts those breakdowns and requires `--facets`.

## Show an item

```bash theme={null}
observal inbox show 11111111-1111-1111-1111-111111111111 --output json
```

The detail result includes the item's body, related subject, exact action URL or command, and append-only history. The CLI displays an action command but never runs it automatically.

## Update one item

Every mutation supports table and JSON output:

```bash theme={null}
observal inbox read 11111111-1111-1111-1111-111111111111 --output json
observal inbox unread 11111111-1111-1111-1111-111111111111 --output json
observal inbox done 11111111-1111-1111-1111-111111111111 --output json
observal inbox dismiss 11111111-1111-1111-1111-111111111111 --output json
observal inbox reopen 11111111-1111-1111-1111-111111111111 --output json
```

Read state and lifecycle state are separate:

* `read` and `unread` change only whether the item has been seen.
* `done` resolves completed work.
* `dismiss` resolves the item without acting on it.
* `reopen` returns a done or dismissed item to `open`.

JSON returns the updated item directly.

## Mark a filtered set read

```bash theme={null}
observal inbox read-all --kind update_available
observal inbox read-all --state open --subject-type mcp --search postgres --yes --output json
```

`read-all` affects only unread items matching the supplied state, kind, action-required, subject-type, and search filters. Human mode asks for confirmation unless `--yes` is present. JSON mode never prompts and therefore requires `--yes`.

JSON returns:

```json theme={null}
{
  "updated": 3
}
```

## Exit codes

Invalid states, kinds, sort orders, filter lengths, item IDs, and non-interactive confirmation use validation exit code 7. Authentication, permission, not-found, rate-limit, unavailable-service, and version failures preserve the shared CLI exit contract.

In JSON mode, stdout contains only the successful result. Failures leave stdout empty and write one categorized error object to stderr.

## Related

* [`observal outdated`](/cli/outdated): report installed updates to Inbox
* [`observal registry`](/cli/registry): inspect Registry subjects referenced by Inbox items


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.