Skill

roam

Every Roam HQ surface — chat, transcripts, On-Air events, SCIM, webhooks — in one local-first CLI with offline...

Verified: 2026-05-13 (printing-press-ingest-2026-05-13+enrich-capability-skill)

When to use roam

Choose if

You need read-mostly access to Roam HQ surfaces (chat, transcripts, On-Air events, webhooks, SCIM) from an agent loop, with FTS5 search, typed exit codes, and an offline-friendly local store. Pick this over hand-rolling against Roam's REST API when you want adaptive rate-limit handling and a `doctor token` introspection path.

Avoid if

You need to administer a Roam workspace via full CRUD (SCIM apply is available but the CLI is read-mostly by design — most write paths require `--apply` and gate on full-access org keys). Also avoid if your users don't have a Roam HQ subscription or if you only need one-off chat posting — Roam's native integrations are simpler.

Risk Flags

  • MEDIUM auth Some HQ v1 endpoints require full-access organization keys; PATs cover only v0 chat/transcripts. Running without correct scopes returns 403. The README recommends `roam-pp-cli doctor token` to inspect reachable families.
  • MEDIUM scope Personal mode restricts several endpoints to resources where the authenticated user was a participant — agents acting as a single user cannot enumerate the full workspace.
  • LOW rate_limit Adaptive limiter honors Retry-After automatically; concrete thresholds are not disclosed. Exit code 7 surfaces rate-limit hits.
  • LOW data_quality Maximum file size 10 MB on uploads. Larger artifacts must be chunked or staged outside Roam.

Cost

Type: Unknown · Free tier: CLI wrapper is free to install via npx. Some HQ v1 endpoints require full-access org keys; Chat/Transcript v0 endpoints work with PATs.

Hidden costs

  • Requires a Roam HQ workspace and a personal access token (PAT) or organization key. The CLI itself is free; the upstream Roam plan is not disclosed in the README.

Install

Default

npx -y @mvanhorn/printing-press install roam
# Set a Roam HQ personal access token (or full-access org key):
export ROAM_API_KEY=<your-token>
# Verify reachable endpoint families:
roam-pp-cli doctor token

Setup docs →

Estimated time to first success: ~10 min

Dependencies

Minimum runtime: Node.js (npx) or pre-built binary from GitHub releases

Distribution

Repository
https://github.com/mvanhorn/printing-press-library
License
MIT