kcadm-cli-wrapper

Stateless CLI wrapper for Keycloak administration via Docker.

Runs the official kcadm.sh tool in a temporary Docker container with pre-configured authentication — no Java install, no saved sessions, no MFA prompts. Every command is self-contained and idempotent.

Why This Exists

Managing Keycloak from the command line typically requires:

• Installing Java and downloading the Keycloak server distribution
• Authenticating with a username/password (blocked by MFA/TOTP)
• Managing session config files that persist across commands

This wrapper solves all three:

Problem	Solution
Java dependency	Runs kcadm.sh inside a Docker container — no local Java
MFA blocks automation	Authenticates via client credentials (service account), not user/password
Session state management	Stateless — auth args passed on every command, no saved config

Quick Start

# 1. Set your client secret (once)
export KEYCLOAK_CLIENT_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 2. Make the script executable
chmod +x kcadm_cli.sh

# 3. Use it like kcadm.sh
./kcadm_cli.sh get realms --fields realm
./kcadm_cli.sh create realms -s realm=my-realm -s enabled=true
./kcadm_cli.sh get organizations -r pos-production

Prerequisites

• Docker installed and running
• Service account client in Keycloak's master realm with realm-admin role
• The client secret exported as KEYCLOAK_CLIENT_SECRET

See GUIDE.md for setup instructions and detailed usage.

What's Inside

File	Purpose
kcadm_cli.sh	The wrapper script — drop it anywhere, chmod +x, use
GUIDE.md	Detailed guide: what/why/how/when for realms, organizations, users, roles
ACCESS-CONTROL.md	Implementation guide: enforce org + role access in TypeScript, Python, Go, Rust, React
examples/onboard-company.sh	End-to-end customer onboarding (org + user + role assignment)
examples/create-roles.sh	Batch-create client roles for POS and Accounting systems