Secrets
Encrypt database passwords, API keys, SSH keys and authentication tokens with ws-cli secrets, instead of storing them in plaintext or version control.
The ws-cli secrets command encrypts secrets with AES-256-GCM, using a key derived from your master key with Argon2id.
Master Keys
A master key is required to encrypt and decrypt secrets.
Generate a Master Key
# Standard master key
ws-cli secrets generate master --output .master.key --mode 0o600
# Longer 64-byte key
ws-cli secrets generate master --length 64 --output .master.key
# Output to stdout (CI/CD)
ws-cli secrets generate master --rawThe --mode flag sets file permissions (e.g., 0o600 for owner-only access). Write octal with the 0o prefix; a value without it is read as decimal.
Master Key Lookup
Point ws-cli at your key with:
WS_SECRETS_MASTER_KEY: Master encryption key for seed secrets.
The master key is read from the first of:
- The
--masterflag (a path to an existing file, or the key itself). WS_SECRETS_MASTER_KEYset to the key.WS_SECRETS_MASTER_KEYset tofile:/path/to/key.- A file mounted at
/run/secrets/workspace/secrets/master_key.
export WS_SECRETS_MASTER_KEY=file:./master.key
ws-cli secrets encrypt "my-secret"⚠️ WARNING
--master takes any value that is not an existing file as the key itself, so a mistyped path silently encrypts with the wrong key.
Encryption & Decryption
Basic Usage
# Encrypt
ws-cli secrets encrypt "my-secret" --master .master.key
# Decrypt
ws-cli secrets decrypt "encrypted-value" --master .master.key
# Encrypt/Decrypt to files
ws-cli secrets encrypt "my-secret" --output encrypted.txt --master .master.key
ws-cli secrets decrypt "..." --output secret.txt --mode 0o600 --master .master.keyBoth commands also read stdin when given -, and encrypted values may span several lines for readability:
echo "my-secret" | ws-cli secrets encrypt - --master .master.key
cat encrypted.txt | ws-cli secrets decrypt - --master .master.keySeed
The seed manifest decrypts secrets into files for you: inline ${secrets.NAME} values in templated entries, and whole files marked secret: true.
Authentication Passwords
Generate Argon2id password hashes for workspace login:
PASSWORD=$(echo -n "password" | ws-cli secrets generate login --raw)Use in Docker deployments:
docker run \
-e WS_AUTH_PASSWORD_HASHED="$PASSWORD" \
ghcr.io/kloudkit/workspace:v0.6.0Quick Reference
Common Flags
--master <key>: Master key, or the path to a file holding it.--output <file>: Write to file.--mode <perm>: File permissions, as0o-prefixed octal or decimal (default0o600).--raw: Disable styling.--force: Overwrite existing files.