Keycloak’s admin CLI, kcadm, is your direct line to managing Keycloak without touching the UI.
Imagine you’ve just spun up a fresh Keycloak instance and need to get users into it before any apps even know it exists. You could log into the admin console, click around, create a realm, then create users. Or, you could script it all with kcadm.
Here’s a common workflow: you need to create a new realm and add a couple of users to it.
First, ensure you have kcadm installed and can reach your Keycloak instance. It usually comes bundled with Keycloak server distribution.
To begin, you need to log in to Keycloak using kcadm. This establishes your administrative session.
kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin
This command uses the default master realm and the built-in admin user for initial authentication. If you’ve changed these, adjust accordingly. The --server flag points to your Keycloak instance’s admin endpoint.
Now, let’s create a new realm. We’ll call it my-new-realm.
kcadm.sh create realms -s realm=my-new-realm -s enabled=true -s ssl_required=none
The -s flag is crucial here; it sets attributes for the resource you’re creating. realm is the name, enabled makes it active, and ssl_required=none is a common setting for development or internal environments, though you’d want external or all for production.
With the realm created, you need to authenticate to that realm to manage its users. This is a common point of confusion: you initially log in to master to create other realms, but then you need to log in as an admin for the new realm.
kcadm.sh config credentials --server http://localhost:8080/auth --realm my-new-realm --user admin --password admin
Notice the --realm flag has changed to my-new-realm. Now, any subsequent kcadm commands will operate within the context of my-new-realm.
Let’s add a user named alice.
kcadm.sh create users -s username=alice -s enabled=true -s email=alice@example.com -s firstName=Alice -s lastName=Wonderland
Again, -s sets the user’s attributes. username, email, firstName, and lastName are standard. enabled=true makes the user account active immediately.
Now, alice exists but can’t log in because she has no password. We need to set one. This involves creating a "credential" of type "password".
kcadm.sh create users/alice/credentials -s type=password -s temporary=false -p mysecretpassword
Here, we’re targeting users/alice/credentials. -s type=password specifies the credential type, and -s temporary=false means the password won’t expire on first use. The actual password is provided as a plain argument after the flags, which is how kcadm handles secrets like passwords.
You can verify alice was created:
kcadm.sh get users -q username=alice
The -q flag allows for querying resources. This will output alice’s user representation, including her UUID.
To add another user, bob:
kcadm.sh create users -s username=bob -s enabled=true -s email=bob@example.com -s firstName=Bob -s lastName=Builder
kcadm.sh create users/bob/credentials -s type=password -s temporary=false -p bobspassword
The most surprising truth about managing Keycloak with kcadm is that every resource you interact with – realms, users, clients, roles, groups, etc. – has a specific REST API endpoint, and kcadm is simply a convenient wrapper around those endpoints. You can often infer kcadm commands by looking at the Keycloak Admin REST API documentation. For instance, creating a user maps directly to a POST request to /admin/realms/{realm}/users.
If you wanted to assign alice to a specific role within my-new-realm, you’d first need to create that role:
kcadm.sh create roles -s name=editor
Then, you’d get the role’s ID and alice’s ID and associate them.
ALICE_ID=$(kcadm.sh get users -q username=alice | jq -r '.[0].id')
ROLE_ID=$(kcadm.sh get roles -q name=editor | jq -r '.[0].id')
kcadm.sh put realms/my-new-realm/users/$ALICE_ID/role-mappings/realm -f <(echo '[{"id": "'$ROLE_ID'", "name": "editor", "composite": false, "clientRole": false}]')
This uses jq to extract IDs, which is very common when chaining kcadm commands, and a put operation to assign the role. The -f flag takes input from a file or stdin, and here we’re piping a JSON structure representing the role to be added.
The next thing you’ll likely want to manage are clients, which are applications that will authenticate users against your Keycloak realm.