'\" t
.\"     Title: xmppc
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 07/05/2026
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "XMPPC" "1" "07/05/2026" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
xmppc \- XMPP Command line Tool
.SH "SYNOPSIS"
.sp
\fIxmppc\fR [\fIOPTIONS\fR] \-m \fIMODE\fR \fICOMMAND\fR [<args>\&...]
.sp
\fIxmppc\fR [\-a \fIACCOUNT\fR] [\-j \fIJID\fR] [\-p \fIPASSWORD\fR] \-m \fIMODE\fR \fICOMMAND\fR [<args>\&...]
.sp
\fIxmppc\fR \fIagent\-skill\fR [\fIinstall\fR]
.SH "DESCRIPTION"
.sp
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 \fIJID\fR\&. If no password is provided via \-p \fIPASSWORD\fR 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 \fIACCOUNT\fR can be used to select the account\&.
.sp
The argument \-m \fIMODE\fR defines the xmppc \fIMODE\fR which should be used (roster, message, pgp, omemo, openpgp, monitor, bookmark, mam, discovery)\&. The \fICOMMAND\fR and the args required by the \fICOMMAND\fR depends on the chosen \fIMODE\fR\&.
.sp
The \fIagent\-skill\fR command prints or installs instructions for agent use\&. It does not connect to XMPP\&.
.SH "OPTIONS"
.PP
\fB\-a, \-\-attribute\fR \fIACCOUNT\fR
.RS 4
\fIACCOUNT\fR
is a name of a xmpp account defined within the configuration file\&.
.RE
.PP
\fB\-j, \-\-jid\fR \fIJID\fR
.RS 4
\fIJID\fR
of the XMPP Account\&.
.RE
.PP
\fB\-p, \-\-pwd\fR \fIPWD\fR
.RS 4
Password of the XMPP Account\&. Use
\fI\-\fR
to read the password from stdin\&.
.RE
.PP
\fB\-v\fR \fIVERBOSE\fR, Verbose flags\&. \-v[v[v[v]]]
.RS 4
\-v is WARN \-vv is INFO \-\-vvv is DEBUG \-vvvv is TRACE
.RE
.PP
\fB\-\-help\fR
.RS 4
Print program version number and help
.RE
.PP
\fBagent\-skill\fR [\fIinstall\fR]
.RS 4
Print the agent\-facing xmppc instructions\&. With
\fIinstall\fR, write a small agent skill that tells agents to run
\fIxmppc agent\-skill\fR\&.
.RE
.SH "MODES AND COMMANDS"
.sp
xmppc modes\&.
.PP
\fB\-m roster\fR
.RS 4
The Roster mode can be used to provided information of the xmpp account\(cqs roster\&. The roster is the XMPP list of contacts\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBlist\fR
\- List all contacts
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBexport\fR
\- Exports all contacts
.RE
.RE
.PP
\fB\-m message\fR
.RS 4
The message mode can be used to send unencrypted messages to another xmpp account\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBchat <jid> <message>\fR
\- Sending unencrypted message to jid\&. On success, prints one compact XML record after the sent stanza appears in MAM:
.sp
.if n \{\
.RS 4
.\}
.nf
<sent archive\-id="mam\-id" message\-id="stanza\-id" to="jid"/>
.fi
.if n \{\
.RE
.\}
.sp
The
\fIarchive\-id\fR
is the MAM archive cursor\&. Use it as
\fImam receive after\-id\fR
when waiting for a reply\&. The
\fImessage\-id\fR
is the client stanza id and is not a MAM cursor\&.
.RE
.RE
.PP
\fB\-m pgp\fR
.RS 4
PGP Mode (XEP\-0027)
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBchat <jid> <message>\fR
\- Sending pgp encrypted message to jid
.RE
.RE
.PP
\fB\-m omemo\fR
.RS 4
OMEMO Mode (XEP\-0384)
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBlist\fR
\- List the device IDs and fingerprints
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdelete\-device\-list\fR
\- Deletes the OMEMO device list
.RE
.RE
.PP
\fB\-m openpgp\fR
.RS 4
openpgp mode (XEP\-0373)
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBsigncrypt <jid> <message>\fR
\- Sending pgp signed and encrypted message to jid
.RE
.RE
.PP
\fB\-m monitor\fR
.RS 4
Monitot mode
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBstanza\fR
\- Stanza Monitor
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmonitor\fR
\- microblog Monitor microblog (XEP\-0277)
.RE
.RE
.PP
\fB\-m bookmark\fR
.RS 4
Bookmark mode (XEP\-0048)
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBlist\fR
\- List bookmarks
.RE
.RE
.PP
\fB\-m mam\fR
.RS 4
Message Archive Management (XEP\-0313)
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBlist <jid> [field=value \&...]\fR
\- List archived messages\&. A bare
\fIjid\fR
is shorthand for
\fIwith=jid\fR\&. Supported fields are
\fIwith\fR,
\fIstart\fR,
\fIend\fR,
\fIafter\-id\fR,
\fIbefore\-id\fR,
\fIids\fR, and
\fImax\fR\&. Field arguments are unordered\&. If no range or id field is supplied,
\fIstart=\-5m\fR
is used\&.
\fImax\fR
defaults to 5 and is capped at 50\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBreceive <jid> after\-id=<mam\-id> [timeout=300s] [max=5]\fR
\- Poll MAM with RSM
\fIafter\fR
until at least one newer archived message is available or the timeout is reached\&. Prints at most
\fImax\fR
messages\&. If no message arrives before the timeout, prints nothing\&.
.sp
\fIlist\fR
and
\fIreceive\fR
print one compact XML record per archived message:
.sp
.if n \{\
.RS 4
.\}
.nf
<message id="mam\-id" message\-id="stanza\-id" stamp="\&.\&.\&." from="\&.\&.\&." to="\&.\&.\&."><body>escaped body</body></message>
.fi
.if n \{\
.RE
.\}
.sp
The
\fIid\fR
attribute is the MAM archive cursor\&. The
\fImessage\-id\fR
attribute is the client stanza id\&.
.RE
.RE
.PP
\fB\-m discovery\fR
.RS 4
Service Discovery (XEP\-0030)
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBinfo <jid>\fR
\- info request for <jid>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBitem <jid>\fR
\- item request for <jid>
.RE
.RE
.SH "SEND\-THEN\-WAIT WORKFLOW"
.sp
To send a message and then wait for a reply, capture the \fI<sent \&.../>\fR line from \fImessage chat\fR, extract its \fIarchive\-id\fR, and pass that value to \fImam receive\fR as \fIafter\-id\fR\&. This skips the sender\(cqs outgoing archived message and waits for newer archived messages in the conversation\&.
.sp
If \fIarchive\-id\fR is empty, the message was sent but the archive cursor was not resolved before timeout\&. Fall back to \fImam list\fR over a recent time window, find the line whose \fImessage\-id\fR matches the \fI<sent \&.../>\fR \fImessage\-id\fR, then use that line\(cqs \fIid\fR as the receive cursor\&.
.SH "AGENT SKILL"
.sp
\fIxmppc agent\-skill\fR 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\&.
.sp
\fIxmppc agent\-skill install\fR writes the small skill $HOME/\&.config/agents/skills/communicating\-through\-xmppc/SKILL\&.md\&. The installed skill points agents back to \fIxmppc agent\-skill\fR for the current command contract\&.
.SH "ENVIRONMENT VARIABLES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
HOME
.RE
.SH "EXAMPLES"
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
Configuration file to setup accounts\&.
.PP
\fB~/\&.config/xmppc\&.conf\fR
.RS 4
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
[default]
jid=account1@domain\&.tld
pwd=password1
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[account2]
jid=account2@domain\&.tld
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[account3]
jid=account3@domain\&.tld
pwd=password3
.fi
.if n \{\
.RE
.\}
.RE
.sp
Instead of \fIpwd\fR, an account may use \fIpwd\-cmd\fR to read the password from a local command:
.sp
.if n \{\
.RS 4
.\}
.nf
[account4]
jid=account4@domain\&.tld
pwd\-cmd=pass show xmpp/account4
.fi
.if n \{\
.RE
.\}
.PP
\fB$HOME/\&.config/xmppc/AGENTS\&.md\fR
.RS 4
Optional user\-written policy for agents using xmppc\&. This file can describe allowed accounts, contacts, and usage rules without exposing secrets\&.
.RE
.SH "EXIT STATUS"
.PP
\fB0\fR
.RS 4
Success
.RE
.PP
\fB1\fR
.RS 4
Failure
.RE
.SH "BUGS"
.sp
See https://codeberg\&.org/Anoxinon_e\&.V\&./xmppc/issues
.SH "AUTHOR"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
DebXWoody
.RE
.SH "RESOURCES"
.sp
Source: https://codeberg\&.org/Anoxinon_e\&.V\&./xmppc
.sp
Documentation: https://codeberg\&.org/Anoxinon_e\&.V\&./xmppc/wiki
.SH "COPYING"
.sp
Copyright (C) 2020 Anoxinon e\&.V\&. Free use of this software is granted under the terms of the GNU General Public License (GPL)\&.