xwiki-cli

This free and open-source (GPLv3+) program helps manipulate things in XWiki from the command line and your text editor. You can consult or edit pages or values in XWiki objects, list page objects and object properties, export or browse a page, and more. It also outputs to the terminal in colors to make your day less dull.

⚠ Wet paint

This alpha-quality software is not battle-tested and it is not an official XWiki tool in any kind of way. Backup your stuff. You've been warned.

That said, XWiki is a dependable piece of software that keeps a history of everything and xwiki-cli does not support deleting things for now so you should be good.

Also expect the UI (output and parameters) to change in the coming months depending on the feedback.

Supported operating systems

GNU/Linux only for now. Might work on Windows with WSL2 since it's essentially GNU/Linux in a VM with some fancy integration. Most features will probably work on BSD and macOS, though not the edition with the text editor. This uses inotify, a Linux-only API to monitor files. BSD and macOS have their API to do this but I don't use those systems. Patches are welcome.

Limitations, missing features, future developments

This section is far from comprehensive, but anyway.

Creating, deleting objects and pages

xwiki-cli cannot create or delete objects yet. It can only manipulate existing objects. If you are writing to an XML file and editing an object present on your XWiki instance but not in the XML file, saving will succeed on the instance but fail in the XML file. It is also not possible to create or delete pages. All this should be possible in the future.

Copying

Copying values or contents from an XML file to another is possible but a bit clunky and as a side effect on how the tool is designed. This should be improved in the future.

Manipulating several instances at the same time

It is not yet possible to manipulate several instances at once (for instance, to edit a page (from an extension you are working on) in an XML file and several instances or wikis you wish to test your developments). It is possible to have the page open several times with distinct xwiki-cli processes and figure something out but this is clunky as hell.

Importing, exporting

It is not possible to import or export whole pages from/to XML files and from/to an XWiki instance. One can only edit the page content object properties for now. This needs to be implemented.

Cleaning up

xwiki-cli does not currently cleans up the working files it uses for editing. This shall be fixed in the future but this needs to be carefully thought out. You might even consider it "feature, not a bug" :-) It uses a folder in /tmp so these files will be cleaned up after during a reboot.

Sets of configurations (tl;dr: use aliases!)

It would be neat to define sets of configurations / frequently used parameters that could be recalled using a name. It would be less tedious to use. Might be implemented in the future. However, it's not clear what it could achieve what a shell alias could not do, so in the meantime go define aliases in your .bashrc or .zshrc and live happy.

Deamon mode

When working on several pages, the number of xwiki-cli instances running can grow high. This is fine performance-wise, xwiki-cli is lightweight and you should barely notice it in top. This is also good stability-wise. If one instance of xwiki-cli crashes, the other ones are unaffected. Not that actually xwiki-cli crashes a lot, but still. However, it quickly becomes clunky, requiring a shell session per edited entity. You can use tmux / screen sessions to keep things somewhat tidy, but if you are messy and unorganized like yours truly, more realistically you'll just end up with a lot of Konsole tabs and end up searching your tabs.

Code editor extensions

Some integration with common text editors would be nice. Codium specifically has been mentioned. This could depend on the Deamon mode feature and maybe the sets of configurations.

Limitations not here that are good to know

It is possible to be disconnected from the internet / the XWiki instance you are using with xwiki-cli, or to edit XML files you are manipulating. xwiki-cli won't pick up changes in the XML file you are reading from (for now anyway) but it will update the XML file you are writing to just fine because it doesn't keep it open or in memory. It re-opens it each time it needs to access it.

And yes, the XML file you are reading from can be different from the XML file you are writing to, which is why the distinction is done in this documentation. See xwiki-cli -h for details.

If it confuses you, just consider them the same thing, this is what happens when you use the --xml-file or the --xml-dir option, which should cover most needs anyway.

Warning on data loss

xwiki-cli, by its nature, can have destructive effects. Though if you are careful, everything should be all right. Here are some random considerations about this.

If you are both reading from an XML file and using an XWiki instance and the value / content you are editing doesn't match, the version in the XML file will be automatically sent to the XWiki instance. This should be fine though since you can rollback from history by the nature of XWiki. The opposite way could have been choosen (the XML file you write to gets the current value from the XWiki instance) but files don't necessarily some kind of history XWiki has. Nothing could have been done about this too, but this could be very confusing.

About working with XML files:

• Always work with files checked in a SCM tool like git. Then, if xwiki-cli eats your homework, you can always revert.
• Always use git add -p or equivalent functionality that lets you check in file hunks. You want to review the changes and not let garbage in. More specifically:
  • xwiki-cli will do its best not to change your XML file indentation, but is currently unable to keep the formatting preceding the root element. It might also add a new line at the end of files. You may want to ignore the changes made there. Anyway, xar:format is your friend for this.
  • your editor might add a new line at the end of file and xwiki-cli will not do anything special regarding this at this time. This may be improved in the future but for now either be careful not to check in the new line added to stuff you edit using xwiki-cli with your text editor, or * configure your text editor not to add new lines at the end of files. This is important because it might end up with spurious empty paragraphs.
• Use xar:format before adding changes.

Suggested workflow:

• edit the file with xwiki-cli and your text editor (with automatic new lines at the end of files disabled)
• save
• mvn xar:format
• git add -p, ignoring irrelevant changes
• git checkout ConcernedFile.xml when you are sure you added everything relevant
• git commit

Usage

For the full list of features, please run:

xwiki-cli --help

Do browse somewhat quickly the help once to have an overview of what features there are. In short, you have flags that define an action and flags that say what to work on.

Several flags help you define what instance to use. The most useful ones are:

• --url URL: give the complete URL of a page (that you copy paste), and the instance as well as the page will be guessed
• -b host:port: give a short form of the instance. The port is optional. The HTTP(S) scheme will be guessed. You'll need to specify the page.

Several flags will define the page:

• --url URL: as said just before
• -p Dotted.Page.Notation: speaks for itself
• -w wikiname if you don't work in the main wiki
• -xml-file /path/to/Page.xml: if you want to read and write from an XML file, the page will be guessed by reading the file. Note that you can work offline, without an instance.

Example: edit the home page.

EDITOR=kate xwiki-cli --user myuser --pass mypass --url http://localhost:8080/xwiki/bin/view/Main/ --edit-content

(Alternatively, you can use the --editor flag instead of the EDITOR variable environment.)

Example: list objects of a page.

xwiki-cli --user myuser --pass mypass --url http://localhost:8080/xwiki/bin/view/Main/ --list-objects

 - XWiki.StyleSheetExtension/0

Example: list properties of an object.

xwiki-cli --user myuser --pass mypass --url http://localhost:8080/xwiki/bin/view/Main/ --list-properties -o XWiki.StyleSheetExtension/0

Or:

xwiki-cli --user myuser --pass mypass -B http://localhost:8080 -p Main.WebHome --list-properties -o XWiki.StyleSheetExtension/0

Or:

xwiki-cli --user myuser --pass mypass -b localhost:8080 -p Main.WebHome --list-properties -o XWiki.StyleSheetExtension/0

Main.WebHome > XWiki.StyleSheetExtension/0:

 - cache: StaticList -- Caching policy = long
 - code: TextArea -- Code =
-----------
.floatinginfobox iframe {
  border: 0;
  height: 169px;
  width: 100%;
}
-----------
 - contentType: StaticList -- Content Type = CSS
 - name: String -- Name = (empty)
 - parse: Boolean -- Parse content = (empty)
 - use: StaticList -- Use this extension = currentPage

Example: get the value of a property of an object.

xwiki-cli --user myuser --pass mypass -b localhost:8080 -p Main.WebHome -o XWiki.StyleSheetExtension/0 --get-property code

.floatinginfobox iframe {
  border: 0;
  height: 169px;
  width: 100%;
}

Example: set the value of a property of an object.

xwiki-cli --user myuser --pass mypass -b localhost:8080 -p Main.WebHome -o XWiki.StyleSheetExtension/0 --set-property name -v "My style"

Value correctly saved

xwiki-cli --user myuser --pass mypass -b localhost:8080 -p Main.WebHome -o XWiki.StyleSheetExtension/0 --get-property name

.my { cool: "style"; }

Example: edit the value of a property of an object with your text editor, and save the value when the file is modified

EDITOR=kate xwiki-cli --user myuser --pass mypass -b localhost:8080 -p Main.WebHome -o XWiki.StyleSheetExtension/0 --edit-property code

You can also specify the name of wiki:

EDITOR=kate xwiki-cli --user myuser --pass mypass -b localhost:8080 -p xwiki:Main.WebHome -o XWiki.StyleSheetExtension/0 --edit-property code

Or:

EDITOR=kate xwiki-cli --user myuser --pass mypass -b localhost:8080 -w xwiki -p Main.WebHome -o XWiki.StyleSheetExtension/0 --edit-property code

With a specified file extension (in this case, not giving an extension, xwiki-cli will decide to use a .less extension, which should make your text editor highlight CSS correctly, supposing LESS is a superset of CSS), and using --url instead of -p , -w and -b because why not:

EDITOR=kate xwiki-cli --user myuser --pass mypass --url http://localhost:8080/xwiki/bin/view/Main/ -o XWiki.StyleSheetExtension/0 --edit-property code --ext css

Example: load from and save to an XML file with --xml-file

EDITOR=kate xwiki-cli --user myuser --pass mypass --url http://localhost:8080/xwiki/bin/view/Cool/ -o XWiki.StyleSheetExtension/0 --edit-property code --ext css --xml-file ~/cool-extension/src/main/resources/Cool/WebHome.xml

Example: load from and save to an XML file, by only specifying a containing folder with --xml-dir

xwiki-cli will find the right file by itself, isn't it this cool?

EDITOR=kate xwiki-cli --user myuser --pass mypass --url http://localhost:8080/xwiki/bin/view/Cool/ -o XWiki.StyleSheetExtension/0 --edit-property code --ext css --xml-dir ~/cool-extension

Tip: Use a aliases or sourced variables to avoid putting credentials in the shell history / handle complex authentication

Using --user and --pass and authentication header directly in the command line each time is cumbersome and not great security-wise. They'd be visible on your screen and saved in your shell history. You can define an alias in your .bashrc or .zshrc that automatically sets these flags for you.

Alternatively, in zsh and probably in bash, you can declare an array and use it in the command line. You can save the array in a shell file. Here's how.

Put this in a file (like /tmp/xwikiauth.sh, in /tmp so it is not saved on disk and it gets deleted on reboot):

declare -a xwikiauth=(--digest --user myuser --pass mypass -H 'Cookie: JSESSIONID=A1BD84A124B5CF7F93C58C4FDF0CD80A; username="SJDHS_"; password="KDSSKjdshfjsf_"; rememberme="true"; validation="8976Abcad879832d"')

(you can get the Cookie HTTP header from the web developer tools of your browser; --user and --pass would be the HTTP Basic auth credentials)

Run this:

source /tmp/xwikiauth.sh

Use like this:

EDITOR=kate ./main -b some.host.example.org.invalid "${xwikiauth[@]}" -p The.Page.To.Edit --edit-content

Note: if you insist on not using a file, you can always put a space before a command. In some shells / some configuration, this makes the command "private", and it does not land in the shell history but that means you'll be copy pasting this line several times.

Compiling

Pre-requisites

xwiki-cli depends on libxml2 and libcurl. To compile it, you will need:

• the development packages of these dependencies.
• pkg-config
• a make
• a C++20 compiler like g++

It also uses inotify to monitor file modifications when editing values or pages with a text editor.

On Debian and Debian-derivatives like Ubuntu, try:

sudo apt install libxml2-dev libcurl4-openssl-dev pkg-config make g++

On openSUSE, try:

sudo zypper install libxml2-devel libcurl-devel pkg-config make g++

Other RPM-based distribution should have similar names for packages.

To check that you have the required dependencies, run:

make check-deps

Additionally, the expected output of pkg-config --libs libxml-2.0 libcurl is -lxml2 -lcurl.

Compiling

Running make should be enough. Optionally, you can set CXX to specify the C++ compiler to use. You might need to edit the Makefile for any compiler other than g++ though.

make

By default, xwiki-cli is built with debugging symbols. If you are short on space and/or would like a smaller binary:

make DEBUGFLAG=""

You can also specify extra compilation flags:

make DEBUGFLAG="" EXTRACFLAGS="-o3 -Werror"

(but please keep in mind xwiki-cli has only been tested without optimization and optimization flags don't seem to reduce the binary size so you are probably better off not enabling optimizations for now)

Installing

Running make install as root should be enough. This will install the xwiki-cli binary in /usr/local/bin. You can specify PREFIX to install elsewhere. For instance make PREFIX=$HOME install will install xwiki-cli in the bin folder of your home directory.

sudo make install

Alternatively, put xwiki-cli's bin folder in your PATH.

Uninstalling

sudo make uninstall

Don't forget to set PREFIX if you set it when installing.

Notes

By default, xwiki-cli will try to produce a desktop notification if there is an error while saving something to the wiki. For this, xwiki-cli will attempt to call notify-send, or kdialog if notify-send is not found.

This can be disabled with --disable-notifications.