# xmppc
`xmppc` is a CLI XMPP client written in C on top of
[libstrophe](http://strophe.im/libstrophe/). It's useful when you want a script,
shell, or agent to do one XMPP thing and then exit, like list a roster, send a
chat message, read recent archive entries, wait for a reply, inspect bookmarks,
and so on.
This repository is a fork — probably a hard fork — of the original
[xmppc](https://codeberg.org/Anoxinon_e.V./xmppc). It may be renamed later.
Please do not send issues from using this fork straight upstream; see
[Issues](#issues).
## Install from source
On Debian or Ubuntu-like systems, install the build tools and libraries first:
```sh
sudo apt-get update
sudo apt-get install -y \
autoconf \
automake \
gcc \
libglib2.0-dev \
libgpgme-dev \
libstrophe-dev \
libtool \
make \
pkg-config
```
Then build the binary:
```sh
./bootstrap.sh
./configure
make
```
Put the resulting `xmppc` somewhere in your `PATH`, for example:
```sh
mkdir -p ~/.local/bin
mv xmppc ~/.local/bin/xmppc
```
## Files
- `~/.config/xmppc/config` — account configuration.
- `~/.config/xmppc/AGENTS.md` — optional instructions for LLM agents using
`xmppc`.
## Accounts and passwords
You can pass a JID directly:
```sh
xmppc --jid user@example.net --pwd 'secret' --mode roster list
```
If `--pwd` is omitted, `xmppc` asks for the password without echoing it. If you
want to pipe a password in, use `--pwd -`:
```sh
pass show xmpp/example | xmppc --jid user@example.net --pwd - --mode roster list
```
Named accounts are probably nicer. `xmppc` reads them from
`~/.config/xmppc/config`; the `[default]` account is used when neither `--account`
nor `--jid` is provided.
```ini
[default]
jid=user@example.net
pwd=secret
[work]
jid=user@work.example
pwd-cmd=pass show xmpp/work
[bot]
jid=bot@example.net
pwd=another-secret
```
Prefer `pwd-cmd` if you already keep passwords in a local password manager. It
runs locally and its stdout, minus the trailing newline, becomes the password.
## Command shape
Most commands follow this pattern:
```sh
xmppc [--account ACCOUNT] [--jid JID] [--pwd PASSWORD] --mode MODE COMMAND [args...]
```
Short options are available too:
```sh
xmppc -a work -m roster list
xmppc -j user@example.net -p - -m mam list friend@example.net
```
Use `-v`, `-vv`, `-vvv`, or `-vvvv` for progressively noisier logging. Use
`--help` for the built-in summary.
## Modes
### Roster
```sh
xmppc -a work -m roster list
xmppc -a work -m roster export
```
`list` shows the account's contacts. `export` exports them.
### Message
```sh
xmppc -a work -m message chat friend@example.net 'hello from xmppc'
```
`message chat` sends an unencrypted chat message. After the sent stanza appears
in Message Archive Management (MAM), it prints one compact XML line:
```xml
```
An important bit is the distinction between the two IDs:
- `archive-id` is the MAM cursor. Use it with `mam receive after-id=...` when you
want to wait for the next reply.
- `message-id` is the client stanza ID. It's useful for matching messages, but
it's not a MAM cursor.
If `archive-id` is empty, the message was sent but the archive cursor wasn't
resolved before the lookup timed out. See [Send, then wait for a
reply](#send-then-wait-for-a-reply) for the fallback.
### Message Archive Management (MAM)
MAM commands use XEP-0313 to read archived messages.
```sh
xmppc -a work -m mam list friend@example.net
xmppc -a work -m mam list with=friend@example.net start=-15m max=20
xmppc -a work -m mam receive friend@example.net after-id=mam-id timeout=300s max=5
```
`mam list` accepts unordered `field=value` terms:
- `with=` filters to a conversation. A bare JID is shorthand for `with=`.
- `start=