Here’s a clean, up-to-date, “everything you need” CLI guide you can keep nearby. I’ll cover:
kc.sh
(the Keycloak server CLI): every top-level command, what it does, the important options, and runnable examples- How options work (file vs env vs CLI) and where to find the full option list
- The two helper CLIs you’ll use a lot:
kcadm.sh
(Admin CLI) andkcreg.sh
(Client Registration)
I’m using Keycloak 26.x syntax (matches the 26.3.x you’re running).
kc.sh — Keycloak server CLI
Where the scripts live
$KEYCLOAK_HOME/bin
contains:
kc.sh
/kc.bat
– server CLIkcadm.sh
– Admin CLIkcreg.sh
– Client Registration CLI. (Keycloak)
Top-level commands (what they do)
Command | What it’s for |
---|---|
start-dev | Quick “developer mode” server (HTTP on 8080, relaxed checks). Not for production. (Keycloak) |
start | Secure, production mode server. You supply TLS/hostname/proxy/etc. (Red Hat Docs) |
build | Pre-build the distribution with your settings/features so start --optimized is super fast. (Red Hat Docs) |
show-config | Print the effective config and where each value came from (file/env/CLI). Great for debugging. (Red Hat Docs) |
import | Import realms (JSON/Dir) into the DB. |
export | Export realms to files/dir. |
bootstrap-admin | Create or recover the initial admin user offline. (Red Hat Docs) |
help | Built-in help for any command (e.g., kc.sh start --help ). |
🔎 The complete set of runtime/build properties you can pass to
kc.sh
is on the “All configuration” page. Every property there works as:--property=value
(CLI) orKC_PROPERTY=value
(env) or inconf/keycloak.conf
. This is the canonical “no-options-missing” reference. (Keycloak)
How configuration works (and precedence)
You can configure Keycloak in three ways:
- Config file:
conf/keycloak.conf
- Environment variables:
KC_*
(e.g.,KC_DB=mariadb
) - CLI:
--db=mariadb --http-port=8180 ...
Precedence for a property is: CLI > Env > Config file. You can also point to a custom file with --config-file=/path/to/my.conf
. (Red Hat Docs)
Databases (incl. MariaDB over UNIX socket)
Key DB knobs you’ll use:
--db=<vendor>
(env:KC_DB
) –mariadb
,mysql
,postgres
,mssql
,oracle
,h2(dev only)
- Either compose the URL from parts:
--db-url-host
,--db-url-port
,--db-url-database
- Or give a full JDBC URL with
--db-url
(env:KC_DB_URL
) when you need special params (like a socket) - Credentials:
--db-username
,--db-password
(env:KC_DB_USERNAME
,KC_DB_PASSWORD
) - Pool:
--db-pool-initial-size
,--db-pool-min-size
,--db-pool-max-size
, etc.
(All properties live on “All configuration”). (Keycloak)
MariaDB via UNIX socket (what you used)
With the MariaDB JDBC driver you can connect locally using localSocket
:
export KC_DB=mariadb
export KC_DB_URL='jdbc:mariadb://localhost:3306/keycloak_db?localSocket=/opt/lampp/var/mysql/mysql.sock'
export KC_DB_USERNAME='root'
export KC_DB_PASSWORD='your-password'
bin/kc.sh start-dev
Code language: JavaScript (javascript)
localSocket
is a MariaDB Connector/J property enabling UNIX domain socket connections. (This is supported by MariaDB’s driver, not MySQL’s). (GitHub, Stack Overflow)
Tip: If you’d rather use TCP, drop
localSocket
and ensure MySQL/MariaDB is listening on127.0.0.1:3306
, then use a normal URL.
Command-by-command details & examples
1) start-dev
(developer mode)
Fastest way to run locally. HTTP only, permissive defaults.
Common options you’ll actually use here
- Port:
--http-port=8080
- Bind:
--hostname=localhost
(dev ignores strict hostname checks) - DB: same flags as
start
(see DB section)
Example (your working socket setup)
export KC_DB=mariadb
export KC_DB_URL='jdbc:mariadb://localhost:3306/keycloak_db?localSocket=/opt/lampp/var/mysql/mysql.sock'
export KC_DB_USERNAME='root'
export KC_DB_PASSWORD='your-password'
bin/kc.sh start-dev
Code language: JavaScript (javascript)
What dev mode is and how to use it: (Keycloak)
2) start
(production mode)
Secure defaults, requires proper hostname/proxy/TLS.
Popular runtime options
- HTTP/HTTPS
--http-enabled=false
(default),--https-port=8443
--https-certificate-file=/path/cert.pem
--https-certificate-key-file=/path/key.pem
--https-protocols=TLSv1.3,TLSv1.2
(enable a specific set) (Red Hat Docs)
- Hostname / proxy
--hostname=auth.example.com
--proxy=edge|reencrypt|passthrough
- Database – same as above
- Logging (level/category), metrics/health, etc. (see “All configuration”) (Keycloak)
Example (TLS on 8443 with MariaDB TCP):
bin/kc.sh start \
--hostname=auth.example.com \
--https-port=8443 \
--https-certificate-file=/etc/ssl/certs/fullchain.pem \
--https-certificate-key-file=/etc/ssl/private/privkey.pem \
--db=mariadb \
--db-username=kc_user \
--db-password=kc_secret \
--db-url-host=127.0.0.1 \
--db-url-port=3306 \
--db-url-database=keycloak_db
Code language: JavaScript (javascript)
3) build
(pre-compute + bake options)
“Bakes” build-time options so production starts much faster.
Typical uses
- Pin the DB vendor:
bin/kc.sh build --db=mariadb
- Toggle features:
--features=token-exchange,admin-fine-grained-authz
- Remove defaults:
--features-disabled=impersonation
After building, start with: bin/kc.sh start --optimized ...
(Red Hat Docs, Keycloak)
Example
bin/kc.sh build \
--db=mariadb \
--features=token-exchange \
--features-disabled=impersonation
bin/kc.sh start --optimized --hostname=auth.example.com
(Features are enabled/disabled via --features
/ --features-disabled
; see the features guide & all-config.) (Keycloak)
4) show-config
Prints the effective configuration and the source of each setting (CLI/env/file). Super useful when a value isn’t sticking.
bin/kc.sh show-config
Troubleshooting hint from RH docs (also: kc.sh --verbose start
for full stacktraces). (Red Hat Docs)
5) import
Load realms from JSON/dir into your DB.
- Common flags (run
--help
for your exact build):--file=/path/realm.json
or--dir=/path/realms/
--realm=myrealm
(limit import to one realm inside the file/dir)- There may be options for strategy/overwrite depending on version.
The official guide shows examples and theimport
command.
Example
bin/kc.sh import --dir=/opt/keycloak/imports
Code language: JavaScript (javascript)
Note:
import
may not support--verbose
; use logs +--help
. (GitHub)
6) export
Dump realms to files (good for backups/migrations).
Examples (see guide for usage):
# export all realms to a directory
bin/kc.sh export --dir=/var/backups/keycloak-realms
# export a single realm to file
bin/kc.sh export --realm=myrealm --file=/var/backups/myrealm.json
Code language: PHP (php)
(Export/import commands are described alongside start/build in the CLI guide page.)
7) bootstrap-admin
Create/recover the admin account offline. Handy if you didn’t set KC_BOOTSTRAP_ADMIN_USERNAME/PASSWORD
before first start, or you lost admin access.
bin/kc.sh bootstrap-admin --user admin --password 'Str0ngP@ss!'
Code language: JavaScript (javascript)
Full details & recovery flow: (Red Hat Docs)
A few more useful knobs (by category)
For a complete, authoritative list, use the All configuration page (every property there works as CLI/env/file). I’m just surfacing common ones here. (Keycloak)
- HTTP/HTTPS:
--http-enabled
,--http-port
,--https-port
,--https-certificate-file
,--https-certificate-key-file
,--https-trust-store
,--https-protocols
(TLS versions) (Red Hat Docs) - Hostname / proxy:
--hostname
,--proxy
- Logging:
--log-level=INFO|DEBUG|TRACE
,--log
category options - Health/metrics:
--health-enabled=true
,--metrics-enabled=true
- Feature toggles:
--features=...
,--features-disabled=...
(Keycloak) - Config file/keystore:
--config-file
,--config-keystore
,--config-keystore-password
,--config-keystore-type
(PKCS12/JCEKS) (Red Hat Docs)
Admin CLI (kcadm.sh
) – quick cookbook
Use it to automate anything you can do in the Admin Console (it talks to the Admin REST API). Docs & examples: Server Admin Guide + Admin CLI docs. (Keycloak, wjw465150.gitbooks.io)
Log in (create a session)
bin/kcadm.sh config credentials \
--server http://localhost:8080 \
--realm master \
--user admin
# prompts for password
Code language: PHP (php)
Realm CRUD
# create a realm from JSON
bin/kcadm.sh create realms -f realm.json
# list realms
bin/kcadm.sh get realms
Code language: PHP (php)
Users
# create a user
bin/kcadm.sh create users -r myrealm -s username=alice -s enabled=true
# set a password
USER_ID=$(bin/kcadm.sh get users -r myrealm -q username=alice --fields id | jq -r '.[0].id')
bin/kcadm.sh set-password -r myrealm --userid "$USER_ID" --new-password 'Sup3rSecret!'
Code language: PHP (php)
Clients
# create a client
bin/kcadm.sh create clients -r myrealm \
-s clientId=my-app \
-s publicClient=false \
-s protocol=openid-connect \
-s 'redirectUris=["https://app.example.com/*"]'
# get client details
bin/kcadm.sh get clients -r myrealm -q clientId=my-app
Code language: PHP (php)
(There are many resources: realms, users, groups, roles, clients, idps… kcadm.sh help
shows usage; the REST model matches the Admin REST API.) (Keycloak)
Client Registration CLI (kcreg.sh
) – quick cookbook
Use it to self-register clients via the Client Registration endpoints. Great for CI when apps need to provision themselves. Docs & patterns: client registration guide. (Keycloak)
Configure credentials once
bin/kcreg.sh config credentials \
--server http://localhost:8080 \
--realm myrealm \
--user admin
# prompts for password
Code language: PHP (php)
Create a client
bin/kcreg.sh create \
-s clientId=my_client \
-s publicClient=false \
-s 'redirectUris=["https://app.example.com/*"]'
Code language: JavaScript (javascript)
Read / update / delete
bin/kcreg.sh get my_client
bin/kcreg.sh get my_client > my_client.json
jq '.standardFlowEnabled=true' my_client.json > my_client2.json
bin/kcreg.sh update my_client -f my_client2.json
bin/kcreg.sh delete my_client
Code language: JavaScript (javascript)
(You can also output -e install
to generate adapter config.) (Keycloak)
A few “put-it-all-together” scenarios
A) Your LAMPP/MariaDB (UNIX socket) dev setup
export KC_DB=mariadb
export KC_DB_URL='jdbc:mariadb://localhost:3306/keycloak_db?localSocket=/opt/lampp/var/mysql/mysql.sock'
export KC_DB_USERNAME='root'
export KC_DB_PASSWORD='your-password'
bin/kc.sh start-dev
Code language: JavaScript (javascript)
(Uses MariaDB Connector/J’s localSocket
property). (GitHub)
B) Build once, start optimized in prod
# one-time build
bin/kc.sh build --db=mariadb --features=token-exchange
# fast starts afterwards
bin/kc.sh start --optimized \
--hostname=auth.example.com \
--https-port=8443 \
--https-certificate-file=/etc/ssl/certs/fullchain.pem \
--https-certificate-key-file=/etc/ssl/private/privkey.pem
Code language: PHP (php)
C) Export / Import realms
# export everything
bin/kc.sh export --dir=/var/backups/kc-$(date +%F)
# import later (e.g., into a new server)
bin/kc.sh import --dir=/var/backups/kc-2025-08-22
Code language: PHP (php)
Where to find every single option
- All configuration — authoritative list of every property/flag (runtime & build). If it’s not on this page, it doesn’t exist. Use it as your “complete options” reference. (Keycloak)
- Configuring Keycloak — how config sources & formats work; examples of
--config-file
, keystores, etc. (Keycloak, Red Hat Docs) - Enabling/disabling features — how
--features
/--features-disabled
behave and examples. (Keycloak) - Start from the command line — shows the
start
,start-dev
,build
,show-config
,import
,export
,help
commands in one place. - Bootstrap admin — creating/recovering the admin account. (Red Hat Docs)
I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.
Do you want to learn Quantum Computing?
Please find my social handles as below;
Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND