apus directory

Directory lookups for channels that support them: contacts/peers, groups, and "me" (self).

Results are meant to be pasted into other commands, especially apus message send --target ....

Common flags

• --channel <name>: channel id or alias. Required when several channels are configured, and auto-selected when only one is configured.
• --account <id>: account id (default: channel default)
• --json: output JSON
• --limit <n>: positive integer cap for peers/groups/members listings

Omit --channel to auto-select the only configured channel. Explicitly empty and whitespace-only values fail with --channel must not be blank while options are parsed, before command bootstrap and directory setup or lookup. Scripts that pass an unset shell variable must omit the flag to request automatic selection.

Omit --account to select the channel default. Explicitly empty and whitespace-only account values fail with --account must not be blank before account setup or lookup.

--limit requires a positive integer. Omit --limit to use the selected channel plugin's default. Explicitly empty and whitespace-only values are rejected.

Default output renders IDs and names in a table. Empty list results name the channel and account that were queried. JSON list output uses an empty array ([]). Failures exit nonzero and use the canonical { "ok": false, "error": { "type": "cli_error", "message": "..." } } envelope in JSON mode.

Notes

• For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
• Before a live lookup, Apus resolves configured SecretRefs only for the selected channel and account. Resolved credentials remain runtime-only. Plugin installation and auto-enable writes preserve the authored references without persisting runtime defaults.
• WhatsApp group listing is live. Gateway lookups reuse its owned connection. A standalone command opens the linked session only when no other process owns that account. Otherwise it reports that live groups are unavailable.
• An already-installed channel plugin can lack directory support. In that case the command reports the unsupported operation. It does not try to reinstall or upgrade the plugin to add support.

Using results with message send

apus directory peers list --channel slack --query "U0"
apus message send --channel slack --target user:U012ABCDEF --message "hello"

ID formats by channel

Self ("me")

apus directory self --channel zalouser

A channel may legitimately return no self identity. This is a successful empty result (exit code 0), not a failed lookup. Channels without a self resolver report that the channel does not expose a self identity, without suggesting account troubleshooting:

{
  "status": "unavailable",
  "channel": "telegram",
  "accountId": "default",
  "reason": "self-identity-unsupported"
}

When a channel implements self lookup but returns no identity, the text output names the channel and account and suggests checking its configuration and authentication. JSON callers can distinguish that case by its reason:

{
  "status": "unavailable",
  "channel": "msteams",
  "accountId": "default",
  "reason": "plugin-returned-no-self-identity"
}

Peers (contacts/users)

apus directory peers list --channel zalouser
apus directory peers list --channel zalouser --query "name"
apus directory peers list --channel zalouser --limit 50

Groups

apus directory groups list --channel zalouser
apus directory groups list --channel zalouser --query "work"
apus directory groups members --channel zalouser --group-id <id>

groups members requires a non-blank --group-id. Empty or whitespace-only IDs fail before plugin setup or lookup.

Related

• CLI reference