1XMPPC(1)
2========
3
4NAME
5----
6xmppc - XMPP Command line Tool
7
8
9SYNOPSIS
10--------
11'xmppc' ['OPTIONS'] -m 'MODE' 'COMMAND' [<args>...]
12
13'xmppc' [-a 'ACCOUNT'] [-j 'JID'] [-p 'PASSWORD'] -m 'MODE' 'COMMAND' [<args>...]
14
15'xmppc' 'agent-skill' ['install']
16
17
18DESCRIPTION
19-----------
20xmppc is a XMPP command line tool. You need an XMPP Account to use this tool.
21The account information can be defined via command line argument -j 'JID'. If no
22password is provided via -p 'PASSWORD' xmppc will ask the user to enter the
23password. Another option is to define 1 or more accounts within a configuration
24file. The option -a 'ACCOUNT' can be used to select the account.
25
26The argument -m 'MODE' defines the xmppc 'MODE' which should be used (roster,
27message, pgp, omemo, openpgp, monitor, bookmark, mam, discovery). The 'COMMAND'
28and the args required by the 'COMMAND' depends on the chosen 'MODE'.
29
30The 'agent-skill' command prints or installs instructions for agent use. It does
31not connect to XMPP.
32
33
34OPTIONS
35-------
36*-a, --attribute* 'ACCOUNT'::
37 'ACCOUNT' is a name of a xmpp account defined within the configuration file.
38
39*-j, --jid* 'JID'::
40 'JID' of the XMPP Account.
41
42*-p, --pwd* 'PWD'::
43 Password of the XMPP Account. Use '-' to read the password from stdin.
44
45*-v* 'VERBOSE'::
46 Verbose flags. -v[v[v[v]]]::
47 -v is WARN -vv is INFO --vvv is DEBUG -vvvv is TRACE
48
49*--help*::
50 Print program version number and help
51
52*agent-skill* ['install']::
53 Print the agent-facing xmppc instructions. With 'install', write a small
54 agent skill that tells agents to run 'xmppc agent-skill'.
55
56
57MODES AND COMMANDS
58------------------
59xmppc modes.
60
61*-m roster*::
62The Roster mode can be used to provided information of the xmpp account's
63roster. The roster is the XMPP list of contacts.
64
65* *list* - List all contacts
66* *export* - Exports all contacts
67
68*-m message*::
69The message mode can be used to send unencrypted messages to another xmpp
70account.
71
72* *chat <jid> <message>* - Sending unencrypted message to jid. On success,
73 prints one compact XML record after the sent stanza appears in MAM:
74+
75----
76<sent archive-id="mam-id" message-id="stanza-id" to="jid"/>
77----
78+
79The 'archive-id' is the MAM archive cursor. Use it as 'mam receive after-id' when
80waiting for a reply. The 'message-id' is the client stanza id and is not a MAM
81cursor.
82
83*-m pgp*::
84PGP Mode (XEP-0027)
85
86* *chat <jid> <message>* - Sending pgp encrypted message to jid
87
88*-m omemo*::
89OMEMO Mode (XEP-0384)
90
91* *list* - List the device IDs and fingerprints
92* *delete-device-list* - Deletes the OMEMO device list
93
94*-m openpgp*::
95openpgp mode (XEP-0373)
96
97* *signcrypt <jid> <message>* - Sending pgp signed and encrypted message to jid
98
99*-m monitor*::
100Monitot mode
101
102* *stanza* - Stanza Monitor
103* *monitor* - microblog Monitor microblog (XEP-0277)
104
105*-m bookmark*:: Bookmark mode (XEP-0048)
106
107* *list* - List bookmarks
108
109*-m mam*:: Message Archive Management (XEP-0313)
110
111* *list <jid> [field=value ...]* - List archived messages. A bare 'jid' is
112 shorthand for 'with=jid'. Supported fields are 'with', 'start', 'end',
113 'after-id', 'before-id', 'ids', and 'max'. Field arguments are unordered.
114 If no range or id field is supplied, 'start=-5m' is used. 'max' defaults to 5
115 and is capped at 50.
116* *receive <jid> after-id=<mam-id> [timeout=300s] [max=5]* - Poll MAM with RSM
117 'after' until at least one newer archived message is available or the timeout
118 is reached. Prints at most 'max' messages. If no message arrives before the
119 timeout, prints nothing.
120+
121'list' and 'receive' print one compact XML record per archived message:
122+
123----
124<message id="mam-id" message-id="stanza-id" stamp="..." from="..." to="..."><body>escaped body</body></message>
125----
126+
127The 'id' attribute is the MAM archive cursor. The 'message-id' attribute is the
128client stanza id.
129
130*-m discovery*:: Service Discovery (XEP-0030)
131
132* *info <jid>* - info request for <jid>
133* *item <jid>* - item request for <jid>
134
135
136SEND-THEN-WAIT WORKFLOW
137-----------------------
138To send a message and then wait for a reply, capture the '<sent .../>' line from
139'message chat', extract its 'archive-id', and pass that value to 'mam receive'
140as 'after-id'. This skips the sender's outgoing archived message and waits for
141newer archived messages in the conversation.
142
143If 'archive-id' is empty, the message was sent but the archive cursor was not
144resolved before timeout. Fall back to 'mam list' over a recent time window, find
145the line whose 'message-id' matches the '<sent .../>' 'message-id', then use that
146line's 'id' as the receive cursor.
147
148AGENT SKILL
149-----------
150'xmppc agent-skill' prints the agent-facing contract for using xmppc safely.
151Agents should read +$HOME/.config/xmppc/AGENTS.md+ when it exists for local policy,
152allowed accounts, and preferred contacts. Agents must not print secrets,
153password commands, or +$HOME/.config/xmppc.conf+.
154
155'xmppc agent-skill install' writes the small skill
156+$HOME/.config/agents/skills/communicating-through-xmppc/SKILL.md+. The installed
157skill points agents back to 'xmppc agent-skill' for the current command contract.
158
159
160ENVIRONMENT VARIABLES
161---------------------
162
163* HOME
164
165
166EXAMPLES
167--------
168 xmppc --jid user@domain.tld --pwd "secret" --mode roster list
169 xmppc --jid user@domain.tld --mode pgp chat friend@domain.tld "Hello"
170 xmppc -a account1 --mode discovery item conference@domain.tld
171 xmppc --mode bookmark list
172
173
174FILES
175-----
176Configuration file to setup accounts.
177
178*~/.config/xmppc.conf*::
179Example:
180
181
182 [default]
183 jid=account1@domain.tld
184 pwd=password1
185
186 [account2]
187 jid=account2@domain.tld
188
189 [account3]
190 jid=account3@domain.tld
191 pwd=password3
192
193Instead of 'pwd', an account may use 'pwd-cmd' to read the password from a local
194command:
195
196 [account4]
197 jid=account4@domain.tld
198 pwd-cmd=pass show xmpp/account4
199
200*$HOME/.config/xmppc/AGENTS.md*::
201Optional user-written policy for agents using xmppc. This file can describe
202allowed accounts, contacts, and usage rules without exposing secrets.
203
204EXIT STATUS
205-----------
206*0*::
207 Success
208
209*1*::
210 Failure
211
212
213BUGS
214----
215See <https://codeberg.org/Anoxinon_e.V./xmppc/issues>
216
217
218AUTHOR
219------
220* DebXWoody
221
222RESOURCES
223---------
224Source: <https://codeberg.org/Anoxinon_e.V./xmppc>
225
226Documentation: <https://codeberg.org/Anoxinon_e.V./xmppc/wiki>
227
228
229COPYING
230-------
231Copyright \(C) 2020 Anoxinon e.V. Free use of this software is
232granted under the terms of the GNU General Public License (GPL).