1'\" t
2.\" Title: xmppc
3.\" Author: [see the "AUTHOR" section]
4.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5.\" Date: 07/05/2026
6.\" Manual: \ \&
7.\" Source: \ \&
8.\" Language: English
9.\"
10.TH "XMPPC" "1" "07/05/2026" "\ \&" "\ \&"
11.\" -----------------------------------------------------------------
12.\" * Define some portability stuff
13.\" -----------------------------------------------------------------
14.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15.\" http://bugs.debian.org/507673
16.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18.ie \n(.g .ds Aq \(aq
19.el .ds Aq '
20.\" -----------------------------------------------------------------
21.\" * set default formatting
22.\" -----------------------------------------------------------------
23.\" disable hyphenation
24.nh
25.\" disable justification (adjust text to left margin only)
26.ad l
27.\" -----------------------------------------------------------------
28.\" * MAIN CONTENT STARTS HERE *
29.\" -----------------------------------------------------------------
30.SH "NAME"
31xmppc \- XMPP Command line Tool
32.SH "SYNOPSIS"
33.sp
34\fIxmppc\fR [\fIOPTIONS\fR] \-m \fIMODE\fR \fICOMMAND\fR [<args>\&...]
35.sp
36\fIxmppc\fR [\-a \fIACCOUNT\fR] [\-j \fIJID\fR] [\-p \fIPASSWORD\fR] \-m \fIMODE\fR \fICOMMAND\fR [<args>\&...]
37.sp
38\fIxmppc\fR \fIagent\-skill\fR [\fIinstall\fR]
39.SH "DESCRIPTION"
40.sp
41xmppc 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\&.
42.sp
43The 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\&.
44.sp
45The \fIagent\-skill\fR command prints or installs instructions for agent use\&. It does not connect to XMPP\&.
46.SH "OPTIONS"
47.PP
48\fB\-a, \-\-attribute\fR \fIACCOUNT\fR
49.RS 4
50\fIACCOUNT\fR
51is a name of a xmpp account defined within the configuration file\&.
52.RE
53.PP
54\fB\-j, \-\-jid\fR \fIJID\fR
55.RS 4
56\fIJID\fR
57of the XMPP Account\&.
58.RE
59.PP
60\fB\-p, \-\-pwd\fR \fIPWD\fR
61.RS 4
62Password of the XMPP Account\&. Use
63\fI\-\fR
64to read the password from stdin\&.
65.RE
66.PP
67\fB\-v\fR \fIVERBOSE\fR, Verbose flags\&. \-v[v[v[v]]]
68.RS 4
69\-v is WARN \-vv is INFO \-\-vvv is DEBUG \-vvvv is TRACE
70.RE
71.PP
72\fB\-\-help\fR
73.RS 4
74Print program version number and help
75.RE
76.PP
77\fBagent\-skill\fR [\fIinstall\fR]
78.RS 4
79Print the agent\-facing xmppc instructions\&. With
80\fIinstall\fR, write a small agent skill that tells agents to run
81\fIxmppc agent\-skill\fR\&.
82.RE
83.SH "MODES AND COMMANDS"
84.sp
85xmppc modes\&.
86.PP
87\fB\-m roster\fR
88.RS 4
89The Roster mode can be used to provided information of the xmpp account\(cqs roster\&. The roster is the XMPP list of contacts\&.
90.sp
91.RS 4
92.ie n \{\
93\h'-04'\(bu\h'+03'\c
94.\}
95.el \{\
96.sp -1
97.IP \(bu 2.3
98.\}
99\fBlist\fR
100\- List all contacts
101.RE
102.sp
103.RS 4
104.ie n \{\
105\h'-04'\(bu\h'+03'\c
106.\}
107.el \{\
108.sp -1
109.IP \(bu 2.3
110.\}
111\fBexport\fR
112\- Exports all contacts
113.RE
114.RE
115.PP
116\fB\-m message\fR
117.RS 4
118The message mode can be used to send unencrypted messages to another xmpp account\&.
119.sp
120.RS 4
121.ie n \{\
122\h'-04'\(bu\h'+03'\c
123.\}
124.el \{\
125.sp -1
126.IP \(bu 2.3
127.\}
128\fBchat <jid> <message>\fR
129\- Sending unencrypted message to jid\&. On success, prints one compact XML record after the sent stanza appears in MAM:
130.sp
131.if n \{\
132.RS 4
133.\}
134.nf
135<sent archive\-id="mam\-id" message\-id="stanza\-id" to="jid"/>
136.fi
137.if n \{\
138.RE
139.\}
140.sp
141The
142\fIarchive\-id\fR
143is the MAM archive cursor\&. Use it as
144\fImam receive after\-id\fR
145when waiting for a reply\&. The
146\fImessage\-id\fR
147is the client stanza id and is not a MAM cursor\&.
148.RE
149.RE
150.PP
151\fB\-m pgp\fR
152.RS 4
153PGP Mode (XEP\-0027)
154.sp
155.RS 4
156.ie n \{\
157\h'-04'\(bu\h'+03'\c
158.\}
159.el \{\
160.sp -1
161.IP \(bu 2.3
162.\}
163\fBchat <jid> <message>\fR
164\- Sending pgp encrypted message to jid
165.RE
166.RE
167.PP
168\fB\-m omemo\fR
169.RS 4
170OMEMO Mode (XEP\-0384)
171.sp
172.RS 4
173.ie n \{\
174\h'-04'\(bu\h'+03'\c
175.\}
176.el \{\
177.sp -1
178.IP \(bu 2.3
179.\}
180\fBlist\fR
181\- List the device IDs and fingerprints
182.RE
183.sp
184.RS 4
185.ie n \{\
186\h'-04'\(bu\h'+03'\c
187.\}
188.el \{\
189.sp -1
190.IP \(bu 2.3
191.\}
192\fBdelete\-device\-list\fR
193\- Deletes the OMEMO device list
194.RE
195.RE
196.PP
197\fB\-m openpgp\fR
198.RS 4
199openpgp mode (XEP\-0373)
200.sp
201.RS 4
202.ie n \{\
203\h'-04'\(bu\h'+03'\c
204.\}
205.el \{\
206.sp -1
207.IP \(bu 2.3
208.\}
209\fBsigncrypt <jid> <message>\fR
210\- Sending pgp signed and encrypted message to jid
211.RE
212.RE
213.PP
214\fB\-m monitor\fR
215.RS 4
216Monitot mode
217.sp
218.RS 4
219.ie n \{\
220\h'-04'\(bu\h'+03'\c
221.\}
222.el \{\
223.sp -1
224.IP \(bu 2.3
225.\}
226\fBstanza\fR
227\- Stanza Monitor
228.RE
229.sp
230.RS 4
231.ie n \{\
232\h'-04'\(bu\h'+03'\c
233.\}
234.el \{\
235.sp -1
236.IP \(bu 2.3
237.\}
238\fBmonitor\fR
239\- microblog Monitor microblog (XEP\-0277)
240.RE
241.RE
242.PP
243\fB\-m bookmark\fR
244.RS 4
245Bookmark mode (XEP\-0048)
246.sp
247.RS 4
248.ie n \{\
249\h'-04'\(bu\h'+03'\c
250.\}
251.el \{\
252.sp -1
253.IP \(bu 2.3
254.\}
255\fBlist\fR
256\- List bookmarks
257.RE
258.RE
259.PP
260\fB\-m mam\fR
261.RS 4
262Message Archive Management (XEP\-0313)
263.sp
264.RS 4
265.ie n \{\
266\h'-04'\(bu\h'+03'\c
267.\}
268.el \{\
269.sp -1
270.IP \(bu 2.3
271.\}
272\fBlist <jid> [field=value \&...]\fR
273\- List archived messages\&. A bare
274\fIjid\fR
275is shorthand for
276\fIwith=jid\fR\&. Supported fields are
277\fIwith\fR,
278\fIstart\fR,
279\fIend\fR,
280\fIafter\-id\fR,
281\fIbefore\-id\fR,
282\fIids\fR, and
283\fImax\fR\&. Field arguments are unordered\&. If no range or id field is supplied,
284\fIstart=\-5m\fR
285is used\&.
286\fImax\fR
287defaults to 5 and is capped at 50\&.
288.RE
289.sp
290.RS 4
291.ie n \{\
292\h'-04'\(bu\h'+03'\c
293.\}
294.el \{\
295.sp -1
296.IP \(bu 2.3
297.\}
298\fBreceive <jid> after\-id=<mam\-id> [timeout=300s] [max=5]\fR
299\- Poll MAM with RSM
300\fIafter\fR
301until at least one newer archived message is available or the timeout is reached\&. Prints at most
302\fImax\fR
303messages\&. If no message arrives before the timeout, prints nothing\&.
304.sp
305\fIlist\fR
306and
307\fIreceive\fR
308print one compact XML record per archived message:
309.sp
310.if n \{\
311.RS 4
312.\}
313.nf
314<message id="mam\-id" message\-id="stanza\-id" stamp="\&.\&.\&." from="\&.\&.\&." to="\&.\&.\&."><body>escaped body</body></message>
315.fi
316.if n \{\
317.RE
318.\}
319.sp
320The
321\fIid\fR
322attribute is the MAM archive cursor\&. The
323\fImessage\-id\fR
324attribute is the client stanza id\&.
325.RE
326.RE
327.PP
328\fB\-m discovery\fR
329.RS 4
330Service Discovery (XEP\-0030)
331.sp
332.RS 4
333.ie n \{\
334\h'-04'\(bu\h'+03'\c
335.\}
336.el \{\
337.sp -1
338.IP \(bu 2.3
339.\}
340\fBinfo <jid>\fR
341\- info request for <jid>
342.RE
343.sp
344.RS 4
345.ie n \{\
346\h'-04'\(bu\h'+03'\c
347.\}
348.el \{\
349.sp -1
350.IP \(bu 2.3
351.\}
352\fBitem <jid>\fR
353\- item request for <jid>
354.RE
355.RE
356.SH "SEND\-THEN\-WAIT WORKFLOW"
357.sp
358To 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\&.
359.sp
360If \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\&.
361.SH "AGENT SKILL"
362.sp
363\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\&.
364.sp
365\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\&.
366.SH "ENVIRONMENT VARIABLES"
367.sp
368.RS 4
369.ie n \{\
370\h'-04'\(bu\h'+03'\c
371.\}
372.el \{\
373.sp -1
374.IP \(bu 2.3
375.\}
376HOME
377.RE
378.SH "EXAMPLES"
379.sp
380.if n \{\
381.RS 4
382.\}
383.nf
384xmppc \-\-jid user@domain\&.tld \-\-pwd "secret" \-\-mode roster list
385xmppc \-\-jid user@domain\&.tld \-\-mode pgp chat friend@domain\&.tld "Hello"
386xmppc \-a account1 \-\-mode discovery item conference@domain\&.tld
387xmppc \-\-mode bookmark list
388.fi
389.if n \{\
390.RE
391.\}
392.SH "FILES"
393.sp
394Configuration file to setup accounts\&.
395.PP
396\fB~/\&.config/xmppc\&.conf\fR
397.RS 4
398Example:
399.sp
400.if n \{\
401.RS 4
402.\}
403.nf
404[default]
405jid=account1@domain\&.tld
406pwd=password1
407.fi
408.if n \{\
409.RE
410.\}
411.sp
412.if n \{\
413.RS 4
414.\}
415.nf
416[account2]
417jid=account2@domain\&.tld
418.fi
419.if n \{\
420.RE
421.\}
422.sp
423.if n \{\
424.RS 4
425.\}
426.nf
427[account3]
428jid=account3@domain\&.tld
429pwd=password3
430.fi
431.if n \{\
432.RE
433.\}
434.RE
435.sp
436Instead of \fIpwd\fR, an account may use \fIpwd\-cmd\fR to read the password from a local command:
437.sp
438.if n \{\
439.RS 4
440.\}
441.nf
442[account4]
443jid=account4@domain\&.tld
444pwd\-cmd=pass show xmpp/account4
445.fi
446.if n \{\
447.RE
448.\}
449.PP
450\fB$HOME/\&.config/xmppc/AGENTS\&.md\fR
451.RS 4
452Optional user\-written policy for agents using xmppc\&. This file can describe allowed accounts, contacts, and usage rules without exposing secrets\&.
453.RE
454.SH "EXIT STATUS"
455.PP
456\fB0\fR
457.RS 4
458Success
459.RE
460.PP
461\fB1\fR
462.RS 4
463Failure
464.RE
465.SH "BUGS"
466.sp
467See https://codeberg\&.org/Anoxinon_e\&.V\&./xmppc/issues
468.SH "AUTHOR"
469.sp
470.RS 4
471.ie n \{\
472\h'-04'\(bu\h'+03'\c
473.\}
474.el \{\
475.sp -1
476.IP \(bu 2.3
477.\}
478DebXWoody
479.RE
480.SH "RESOURCES"
481.sp
482Source: https://codeberg\&.org/Anoxinon_e\&.V\&./xmppc
483.sp
484Documentation: https://codeberg\&.org/Anoxinon_e\&.V\&./xmppc/wiki
485.SH "COPYING"
486.sp
487Copyright (C) 2020 Anoxinon e\&.V\&. Free use of this software is granted under the terms of the GNU General Public License (GPL)\&.