CLI overview

Every command has the form monedula-acl-rbac <command> [flags]; each command page lists its flags and exit codes. The reference describes version 0.10.0.

Commands

Command	Purpose	Changes external state
extract	Read ACLs from one of nine sources into a canonical acls.json.	No
plan	Turn acls.json into plan.json and report.txt. --revalidate re-checksums an edited plan.	No
report	Print the report of a plan.json again, as text, Markdown or JSON.	No
apply	Create the plan’s role bindings in MDS. --dry-run previews the calls.	Yes
verify	Check in MDS that each source ACL’s access is granted.	No
delete-acls	Write the script that deletes the converted Allow ACLs, and its rollback script.	Writes a script you run
delete-deny-acls	Write the script that removes DENY ACLs after a live re-check, and its rollback script.	Writes a script you run
emit	Render a plan as a Confluent CLI script, CFK manifests or MDS curl commands.	No
convert	Extract, plan and emit from a file in one call, without a run directory.	No
discover	Query MDS for cluster IDs and print a scopes.yaml stub.	No
init	Write a starter scopes.yaml and rules.yaml into a directory.	No
status	Summarize the state of a run directory.	No
diff	Compare two acls.json or two plan.json files.	No
mds list-bindings	List the role bindings MDS holds for given principals.	No
auth login	Log in to MDS interactively and cache the token.	No; writes a local token cache
rules show	Print the built-in mapping rules.	No
completion bash, zsh, fish, powershell	Generate the completion script for that shell.	No

monedula-acl-rbac --version prints the version, the commit and the build date.

The run directory

The migration commands read and write their artifacts in a run directory. A command picks it in this order:

1. --run-dir.
2. The parent directory of --out.
3. The directory of the input artifact, such as --plan for apply or --acls for plan.
4. The environment variable MONEDULA_ACL_RBAC_RUN_DIR.
5. A new runs/<UTC timestamp>/ in the current directory, such as runs/2026-05-21T10-00-00Z/, with a -2, -3 and so on suffix if that name exists.

The directory is created with mode 0700. Its files:

File	Written by	Contents
acls.json	extract	The canonical ACL snapshot.
extract.log, extract-source.json	extract	How and from where the ACLs were read.
existing-bindings.json	extract --from cfk or k8s	Role bindings that already exist, which plan marks SKIP_EXISTS.
plan.json, plan.json.sha256	plan	The plan and its checksum.
report.txt	plan	The readable report of the plan.
would-apply.log	apply --dry-run	Every call apply would make, with request bodies.
apply.log	apply	Every MDS call and its result.
.lock	apply	The lock held while apply runs.
verify.json	verify	The result of every check, stamped with the plan’s SHA-256.
delete-acls.sh, deleted-acls.json, rollback.sh	delete-acls	The deletion script, the ACLs it removes and the script that recreates them.
delete.log	delete-acls.sh	One OK or FAIL line per ACL.
delete-deny-acls.sh, deleted-deny-acls.json, rollback-deny.sh	delete-deny-acls	The DENY deletion script, its ACLs and its rollback script.
runtime.env	delete-deny-acls	Connection settings, credential references and a per-run token for the DENY script; mode 0600, deleted when the script exits.
delete-deny.log	delete-deny-acls.sh	One OK, SKIP or FAIL line per DENY ACL.

Global flags

Two flags work on every command:

• --log-format: text (default) or json, for piping structured logs into a CI or observability stack.
• --log-level: debug, info (default), warn or error.

Diagnostic logs go to stderr. The audit files in the run directory, such as apply.log and verify.json, keep their own line formats whatever --log-format says.

MDS connection flags

apply, verify, discover and mds list-bindings connect to MDS with these flags, and delete-deny-acls passes them on to the script it generates. auth login takes the URL and TLS flags only.

• --mds-url: the MDS base URL. Required.
• --mds-token-file: a file with a pre-fetched bearer token.
• --mds-user and --mds-password-file: a user name and a file with its password, exchanged for a token.
• --cache-token: store the resolved token in the user configuration directory, under monedula-acl-rbac/tokens/, for later commands.
• --mds-ca-cert, --mds-client-cert, --mds-client-key: a PEM CA bundle, and a client certificate and key for mutual TLS.
• --mds-insecure-skip-verify: skip certificate verification, with a warning on every run. For development clusters only.
• --mds-max-retries: retries of transient failures after the first call, 3 by default; 0 turns them off.

Credentials resolve in this order: the token file, then the user name and password, then a token cached by auth login or --cache-token for the same URL and operating-system user. delete-deny-acls does not accept a cached token alone, because its script authenticates later, without you.

Kafka connection flags

extract --from live connects to Kafka with these flags, and delete-acls and delete-deny-acls write them into the scripts they generate:

• --bootstrap-server, or its alias --bootstrap: the bootstrap servers, comma-separated.
• --command-config: a Kafka client properties file, as for kafka-acls.sh, with the TLS and SASL settings.

Environment variables

Variable	Effect
MONEDULA_ACL_RBAC_LOG_FORMAT, MONEDULA_ACL_RBAC_LOG_LEVEL	Defaults for --log-format and --log-level.
MONEDULA_ACL_RBAC_MDS_URL	Default for --mds-url.
MONEDULA_ACL_RBAC_MDS_TOKEN_FILE	Default for --mds-token-file.
MONEDULA_ACL_RBAC_MDS_USER, MONEDULA_ACL_RBAC_MDS_PASSWORD_FILE	Defaults for --mds-user and --mds-password-file.
MONEDULA_ACL_RBAC_MDS_CA_CERT, MONEDULA_ACL_RBAC_MDS_CLIENT_CERT, MONEDULA_ACL_RBAC_MDS_CLIENT_KEY	Defaults for the MDS TLS flags.
MONEDULA_ACL_RBAC_MDS_INSECURE_SKIP_VERIFY	1, true or yes turns on --mds-insecure-skip-verify.
MONEDULA_ACL_RBAC_MDS_MAX_RETRIES	Default for --mds-max-retries.
MONEDULA_ACL_RBAC_RUN_DIR	The run directory when no flag or input artifact names one.
MONEDULA_SKIP_PLAN_HASH_CHECK	1 makes the generated deletion scripts skip their plan.json hash check, for a script run away from its run directory.
MONEDULA_KAFKA_ACLS_BIN	The Kafka ACL tool that the DENY deletion script calls, kafka-acls by default.

Output formats

Commands that print a structured summary take --format:

Command	--format values	Default
apply	text, json	text
verify	text, json	text
diff	text, json	text
mds list-bindings	text, json, yaml	text
report	text, json, markdown	text
status	text, json	text
emit	script, cfk, mds-curl	script
convert	script, cfk, mds-curl	script

For emit and convert, --format picks the shape of the artifact rather than the encoding of a summary. plan, extract, delete-acls, delete-deny-acls, discover, init, auth login and rules show produce a single artifact and have no --format. No command writes CSV.

The JSON documents carry schema_version: "1" and are described by JSON Schemas:

Document	Schema reference
acls.json	acls.v1.json
plan.json	plan.v1.json
apply --format json	apply-summary.v1.json
verify --format json and verify.json	verify-summary.v1.json
status --format json	status.v1.json
report --format json	report.v1.json

The JSON output of diff and mds list-bindings carries schema_version: "1" as well, without a published schema.

Exit codes

Code	Meaning
0	Success. For verify, every result is OK.
1	Usage error: a missing required flag, a malformed argument, an unknown command or flag, a missing acknowledgement flag such as --i-understand-this-is-destructive, or a confirmation that was refused or impossible without --confirm outside a terminal.
2	Input error: a malformed or unreadable input file, such as the acls.json, scopes.yaml, rules.yaml or principals.yaml that plan reads, the vars.yaml of extract --from script, the plan.json that report or emit reads, or a verify.json that is malformed or was made for a different plan.
3	The plan has unmapped or rejected ACLs: plan without --allow-unmapped or --allow-rejected, and report --strict.
4	External system error: MDS unreachable or refusing the credentials, Kafka unreachable or failing authentication, or the Kubernetes API unreachable or denying access. Errors the CLI does not classify also exit 4.
5	A guardrail refused or reports an unhealthy state: a plan.json that no longer matches its checksum, verify with any missing or unknown result, or init refusing to overwrite a file.

Because unclassified errors fall back to 4, some refusals exit 4 rather than 5:

• apply when the run directory’s lock is held, or stale and not cleared with --force-unlock.
• delete-acls when no ACL is eligible for deletion, or when acls.json changed since planning.
• delete-deny-acls when any verify result is not confirmed, or when no DENY ACL is eligible, which includes every wildcard-principal DENY.

For the same reason, some commands report an unreadable or invalid input file with 4 rather than 2, for example convert and diff.

The generated deletion scripts exit 5 when plan.json changed since generation or cannot be hashed, and the DENY script also when runtime.env is missing or not mode 0600. Each command page lists the exact codes of that command.