Administer Keycloak server from shell with Admin CLI

A few months ago we introduced Client Registration CLI - a tool for registering new clients with Keycloak server in a self-service manner.

With release 2.5.0 we now also have Admin CLI - a general purpose administration tool that an admin can use to perform a full set of actions over Admin REST API without having to use a web based Admin Console.

This tool should come especially handy in combination with shell scripts or tools like Ansible or Docker, where before one would have to resort to using curl or wget in a much more cumbersome way.

You can find Admin CLI execution scripts in KEYCLOAK/bin directory - there's kcadm.sh for Bash, and kcadm.bat for Windows CMD.

Running the tool without any parameters will greet you with some help to get you started.

$ kcadm.sh

Typical usage begins with authentication step where user or client credentials are provided.

$ kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin

Session is maintained by saving an access token into a configuration file - by default it is at ~/.keycloak/kcadm.config.

You can also pass authentication parameters to any other commands together with --no-config option, which will skip using a config file altogether - authentication, access token retrieval, and operation invocation will all be part of a single command execution after which the token will simply be forgotten.

Assuming we've authenticated using a configuration file we can then perform operations against Admin REST endpoints. For example, you may want to create a new realm with roles, clients, some users, then reset a user's password, and set up events logging.

Create a new realm

$ kcadm.sh create realms -s realm=demo -s enabled=true

Create new realm roles

$ kcadm.sh create roles -r demo -s name=admin
$ kcadm.sh create roles -r demo -s name=user

Create a new public client

$ kcadm.sh create clients -r demo -s clientId=myapp -s publicClient=true -s 'redirectUris=["http://localhost:8980/myapp/*"]' -o

Create a new user

$ SUPER_ID=`kcadm.sh create users -r demo -s username=super -i`

Add client role to a user

$ kcadm.sh add-roles -r demo --uusername super --cclientid realm-management --rolename realm-admin

Add realm roles to a user

$ kcadm.sh add-roles -r demo --uusername super --rolename admin --rolename user

Update a user

$ kcadm.sh update users/$SUPER_ID -r demo -s enabled=true

Change user's password

$ kcadm.sh set-password -r demo --username super --new-password password


We can now login as a newly created user so we don't have to continually specify the target realm:

$ kcadm.sh config credentials --server http://localhost:8080/auth --realm demo --user super --password password

Get existing users

$ kcadm.sh get users --limit 20

Get existing clients

$ kcadm.sh get clients --fields id,clientId,publicClient,redirectUris

Setup login events logging

$ kcadm.sh update events/config -s eventsEnabled=true

Get last twenty login events

$ kcadm.sh get events --offset 0 --limit 100


As you may have guessed by now Admin CLI is pretty generic. You specify a command followed by a target endpoint URI which will be resolved relative to Admin REST API root, and current realm as specified with --realm option during authentication. It also takes target realm override into account which you specify with -r option. This way any Admin REST API endpoint can be reached. Content to send is specified by using -s option - specified attributes become part of a JSON document sent to a target URI.


You can find a more comprehensive list of recipes for specific tasks in Admin CLI chapter of a Server Administration Guide.


Give Admin CLI a try, and let us know how it works for you.