Migration Guide: Old CLI → Unified CLI

This guide helps you migrate from the old Kimberlite CLI structure to the new unified kimberlite command.

What Changed?

The new unified CLI consolidates all Kimberlite tools into a single kimberlite command with hierarchical subcommands. This provides:

• Single entry point: One command instead of many binaries
• Consistent UX: Unified flag conventions and output styling
• Better discovery: kimberlite help shows all available commands
• Shell completions: Tab completion for all commands

Command Mapping

Core Commands

Old CLI	New CLI	Notes
kimberlite init	kimberlite init	Compatible
kimberlite start <path>	kimberlite start <path>	Compatible
N/A	kimberlite dev	🆕 New: All-in-one dev server
kimberlite-repl	kimberlite repl --tenant <ID>	Requires --tenant flag
N/A	kimberlite query "SQL" --tenant <ID>	🆕 New: One-shot queries

Tenant Management

Old CLI	New CLI	Notes
N/A	kimberlite tenant create --id <ID> --name <NAME>	🆕 New
N/A	kimberlite tenant list	🆕 New
N/A	kimberlite tenant delete --id <ID>	🆕 New
N/A	kimberlite tenant info --id <ID>	🆕 New

Cluster Management

Old CLI	New CLI	Notes
N/A	kimberlite cluster init --nodes <N>	🆕 New
N/A	kimberlite cluster start	🆕 New
N/A	kimberlite cluster stop	🆕 New
N/A	kimberlite cluster status	🆕 New

Migration Workflow

Old CLI	New CLI	Notes
N/A	kimberlite migration create <name>	🆕 New
N/A	kimberlite migration apply	🆕 New
N/A	kimberlite migration rollback	🆕 New
N/A	kimberlite migration status	🆕 New

Simulation Testing

Old CLI	New CLI	Notes
vopr --seed <SEED>	kimberlite sim verify --seed <SEED>	Integration
vopr -n <N>	kimberlite sim run --iterations <N>	Integration
N/A	kimberlite sim report --output <FILE>	🆕 New
vopr <advanced-flags>	vopr <advanced-flags>	Standalone binary still available

Configuration

Old CLI	New CLI	Notes
Manual TOML editing	kimberlite config show	🆕 New: View config
Manual TOML editing	kimberlite config set <key> <value>	🆕 New: Update config
N/A	kimberlite config validate	🆕 New: Validate config

Studio UI

Old CLI	New CLI	Notes
N/A	kimberlite studio	🆕 New: Standalone Studio
N/A	kimberlite dev	🆕 New: Auto-launch with dev server

Shell Completions

Old CLI	New CLI	Notes
N/A	kimberlite completion bash	🆕 New
N/A	kimberlite completion zsh	🆕 New
N/A	kimberlite completion fish	🆕 New

Breaking Changes

1. REPL Requires --tenant Flag

Old:

kimberlite-repl  # Implicitly used tenant 1

New:

kimberlite repl --tenant 1  # Explicit tenant required

Rationale: Prevents accidental cross-tenant data access (compliance-first design).

Workaround: Add alias to your shell config:

alias repl='kimberlite repl --tenant 1'

2. Crate Names Changed

Old: kmb-* (e.g., kmb-sim, kmb-client) New: kimberlite-* (e.g., kimberlite-sim, kimberlite-client)

Impact: If you depend on Kimberlite crates in your Cargo.toml, update package names:

# Old
[dependencies]
kmb-client = { path = "../kmb-client" }

# New
[dependencies]
kimberlite-client = { path = "../kimberlite-client" }

CLI binary name unchanged: kimberlite command still works.

3. Studio Port Flag

Old: kimberlite studio -p 8080 (if it existed) New: kimberlite studio --port 8080

Impact: Short flag -p removed to avoid conflict with --project flag.

4. Dev Server Replaces Multiple Terminals

Old workflow:

# Terminal 1
kimberlite start

# Terminal 2
kimberlite-studio

# Terminal 3
kimberlite-repl

New workflow:

# Single terminal
kimberlite dev

# Opens browser to Studio automatically
# Connect with: kimberlite repl --tenant 1 (in new terminal)

New Features

1. Unified Dev Command (kimberlite dev)

The star feature of the new CLI:

kimberlite dev

This single command:

• Starts database server
• Launches Studio UI
• Applies pending migrations
• Sets up auto-reload (future)
• Provides aggregated logging

Benefits:

• No more juggling multiple terminals
• Zero-config development
• Integrated migration workflow

2. Tenant Safety

All commands require explicit --tenant flag:

# ERROR: No tenant specified
kimberlite query "SELECT * FROM patients"

# CORRECT: Explicit tenant
kimberlite query "SELECT * FROM patients" --tenant 1

Benefits:

• Prevents accidental cross-tenant queries
• Clear audit trail (tenant always logged)
• HIPAA/GDPR compliance

3. Migration Management

File-based SQL migrations:

# Create migration
kimberlite migration create add_users_table

# Edit migrations/0001_add_users_table.sql
# CREATE TABLE users (...);

# Apply
kimberlite migration apply

# Check status
kimberlite migration status

Benefits:

• Version-controlled schema changes
• Checksum validation (tamper detection)
• Rollback support

4. Local Cluster Testing

Test multi-node scenarios without complex setup:

kimberlite cluster init --nodes 3
kimberlite cluster start
kimberlite cluster status

Benefits:

• Test failover locally
• Verify replication
• No Docker/Kubernetes required

5. Config Management

Structured configuration with validation:

# View current config
kimberlite config show

# Update setting
kimberlite config set database.bind_address "0.0.0.0:5432"

# Validate config files
kimberlite config validate

Benefits:

• No manual TOML editing
• Validation on write
• Environment-specific overrides

6. Integrated Simulation Testing

VOPR simulations now accessible via CLI:

kimberlite sim run --iterations 1000
kimberlite sim verify --seed 12345

Benefits:

• Discover bugs before production
• Reproduce failures exactly
• Automated failure diagnosis

Migration Steps

Step 1: Update Dependencies

If you’re using Kimberlite crates:

# Update Cargo.toml
[dependencies]
kimberlite = "0.2"  # or latest version
kimberlite-client = "0.2"
kimberlite-types = "0.2"

Step 2: Update Scripts

Update any scripts or CI/CD pipelines:

# Old
./kimberlite start /data

# New
./kimberlite start /data --address 0.0.0.0:5432

Step 3: Create Config File

Initialize config in existing projects:

cd my-existing-project
kimberlite init  # Creates kimberlite.toml

Step 4: Migrate Environment Variables

Old environment variables still work:

# These still work
export KMB_DATA_DIR=/var/lib/kimberlite
export KMB_BIND_ADDRESS=0.0.0.0:5432

New config file approach (recommended):

# kimberlite.toml
[database]
data_dir = "/var/lib/kimberlite"
bind_address = "0.0.0.0:5432"

Step 5: Update Aliases

Add helpful aliases to your shell config:

# ~/.bashrc or ~/.zshrc
alias kmb-dev='kimberlite dev'
alias repl='kimberlite repl --tenant 1'
alias kmb-migrate='kimberlite migration apply'

Step 6: Install Shell Completions

# Bash
kimberlite completion bash > ~/.local/share/bash-completion/completions/kimberlite

# Zsh
kimberlite completion zsh > ~/.zsh/completions/_kimberlite

# Fish
kimberlite completion fish > ~/.config/fish/completions/kimberlite.fish

Compatibility

Backward Compatibility

• Config files: Old kimberlite.toml format still works
• Environment variables: KMB_* variables still work
• Data format: Existing data files compatible
• VOPR binary: Standalone vopr still available

Forward Compatibility

New features are opt-in:

• Migrations: Only used if migrations/ directory exists
• Cluster: Only used if explicitly initialized
• Studio: Can be disabled with --no-studio

Troubleshooting

“Command not found: kimberlite”

Problem: Old CLI binaries still in PATH

Solution: Rebuild and ensure new binary is in PATH:

cargo build --release
export PATH="$PWD/target/release:$PATH"
kimberlite --version  # Verify

“Tenant is required”

Problem: Old scripts don’t specify --tenant

Solution: Add --tenant flag to all commands:

# Old
kmb-client query "SELECT * FROM patients"

# New
kimberlite query "SELECT * FROM patients" --tenant 1

“Migration checksum mismatch”

Problem: Migration files were edited after being applied

Solution: Don’t edit applied migrations. Create a new one:

kimberlite migration create fix_previous_change

“Port already in use”

Problem: Old server still running

Solution: Stop old server or use different port:

# Stop old server
pkill kimberlite

# Or use custom port
kimberlite dev --port 5433

FAQ

Q: Can I use both old and new CLI?

A: Yes, but not recommended. The new CLI is the supported version. Migrate as soon as possible.

Q: Will the old CLI be maintained?

A: No. All future development is on the unified CLI. The old CLI is deprecated.

Q: Do I need to migrate my data?

A: No. The data format is unchanged. Just update the CLI.

Q: What about the standalone vopr binary?

A: It’s still available for advanced use cases. Use kimberlite sim for common scenarios.

Q: Can I still use environment variables?

A: Yes. Environment variables have highest precedence over config files.

Q: How do I migrate CI/CD pipelines?

A: Update scripts to use new commands. Example:

# Old
- run: kimberlite start /data &
- run: kimberlite-repl < test.sql

# New
- run: kimberlite start /data &
- run: kimberlite query "$(cat test.sql)" --tenant 1

Getting Help

If you encounter issues during migration:

1. Check this guide: Most common scenarios are covered
2. CLI help: Run kimberlite help <command> for detailed info
3. GitHub Issues: https://github.com/kimberlitedb/kimberlite/issues
4. Discussions: Ask in GitHub Discussions

Summary

The unified CLI provides:

• Better developer experience
• Consistent command structure
• New features (dev server, migrations, cluster)
• Improved safety (tenant requirements)
• Backward compatibility (data, config)

Recommended migration timeline: Within 1-2 weeks

Deprecation timeline: Old CLI will be removed in version 0.3

Next Steps

• Getting Started: Learn the new CLI
• Shell Completions: Set up tab completion
• Configuration Guide: Understanding config files

Happy migrating! 🚀