CLI Commands

import { Aside } from ‘@astrojs/starlight/components’;

Kotauth includes a set of CLI subcommands accessible via java -jar kauth.jar cli <command>. These tools handle operations that should not require a running HTTP server or browser session — key generation, emergency account recovery, tenant backup/restore, etc.

Usage

java -jar kauth.jar cli <command> [options]

When running with Docker Compose, use docker compose exec:

docker compose exec kauth java -jar kauth.jar cli <command> [options]

Or with the Makefile shortcuts:

make generate-key
make reset-mfa USER=admin

---

generate-secret-key

Generates a cryptographically secure 32-byte hex string suitable for KAUTH_SECRET_KEY.

java -jar kauth.jar cli generate-secret-key

Output:

a1b2c3d4e5f6...  # 64-character hex string

This command is pure cryptography — it does not connect to the database or require any environment variables. Use it to provision a new key before first startup or when rotating an existing key.

You can also generate a key with `openssl rand -hex 32`, but the built-in command ensures the output meets Kotauth's requirements.

---

reset-admin-mfa

Resets MFA enrollment for a user on the master tenant. This is the recovery path when an admin loses access to their authenticator app and all recovery codes.

java -jar kauth.jar cli reset-admin-mfa --username=admin

This command connects to the database directly (using DB_* environment variables) without running Flyway migrations or starting the HTTP server. It removes the TOTP secret and recovery codes for the specified user, forcing re-enrollment on the next login.

Option	Required	Description
--username	Yes	The username of the admin account to reset

This command requires database connectivity. The `DB_URL` (or `DB_HOST` / `DB_PORT` / `DB_NAME`), `DB_USER`, and `DB_PASSWORD` environment variables must be set.

Only accounts on the master tenant can be reset via CLI. To reset MFA for users on other workspaces, use the admin console.

---

export-tenant

Exports a workspace as an encrypted archive file. The archive uses the bkp1 envelope format with PBKDF2 (600,000 iterations) key derivation and AES-256-GCM encryption.

java -jar kauth.jar cli export-tenant \
  --slug=my-workspace \
  --output=/backups/my-workspace.bkp1 \
  --passphrase="your-strong-passphrase"

Option	Required	Description
--slug	Yes	Workspace slug to export
--output	Yes	Output file path
--passphrase	Yes	Encryption passphrase

The archive contains all tenant data: users, roles, groups, applications, sessions, audit logs, attributes, claim mappers, and settings.

This command requires database connectivity. The `DB_URL` (or `DB_HOST` / `DB_PORT` / `DB_NAME`), `DB_USER`, and `DB_PASSWORD` environment variables must be set.

---

import-tenant

Imports a workspace from an encrypted archive file. Validates schema-version compatibility before applying any data.

java -jar kauth.jar cli import-tenant \
  --input=/backups/my-workspace.bkp1 \
  --passphrase="your-strong-passphrase"

Option	Required	Description
--input	Yes	Archive file path
--passphrase	Yes	Decryption passphrase

Importing a tenant with a slug that already exists will fail. Delete or rename the existing workspace first.

This command requires database connectivity. The `DB_URL` (or `DB_HOST` / `DB_PORT` / `DB_NAME`), `DB_USER`, and `DB_PASSWORD` environment variables must be set.

See Backup & Restore for full documentation on the archive format, API endpoints, and schema compatibility.