pp-roam

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/roam/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Roam — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `roam-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install roam --cli-only
   ```
2. Verify: `roam-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/productivity/roam/cmd/roam-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for roam-pp-cli when you need to script Roam HQ from a shell or agent: tail webhook deliveries, post deploy notifications, search transcripts across many meetings at once, reconcile SCIM membership against an HRIS roster, or extract decisions from last week's recordings. The remote MCP at api.ro.am/mcp is great for ad-hoc agent chat; this CLI is the choice when you want pipelines, cron, or local-first search.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`grep`** — Search across every chat message and meeting transcript at once with --since, --from-user, --in-meeting, --in-group filters.

  _Reach for this when an agent needs to recall what was said across many meetings without re-paging the rate-limited transcript API._

  ```bash
  roam-pp-cli grep "pricing" --since 14d --in-group eng --json --select transcript_id,line
  ```
- **`decisions`** — Surface decision-shaped lines ("we decided", "action item", "agreed", "let's go with") from synced transcripts.

  _Use when an agent owes the team a Monday recap; deterministic and citation-bearing._

  ```bash
  roam-pp-cli decisions --since 7d --in-group product --agent
  ```
- **`onair-attendance-drift`** — Compare invited guests vs actual attendance for an On-Air event; print invited-no-show and walk-in sets.

  _Use when an agent is asked who didn't show or who attended without an invite._

  ```bash
  roam-pp-cli onair-attendance-drift --event evt_123 --json
  ```
- **`webhook-tail`** — Tail recent webhook deliveries from the local subscription registry, --since filtered.

  _Use when debugging a webhook integration without standing up a listener._

  ```bash
  roam-pp-cli webhook-tail --since 1h --json
  ```
- **`mention-inbox`** — Local FTS over messages.text for @user tokens with --since filter; tail format.

  _Use when an agent must surface unread mentions across all groups without round-tripping the API per group._

  ```bash
  roam-pp-cli mention-inbox --user @me --since 7d --agent
  ```

### Mutation safety
- **`onair-reaper`** — Find recurring On-Air events with zero attendance over N days. --apply cancels them via the absorbed cancel endpoint.

  _Use when cleaning up dead recurring events; safe by default._

  ```bash
  roam-pp-cli onair-reaper --stale-days 60 --dry-run
  ```
- **`scim-diff`** — Diff a CSV/JSON HRIS roster against /Users SCIM list; print add/update/remove sets. --apply runs SCIM CRUD.

  _Use when an agent needs to reconcile an external roster with Roam membership without clicking through admin UI._

  ```bash
  roam-pp-cli scim-diff --roster hris.csv --apply --dry-run
  ```

### Agent-native plumbing
- **`transcript-fanout`** — Run a single question against every transcript in a date range; one row per transcript with answer + citation.

  _Use when an agent must scan many meetings for a single question without re-prompting each one._

  ```bash
  roam-pp-cli transcript-fanout --question "did anyone mention Q3 hiring?" --since 30d --agent
  ```
- **`relay`** — Pipe arbitrary stdin lines into a Roam group via /chat.post with deterministic idempotency keys and 429 backoff.

  _Use when an agent needs to forward a stream (CI, alerts, logs) into Roam without writing a custom webhook._

  ```bash
  tail -F deploys.log | roam-pp-cli relay --to eng-deploys --idempotent-key-prefix deploys
  ```

### Reachability mitigation
- **`doctor token`** — Probe one representative GET per spec family (HQ, On-Air, Chat, SCIM, Webhooks) and print which families this key can reach.

  _Use when an agent needs to know which Roam commands will work with the credential it has before attempting them._

  ```bash
  roam-pp-cli doctor token
  ```

## Command Reference

**addr-info** — Manage addr info

- `roam-pp-cli addr-info` — Get information about a chat address, which is the name for any entity that may participate in a chat, such as a...

**app-uninstall** — Manage app uninstall

- `roam-pp-cli app-uninstall` — Revoke an access token and uninstall your app. On successful response, your access token will no longer be...

**chat-delete** — Manage chat delete

- `roam-pp-cli chat-delete` — Delete a previously posted bot message. The bot must own the message being deleted (matched by address ID). Personal...

**chat-history** — Manage chat history

- `roam-pp-cli chat-history` — List messages in a chat, filtered by date range (after/before). The ordering of results depends on the filter...

**chat-list** — Manage chat list

- `roam-pp-cli chat-list` — List all accessible chats, which consist of all DMs, MultiDMs, and Channels that your bot has been added to, in...

**chat-post** — Manage chat post

- `roam-pp-cli chat-post` — Post a message to a chat. Messages can be plain markdown text, rich [Block Kit](/docs/guides/block-kit) layouts, or...

**chat-send-message** — Manage chat send message

- `roam-pp-cli chat-send-message` — Sends the given message to the specified recipients. At this time, we only support sending to a single group...

**chat-typing** — Manage chat typing

- `roam-pp-cli chat-typing` — Notify other chat participants that you are working on a response. If they have the chat open, they will see '(Bot...

**chat-update** — Manage chat update

- `roam-pp-cli chat-update` — Edit a previously posted bot message. The updated message can contain plain markdown text or rich [Block...

**group-add** — Manage group add

- `roam-pp-cli group-add` — Add one or more group members and/or admins. Apps may add members to a group if one of the following conditions is...

**group-archive** — Manage group archive

- `roam-pp-cli group-archive` — Archive a group by ID. **Access:** Organization only. **Required scope:** `group:write` --- **OpenAPI Spec:**...

**group-create** — Manage group create

- `roam-pp-cli group-create` — Create a group address that can be used for chat. Groups which specify an admin will operate in an 'Admin only'...

**group-members** — Manage group members

- `roam-pp-cli group-members` — List members in a group. Apps may list members if one of the following conditions is true: 1. It is a public group...

**group-remove** — Manage group remove

- `roam-pp-cli group-remove` — Remove one or more group members. Apps may remove members from a group if one of the following conditions is true:...

**group-rename** — Manage group rename

- `roam-pp-cli group-rename` — Rename a group by ID. Apps may only rename groups for which they are an admin. **Access:** Organization only....

**groups** — Ma