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:

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:

{
  "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

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

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:

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

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:

{
  "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: report installed updates to Inbox
• observal registry: inspect Registry subjects referenced by Inbox items