From dcd20d564fcc8d3efc6cd453cf8b67ec6623929c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 16 Jan 2026 22:35:36 +0000 Subject: [PATCH] docs: expand directory CLI guide --- docs/cli/directory.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/cli/directory.md b/docs/cli/directory.md index 46e8eda88..db05d637e 100644 --- a/docs/cli/directory.md +++ b/docs/cli/directory.md @@ -10,12 +10,32 @@ read_when: Directory lookups for channels that support it (contacts/peers, groups, and “me”). ## Common flags -- `--channel `: channel id/alias (auto when exactly one channel is configured) +- `--channel `: channel id/alias (required when multiple channels are configured; auto when only one is configured) - `--account `: account id (default: channel default) - `--json`: output JSON ## Notes -- For many channels, `directory` lists IDs from your configuration (allowlists / configured groups), not a live provider directory. +- `directory` is meant to help you find IDs you can paste into other commands (especially `clawdbot message send --to ...`). +- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory. +- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting. + +## Using results with `message send` + +```bash +clawdbot directory peers list --channel slack --query "U0" +clawdbot message send --channel slack --to user:U012ABCDEF --message "hello" +``` + +## ID formats (by channel) + +- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group) +- Telegram: `@username` or numeric chat id; groups are numeric ids +- Slack: `user:U…` and `channel:C…` +- Discord: `user:` and `channel:` +- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server` +- Microsoft Teams (plugin): `user:` and `conversation:` +- Zalo (plugin): user id (Bot API) +- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`) ## Self (“me”)