Metadata-Version: 2.3
Name: keycloak-util
Version: 0.1.1
Summary: CLI tool for managing multiple Keycloak configurations and generating tokens
License: GPL-3.0-or-later
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: httpx (>=0.27.0,<1)
Requires-Dist: pydantic (>=2.6.0,<3)
Requires-Dist: pyjwt (>=2.8.0,<3)
Requires-Dist: pyperclip (>=1.8.0,<2)
Requires-Dist: pyyaml (>=6.0.1,<7)
Requires-Dist: questionary (>=2.0.1,<3)
Requires-Dist: rich (>=13.7.0,<14)
Requires-Dist: typer (>=0.12.0)
Description-Content-Type: text/markdown

# keycloak-cli

CLI tool for managing multiple Keycloak configurations and generating tokens.

## Install

```bash
poetry install
```

## Usage

```bash
kc --help
```

### Quick Start

```bash
# Initialize your first Keycloak configuration
kc init

# Check server status
kc status

# Generate a token for a client
kc token get
```

## Commands

### `kc init`

Interactive setup wizard to create a Keycloak configuration. Prompts for organization, environment, server URL, realm, and admin credentials. Tests the connection before saving.

### `kc config` — Configuration Management

Manage stored Keycloak server configurations (org/env pairs).

| Command            | Description                          |
| ------------------ | ------------------------------------ |
| `kc config list`   | List all configurations              |
| `kc config add`    | Add a new configuration              |
| `kc config show`   | Show details of a specific config    |
| `kc config use`    | Switch the default configuration     |
| `kc config update` | Update config properties             |
| `kc config remove` | Delete a configuration               |

```bash
# List configs as table or JSON
kc config list --output json

# Switch default config
kc config use myorg/production
```

### `kc token` — Token Management

Generate, cache, decode, and verify JWT access tokens.

| Command             | Description                              |
| ------------------- | ---------------------------------------- |
| `kc token get`      | Get token (from cache or generate new)   |
| `kc token generate` | Always generate a fresh token            |
| `kc token decode`   | Decode and inspect a JWT token           |
| `kc token verify`   | Check if a token is still valid          |

```bash
# Get a token (uses cache if valid)
kc token get my-client

# Generate fresh token and copy to clipboard
kc token generate my-client --copy

# Output as Authorization header
kc token get my-client --as-header

# Decode a token from stdin
echo $TOKEN | kc token decode -
```

### `kc client` — Client Management

Manage Keycloak clients via the Admin API.

| Command             | Description                        |
| ------------------- | ---------------------------------- |
| `kc client list`    | List all clients in the realm      |
| `kc client show`    | Show detailed client configuration |
| `kc client create`  | Create a new client                |
| `kc client update`  | Update client properties           |
| `kc client secret`  | Get or regenerate client secret    |

```bash
# List clients (excludes internal clients by default)
kc client list

# Include internal clients
kc client list --all

# Search clients
kc client list --search my-app

# Create a client with service account
kc client create my-app --service-account --description "My application"

# Update client interactively
kc client update my-app

# Update client with flags
kc client update my-app --ttl 3600 --description "Updated"

# Regenerate client secret
kc client secret my-app --regenerate
```

### `kc status`

Dashboard overview showing all configured servers, their health status, and which config is active.

### `kc health`

Run health checks against a Keycloak server: connectivity, realm existence, token endpoint, and admin authentication.

```bash
# Check current config
kc health

# Check all configs
kc health --all
```

### `kc history`

View recent CLI command history.

```bash
kc history
kc history --limit 50
kc history --clear
```

## Global Options

| Option          | Description          |
| --------------- | -------------------- |
| `--version`/`-V` | Show version and exit |
| `--config`/`-c` | Specify config key (org/env) for most commands |

## Configuration

Configurations are stored at `~/.keycloak-cli/config.yaml`. Each configuration is identified by an org/env pair (e.g., `myorg/staging`).

Token cache is stored at `~/.keycloak-cli/cache/tokens/`.

## License

GPL-3.0-or-later
