Prepare Secret

Creates or inspects the Witboost secret as a JSON file ready to upload to a secret backend compatible with External Secrets Operator (e.g. HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GitLab Variables).

Prerequisites

• init: a valid license bundle must have been provided by the Witboost team.
• update --update-license: a valid license bundle is required — either passed inline as a base64-encoded string or entered interactively when prompted.
• update / validate: the existing secret JSON file must be available.

Usage

witboost-infra prepare-secret <subcommand> [options]

Subcommand	Argument	Description
init	—	Interactively generate a new secret JSON file from scratch
update	<file>	Load an existing secret JSON file and apply key mutations
validate	<file>	Validate an existing secret JSON file

init Options

Option	Description	Default
--output <file>	Path for the output file	./ready_to_use_secret.json (current directory)
--db-host <string>	Database hostname	— (prompted interactively)
--db-port <string>	Database port	— (prompted interactively)
--db-username <string>	Database username	— (prompted interactively)
--db-password <string>	Database password	— (prompted interactively)
--license-bundle <string>	Base64-encoded license bundle	— (prompted interactively)
--hasura-admin-secret <string>	Hasura admin secret	Auto-generated if omitted
--backend-plugin-auth-secret <string>	Backend plugin auth secret (base64)	Auto-generated if omitted
--user-config-key <string>	User config encryption key (64-char hex)	Auto-generated if omitted
--user-config-iv <string>	User config encryption IV (32-char hex)	Auto-generated if omitted

When all required options are provided via CLI flags, the command runs non-interactively — no prompts are shown. This is useful for CI/CD pipelines. When any required value is missing, only the missing values are prompted interactively.

Interactive prompts

When run without CLI options, init walks the user through two phases:

Phase 1 — Mandatory values (must be provided):

Prompt	Description
DB Host	Hostname of the database server (e.g. witboost-db.internal.company.com)
DB Port	Database port number (e.g. 5432 for PostgreSQL)
DB Username	Database user (e.g. witboost_admin)
DB Password	Database password (masked input)
License bundle	Base64-encoded license bundle as received from the Witboost team

Phase 2 — Optional secrets (leave blank to auto-generate):

These secrets are auto-generated if left blank. Provide existing values only if you want to preserve previously generated secrets (e.g. to avoid overwriting values from an existing installation).

Prompt	Format	Validation
Hasura Admin Secret	Alphanumeric string	At least 64 characters, only a-z, A-Z, 0-9
Backend Plugin Auth Secret	Base64-encoded string	At least 32 characters, valid base64
User Config Encryption Key	Hex string	Exactly 64 hex characters (0-9, a-f)
User Config Encryption IV	Hex string	Exactly 32 hex characters (0-9, a-f)

update Options

Option	Description
--add-key <KEY:VALUE>	Add or set a key. Repeat the flag for multiple keys
--modify-key <KEY:VALUE>	Modify an existing key. Repeat the flag for multiple keys
--remove-key <KEY>	Remove a key. Comma-separate for multiple: KEY1,KEY2
--update-license [bundle]	Update the license bundle (CORE_LICENSE_FILE and CORE_SIGNATURE). Pass a base64-encoded bundle for non-interactive mode, or omit the value to be prompted interactively
--output <file>	Path for the output file (default: ./ready_to_use_secret.json)

At least one of --add-key, --modify-key, --remove-key, or --update-license is required.

validate Options

Argument	Description
<file>	Path to the secret JSON file to validate

Examples

Generate a new secret

init prompts for DB Host, DB Port, DB Username, DB Password, and License bundle. The four cryptographic secrets can optionally be provided or left blank to auto-generate.

# Interactive — prompts for all values
witboost-infra prepare-secret init

# Writes to a custom location
witboost-infra prepare-secret init --output my_secret.json

# Fully non-interactive (CI/CD) — all mandatory values via CLI flags, optional secrets auto-generated
witboost-infra prepare-secret init \
  --db-host witboost-db.internal.company.com \
  --db-port 5432 \
  --db-username witboost_admin \
  --db-password 's3cret!' \
  --license-bundle 'eyJsaWNlbnNlIjoie30iLCJzaWduYXR1cmUiOiIuLi4ifQ==' \
  --output my_secret.json

# Non-interactive with explicit secrets
witboost-infra prepare-secret init \
  --db-host witboost-db.internal.company.com \
  --db-port 5432 \
  --db-username witboost_admin \
  --db-password 's3cret!' \
  --license-bundle 'eyJsaWNlbnNlIjoie30iLCJzaWduYXR1cmUiOiIuLi4ifQ==' \
  --hasura-admin-secret 'myExistingHasuraSecret' \
  --backend-plugin-auth-secret 'bXlFeGlzdGluZ0F1dGhTZWNyZXQ=' \
  --user-config-key 'aabbccdd...' \
  --user-config-iv '11223344...' \
  --output my_secret.json

tip

init writes the ten core keys only. Add optional keys (e.g. TECHNICAL_GITLAB_TOKEN) with update afterwards.

Update an existing secret

# Add a key
witboost-infra prepare-secret update existing_secret.json --add-key TECHNICAL_GITLAB_TOKEN:mytoken

# Update the license bundle interactively (prompts for the bundle)
witboost-infra prepare-secret update existing_secret.json --update-license

# Update the license bundle non-interactively (CI/CD)
witboost-infra prepare-secret update existing_secret.json \
  --update-license 'eyJsaWNlbnNlIjoie30iLCJzaWduYXR1cmUiOiIuLi4ifQ=='

# Multiple mutations
witboost-infra prepare-secret update existing_secret.json \
  --add-key KEY1:VAL1 \
  --add-key KEY2:VAL2 \
  --remove-key OLD_KEY \
  --output updated_secret.json

note

After all mutations, advisory warnings are printed for any missing or malformed mandatory key.

Quoting values that contain special characters

When a value contains shell-special characters (spaces, $, !, etc.), wrap the value in single quotes:

witboost-infra prepare-secret update existing_secret.json \
  --add-key 'MY_KEY:value with spaces'

warning

Do not use --add-key or --modify-key to set CORE_LICENSE_FILE or CORE_SIGNATURE.

License values contain JSON with double quotes, braces, and commas that are interpreted differently across shells (bash, zsh, PowerShell, cmd.exe). This leads to silently mangled values that are difficult to diagnose.

Always use --update-license to update the license. It accepts the base64-encoded bundle (which contains no special characters) and correctly decodes both CORE_LICENSE_FILE and CORE_SIGNATURE internally. The interactive mode also masks the input for security.

# Interactive — prompts with masked input
witboost-infra prepare-secret update existing_secret.json --update-license

# Non-interactive (CI/CD) — pass the base64 bundle directly
witboost-infra prepare-secret update existing_secret.json \
  --update-license 'eyJsaWNlbnNlIjoie30iLCJzaWduYXR1cmUiOiIuLi4ifQ=='

Validate an existing secret

Checks an existing secret file without modifying it.

witboost-infra prepare-secret validate existing_secret.json

Output

A JSON file ({"KEY":"value",...}), written to ./ready_to_use_secret.json in the current directory by default. Use --output <file> to specify a custom path.