Skip to main content

​
Synopsis

chameleon config <subcommand> [args]
Manage ChameleonDB configuration and integrity modes.

​
Description

The config command manages:
  • Paranoid modes - Ring-based schema governance (readonly/standard/privileged/emergency)
  • Mode passwords - Authentication for mode upgrades
  • Configuration values - Project settings

​
Subcommands

​
config get

Get a configuration value.

​
Synopsis

chameleon config get <key>

​
Arguments

​
key
string
required
Configuration key to retrieveCommon keys:
  • mode - Current paranoid mode
  • database.driver - Database driver
  • schema.paths - Schema file paths

​
Examples

​
Get Current Mode

chameleon config get mode
Output: 
readonly

​
Get Database Driver

chameleon config get database.driver
Output: 
postgresql

​
config set

Set a configuration value.

​
Synopsis

chameleon config set <key>=<value>

​
Arguments

​
key=value
string
required
Configuration assignmentFormat: key=valueExample: mode=standard

​
Examples

​
Upgrade Mode (Requires Password)

chameleon config set mode=standard
Output: 
🔐 Enter mode password: ********
✅ Mode upgraded to standard

​
Downgrade Mode (No Password)

chameleon config set mode=readonly
Output: 
✅ Mode downgraded to readonly
Note: Downgrades (to more restrictive modes) don’t require a password.

​
config auth set-password

Set or change the mode password.

​
Synopsis

chameleon config auth set-password

​
Examples

​
Set Password (First Time)

chameleon config auth set-password
Output: 
Enter new password: ********
Confirm password: ********
✅ Mode password configured

​
Change Password

chameleon config auth set-password
Output: 
Enter current password: ********
Enter new password: ********
Confirm password: ********
✅ Mode password updated

​
Paranoid Modes

ChameleonDB uses Unix-style protection rings for schema governance:
ModeRingSchema ChangesPassword Required
readonlyR3❌ BlockedNo (default)
standardR2✅ ControlledYes (upgrade)
privilegedR1✅ DirectYes (upgrade)
emergencyR0✅ No checksYes (upgrade)

​
Mode Descriptions

​
readonly
mode
Ring 3 - Production default
  • Schema modifications blocked
  • Migrations fail with error
  • Introspection disabled
  • No password needed to set (downgrade)
Use case: Production databases
​
standard
mode
Ring 2 - Development mode
  • Schema changes allowed
  • Migrations validated and logged
  • Integrity checks enforced
  • Password required to upgrade from readonly
Use case: Development teams
​
privileged
mode
Ring 1 - DBA access
  • Direct schema changes
  • Reduced validation
  • All operations logged
  • Password required to upgrade
Use case: Database administrators
​
emergency
mode
Ring 0 - Emergency recovery
  • No integrity checks
  • All operations allowed
  • Full audit logging
  • Password required to upgrade
Use case: Incident recovery only

​
Mode Workflow

​
Initial Setup (After Init)

# 1. Initialize project
chameleon init

# Default mode: readonly
chameleon config get mode
# Output: readonly

# 2. Set password (recommended)
chameleon config auth set-password
# Enter password: ********

# 3. Upgrade to standard for development
chameleon config set mode=standard
# Enter password: ********
# ✅ Mode upgraded to standard

# 4. Now migrations work
chameleon migrate --apply
✓ Migration applied successfully

​
Production Deployment

# 1. Deploy with readonly mode
chameleon config set mode=readonly
✅ Mode downgraded to readonly

# 2. Migrations are blocked
chameleon migrate --apply
❌ readonly mode: schema modifications blocked

# 3. Emergency upgrade (requires password)
chameleon config set mode=standard
🔐 Enter mode password: ********
✅ Mode upgraded to standard

# 4. Apply migration
chameleon migrate --apply
✓ Migration applied

# 5. Lock again
chameleon config set mode=readonly
✅ Mode downgraded to readonly

​
Emergency Recovery

# Upgrade to emergency mode
chameleon config set mode=emergency
🔐 Enter mode password: ********
⚠️  WARNING: Emergency mode disables safety checks
✅ Mode upgraded to emergency

# Perform recovery operations
# ...

# Return to safe mode
chameleon config set mode=readonly
✅ Mode downgraded to readonly

​
Password Management

​
Password Storage

Passwords are hashed and stored in: 
.chameleon/config.yml
Example: 
auth:
  mode_password_hash: "$2a$10$abc123..."

​
Password Requirements

  • Minimum length: 8 characters (recommended: 12+)
  • No complexity requirements (use strong passwords)
  • Stored as bcrypt hash

​
Lost Password Recovery

If you lose the mode password:
  1. Option 1: Reset password hash 
    # Edit config manually
vim .chameleon/config.yml

# Remove the auth section:
# auth:
#   mode_password_hash: "..."

# Set new password
chameleon config auth set-password
  2. Option 2: Use privileged access Contact DBA or use emergency access if configured.

​
Configuration File

Configuration is stored in .chameleon.yml: 
database:
  driver: postgresql
  connection_string: ${DATABASE_URL}

schema:
  paths:
    - ./schemas
  merged_output: .chameleon/state/schema.merged.cham

features:
  auto_migration: true
  rollback: true
  backup_on_migrate: true
  audit_logging: true

safety:
  validation: true
  confirmation: false

auth:
  mode_password_hash: "$2a$10$..."

​
Edit Configuration

Direct editing: 
vim .chameleon.yml
Or use config set: 
chameleon config set features.backup_on_migrate=false

​
Mode Enforcement

​
Readonly Mode Blocks

# Migrate blocked
chameleon migrate --apply
❌ readonly mode: schema modifications blocked

# Introspect blocked
chameleon introspect postgresql://...
❌ readonly mode: introspect is blocked

​
Standard Mode Allows

# Migrate allowed
chameleon migrate --apply
✓ Migration applied successfully

# Introspect allowed
chameleon introspect postgresql://...
✓ Schema written to schemas/schema.cham

​
Troubleshooting

​
Wrong Password

chameleon config set mode=standard
Output: 
🔐 Enter mode password: ********
❌ Invalid password
Solution: Re-enter correct password or reset (see Lost Password Recovery).

​
No Password Set

chameleon config set mode=standard
Output: 
❌ Mode password not set
   Run: chameleon config auth set-password
Solution: 
chameleon config auth set-password

​
Cannot Read Config

❌ failed to load config: no such file or directory
Solution: Run from project directory with .chameleon.yml: 
cd /path/to/project
chameleon config get mode

​
Security Best Practices

​
1. Always Set a Password

chameleon config auth set-password
Protects against unauthorized mode upgrades.

​
2. Use Readonly in Production

chameleon config set mode=readonly
Prevents accidental schema changes.

​
3. Audit Mode Changes

chameleon journal last 50 | grep mode
Track who upgraded modes and when.

​
4. Rotate Passwords Regularly

chameleon config auth set-password
Change password every 90 days.

​
5. Document Emergency Procedures

Create runbook for mode upgrades: 
## Emergency Schema Change

1. Get DBA approval
2. Upgrade mode: `chameleon config set mode=standard`
3. Apply migration: `chameleon migrate --apply`
4. Downgrade mode: `chameleon config set mode=readonly`
5. Log in incident tracker

​
See Also