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 Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.