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>


COPYING
-------
Copyright \(C) 2020 Anoxinon e.V. Free use of this software is
granted under the terms of the GNU General Public License (GPL).
