pubsub: PubSub management

PubSub commands are low level command to handle a PubSub Service. They are using the generic pubsub arguments

For most of those commands, pubsub commands are used to specify the destination item.


Publish a pubsub item.

stdin is used to get the raw XML of the payload of the item to publish.

-f KEY VALUE, --field KEY VALUE can be used to specify publish options, i.e. option which must be set if the node already exists, or used if the node is to be created, see XEP-0060 §7.1.5 for details.

In the same way as for create, -F, --full-prefix can be used if you need to specify the full option name.


Create an item with a custom note XML:

$ echo '<note xmlns="">this is a note</note>' | li pubsub set -n "notes"


Retrieve items from specified node. Default output is prettified and highlighted XML.


Retrieve the last 5 notes from our custom notes node:

$ li pubsub get -n notes -m 5


Delete an item from a node. If -N, --notify is specified, subscribers will be notified of the item retraction.

By default a confirmation is requested before deletion is requested to the PubSub service, but you can override this behaviour by using -f, --force option.


Delete item with id 123456 from a node:

$ li pubsub delete -n test_node -i 123456


Edit the raw XML of an item payload using your local editor (the one set in $EDITOR).

If you don’t change anything or publish an empty blog post, the edition will be cancelled.

draft commands can be used.


Edit the last note in our custom node:

$ li pubsub edit -n notes -L


Move a item to a new ID. As there is currently no “rename” or “move” operation in XMPP PubSub, this is done by republishing the item with the new ID, then deleting the old item if the publication succeed.

This is notably useful when user friendly URL based on ID are used, and one need to fix a typo or something else.


Rename a PubSub item with ID 123 to 456:

$ li pubsub rename -n some_node -i 123 456


Subscribe to a node.

Subscription is used to get notifications from the node in case of new/updated item or deletion.


Subscribe to an information blog:

$ li pubsub subscribe -n informations -s


Unsubscribe from a node.


Unsubscribe from an information blog:

$ li pubsub unsubscribe -n informations -s


Retrieve subscriptions for all nodes on a service.

-n NODE, --node NODE can be used to request subscriptions for a specific node (e.g. if it has subscription with multiple subIDs).


Retrieve all subscriptions on a pubsub service:

$ li pubsub subscriptions -s


Retrieve affiliations for all nodes at a service.

-n NODE, --node NODE can be used to request affiliation for a specific node.


Retrieve all affiliations at a pubsub service:

$ li pubsub affiliations -s

Retrieve affiliation for the notes node:

$ li pubsub affiliations -s -n notes


Modify items using an external command.

transform will retrieve requested items, and will send each of them to the standard input (stdin) of the specified command. The output of the command will be used, it can be 3 things:

  • a raw XML of the modified item, in which case the item will be republished

  • the string SKIP, in which case the item will be ignored

  • the string DELETE, in which case the item will be retracted

By default a dry run is done, which means that no item is modified or deleted. To actually do the transformation, you have to use --apply argument.

If you have to modify the publisher of an item, you need specific privileges. The --admin allows you do to that, but it must be supported by your PubSub service (currently only Libervia PubSub supports this non standard feature).

To modify all items of a node, use the -A, --all option. This will use RSM repetitively until all items are treated. Of course that means that your PubSub service must support RSM. The items being republished, they will reappear on top of your node, that’s why it is recommended to use --order-by creation option when supported by the service, to keep consistent order and avoid transforming the same items several times.

If the command you’re using exit with a non zero code, the process will stop. Use -I, --ignore_errors if you want to continue transformation even if an non zero code is returned.


Imagine that you want to replace all occurrences of “sàt” by “Libervia” in your personal blog. You first create a Python script like this:

#!/usr/bin/env python3

import sys
item_raw =
if not "sàt" in item_raw:
    print(item_raw.replace("sàt", "Libervia"))

And save it a some location, e.g. ~/ (don’t forget to make it executable with chmod +x ~/

To be sure it’s safe, you can first do a dry-run and check the result:

$ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation ~/

Once you have checked that you have the expected behaviour, you can apply the transformations:

$ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation --apply ~/

And that’s it. You can use the same technique for more complex transformations, including modifying the XML (with Python, you can easily do that with standard xml.etree.ElementTree module or with lxml.etree).


Build an XMPP URI linking to a PubSub node or item.


Build a link to personal blog:

$ li pubsub uri -n urn:xmpp:microblog:0


Subcommands for node management. Please check pubsub/node: PubSub nodes management.


Subcommands for hooks management. Please check pubsub/hook: PubSub hooks management.