pp-roam

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roam — Printing Press CLI

Prerequisites: Install the CLI

前置条件：安装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:

Install via the Printing Press installer:

bash

npx -y @mvanhorn/printing-press install roam --cli-only

Verify:
```
roam-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

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

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

Roam HQ ships a remote MCP but no CLI. roam-pp-cli unifies all five Roam HQ APIs (HQ, On-Air, Chat, SCIM, Webhooks) into a single binary with a local SQLite cache and FTS5 search across messages and transcripts. Cron-friendly chat relay, decision extraction, attendance drift, and SCIM roster diff are built-in.

本技能基于

roam-pp-cli

二进制文件运行。**在调用本技能的任何命令前，你必须确认CLI已安装。**如果未安装，请先执行以下步骤安装：

通过Printing Press安装器安装：

bash

npx -y @mvanhorn/printing-press install roam --cli-only

验证：
```
roam-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等情况），可改用Go直接安装（要求Go 1.26.3或更高版本）：

bash

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

如果安装后执行

--version

提示“command not found”，说明安装步骤未将二进制文件添加到

$PATH

中。请在验证成功前不要执行技能命令。

Roam HQ提供远程MCP但无CLI工具。roam-pp-cli将Roam HQ的五大API（HQ、On-Air、Chat、SCIM、Webhooks）整合为单个二进制文件，带有本地SQLite缓存和针对消息与会议记录的FTS5搜索功能。还内置了支持Cron的聊天中继、决策提取、出勤偏差分析和SCIM名单对比功能。

When to Use This CLI

何时使用该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.

当你需要从Shell或Agent脚本化操作Roam HQ时，可使用roam-pp-cli：比如查看webhook投递记录、发布部署通知、跨多个会议搜索记录、将SCIM成员列表与HRIS名单进行比对，或从上周的录制内容中提取决策信息。api.ro.am/mcp的远程MCP适合临时Agent聊天；而当你需要流水线、Cron任务或本地优先搜索时，该CLI是最佳选择。

Unique Capabilities

独特功能

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

这些功能是其他同类型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
```

grep
— 通过--since、--from-user、--in-meeting、--in-group等过滤器，一次性搜索所有聊天消息和会议记录。
当Agent需要回忆多个会议中的讨论内容，且不想受限于API速率限制时，可使用该功能。
bash
```
roam-pp-cli grep "pricing" --since 14d --in-group eng --json --select transcript_id,line
```
decisions
— 从同步的会议记录中提取决策类语句（如“我们决定”、“行动项”、“同意”、“我们选择”）。
当Agent需要为团队生成周一复盘时使用，结果可确定且带有引用来源。
bash
```
roam-pp-cli decisions --since 7d --in-group product --agent
```
onair-attendance-drift
— 对比On-Air活动的受邀嘉宾与实际出勤人员；输出未到场受邀者和临时到场者名单。
当Agent被询问谁未到场或谁未受邀却参加活动时使用。
bash
```
roam-pp-cli onair-attendance-drift --event evt_123 --json
```
webhook-tail
— 从本地订阅注册表中查看最近的webhook投递记录，支持--since过滤。
当调试webhook集成但不想搭建监听服务时使用。
bash
```
roam-pp-cli webhook-tail --since 1h --json
```
mention-inbox
— 对消息文本中的@user标签进行本地FTS搜索，支持--since过滤；采用实时更新格式。
当Agent需要查看所有群组中未读的@提及消息，且不想逐个调用API时使用。
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
```

onair-reaper
— 查找连续N天零出勤的重复On-Air活动。--apply参数会通过整合的取消端点取消这些活动。
当清理无效的重复活动时使用，默认是安全的试运行模式。
bash
```
roam-pp-cli onair-reaper --stale-days 60 --dry-run
```
scim-diff
— 将CSV/JSON格式的HRIS名单与/Users SCIM列表进行比对；输出添加/更新/移除的人员集合。--apply参数会执行SCIM增删改操作。
当Agent需要将外部名单与Roam成员列表进行比对，且不想通过管理UI手动操作时使用。
bash
```
roam-pp-cli scim-diff --roster hris.csv --apply --dry-run
```

Agent-native plumbing

Agent原生管道

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
```

transcript-fanout
— 在指定日期范围内的所有会议记录中执行同一个问题；每个会议记录对应一行结果，包含答案和引用来源。
当Agent需要针对多个会议记录查询同一个问题，且不想逐个重复提问时使用。
bash
```
roam-pp-cli transcript-fanout --question "did anyone mention Q3 hiring?" --since 30d --agent
```
relay
— 将任意标准输入行通过/chat.post接口转发到Roam群组，带有确定性幂等键和429退避机制。
当Agent需要将流数据（CI、告警、日志）转发到Roam，且不想编写自定义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
```

doctor token
— 针对每个API家族（HQ、On-Air、Chat、SCIM、Webhooks）执行一个代表性的GET请求，输出该密钥可访问的API家族。
当Agent需要确认当前凭证可使用哪些Roam命令时使用。
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 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 — Manage groups

```
roam-pp-cli groups 02-create
```
— Creates a new group in your Roam organization. Required fields:
```
displayName
```
(max 64 characters). Optional:...
```
roam-pp-cli groups 02-delete
```
— Archives a group in Roam. This is a soft delete — the group data is retained but becomes inactive....
```
roam-pp-cli groups 02-get
```
— Retrieves a single group by its Roam Address ID. The response includes the group's
```
displayName
```
and
```
members
```
array...
```
roam-pp-cli groups 02-list
```
— Returns a paginated list of groups in your Roam organization. Pagination: Use
```
startIndex
```
(1-based) and
```
count
```
...
```
roam-pp-cli groups 02-patch
```
— Partially updates a group. Use this to add or remove members without replacing the entire group. **Supported...
```
roam-pp-cli groups 02-replace
```
— Fully replaces a group's attributes. The entire
```
members
```
list is replaced with the provided values. **Required...

groups-list — Manage groups list

```
roam-pp-cli groups-list
```
— Lists all public, non-archived groups in your home Roam. Access: Organization only. Required scope:...

item-upload — Manage item upload

```
roam-pp-cli item-upload
```
— Upload a file so that it can be sent as a chat message attachment. The returned object contains an item ID which can...

lobby-booking-list — Manage lobby booking list

```
roam-pp-cli lobby-booking-list
```
— Lists bookings for a specific lobby configuration, filtered by date range (after/before). The ordering of results...

lobby-list — Manage lobby list

```
roam-pp-cli lobby-list
```
— Lists active lobbies in your account. A lobby URL has the form
```
ro.am/{handle}
```
or
```
ro.am/{handle}/{slug}
```
. - The...

magicast-info — Manage magicast info

```
roam-pp-cli magicast-info
```
— Retrieve a magicast by ID. Access: Organization and Personal. In Personal mode, only magicasts owned by the...

magicast-list — Manage magicast list

```
roam-pp-cli magicast-list
```
— Lists all magicasts in your Roam, sorted in reverse chronological order. Access: Organization and Personal. In...

meeting-list — Manage meeting list

```
roam-pp-cli meeting-list
```
— Lists all meetings in your home Roam, filtered by date range (after/before). The ordering of results depends on the...

meetinglink-create — Manage meetinglink create

```
roam-pp-cli meetinglink-create
```
— Create a meeting link. Access: Organization and Personal. In Organization mode, specify the host by email. In...

meetinglink-info — Manage meetinglink info

```
roam-pp-cli meetinglink-info
```
— Get a meeting link. Access: Organization only. Required scope:
```
meetinglink:read
```
--- OpenAPI Spec:...

meetinglink-update — Manage meetinglink update

```
roam-pp-cli meetinglink-update
```
— Update a meeting link. Access: Organization only. Required scope:
```
meetinglink:write
```
--- OpenAPI Spec:...

messageevent-export — Manage messageevent export

```
roam-pp-cli messageevent-export
```
— Obtain a daily message event export containing DMs and group chats within your account. For customers with archival...

onair-attendance-list — Manage onair attendance list

```
roam-pp-cli onair-attendance-list
```
— Returns the attendance report for an On-Air event, combining RSVP data with join/duration information. Guests with...

onair-event-cancel — Manage onair event cancel

```
roam-pp-cli onair-event-cancel
```
— Cancels an On-Air event. This action cannot be undone. Access: Organization and Personal. Required scope:...

onair-event-create — Manage onair event create

```
roam-pp-cli onair-event-create
```
— Creates a new On-Air event. The calendar host must be a member of the organization. When using a personal access...

onair-event-info — Manage onair event info

```
roam-pp-cli onair-event-info
```
— Returns details for a single On-Air event. Access: Organization and Personal. Required scope:
```
onair:read
```
...

onair-event-list — Manage onair event list

```
roam-pp-cli onair-event-list
```
— Returns a paginated list of On-Air events for the organization. Results are sorted by start time in descending order...

onair-event-update — Manage onair event update

```
roam-pp-cli onair-event-update
```
— Updates an existing On-Air event. Only the fields provided in the request body are updated; omitted fields remain...

onair-guest-add — Manage onair guest add

```
roam-pp-cli onair-guest-add
```
— Adds one or more guests to an On-Air event. Access: Organization and Personal. Required scope:
```
onair:write
```
...

onair-guest-info — Manage onair guest info

```
roam-pp-cli onair-guest-info
```
— Returns details for a single On-Air event guest. Access: Organization and Personal. Required scope:...

onair-guest-list — Manage onair guest list

```
roam-pp-cli onair-guest-list
```
— Returns a paginated list of guests for an On-Air event. Optionally filter by RSVP status. Results are sorted by...

onair-guest-remove — Manage onair guest remove

```
roam-pp-cli onair-guest-remove
```
— Removes a guest from an On-Air event. Access: Organization and Personal. Required scope:
```
onair:write
```
---...

onair-guest-update — Manage onair guest update

```
roam-pp-cli onair-guest-update
```
— Updates the RSVP status of a guest. Access: Organization and Personal. Required scope:
```
onair:write
```
---...

reaction-add — Manage reaction add

```
roam-pp-cli reaction-add
```
— Add a reaction to a message in a chat. Access: Organization only. Required scope:
```
chat:send_message
```
or...

recording-list — Manage recording list

```
roam-pp-cli recording-list
```
— Lists all recordings in your home Roam, filtered by date range (after/before). The ordering of results depends on...

resource-types — Manage resource types

```
roam-pp-cli resource-types
```
— Returns the list of resource types supported by Roam:
```
User
```
and
```
Group
```
. No authentication required for this...

schemas — Manage schemas

```
roam-pp-cli schemas 03-metadata-get
```
— Returns the definition of a specific SCIM schema by its URN identifier. No authentication required for this...
```
roam-pp-cli schemas 03-metadata-list
```
— Returns all SCIM schemas supported by Roam, including the core User and Group schemas plus Roam's custom role...

service-provider-config — Manage service provider config

```
roam-pp-cli service-provider-config
```
— Returns Roam's SCIM capabilities and supported features. Use this endpoint to discover which SCIM operations are...

test — Manage test

```
roam-pp-cli test
```
— Test endpoint

token-info — Manage token info

```
roam-pp-cli token-info
```
— Get information about the access token, such as the Chat Address. Access: Organization and Personal. **No...

transcript-info — Manage transcript info

```
roam-pp-cli transcript-info
```
— Retrieve a transcript by ID from your home Roam. Works for both completed and live (ongoing) meetings. For live...

transcript-list — Manage transcript list

```
roam-pp-cli transcript-list
```
— Lists all transcripts in your home Roam, filtered by date range (after/before). This endpoint returns transcript...

transcript-prompt — Manage transcript prompt

```
roam-pp-cli transcript-prompt
```
— Ask a question about a specific meeting transcript and receive an AI-generated answer based on its content. Use...

user-info — Manage user info

```
roam-pp-cli user-info
```
— Get detailed information about a single user by ID. Access: Organization only. Required scope:
```
user:read
```
...

user-list — Manage user list

```
roam-pp-cli user-list
```
— List all users in the account. Users are returned in the order they were added to the account. Access:...

user-lookup — Manage user lookup

```
roam-pp-cli user-lookup
```
— Look up users in the account by email. Access: Organization only. Required scopes:
```
user:read
```
and...

userauditlog-list — Manage userauditlog list

```
roam-pp-cli userauditlog-list
```
— Get a list of user audit log entries for the account. Access: Organization only. Required scope:...

users — Manage users

```
roam-pp-cli users 01-create
```
— Provisions a new user in your Roam organization. Required fields:
```
userName
```
,
```
name.givenName
```
,...
```
roam-pp-cli users 01-delete
```
— Archives a user in Roam. This is a soft delete — the user's data is retained but they lose access....
```
roam-pp-cli users 01-get
```
— Retrieves a single user by their Roam Person ID. The response includes all user attributes, the
```
active
```
status, and...
```
roam-pp-cli users 01-list
```
— Returns a paginated list of users in your Roam organization. Filtering: Supports SCIM filter expressions, e.g.,...
```
roam-pp-cli users 01-patch
```
— Partially updates a user. Roam supports SCIM PATCH for Users with limited semantics. Supported operations: -...
```
roam-pp-cli users 01-replace
```
— Fully replaces a user's attributes. You must provide all required fields in the request body. **Roam-specific...

webhook-subscribe — Manage webhook subscribe

```
roam-pp-cli webhook-subscribe
```
— Create or update a webhook subscription for a given event. If a subscription already exists for the same event and...

webhook-unsubscribe — Manage webhook unsubscribe

```
roam-pp-cli webhook-unsubscribe
```
— Remove a webhook subscription by ID. Access: Organization only. Required scope:
```
webhook:write
```
---...

addr-info — 管理地址信息

```
roam-pp-cli addr-info
```
— 获取聊天地址的信息，聊天地址是指可参与聊天的任何实体的名称，例如……

app-uninstall — 管理应用卸载

```
roam-pp-cli app-uninstall
```
— 撤销访问令牌并卸载应用。成功响应后，你的访问令牌将不再……

chat-delete — 管理聊天消息删除

```
roam-pp-cli chat-delete
```
— 删除之前发送的机器人消息。机器人必须拥有要删除的消息（通过地址ID匹配）。个人……

chat-history — 管理聊天历史

```
roam-pp-cli chat-history
```
— 列出聊天中的消息，支持按日期范围（after/before）过滤。结果的排序方式取决于过滤器……

chat-list — 管理聊天列表

```
roam-pp-cli chat-list
```
— 列出所有可访问的聊天，包括所有私信、多人私信和机器人已加入的频道，按……

chat-post — 管理聊天消息发送

```
roam-pp-cli chat-post
```
— 向聊天发送消息。消息可以是纯markdown文本、富文本Block Kit布局，或……

chat-send-message — 管理聊天消息发送

```
roam-pp-cli chat-send-message
```
— 向指定收件人发送给定消息。目前仅支持发送到单个群组……

chat-typing — 管理聊天输入状态

```
roam-pp-cli chat-typing
```
— 通知其他聊天参与者你正在回复。如果他们打开了聊天窗口，会看到'(Bot……

chat-update — 管理聊天消息编辑

```
roam-pp-cli chat-update
```
— 编辑之前发送的机器人消息。更新后的消息可以包含纯markdown文本或富文本[Block……

group-add — 管理群组成员添加

```
roam-pp-cli group-add
```
— 添加一个或多个群组成员和/或管理员。应用在以下条件之一满足时可添加成员到群组：……

group-archive — 管理群组归档

```
roam-pp-cli group-archive
```
— 通过ID归档群组。**访问权限：**仅组织用户。所需权限范围：
```
group:write
```
--- OpenAPI规范：……

group-create — 管理群组创建

```
roam-pp-cli group-create
```
— 创建可用于聊天的群组地址。指定管理员的群组将以“仅管理员”模式运行……

group-members — 管理群组成员列表

```
roam-pp-cli group-members
```
— 列出群组成员。应用在以下条件之一满足时可列出成员：1. 这是一个公开群组……

group-remove — 管理群组成员移除

```
roam-pp-cli group-remove
```
— 移除一个或多个群组成员。应用在以下条件之一满足时可移除成员：……

group-rename — 管理群组重命名

```
roam-pp-cli group-rename
```
— 通过ID重命名群组。应用仅可重命名其作为管理员的群组。**访问权限：**仅组织用户……

groups — 管理群组

```
roam-pp-cli groups 02-create
```
— 在你的Roam组织中创建新群组。必填字段：
```
displayName
```
（最多64个字符）。可选字段：……
```
roam-pp-cli groups 02-delete
```
— 在Roam中归档群组。这是软删除——群组数据会保留但变为非活跃状态……
```
roam-pp-cli groups 02-get
```
— 通过Roam地址ID检索单个群组。响应包含群组的
```
displayName
```
和
```
members
```
数组……
```
roam-pp-cli groups 02-list
```
— 返回Roam组织中群组的分页列表。**分页：**使用
```
startIndex
```
（从1开始）和
```
count
```
……
```
roam-pp-cli groups 02-patch
```
— 部分更新群组。用于添加或移除成员而无需替换整个群组。**支持的……
```
roam-pp-cli groups 02-replace
```
— 完全替换群组的属性。整个
```
members
```
列表将被提供的值替换。**必填……

groups-list — 管理群组列表

```
roam-pp-cli groups-list
```
— 列出你的Roam中所有公开、未归档的群组。**访问权限：**仅组织用户。所需权限范围：……

item-upload — 管理文件上传

```
roam-pp-cli item-upload
```
— 上传文件以便作为聊天消息附件发送。返回的对象包含一个项目ID，可……

lobby-booking-list — 管理预约列表

```
roam-pp-cli lobby-booking-list
```
— 列出特定大厅配置的预约，支持按日期范围（after/before）过滤。结果的排序方式……

lobby-list — 管理大厅列表

```
roam-pp-cli lobby-list
```
— 列出账户中的活跃大厅。大厅URL格式为
```
ro.am/{handle}
```
或
```
ro.am/{handle}/{slug}
```
。- ……

magicast-info — 管理magicast信息

```
roam-pp-cli magicast-info
```
— 通过ID检索magicast。**访问权限：**组织和个人用户。个人模式下，仅可访问自己拥有的……

magicast-list — 管理magicast列表

```
roam-pp-cli magicast-list
```
— 列出Roam中的所有magicast，按时间倒序排序。**访问权限：**组织和个人用户。在……

meeting-list — 管理会议列表

```
roam-pp-cli meeting-list
```
— 列出你的Roam中的所有会议，支持按日期范围（after/before）过滤。结果的排序方式取决于……

meetinglink-create — 管理会议链接创建

```
roam-pp-cli meetinglink-create
```
— 创建会议链接。**访问权限：**组织和个人用户。组织模式下，通过邮箱指定主持人。在……

meetinglink-info — 管理会议链接信息

```
roam-pp-cli meetinglink-info
```
— 获取会议链接。**访问权限：**仅组织用户。所需权限范围：
```
meetinglink:read
```
--- OpenAPI规范：……

meetinglink-update — 管理会议链接更新

```
roam-pp-cli meetinglink-update
```
— 更新会议链接。**访问权限：**仅组织用户。所需权限范围：
```
meetinglink:write
```
--- OpenAPI规范：……

messageevent-export — 管理消息事件导出

```
roam-pp-cli messageevent-export
```
— 获取包含账户内私信和群组聊天的每日消息事件导出。对于有归档需求的客户……

onair-attendance-list — 管理On-Air出勤列表

```
roam-pp-cli onair-attendance-list
```
— 返回On-Air活动的出勤报告，结合RSVP数据和加入/时长信息。……

onair-event-cancel — 管理On-Air活动取消

```
roam-pp-cli onair-event-cancel
```
— 取消On-Air活动。此操作不可撤销。**访问权限：**组织和个人用户。所需权限范围：……

onair-event-create — 管理On-Air活动创建

```
roam-pp-cli onair-event-create
```
— 创建新的On-Air活动。日历主持人必须是组织成员。使用个人访问……

onair-event-info — 管理On-Air活动信息

```
roam-pp-cli onair-event-info
```
— 返回单个On-Air活动的详细信息。**访问权限：**组织和个人用户。所需权限范围：
```
onair:read
```
……

onair-event-list — 管理On-Air活动列表

```
roam-pp-cli onair-event-list
```
— 返回组织中On-Air活动的分页列表。结果按开始时间倒序排序……

onair-event-update — 管理On-Air活动更新

```
roam-pp-cli onair-event-update
```
— 更新现有On-Air活动。仅更新请求体中提供的字段；未提供的字段保持……

onair-guest-add — 管理On-Air嘉宾添加

```
roam-pp-cli onair-guest-add
```
— 为On-Air活动添加一个或多个嘉宾。**访问权限：**组织和个人用户。所需权限范围：
```
onair:write
```
……

onair-guest-info — 管理On-Air嘉宾信息

```
roam-pp-cli onair-guest-info
```
— 返回单个On-Air活动嘉宾的详细信息。**访问权限：**组织和个人用户。所需权限范围：……

onair-guest-list — 管理On-Air嘉宾列表

```
roam-pp-cli onair-guest-list
```
— 返回On-Air活动嘉宾的分页列表。可按RSVP状态过滤。结果按……

onair-guest-remove — 管理On-Air嘉宾移除

```
roam-pp-cli onair-guest-remove
```
— 从On-Air活动中移除嘉宾。**访问权限：**组织和个人用户。所需权限范围：
```
onair:write
```
--- ……

onair-guest-update — 管理On-Air嘉宾RSVP更新

```
roam-pp-cli onair-guest-update
```
— 更新嘉宾的RSVP状态。**访问权限：**组织和个人用户。所需权限范围：
```
onair:write
```
--- ……

reaction-add — 管理消息反应添加

```
roam-pp-cli reaction-add
```
— 为聊天消息添加反应。**访问权限：**仅组织用户。所需权限范围：
```
chat:send_message
```
或……

recording-list — 管理录制内容列表

```
roam-pp-cli recording-list
```
— 列出你的Roam中的所有录制内容，支持按日期范围（after/before）过滤。结果的排序方式取决于……

resource-types — 管理资源类型

```
roam-pp-cli resource-types
```
— 返回Roam支持的资源类型列表：
```
User
```
和
```
Group
```
。无需认证即可访问……

schemas — 管理SCIM模式

```
roam-pp-cli schemas 03-metadata-get
```
— 通过URN标识符返回特定SCIM模式的定义。无需认证即可访问……
```
roam-pp-cli schemas 03-metadata-list
```
— 返回Roam支持的所有SCIM模式，包括核心User和Group模式以及Roam的自定义角色……

service-provider-config — 管理服务提供商配置

```
roam-pp-cli service-provider-config
```
— 返回Roam的SCIM功能和支持的特性。使用此端点可发现Roam支持哪些SCIM操作……

test — 管理测试端点

```
roam-pp-cli test
```
— 测试端点

token-info — 管理令牌信息

```
roam-pp-cli token-info
```
— 获取访问令牌的信息，如聊天地址。**访问权限：**组织和个人用户。**无需……

transcript-info — 管理会议记录信息

```
roam-pp-cli transcript-info
```
— 通过ID从你的Roam中检索会议记录。支持已完成和进行中的会议。对于直播……

transcript-list — 管理会议记录列表

```
roam-pp-cli transcript-list
```
— 列出你的Roam中的所有会议记录，支持按日期范围（after/before）过滤。此端点返回会议记录……

transcript-prompt — 管理会议记录提问

```
roam-pp-cli transcript-prompt
```
— 针对特定会议记录提问，并基于内容获取AI生成的答案。使用……

user-info — 管理用户信息

```
roam-pp-cli user-info
```
— 通过ID获取单个用户的详细信息。**访问权限：**仅组织用户。所需权限范围：
```
user:read
```
……

user-list — 管理用户列表

```
roam-pp-cli user-list
```
— 列出账户中的所有用户。用户按加入账户的顺序返回。访问权限：……

user-lookup — 管理用户查找

```
roam-pp-cli user-lookup
```
— 通过邮箱查找账户中的用户。**访问权限：**仅组织用户。所需权限范围：
```
user:read
```
和……

userauditlog-list — 管理用户审计日志列表

```
roam-pp-cli userauditlog-list
```
— 获取账户的用户审计日志条目列表。**访问权限：**仅组织用户。所需权限范围：……

users — 管理用户

```
roam-pp-cli users 01-create
```
— 在你的Roam组织中创建新用户。必填字段：
```
userName
```
、
```
name.givenName
```
、……
```
roam-pp-cli users 01-delete
```
— 在Roam中归档用户。这是软删除——用户数据会保留但失去访问权限……
```
roam-pp-cli users 01-get
```
— 通过Roam人员ID检索单个用户。响应包含所有用户属性、
```
active
```
状态和……
```
roam-pp-cli users 01-list
```
— 返回Roam组织中用户的分页列表。**过滤：**支持SCIM过滤表达式，例如……
```
roam-pp-cli users 01-patch
```
— 部分更新用户。Roam对用户支持有限语义的SCIM PATCH。支持的操作：- ……
```
roam-pp-cli users 01-replace
```
— 完全替换用户的属性。你必须在请求体中提供所有必填字段。**Roam特定……

webhook-subscribe — 管理webhook订阅

```
roam-pp-cli webhook-subscribe
```
— 为指定事件创建或更新webhook订阅。如果同一事件和……已存在订阅……

webhook-unsubscribe — 管理webhook取消订阅

```
roam-pp-cli webhook-unsubscribe
```
— 通过ID移除webhook订阅。**访问权限：**仅组织用户。所需权限范围：
```
webhook:write
```
--- ……

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:

bash

roam-pp-cli which "<capability in your own words>"

which

resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当你知道要做什么但不知道对应的命令时，可直接询问CLI：

bash

roam-pp-cli which "<用你自己的语言描述功能>"

which

命令会将自然语言的功能查询解析为CLI精选功能索引中最匹配的命令。退出码

表示至少有一个匹配项；退出码

表示无匹配项——此时可改用

--help

或缩小查询范围。

Recipes

使用示例

Daily standup digest

每日站会摘要

bash

roam-pp-cli decisions --since 1d --in-group standup --agent --select transcript_id,line,speaker

Pull yesterday's decisions from the standup group, formatted for agent consumption with citation.

bash

roam-pp-cli decisions --since 1d --in-group standup --agent --select transcript_id,line,speaker

从站会群组中提取昨天的决策，格式适合Agent使用并带有引用来源。

Cross-meeting question scan

跨会议问题扫描

bash

roam-pp-cli transcript-fanout --question "did anyone mention Q3 hiring?" --since 30d --agent

Run one question against every transcript in the last 30 days.

bash

roam-pp-cli transcript-fanout --question "did anyone mention Q3 hiring?" --since 30d --agent

针对过去30天的所有会议记录执行同一个问题。

Reconcile HRIS roster with Roam SCIM

对比HRIS名单与Roam SCIM

bash

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

See add/update/remove sets before applying; drop --dry-run to execute.

bash

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

在执行前查看添加/更新/移除的人员集合；移除--dry-run参数即可执行变更。

Pipe CI alerts into Roam

将CI告警转发到Roam

bash

tail -F /var/log/ci.log | roam-pp-cli relay --to eng-alerts --idempotent-key-prefix ci

Stream CI log lines into a Roam group with deterministic dedupe.

bash

tail -F /var/log/ci.log | roam-pp-cli relay --to eng-alerts --idempotent-key-prefix ci

将CI日志流转发到Roam群组，并带有确定性去重机制。

Narrow a deeply-nested transcript response

精简嵌套的会议记录响应

bash

roam-pp-cli transcript-info --id <id> --json --select segments.speaker,segments.text

Use --select with dotted paths to keep agent context small on long transcripts.

bash

roam-pp-cli transcript-info --id <id> --json --select segments.speaker,segments.text

使用--select参数和点路径，在处理长会议记录时缩小Agent的上下文范围。

Auth Setup

认证设置

Bearer auth via ROAM_API_KEY. Roam supports two key tiers: full-access organization keys and personal access tokens. Some HQ v1 endpoints require full-access; Chat/Transcript v0 endpoints work with PATs. Run

roam-pp-cli doctor token

to see which families your key can reach.

Run

roam-pp-cli doctor

to verify setup.

通过ROAM_API_KEY进行Bearer认证。Roam支持两种密钥级别：全权限组织密钥和个人访问令牌。部分HQ v1端点需要全权限密钥；Chat/Transcript v0端点支持个人访问令牌。执行

roam-pp-cli doctor token

可查看你的密钥可访问的API家族。

执行

roam-pp-cli doctor

可验证设置是否正确。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
bash
```
roam-pp-cli addr-info --agent --select id,name,status
```
Previewable —
```
--dry-run
```
shows the request without sending
Offline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag
Explicit retries — use
```
--idempotent
```
only when an already-existing create should count as success, and
```
--ignore-missing
```
only when a missing delete target should count as success

在任何命令后添加

--agent

参数。该参数等价于：

--json --compact --no-input --no-color --yes

。

可管道化 — 标准输出为JSON，错误输出到标准错误
可过滤 —
```
--select
```
参数保留字段子集。点路径可深入嵌套结构；数组会遍历每个元素。在处理冗长API时，这对缩小上下文范围至关重要：
bash
```
roam-pp-cli addr-info --agent --select id,name,status
```
可预览 —
```
--dry-run
```
参数显示请求但不发送
离线友好 — 同步/搜索命令在可用时可使用本地SQLite存储
非交互式 — 从不提示，所有输入均通过标志参数提供
显式重试 — 仅当已存在的创建操作应视为成功时使用
```
--idempotent
```
；仅当缺失的删除目标应视为成功时使用
```
--ignore-missing
```

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse

.results

for data and

.meta.source

to know whether it's live or local. A human-readable

N results (live)

summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.

从本地存储或API读取数据的命令会将输出包装在来源信封中：

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析

.results

获取数据，

.meta.source

可判断数据是实时的还是本地的。仅当标准输出为终端时，才会在标准错误中打印人类可读的

N results (live)

摘要；管道/Agent消费者仅会在标准输出中获取纯JSON。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:

roam-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
roam-pp-cli feedback --stdin < notes.txt
roam-pp-cli feedback list --json --limit 10

Entries are stored locally at

~/.roam-pp-cli/feedback.jsonl

. They are never POSTed unless

ROAM_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

ROAM_FEEDBACK_AUTO_SEND=true

. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

当你（或Agent）发现该CLI存在问题时，可记录反馈：

roam-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
roam-pp-cli feedback --stdin < notes.txt
roam-pp-cli feedback list --json --limit 10

反馈条目会存储在本地

~/.roam-pp-cli/feedback.jsonl

文件中。除非设置了

ROAM_FEEDBACK_ENDPOINT

且传递了

--send

参数或设置了

ROAM_FEEDBACK_AUTO_SEND=true

，否则反馈不会被POST到服务器。默认行为是仅本地存储。

请记录让你感到意外的内容，而非正式的bug报告。简短、具体、单行描述：这样的内容更有价值。

Output Delivery

输出交付

Every command accepts

--deliver <sink>

. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL ( `application/json` or `application/x-ndjson` when `--compact` )

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

每个命令都支持

--deliver <sink>

参数。输出会发送到指定的接收端，同时（或替代）输出到标准输出，这样Agent无需手动管道即可路由命令结果。支持三种接收端：

接收端	效果
`stdout`	默认；仅输出到标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出体POST到指定URL（当使用 `--compact` 时为 `application/json` 或 `application/x-ndjson` 格式）

未知的协议会被拒绝，并返回结构化错误信息，列出支持的接收端类型。Webhook失败会返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

roam-pp-cli profile save briefing --json
roam-pp-cli --profile briefing addr-info
roam-pp-cli profile list --json
roam-pp-cli profile show briefing
roam-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults.

agent-context

lists all available profiles under

available_profiles

so introspecting agents discover them at runtime.

配置文件是一组保存的标志值，可在多次调用中复用。当定时Agent每次运行都使用相同配置调用同一命令时，可使用此功能——即HeyGen的“Beacon”模式。

roam-pp-cli profile save briefing --json
roam-pp-cli --profile briefing addr-info
roam-pp-cli profile list --json
roam-pp-cli profile show briefing
roam-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件中的值；配置文件中的值优先于默认值。

agent-context

会在

available_profiles

下列出所有可用配置文件，以便Agent在运行时发现它们。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
4	需要认证
5	API错误（上游问题）
7	速率限制（等待后重试）
10	配置错误

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
roam-pp-cli --help
```
output
Starts with
install
→ ends with
```
mcp
```
→ MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with
```
--agent
```
)

解析

$ARGUMENTS

：

为空、
help
或
--help
→ 显示
```
roam-pp-cli --help
```
输出
以
install
开头 → 结尾为
```
mcp
```
→ MCP安装；否则 → 参见上方的前置条件
其他内容 → 直接使用（以
```
--agent
```
标志执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

bash

claude mcp add roam-pp-mcp -- roam-pp-mcp

Verify:

claude mcp list

从该CLI的公开库条目或预构建版本中安装MCP二进制文件，然后注册：

bash

claude mcp add roam-pp-mcp -- roam-pp-mcp

验证：

claude mcp list

Direct Use

直接使用

Check if installed:
```
which roam-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

roam-pp-cli <command> [subcommand] [args] --agent

If ambiguous, drill into subcommand help:
```
roam-pp-cli <command> --help
```
.

检查是否已安装：
```
which roam-pp-cli
```
如果未找到，提供安装选项（参见顶部的前置条件）。
将用户查询与上方独特功能和命令参考中的最佳命令匹配。

带

--agent

标志执行：

bash

roam-pp-cli <command> [subcommand] [args] --agent

如果存在歧义，查看子命令帮助：
```
roam-pp-cli <command> --help
```
。