04 Nov 2015

The new Apache Syncope CLI client

Written by massi

If you are following the Apache Syncope dev mailing list you have seen different commits for the CLI admin tool. In this post we will discuss what the new client does and which are the most useful features (of course from my point of view).

What is exactly a CLI tool?

As the Wikipedia page suggests a command line interface (CLI) is a means of interacting with a computer program where the user (or client) issues commands to the program in the form of successive lines of text (command lines). In our case the CLI tool is the way to call, more or less, every Syncope core commands through a shell.

Maybe could be better show some examples rather than speak about it.


Before starting with examples some information about the client and this post:

  • I will show you only the most attractive (IMHO) features of the client;
  • it is a SNAPSHOT client release, so there will be other improvements until the 2.0 version is released;
  • for the moment the client is yet executed with java -jar command;
  • the below examples is based on a Syncope debug installation.


The installation process is very simple and it starts running the command:

java -jar target/syncope-client-cli-2.0.0-SNAPSHOT.jar install --setup


When the installation is completed you can find the cli.properties file under the Syncope conf directory; the file contains the URL of the Syncope rest services and the admin credentials to call the services:

  • syncope.rest.services=http://localhost:9080/syncope/rest
  • syncope.admin.user=admin
  • syncope.admin.password=ZNmH7WWjEI4+TlDLNI+1e6cnDziKu458

As you can read the password is stored with a reversible encryption to be not read by other users.

Logger service

Before showing the most useful command options of the logger service I want to show you an option implemented by each service: --list. When you run a command with this option the client print all the objects of the called command, then running --list on logger command the output will be the list of the configured logger:

java -jar target/syncope-client-cli-2.0.0-SNAPSHOT.jar logger --list

Another option of the logger command is the possibility to change each logger in a particular configuration running a single command. It is very useful in the production environment when we need to have a DEBUG configuration. To achieve this configuration we have to run

java -jar target/syncope-client-cli-2.0.0-SNAPSHOT.jar logger --update-all DEBUG

As you can read the result will be a table with the new loggers configuration.

User service

The user command, as you can imagine, is one of the most useful command of the client. It is able to:

Basically you can search the users in different ways, read or delete one or more of them and, as you can do with most of the other commands, you can run the --details option to get some useful information about the amount of users managed.

Entitlement service

Another very useful command is the entitlement one. This because using this command you can know the information about the entitlement assigned to the user. For instance running the command

java -jar target/syncope-client-cli-2.0.0-SNAPSHOT.jar entitlement --read-by-userid 1

where 1 is the user id, we get the entitlements of that user:


Or we could get the roles with a particular entitlement running

java -jar target/syncope-client-cli-2.0.0-SNAPSHOT.jar entitlement --list-role GROUP_READ

General info

Of course I can't explain with a single post each command. For this purpose there will be the documentation. But in general the idea was to develop a client able to help you to work with Syncope when the GUI console is unreachable or when you are working remotely or, as in my case, when you prefer a CLI client to a GUI one.

Implemented services


« Return