JP, a powerful command line interface for Salut-à-Toi

Salut à toi is a unique XMPP client. As its official description says, it's a "multipurpose, multi front-end, free (libre) and decentralized communication tool". It has been actively developed by Jérôme Poisson (Goffi) and Adrien Cossa (Souliane) since 2008. Today, I will focus on the use of "JP", a command-line interface. It can be used to send or receive files directly from a shell, pipe commands to or from XMPP, use XMPP easily in a script and of course play with pubsub nodes.

The following article describes uses of JP. Several of them are availabled in the trunk version of Salut-à-Toi.

Introduction

JP can be used to launch complexes commands in script, for debugging purpose or to explore XMPP services. JP is the command line interface and it connect to the daemon Salut-à-Toi (SàT). You can share the session between the front-ends:

  • JP of course.
  • Primitivus as a console front-end.
  • Livervia, a web based front-end.
  • Sententia an Emacs front-end (WIP).
  • Cagou an original mobile XMPP client based on SàT (WIP).

If you want to send a file easily, discover which services are available on a server, send messages in your scripts, manage your xmpp account, control video player, edit your blog post with your favorite editor, pipe streams, manage your pubsub nodes etc, JP is for you!

Usage

JP can be used as a command line tools or in a small shell environment.

First, we need to configure and launch the daemon sat.

$ sat

Your default profile will be connected. If you have no profile, JP can be used to create one. 

$ jp profile create -j my_jid@example.org  -x mypassword profile_name
$ jp profile connect -p profile_name

Your password is saved in the sat settings. You can connect automatically with the option -c. It should be noted that SàT defines a default profile. It can be bypassed with the option -p. [ref]It is possible to use jp profile modify to set the default profile.[/ref]

$ echo "test message" | jp message send recipient@example.org -p profile_name -c

You can obtain help about a command with the option -h.

$ jp pubsub -h
usage: jp pubsub [-h]
                 {get,delete,edit,subscribe,unsubscribe,subscriptions,node,affiliations,search,hook,uri}
                 ...

positional arguments:
  {get,delete,edit,subscribe,unsubscribe,subscriptions,node,affiliations,search,hook,uri}
    get                 get pubsub item(s)
    delete              delete an item
    edit                edit an existing or new pubsub item
    subscribe           subscribe to a node
    unsubscribe         unsubscribe from a node
    subscriptions       retrieve all subscriptions on a service
    node                node handling
    affiliations        retrieve all affiliations on a service
    search              search items corresponding to filters
    hook                trigger action on Pubsub notifications
    uri                 build URI

optional arguments:
  -h, --help            show this help message and exit

JP is a Swiss army knife. Let's discover its possibilities through a few examples.

Examples

$ jp -h
usage: jp [-h] [--version]
          {file,input,uri,message,event,info,account,param,debug,ad-hoc,ticket,invitation,profile,shell,avatar,pipe,pubsub,bookmarks,roster,identity,blog}
          ...

This software is a command line tool for XMPP.
Get the latest version at http://salut-a-toi.org

optional arguments:
  -h, --help            show this help message and exit
  --version             show programʼs version number and exit

Available commands:
  {file,input,uri,message,event,info,account,param,debug,ad-hoc,ticket,invitation,profile,shell,avatar,pipe,pubsub,bookmarks,roster,identity,blog}
    file                File sending/receiving
    input               launch command with external input
    uri                 XMPP URI parsing/generation
    message             messages handling
    event               event management
    info                Get various pieces of information on entities
    account             XMPP account management
    param               Save/load parameters template
    debug               debugging tools
    ad-hoc              Ad-hoc commands
    ticket              tickets handling
    invitation          invitation of user(s) without XMPP account
    profile             profile commands
    shell               launch jp in shell (REPL) mode
    avatar              avatar uploading/retrieving
    pipe                stream piping through XMPP
    pubsub              PubSub nodes/items management
    bookmarks           manage bookmarks
    roster              Manage an entityʼs roster
    identity            identity management
    blog                blog/microblog management

Send a message

$ echo "Hello World" > filetest
$ jp message send recipient@example.org < filetest

or

$ echo "test  jp" | jp message send recipient@example.org

Send files

The following command allows to send the file file.txt to recipient@example.org.

$ jp file send file.txt recipient@example.org

Receive files

The following command allows to receive a file in the /tmp directory.

$ jp file receive -p agayon --path /tmp

Get information about a server

$ jp info version agayon.be
Client name: Prosody
Client version: 0.10.0
Operating System: Linux

Get disco information

Query a Server

$ jp info disco agayon.be
Features

http://jabber.org/protocol/commands
http://jabber.org/protocol/disco#info
http://jabber.org/protocol/disco#items
http://jabber.org/protocol/pubsub#auto-create
http://jabber.org/protocol/pubsub#config-node
http://jabber.org/protocol/pubsub#create-nodes
http://jabber.org/protocol/pubsub#delete-any
http://jabber.org/protocol/pubsub#delete-nodes
http://jabber.org/protocol/pubsub#groupblog
http://jabber.org/protocol/pubsub#instant-nodes
http://jabber.org/protocol/pubsub#item-ids
http://jabber.org/protocol/pubsub#meta-data
http://jabber.org/protocol/pubsub#outcast-affiliation
http://jabber.org/protocol/pubsub#persistent-items
http://jabber.org/protocol/pubsub#publish
http://jabber.org/protocol/pubsub#publish-options
http://jabber.org/protocol/pubsub#publisher-affiliation
http://jabber.org/protocol/pubsub#purge-nodes
http://jabber.org/protocol/pubsub#retract-items
http://jabber.org/protocol/pubsub#retrieve-affiliations
http://jabber.org/protocol/pubsub#retrieve-default
http://jabber.org/protocol/pubsub#retrieve-items
http://jabber.org/protocol/pubsub#retrieve-subscriptions
http://jabber.org/protocol/pubsub#subscribe
https://salut-a-toi.org/spec/pubsub_admin:0
https://salut-a-toi/protocol/schema:0
jabber:iq:auth
jabber:iq:last
jabber:iq:private
jabber:iq:roster
jabber:iq:time
jabber:iq:version
msgoffline
urn:xmpp:blocking
urn:xmpp:carbons:1
urn:xmpp:carbons:2
urn:xmpp:http:upload
urn:xmpp:http:upload:0
urn:xmpp:mam:0
urn:xmpp:order-by:0
urn:xmpp:ping
urn:xmpp:time
vcard-temp

Identities

┌───────┬──────┬─────────────────┐
│catego │ type │ name            │
├┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│store  │ file │ HTTP File Upload│
│pubsub │ pep  │ Prosody         │
│server │ im   │ Prosody         │
└───────┴──────┴─────────────────┘

Extensions

urn:xmpp:http:upload
        type: text-single
        var: max-file-size
        value: 1048576
urn:xmpp:http:upload:0
        type: text-single
        var: max-file-size
        value: 1048576

Items

┌──────────────────────┬──┬────────────────────┐
│entity                │  │ name               │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│test-pubsub.agayon.be │  │                    │
│upload.agayon.be      │  │                    │
│auth.agayon.be        │  │                    │
│proxy.agayon.be       │  │                    │
│pubsub.agayon.be      │  │                    │
│chat.agayon.be        │  │ Agayon.be chatrooms│
└──────────────────────┴──┴────────────────────┘

Query an account

$ jp info disco info@agayon.be
Items

┌───────────────┬───────────────────────────────────────────────────┬─┐
│entity         │ node                                              │ │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┤
│info@agayon.be │ eu.siacs.conversations.axolotl.bundles:1948395845 │ │
│info@agayon.be │ http://jabber.org/protocol/activity               │ │
│info@agayon.be │ http://jabber.org/protocol/mood                   │ │
│info@agayon.be │ eu.siacs.conversations.axolotl.devicelist         │ │
│info@agayon.be │ storage:bookmarks                                 │ │
└───────────────┴───────────────────────────────────────────────────┴─┘

Manage pubsub nodes

The following examples show how to manage pubsub nodes on the service pubsub.agayon.be.

Create a node

$ jp pubsub node create -s pubsub.agayon.be -n node_name

Subscribe to a node

$ jp pubsub subscribe -s pubsub.agayon.be -n node_name

Edit

The edit command allows to edit an item under a node.

$ jp pubsub edit -s pubsub.agayon.be -n node_name

The default text editor is opened. It is possible to directly edit a XML file. This command is useful for debugging purpose.

If you want to edit a post without having to edit xml directly, use jp blog edit.

As an example, you can try to edit the following xml file.

<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>author@example.com</name>
  </author>
  <generator>JP (SàT)</generator>
  <title>I am a pubsub post !</title>
  <content>This is the content of this great post.</content>
</entry>

Once the file is saved, a notification appears in Gajim. For now, the name of the post is a hash.

pubsub post on Gajim

pubsub post on Gajim

Manage your XMPP Blog

It is possible to manage a post with XMPP. It is based on PEP, a simplified version of pubsub. If your server support PEP, JP can help you to manage this blog easily.

Publish a post

First, you need to define your preferred syntax. In this example, I select markdown. This option can also be set in any other frontend (e.g. Primitivus). Whereafter you can edit a new post with the syntax jp blog edit.

$ jp param set Composition Syntax markdown -p agayon
$ jp blog edit

Your favorite editor open and you can edit your blog post with markdown syntax. When you save and close it, another file open. You can edit your settings:

{
    "allow_comments": true,
}

You can verify the accessibility of your post with the following command:

$ jp blog get 
content: 
Great test !
Make testing great again !
Yuuuuuuge publication.

It is also possible to modify your last blog post simply with jp blog edit --last-item.

Your blog post are also visible on other clients like Movim (see below) and interfaces like Livervia.

Post on movim

Use jp shell:

In order to ease debugging of services, JP comes with a shell interface. You only need to launch jp shell. You can obtain help by typing ?.

$ jp shell
cmd pubsub
pubsub> ?
Shell commands:
Documented commands (type help <topic>):
========================================
cmd    do    help  shell  use_clear  version
debug  exit  quit  use    verbose    whoami 

Action commands:
positional arguments:
  {get,delete,edit,subscribe,unsubscribe,subscriptions,node,affiliations,search,hook,uri}
    get                 get pubsub item(s)
    delete              delete an item
    edit                edit an existing or new pubsub item
    subscribe           subscribe to a node
    unsubscribe         unsubscribe from a node
    subscriptions       retrieve all subscriptions on a service
    node                node handling
    affiliations        retrieve all affiliations on a service
    search              search items corresponding to filters
    hook                trigger action on Pubsub notifications
    uri                 build URI

Select a command

> cmd pubsub
pubsub> use node urn:xmpp:microblog:0

Navigate into commands

> cmd bookmarks/list
bookmarks/list> -c
... CMD result
bookmarks/list> cmd ..
bookmarks> cmd
>

Example: List bookmarks

$  jp shell
> cmd bookmarks
bookmarks> cmd list
bookmarks/list> ?
Shell commands:
Documented commands (type help <topic>):
========================================
cmd    do    help  shell  use_clear  version
debug  exit  quit  use    verbose    whoami 

Action commands:
optional arguments:
  -h, --help            show this help message and exit
  -p PROFILE, --profile PROFILE
                        Use PROFILE profile key (default: @DEFAULT@)
  --pwd PASSWORD        Password used to connect profile, if necessary
  -c, --connect         Connect the profile before doing anything else
  -l {all,local,private,pubsub}, --location {all,local,private,pubsub}
                        storage location (default: all)
  -t {muc,url}, --type {muc,url}
                        bookmarks type (default: muc)
bookmarks/list> -t muc
private:
    Movim [movim@conference.movim.eu] (*)
    Archlinux - blah blah [archlinux-fr@chat.jabberfr.org]
    bot [bot@chat.agayon.be] (*)

Example: get disco information

> cmd info
info> use jid pubsub.agayon.be 
info> disco
Features

http://jabber.org/protocol/disco#info
http://jabber.org/protocol/disco#items
http://jabber.org/protocol/pubsub
http://jabber.org/protocol/pubsub#create-nodes
http://jabber.org/protocol/pubsub#delete-items
http://jabber.org/protocol/pubsub#delete-nodes
http://jabber.org/protocol/pubsub#instant-nodes
http://jabber.org/protocol/pubsub#item-ids
http://jabber.org/protocol/pubsub#publish
http://jabber.org/protocol/pubsub#publisher-affiliation
http://jabber.org/protocol/pubsub#purge-nodes
http://jabber.org/protocol/pubsub#retract-items
http://jabber.org/protocol/pubsub#retrieve-items
http://jabber.org/protocol/pubsub#retrieve-subscriptions
http://jabber.org/protocol/pubsub#subscribe

Identities

┌───────┬─────────┬───────────────────────┐
│catego │ type    │ name                  │
├┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│pubsub │ service │ Prosody PubSub Service│
└───────┴─────────┴───────────────────────┘

More

Some alternatives

SleekXMPP

SleekXMPP is a xmpp python library. It provide two examples of pubsub clients. The first, pubsub_client.py can manage nodes and the second one, pubsub_events.py, can manage events.

./pubsub_client.py -j jid --password=passwd pubsub.agayon.be create node_name

Gajim

Gajim is a great desktop client. It can be used to post on pubsub nodes too.

pubsub post on Gajim

Movim

Movim is a social network platform based on XMPP. It massively use pubsub to allow users to interact.

Conclusions

Salut-à-Toi is a great XMPP client. JP, its command-line interface, is a powerful tool. It can be useful to debug services, pubsub nodes and play with 'social' capacities of XMPP. It is actively developed and new features are coming. We will be soon able to make todolist or fill a bug ticket on a XMPP based system.

Links

links

social