plat-cli

Platform Engineering DevEx CLI - Simplify complex cloud operations with modern TUI and classic CLI interfaces

🚀 Quick Start

# Install globally
yarn global add plat-cli

# Launch interactive TUI (recommended)
plat-cli

# Or use classic CLI for automation
plat-cli gcp cloudsql migrate \
  --source-project my-project-prd-01 \
  --source-instance db-instance-v2 \
  --target-project my-project-prd-01 \
  --target-instance db-instance \
  --databases myapp_db \
  --source-ip 34.95.123.45 \
  --source-user postgres \
  --source-password MySecurePass123 \
  --target-ip 34.95.67.89 \
  --target-user postgres \
  --target-password MySecurePass123

✨ Features

• 🎯 CloudSQL PostgreSQL Migration - Seamless database migrations between instances
• 🖥️ Dual Interface - Interactive TUI with Ink or Classic CLI for scripts
• 📦 Batch Operations - Migrate multiple databases in parallel (N:1, N:N)
• 🔄 Smart Strategies - Auto-detect optimal migration patterns
• 📊 Real-time Progress - Live progress tracking with ETA
• 🔐 Users & Roles Migration - Optional migration of database users and permissions
• 💾 Local Cache - SQLite-powered persistent cache for better performance of configurations and inputs
• 🔁 Auto Retry - Intelligent retry with exponential backoff
• 🎨 Modern UX - Beautiful TUI with React and @inkjs/ui components

📦 Installation

Prerequisites

• Node.js >= 18
• PostgreSQL client tools (pg_dump, pg_restore)
• Google Cloud credentials (for CloudSQL operations)

Install

# Global installation (recommended) inside the plat-cli folder
yarn global add .

# Or with npm inside the plat-cli folder
npm install -g .

# Local project installation inside the plat-cli folder
yarn add .

🎮 Usage Modes

Interactive TUI Mode (Default)

Simply run plat-cli without arguments to launch the modern TUI:

plat-cli

Navigate with arrow keys, select options, and follow the guided workflow.

Features:

• Visual navigation menu
• Form-based configuration
• Real-time validation
• Progress visualization
• Batch migration support

Classic CLI Mode

Perfect for automation, CI/CD, and scripts:

# Single database migration
plat-cli gcp cloudsql migrate \
  --source-project my-project \
  --source-instance source-db \
  --target-project my-project \
  --target-instance target-db \
  --databases app_db,analytics_db

# Batch migration from file
plat-cli gcp cloudsql migrate \
  --sources-file instances.txt \
  --target-project production \
  --target-instance consolidated-db \
  --strategy consolidate

📚 Core Commands

CloudSQL Migration

# Complete migration example with all connection details
plat-cli gcp cloudsql migrate \
  --source-project my-project-prd-01 \
  --source-instance db-instance-v2 \
  --target-project my-project-prd-01 \
  --target-instance db-instance \
  --databases myapp_db,analytics_db \
  --source-ip 34.95.123.45 \
  --source-user postgres \
  --source-password MySecurePass123 \
  --target-ip 34.95.67.89 \
  --target-user postgres \
  --target-password MySecurePass123

# Test connection
plat-cli gcp cloudsql test-connection \
  --project my-project \
  --instance my-instance

# List databases
plat-cli gcp cloudsql list-databases \
  --project my-project \
  --instance my-instance

# Migrate with dry-run
plat-cli gcp cloudsql migrate \
  --source-project prod \
  --source-instance db-v1 \
  --target-project prod \
  --target-instance db-v2 \
  --include-all \
  --dry-run

# Migrate with users and roles (optional)
plat-cli gcp cloudsql migrate \
  --source-project prod \
  --source-instance db-v1 \
  --target-project prod \
  --target-instance db-v2 \
  --include-all \
  --include-users-roles \
  --password-strategy default \
  --default-password 'SecurePass123!'

Migration Strategies

| Strategy | Description | Use Case | | --------------- | --------------------------- | --------------------------- | | simple | Direct 1:1 migration | Single instance migrations | | consolidate | N:1 consolidation | Merge multiple DBs into one | | version-based | Group by PostgreSQL version | Version-specific migrations | | custom | Custom mapping file | Complex migration patterns |

⚙️ Configuration

Environment Variables

Create a .env file:

# Google Cloud
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Connection method (choose one)
USE_CLOUD_SQL_PROXY=true

Batch Migration Example

Create instances.txt:

instance-1
instance-2
project:instance-3

Run batch migration:

plat-cli gcp cloudsql migrate \
  --sources-file instances.txt \
  --target-project production \
  --target-instance main-db \
  --strategy consolidate \
  --conflict-resolution prefix

Configuration File

Use JSON for complex configurations:

{
  "source": {
    "project": "my-project",
    "instance": "source-db",
    "databases": ["app", "analytics"]
  },
  "target": {
    "project": "my-project",
    "instance": "target-db"
  },
  "options": {
    "strategy": "simple",
    "retryAttempts": 3,
    "jobs": 2,
    "includeUsersRoles": false,
    "passwordStrategy": {
      "type": "default",
      "defaultPassword": "ChangeMeNow123!"
    }
  }
}

Security Note: When migrating users, passwords cannot be extracted from the source. You must set new passwords using one of the strategies: same (use migration user password), default (set a default password), or individual (set per-user passwords).

plat-cli gcp cloudsql migrate --config migration.json

🛠️ Advanced Features

Batch Migration Strategies

N:1 Consolidation

# Merge multiple instances into one
plat-cli gcp cloudsql migrate \
  --sources-file instances.txt \
  --target-instance consolidated-db \
  --strategy consolidate \
  --conflict-resolution prefix

Version-based Migration

# Group by PostgreSQL version
plat-cli gcp cloudsql migrate \
  --mapping-file version-mapping.json \
  --strategy version-based

Progress Tracking

The CLI provides real-time progress with:

• Overall progress percentage
• Current operation status
• ETA calculation
• Transfer speed metrics
• Per-database progress

Dry Run Mode

Test your configuration without making changes:

plat-cli gcp cloudsql migrate \
  --source-instance db1 \
  --target-instance db2 \
  --dry-run

🔧 Development

# Clone repository
git clone https://github.com/devxplat/plat-cli.git
cd plat-cli

# Install dependencies
yarn install

# Run in development
yarn dev

# Run tests
yarn test

# Lint code
yarn lint

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

AGPLv3 © devxplat

🔗 Links

• Documentation
• Issues
• Changelog

Built with ❤️ for Platform Engineers and SREs by DevX Platform