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) and kcreg.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 CLI
• kcadm.sh – Admin CLI
• kcreg.sh – Client Registration CLI. (Keycloak)

Top-level commands (what they do)

🔎 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) or KC_PROPERTY=value (env) or in conf/keycloak.conf. This is the canonical “no-options-missing” reference. (Keycloak)

How configuration works (and precedence)

You can configure Keycloak in three ways:

1. Config file: conf/keycloak.conf
2. Environment variables: KC_* (e.g., KC_DB=mariadb)
3. 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 on 127.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 the import 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)

(Red Hat Docs, Keycloak)

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)

Rajesh Kumar

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

Rajesh Kumar DailyLogs