GCP Tools - Unified Firebase/GCP Management CLI

A comprehensive command-line interface for managing Google Cloud Platform and Firebase projects with unified secrets management, deployment tracking, monitoring, and pre-deployment checks.

🚀 What This Tool Does

GCP Tools replaces 50+ individual scripts with a single, unified CLI that provides:

• 🔐 Complete Secrets Management - Create, update, delete, backup, restore, and compare secrets across environments
• 🚀 Comprehensive Deployment - Deploy functions, hosting, API Gateway, Pub/Sub topics, and all services with tracking
• 📊 Advanced Monitoring - Monitor function status, logs, deployment history, and real-time metrics
• 🔍 Pre-deployment Validation - Comprehensive checks for secrets, extensions, collections, feature flags, and migrations
• 🔑 Authentication Management - Unified authentication with project switching and status monitoring
• 🔗 GitLab Integration - Automated commit collection and project management
• 🔔 Teams Integration - Automated notifications for all operations with rich formatting
• ⚙️ Centralized Configuration - Single configuration file for all projects and environments
• 🛡️ Security Features - Secure defaults, encrypted backups, and audit trails
• 📈 Progress Tracking - Real-time progress indicators and comprehensive logging
• 💾 Local Storage - All data stored locally in JSON format for portability and offline access

📋 Prerequisites

• Node.js 20+ (managed via nvm)
• pnpm package manager
• Google Cloud SDK (gcloud CLI)
• Firebase CLI
• GCP Service Account credentials
• Microsoft Teams Webhook (optional, for notifications)

🛠️ Installation

Option 1: Install as Project Dependency (Recommended)

# Install as a dev dependency in your project
npm install --save-dev @ckohler72/gcp-tools

# Or with pnpm
pnpm add -D @ckohler72/gcp-tools

# Or with yarn
yarn add -D @ckohler72/gcp-tools

Option 2: Install Globally (Alternative)

# Install globally (if you prefer global access)
npm install -g @ckohler72/gcp-tools

Option 3: Install from Source

# Clone the repository
git clone https://github.com/ckohler72/gcp-tools.git
cd gcp-tools

# Install dependencies
npm install

# Build the package
npm run build

# Link globally (optional)
npm link

3. Configure Projects

After installation, run the initialization command in your project directory:

# Navigate to your project directory
cd /path/to/your/project

# Initialize GCP Tools for this project
gcp-tools init

This creates a .gcp-tools.json file in your project directory with your configuration.

Note: Add .gcp-tools.json to your .gitignore file to keep sensitive configuration out of version control.

{
	"rm-titan-dev": {
		"projectId": "rm-titan-dev",
		"region": "us-central1",
		"serviceAccount": "/path/to/dev-service-account.json",
		"firebaseAlias": "rm-titan-dev",
		"environment": "development"
	},
	"rm-titan-prod": {
		"projectId": "rm-titan-prod",
		"region": "us-central1",
		"serviceAccount": "/path/to/prod-service-account.json",
		"firebaseAlias": "rm-titan-prod",
		"environment": "production"
	},
	"teamsWebhookUrl": "https://your-teams-webhook-url"
}

4. Test Installation

# Use the run script (recommended)
gcp-tools --help

# Or manually activate nvm and run
source ~/.nvm/nvm.sh && nvm use 20 && node src/cli.js --help

🎯 Quick Start

First Time Setup

# 1. Install as dev dependency in your project
npm install --save-dev @ckohler72/gcp-tools

# 2. Initialize configuration
npx gcp-tools init

# 3. View your configuration
npx gcp-tools setup view

# 4. Add more projects (optional)
npx gcp-tools setup add-project

# 5. Validate configuration
npx gcp-tools setup validate

# 6. Setup authentication for all projects
npx gcp-tools auth setup-all

# 7. Check authentication status
npx gcp-tools auth status

# 8. Run a quick secrets comparison
npx gcp-tools secrets compare

Daily Workflow Examples

# Deploy to production
npx gcp-tools check pre-deploy --environment prod
npx gcp-tools deploy all --environment prod --message "Release v2.0"

# Manage secrets
npx gcp-tools secrets list --project rm-titan-dev
npx gcp-tools secrets update --project rm-titan-prod --secret API_KEY --value "new-value"

# Monitor deployments
npx gcp-tools monitor deployments --project rm-titan-prod --limit 10

📚 Complete Command Reference

🔧 Initialization Commands

| Command | Description | Example | | -------------- | -------------------------------------- | ------------------------ | | init | Initialize GCP Tools configuration | gcp-tools init | | init --force | Force overwrite existing configuration | gcp-tools init --force |

⚙️ Setup Commands

| Command | Description | Example | | --------------------------- | ----------------------------------- | ------------------------------------------- | | setup view | View current configuration | gcp-tools setup view | | setup view --project <id> | View specific project config | gcp-tools setup view --project my-project | | setup add-project | Add new project to configuration | gcp-tools setup add-project | | setup edit-project | Edit existing project configuration | gcp-tools setup edit-project | | setup remove-project | Remove project from configuration | gcp-tools setup remove-project | | setup teams | Configure Teams webhook URL | gcp-tools setup teams | | setup validate | Validate current configuration | gcp-tools setup validate |

🔐 Secrets Management

| Command | Description | Example | | ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- | | secrets list | List all secrets | gcp-tools secrets list --project rm-titan-dev | | secrets compare | Compare dev/prod secrets | gcp-tools secrets compare | | secrets update | Update secret value/labels | gcp-tools secrets update --project rm-titan-prod --secret API_KEY --value "new-value" | | secrets add | Add new secret | gcp-tools secrets add --project rm-titan-dev --name NEW_SECRET --value "secret-value" | | secrets delete | Delete secret | gcp-tools secrets delete --project rm-titan-prod --secret OLD_SECRET | | secrets backup | Backup all secrets | gcp-tools secrets backup --project rm-titan-dev --output ./backups | | secrets restore | Restore from backup | gcp-tools secrets restore --file ./backups/secrets-backup.json --project rm-titan-prod |

🚀 Deployment Commands

| Command | Description | Example | | ------------------ | --------------------- | -------------------------------------------------------------------------------- | | deploy all | Deploy all services | gcp-tools deploy all --environment prod --message "Release v1.2.3" | | deploy functions | Deploy functions only | gcp-tools deploy functions --environment dev --functions "function1,function2" | | deploy hosting | Deploy hosting only | gcp-tools deploy hosting --environment prod --message "UI updates" | | deploy gateway | Deploy API Gateway | gcp-tools deploy gateway --environment prod --api-spec ./api/spec.json | | deploy pubsub | Deploy Pub/Sub topics | gcp-tools deploy pubsub --project rm-titan-prod --topics "topic1,topic2" |

📊 Monitoring Commands

| Command | Description | Example | | --------------------- | --------------------------- | ---------------------------------------------------------------------- | | monitor functions | Monitor function status | gcp-tools monitor functions --project rm-titan-dev | | monitor logs | Check function logs | gcp-tools monitor logs --project rm-titan-prod --function myFunction | | monitor status | Check function status | gcp-tools monitor status --project rm-titan-dev | | monitor deployments | View deployment history | gcp-tools monitor deployments --project rm-titan-dev --limit 20 | | monitor failures | Monitor deployment failures | gcp-tools monitor failures --project rm-titan-dev --days 7 |

🔍 Pre-deployment Checks

| Command | Description | Example | | --------------------- | ----------------------------- | ----------------------------------------------- | | check pre-deploy | Run all pre-deployment checks | gcp-tools check pre-deploy --environment prod | | check secrets | Check secrets only | gcp-tools check secrets | | check extensions | Check extensions only | gcp-tools check extensions | | check collections | Check collections only | gcp-tools check collections | | check feature-flags | Check feature flags only | gcp-tools check feature-flags | | check migrations | Check migrations only | gcp-tools check migrations |

🔑 Authentication Commands

| Command | Description | Example | | ---------------- | ----------------------- | ----------------------------------------------- | | auth login | Authenticate with GCP | gcp-tools auth login --project rm-titan-dev | | auth reauth | Re-authenticate project | gcp-tools auth reauth --project rm-titan-prod | | auth status | Check auth status | gcp-tools auth status | | auth switch | Switch project | gcp-tools auth switch --project rm-titan-prod | | auth setup-all | Setup all projects | gcp-tools auth setup-all |

🔗 GitLab Integration

| Command | Description | Example | | ----------------- | --------------- | ----------------------------------------------------------- | | gitlab commits | Collect commits | gcp-tools gitlab commits --branch main --environment prod | | gitlab projects | List projects | gcp-tools gitlab projects | | gitlab test | Test connection | gcp-tools gitlab test |

💾 Storage Management

| Command | Description | Example | | ----------------- | --------------------------------- | --------------------------------------------------------------- | | storage status | Show local storage status | gcp-tools storage status | | storage export | Export project data | gcp-tools storage export --project rm-titan-dev --format json | | storage compare | Compare data between environments | gcp-tools storage compare --type collections | | storage cleanup | Clean up old data files | gcp-tools storage cleanup --days 30 | | storage sync | Sync data between environments | gcp-tools storage sync --type collections --dry-run |

🔄 Common Workflows

Complete Deployment Workflow

# 1. Check authentication status
gcp-tools auth status

# 2. Run pre-deployment checks
gcp-tools check pre-deploy --environment prod

# 3. Collect GitLab commits for tracking
gcp-tools gitlab commits --branch main --environment prod

# 4. Deploy all services
gcp-tools deploy all --environment prod --message "Release v2.0"

# 5. Monitor deployment status
gcp-tools monitor deployments --project rm-titan-prod --limit 10

Secrets Management Workflow

# 1. Compare secrets between environments
gcp-tools secrets compare

# 2. Backup production secrets
gcp-tools secrets backup --project rm-titan-prod --output ./backups

# 3. Update secrets in development
gcp-tools secrets update --project rm-titan-dev --secret API_KEY --value "new-value"

# 4. Restore secrets to staging
gcp-tools secrets restore --file ./backups/prod-backup.json --project rm-titan-staging --mode skip

Authentication Setup Workflow

# 1. Setup authentication for all projects
gcp-tools auth setup-all

# 2. Verify authentication status
gcp-tools auth status

# 3. Switch to production project
gcp-tools auth switch --project rm-titan-prod

# 4. Test deployment capabilities
gcp-tools deploy functions --environment prod --functions "test-function"

🏗️ Architecture Overview

Project Structure

src/
├── cli.js                 # Main CLI entry point
├── core/
│   ├── config.js          # Configuration management
│   ├── auth.js            # Authentication management
│   └── logger.js          # Unified logging
├── commands/
│   ├── secrets/           # Secrets management commands
│   ├── deploy/            # Deployment commands
│   ├── monitor/           # Monitoring commands
│   ├── check/             # Pre-deployment check commands
│   ├── auth/              # Authentication commands
│   ├── gitlab/            # GitLab integration commands
│   └── storage/           # Local storage management commands
└── utils/
    ├── teams.js           # Teams notification system
    ├── deploymentTracker.js # Local deployment tracking
    └── localStorage.js    # Local storage management

Local Storage System

All data is stored locally in JSON format for portability and offline access:

logs/
├── deployments/          # Deployment tracking data
├── storage/              # General project data
├── collections/          # Firestore collections data
├── rules/                # Firestore/Storage rules
├── feature-flags/        # Feature flags data
└── migrations/           # Database migrations data

🔄 Migration from Legacy Tools

This unified CLI replaces 50+ legacy tools. Here's the migration mapping:

Secrets Management

• checkSecrets.mjs → gcp-tools secrets compare
• updateSecret.mjs → gcp-tools secrets update
• addNewSecret.mjs → gcp-tools secrets add
• deleteSecret.mjs → gcp-tools secrets delete
• backupSecrets.mjs → gcp-tools secrets backup
• restoreSecrets.mjs → gcp-tools secrets restore

Deployment

• deployFunctions.mjs → gcp-tools deploy functions
• deployGateway.mjs → gcp-tools deploy gateway
• deployPubSub.mjs → gcp-tools deploy pubsub
• deploy.sh → gcp-tools deploy all

Monitoring

• inspectCloudFunctions.mjs → gcp-tools monitor functions
• viewFunctionDeployments.mjs → gcp-tools monitor deployments
• quick-function-check.sh → gcp-tools monitor status

Pre-deployment Checks

• preDeployCheck.mjs → gcp-tools check pre-deploy
• checkCollections.mjs → gcp-tools check collections
• checkExtensions.mjs → gcp-tools check extensions
• checkFeatureFlags.mjs → gcp-tools check feature-flags
• checkMigrations.mjs → gcp-tools check migrations

Authentication

• auth.sh → gcp-tools auth login
• gcloud-reauth.sh → gcp-tools auth reauth
• setCreds.js → Integrated into authentication system

GitLab Integration

• collect-gitlab-commits.mjs → gcp-tools gitlab commits
• gitlab-commits.mjs → gcp-tools gitlab commits

🛠️ Troubleshooting

Common Issues

Authentication Errors

# Check authentication status
gcp-tools auth status

# Re-authenticate if needed
gcp-tools auth reauth --project rm-titan-dev

Configuration Issues

# Verify configuration
gcp-tools --config ./config/projects.json --help

# Check if projects are configured
cat config/projects.json

Teams Notifications Not Working

# Test Teams connection
gcp-tools gitlab test  # This will also test Teams integration

# Check Teams webhook URL in config
grep teamsWebhookUrl config/projects.json

Deployment Failures

# Check function status
gcp-tools monitor status --project rm-titan-dev

# View function logs
gcp-tools monitor logs --project rm-titan-dev --function function-name

# Run pre-deployment checks
gcp-tools check pre-deploy --environment dev

Getting Help

• Run gcp-tools <command> --help for specific command help
• Check the logs directory for detailed operation logs
• Use --verbose flag for detailed debugging information
• Review Teams notifications for operation status

🎯 Key Benefits

1. Unified Interface

• Single CLI: One tool instead of 50+ individual scripts
• Consistent Commands: Standardized syntax and options across all operations
• Integrated Help: Comprehensive help system with examples

2. Enhanced Reliability

• Error Handling: Robust error management with detailed error messages
• Progress Feedback: Real-time progress indicators for long operations
• Validation: Comprehensive input validation and configuration checking

3. Better User Experience

• Interactive Prompts: Smart defaults and guided workflows
• Teams Notifications: Automatic notifications for all operations
• Detailed Logging: Multi-level logging with timestamps and context

4. Improved Security

• Centralized Auth: Unified authentication management
• Secure Defaults: Safe default behaviors and confirmation prompts
• Audit Trail: Complete operation tracking and logging

5. Enhanced Maintainability

• Modular Architecture: Clean separation of concerns
• Consistent Patterns: Standardized code patterns across all commands
• Comprehensive Testing: Built-in validation and error handling

6. Local Storage Benefits

• Portability: No external database dependencies
• Performance: Faster data access (local files vs network)
• Transparency: Data stored in human-readable JSON format
• Offline Support: Works without internet connection

📈 Development

Adding New Commands

1. Create command file in appropriate directory under src/commands/
2. Export command using Commander.js
3. Import and add to main CLI in src/cli.js

Testing

# Test individual commands
gcp-tools secrets list --help
gcp-tools deploy functions --help

# Test with verbose logging
gcp-tools secrets compare --verbose

Linting

# Run linting
pnpm run lint

# Fix linting issues
pnpm run lint:fix

📝 License

MIT License - see LICENSE file for details

🎉 Summary

The unified GCP tools provide a comprehensive, maintainable solution for managing Firebase/GCP projects. With 50+ legacy tools successfully migrated into 7 command categories with 30+ individual commands, the new architecture offers:

• Better Developer Experience: Single CLI with consistent interface
• Enhanced Reliability: Robust error handling and validation
• Improved Security: Centralized authentication and secure defaults
• Complete Integration: Teams notifications and GitLab integration
• Future-Proof Architecture: Modular design for easy extension
• Local Storage: Portable, offline-capable data management

The unified GCP tools are production-ready and will significantly improve your Firebase/GCP project management workflow!