XMPPC(1)

NAME

xmppc - XMPP Command line Tool

SYNOPSIS

xmppc [OPTIONS] -m MODE COMMAND [<args>…]

xmppc [-a ACCOUNT] [-j JID] [-p PASSWORD] -m MODE COMMAND [<args>…]

xmppc agent-skill [install]

DESCRIPTION

xmppc is a XMPP command line tool. You need an XMPP Account to use this tool. The account information can be defined via command line argument -j JID. If no password is provided via -p PASSWORD xmppc will ask the user to enter the password. Another option is to define 1 or more accounts within a configuration file. The option -a ACCOUNT can be used to select the account.

The argument -m MODE defines the xmppc MODE which should be used (roster, message, pgp, omemo, openpgp, monitor, bookmark, mam, discovery). The COMMAND and the args required by the COMMAND depends on the chosen MODE.

The agent-skill command prints or installs instructions for agent use. It does not connect to XMPP.

OPTIONS

-a, --attribute ACCOUNT: ACCOUNT is a name of a xmpp account defined within the configuration file.
-j, --jid JID: JID of the XMPP Account.
-p, --pwd PWD: Password of the XMPP Account. Use - to read the password from stdin.
-v VERBOSE
Verbose flags. -v[v[v[v]]]: -v is WARN -vv is INFO --vvv is DEBUG -vvvv is TRACE
--help: Print program version number and help
agent-skill [install]: Print the agent-facing xmppc instructions. With install, write a small agent skill that tells agents to run xmppc agent-skill.

MODES AND COMMANDS

xmppc modes.

-m roster

The Roster mode can be used to provided information of the xmpp account’s roster. The roster is the XMPP list of contacts.

list - List all contacts
export - Exports all contacts

-m message

The message mode can be used to send unencrypted messages to another xmpp account.

chat <jid> <message> - Sending unencrypted message to jid. On success, prints one compact XML record after the sent stanza appears in MAM:
```
<sent archive-id="mam-id" message-id="stanza-id" to="jid"/>
```
The archive-id is the MAM archive cursor. Use it as mam receive after-id when waiting for a reply. The message-id is the client stanza id and is not a MAM cursor.

-m pgp

PGP Mode (XEP-0027)

chat <jid> <message> - Sending pgp encrypted message to jid

-m omemo

OMEMO Mode (XEP-0384)

list - List the device IDs and fingerprints
delete-device-list - Deletes the OMEMO device list

-m openpgp

openpgp mode (XEP-0373)

signcrypt <jid> <message> - Sending pgp signed and encrypted message to jid

-m monitor

Monitot mode

stanza - Stanza Monitor
monitor - microblog Monitor microblog (XEP-0277)

-m bookmark

Bookmark mode (XEP-0048)

list - List bookmarks

-m mam

Message Archive Management (XEP-0313)

list <jid> [field=value …] - List archived messages. A bare jid is shorthand for with=jid. Supported fields are with, start, end, after-id, before-id, ids, and max. Field arguments are unordered. If no range or id field is supplied, start=-5m is used. max defaults to 5 and is capped at 50.
receive <jid> after-id=<mam-id> [timeout=300s] [max=5] - Poll MAM with RSM after until at least one newer archived message is available or the timeout is reached. Prints at most max messages. If no message arrives before the timeout, prints nothing.

list and receive print one compact XML record per archived message:
```
<message id="mam-id" message-id="stanza-id" stamp="..." from="..." to="..."><body>escaped body</body></message>
```
The id attribute is the MAM archive cursor. The message-id attribute is the client stanza id.

-m discovery

Service Discovery (XEP-0030)

info <jid> - info request for <jid>
item <jid> - item request for <jid>

SEND-THEN-WAIT WORKFLOW

To send a message and then wait for a reply, capture the <sent …/> line from message chat, extract its archive-id, and pass that value to mam receive as after-id. This skips the sender’s outgoing archived message and waits for newer archived messages in the conversation.

If archive-id is empty, the message was sent but the archive cursor was not resolved before timeout. Fall back to mam list over a recent time window, find the line whose message-id matches the <sent …/> message-id, then use that line’s id as the receive cursor.

AGENT SKILL

xmppc agent-skill prints the agent-facing contract for using xmppc safely. Agents should read $HOME/.config/xmppc/AGENTS.md when it exists for local policy, allowed accounts, and preferred contacts. Agents must not print secrets, password commands, or $HOME/.config/xmppc.conf.

xmppc agent-skill install writes the small skill $HOME/.config/agents/skills/communicating-through-xmppc/SKILL.md. The installed skill points agents back to xmppc agent-skill for the current command contract.

ENVIRONMENT VARIABLES

HOME

EXAMPLES

xmppc --jid user@domain.tld --pwd "secret" --mode roster list
xmppc --jid user@domain.tld --mode pgp chat friend@domain.tld "Hello"
xmppc -a account1 --mode discovery item conference@domain.tld
xmppc --mode bookmark list

FILES

Configuration file to setup accounts.

~/.config/xmppc.conf

Example:

[default]
jid=account1@domain.tld
pwd=password1

[account2]
jid=account2@domain.tld

[account3]
jid=account3@domain.tld
pwd=password3

Instead of pwd, an account may use pwd-cmd to read the password from a local command:

[account4]
jid=account4@domain.tld
pwd-cmd=pass show xmpp/account4

$HOME/.config/xmppc/AGENTS.md: Optional user-written policy for agents using xmppc. This file can describe allowed accounts, contacts, and usage rules without exposing secrets.

EXIT STATUS

0: Success
1: Failure

BUGS

See https://codeberg.org/Anoxinon_e.V./xmppc/issues

AUTHOR

DebXWoody

RESOURCES

Source: https://codeberg.org/Anoxinon_e.V./xmppc

Documentation: https://codeberg.org/Anoxinon_e.V./xmppc/wiki