FlexGate CLI - Complete Documentation

Overview
Installation
Quick Start
Commands Reference
Configuration Guide
Use Cases
Examples
Troubleshooting

Overview

FlexGate CLI is a command-line tool for managing FlexGate configuration without Admin UI. Perfect for:

🖥️ EC2/Cloud Instances - Configure via SSH
🐳 Docker/Containers - Automated setup
🚀 CI/CD Pipelines - Scripted deployment
📝 Infrastructure as Code - JSON configuration files
🔧 Headless Servers - No browser needed

Installation

Global (Recommended)

npm install -g flexgate-proxy

Verify:

flexgate --version
# Output: 0.1.0-beta.4

Local Project

npm install flexgate-proxy
npx flexgate --help

Quick Start

1. Initialize Configuration

flexgate init --interactive

Interactive Wizard:

🚀 FlexGate Configuration Wizard

? Server port: 3000
? Environment: production
? Database host: localhost
? Database port: 5432
? Database name: flexgate
? Database user: flexgate
? Database password: ********
? Redis host: localhost
? Redis port: 6379
? Enable Prometheus metrics? Yes

✅ Configuration saved to: config/flexgate.json
✅ Environment file generated: .env

2. Verify Configuration

flexgate config show

3. Test Connections

flexgate db test
flexgate redis test

4. Start FlexGate

npm start

Done! 🎉

Commands Reference

`flexgate init`

Initialize FlexGate configuration.

Syntax:

flexgate init [options]

Options:

-i, --interactive - Interactive configuration wizard
-f, --force - Overwrite existing configuration

Examples:

# Interactive setup (recommended)
flexgate init --interactive

# Use defaults
flexgate init

# Force overwrite
flexgate init --force

`flexgate config show`

Display current configuration.

Syntax:

flexgate config show [options]

Options:

--json - Output as JSON

Examples:

# Human-readable format
flexgate config show

# JSON format
flexgate config show --json

Output:

📋 Current Configuration:

Server:
  Port: 3000
  Host: 0.0.0.0
  Environment: production

Database:
  Host: localhost:5432
  Name: flexgate
  User: flexgate
  SSL: false

Redis:
  Host: localhost:6379
  Database: 0

Security:
  CORS Enabled: true
  Rate Limiting: true

Logging:
  Level: info
  Format: json

Monitoring:
  Metrics: true
  Prometheus Port: 9090

`flexgate config set`

Set a configuration value.

Syntax:

flexgate config set <key> <value>

Examples:

# Server
flexgate config set server.port 8080
flexgate config set server.host "0.0.0.0"
flexgate config set server.environment production

# Database
flexgate config set database.host db.example.com
flexgate config set database.port 5432
flexgate config set database.name flexgate_prod
flexgate config set database.user flexgate_user
flexgate config set database.password secret123
flexgate config set database.ssl true
flexgate config set database.poolMax 20

# Redis
flexgate config set redis.host redis.example.com
flexgate config set redis.port 6379
flexgate config set redis.password redissecret
flexgate config set redis.db 1

# Security
flexgate config set security.corsEnabled true
flexgate config set security.rateLimitEnabled true
flexgate config set security.rateLimitMaxRequests 1000

# Logging
flexgate config set logging.level debug
flexgate config set logging.format json
flexgate config set logging.destination both

# Monitoring
flexgate config set monitoring.metricsEnabled true
flexgate config set monitoring.prometheusPort 9090

What It Does:

Updates config/flexgate.json
Regenerates .env file
Validates the value
Confirms the change

`flexgate config get`

Get a configuration value.

Syntax:

flexgate config get <key>

Examples:

flexgate config get server.port
# Output: 3000

flexgate config get database.host
# Output: localhost

flexgate config get logging.level
# Output: info

`flexgate config import`

Import configuration from JSON file.

Syntax:

flexgate config import <file>

Examples:

# Import production config
flexgate config import config/flexgate.production.json.example

# Import from custom path
flexgate config import /opt/flexgate-config.json

# Import backup
flexgate config import /tmp/flexgate-backup.json

What It Does:

Reads JSON file
Validates against schema
Saves to config/flexgate.json
Regenerates .env
Displays imported configuration

`flexgate config export`

Export configuration to JSON file.

Syntax:

flexgate config export <file>

Examples:

# Export to file
flexgate config export backup.json

# Export with timestamp
flexgate config export backup-$(date +%Y%m%d).json

# Export to specific path
flexgate config export /tmp/flexgate-backup.json

Use Case: Backup, share configs, version control

`flexgate config reset`

Reset configuration to defaults.

Syntax:

flexgate config reset [options]

Options:

-f, --force - Skip confirmation

Examples:

# With confirmation
flexgate config reset

# Skip confirmation
flexgate config reset --force

Warning: This will erase all custom configuration!

`flexgate db test`

Test PostgreSQL database connection.

Syntax:

flexgate db test

Example:

flexgate db test

Output (Success):

Testing database connection...
✅ Database connection successful
   Host: localhost:5432
   Database: flexgate
   User: flexgate
   SSL: false

Output (Failure):

Testing database connection...
❌ Database connection failed
   Error: Connection timeout
   Host: localhost:5432

`flexgate redis test`

Test Redis connection.

Syntax:

flexgate redis test

Example:

flexgate redis test

Output (Success):

Testing Redis connection...
✅ Redis connection successful
   Host: localhost:6379
   Database: 0
   Ping: PONG

Output (Failure):

Testing Redis connection...
❌ Redis connection failed
   Error: ECONNREFUSED
   Host: localhost:6379

`flexgate health`

Check all services health.

Syntax:

flexgate health

Example:

flexgate health

Output:

🏥 Running health checks...

✅ FlexGate API: healthy
✅ PostgreSQL: healthy
✅ Redis: healthy
✅ Admin UI: healthy

Configuration Guide

Configuration File

Location: config/flexgate.json

Structure:

{
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "environment": "production"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "flexgate",
    "user": "flexgate",
    "password": "flexgate",
    "ssl": false,
    "poolMin": 2,
    "poolMax": 10
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "db": 0
  },
  "security": {
    "corsOrigins": ["http://localhost:3001"],
    "corsEnabled": true,
    "rateLimitEnabled": true,
    "rateLimitWindowMs": 60000,
    "rateLimitMaxRequests": 100
  },
  "logging": {
    "level": "info",
    "format": "json",
    "destination": "file",
    "maxFiles": 10,
    "maxSize": "10m"
  },
  "monitoring": {
    "metricsEnabled": true,
    "prometheusPort": 9090,
    "healthCheckInterval": 30000
  }
}

Environment-Specific Configurations

Create separate configs for each environment:

config/
  flexgate.development.json
  flexgate.staging.json
  flexgate.production.json

Load:

NODE_ENV=production npm start

Use Cases

1. EC2 Deployment

# 1. SSH into EC2
ssh -i key.pem ec2-user@ec2-instance

# 2. Install FlexGate
npm install -g flexgate-proxy

# 3. Configure
flexgate init --interactive

# 4. Test
flexgate db test
flexgate redis test

# 5. Start
npm start

2. Docker Container

Dockerfile:

FROM node:18-alpine

WORKDIR /app

# Install FlexGate
RUN npm install -g flexgate-proxy

# Copy configuration
COPY config/flexgate.json /app/config/flexgate.json

# Generate .env
RUN flexgate config import /app/config/flexgate.json

EXPOSE 8080

CMD ["npm", "start"]

3. CI/CD Pipeline

Jenkins (Jenkinsfile):

stage('Configure FlexGate') {
    steps {
        sh 'npm install -g flexgate-proxy'
        sh 'flexgate config import config/production.json'
        sh 'flexgate db test'
        sh 'flexgate redis test'
    }
}

4. GitOps Workflow

# 1. Edit configuration
vim config/flexgate.production.json

# 2. Commit to git
git add config/flexgate.production.json
git commit -m "Update production config"
git push

# 3. Deploy
flexgate config import config/flexgate.production.json
npm start

5. Batch Configuration

Configure multiple values at once:

#!/bin/bash
flexgate config set server.port 8080
flexgate config set database.host db-prod.internal
flexgate config set database.ssl true
flexgate config set redis.host redis-prod.internal
flexgate config set logging.level warn
flexgate config set monitoring.metricsEnabled true

Examples

Complete EC2 Setup Script

#!/bin/bash
set -e

echo "🚀 FlexGate EC2 Setup"

# Install Node.js
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

# Install FlexGate
sudo npm install -g flexgate-proxy

# Configure
flexgate init --force <<EOF
8080
production
flexgate-db.xxxx.us-east-1.rds.amazonaws.com
5432
flexgate_prod
flexgate_user
SECURE_PASSWORD
flexgate-redis.xxxxx.cache.amazonaws.com
6379
REDIS_PASSWORD
0
yes
EOF

# Test connections
echo "Testing database..."
flexgate db test || exit 1

echo "Testing Redis..."
flexgate redis test || exit 1

# Health check
flexgate health

echo "✅ FlexGate setup complete!"
echo "Run: npm start"

Production Configuration Template

config/flexgate.production.json:

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0",
    "environment": "production"
  },
  "database": {
    "host": "flexgate-db.internal",
    "port": 5432,
    "name": "flexgate_prod",
    "user": "flexgate_user",
    "password": "${DB_PASSWORD}",
    "ssl": true,
    "poolMin": 5,
    "poolMax": 20
  },
  "redis": {
    "host": "flexgate-redis.internal",
    "port": 6379,
    "password": "${REDIS_PASSWORD}",
    "db": 0
  },
  "security": {
    "corsOrigins": ["https://admin.example.com"],
    "corsEnabled": true,
    "rateLimitEnabled": true,
    "rateLimitMaxRequests": 1000
  },
  "logging": {
    "level": "warn",
    "format": "json",
    "destination": "both",
    "maxFiles": 30,
    "maxSize": "100m"
  },
  "monitoring": {
    "metricsEnabled": true,
    "prometheusPort": 9090,
    "healthCheckInterval": 30000
  }
}

Deploy:

export DB_PASSWORD="secure_db_password"
export REDIS_PASSWORD="secure_redis_password"
flexgate config import config/flexgate.production.json
npm start

Troubleshooting

Configuration Not Found

Error:

Error: Configuration file not found: config/flexgate.json

Solution:

flexgate init --interactive

Invalid Configuration Value

Error:

Error: Port must be between 1 and 65535

Solution:

# Check valid range
flexgate config set server.port 8080

# View current value
flexgate config get server.port

Database Connection Failed

Error:

❌ Database connection failed
   Error: Connection timeout

Solution:

# Verify config
flexgate config get database.host
flexgate config get database.port

# Update if needed
flexgate config set database.host correct-host
flexgate db test

Redis Connection Failed

Error:

❌ Redis connection failed
   Error: ECONNREFUSED

Solution:

# Check Redis config
flexgate config show

# Test connection
flexgate redis test

# Update if needed
flexgate config set redis.host correct-host

Import Failed

Error:

Error: Invalid JSON in file

Solution:

# Validate JSON syntax
cat config/flexgate.json | jq .

# Or reset and reconfigure
flexgate config reset --force
flexgate init --interactive

Configuration Precedence

FlexGate loads configuration in this order (later overrides earlier):

Default values (in code)
JSON configuration (config/flexgate.json)
Environment variables (.env)
CLI arguments (if provided)

Example:

# JSON: port = 3000
# ENV:  PORT=8080
# CLI:  --port 9000

# Result: 9000 (CLI wins)

Tips & Best Practices

1. Always Test Connections

flexgate db test && flexgate redis test && echo "✅ Ready" || echo "❌ Not ready"

2. Backup Before Changes

flexgate config export backup-$(date +%Y%m%d).json

3. Version Control Configs

git add config/flexgate.production.json
git commit -m "Update production database host"

4. Use Environment Variables for Secrets

Bad:

{"database": {"password": "plaintext_password"}}

Good:

{"database": {"password": "${DB_PASSWORD}"}}

5. Validate After Import

flexgate config import production.json
flexgate config show
flexgate health

Summary

FlexGate CLI provides three configuration methods:

Admin UI - Visual, localhost:3001
CLI - Terminal, this tool
JSON - Direct file editing

Choose CLI for:

✅ EC2/cloud instances
✅ Headless servers
✅ CI/CD automation
✅ Quick configuration changes
✅ Connection testing

No browser needed! 🚀

Additional Resources

Full Guide: CLI_JSON_CONFIGURATION_GUIDE.md
Quick Reference: CLI_QUICK_REFERENCE.md
Troubleshooting: TROUBLESHOOTING_GUIDE.md
API Documentation: docs/api.md

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

FlexGate CLI - Complete Documentation

Table of Contents

Overview

Installation

Global (Recommended)

Local Project

Quick Start

1. Initialize Configuration

2. Verify Configuration

3. Test Connections

4. Start FlexGate

Commands Reference

flexgate init

flexgate config show

flexgate config set

flexgate config get

flexgate config import

flexgate config export

flexgate config reset

flexgate db test

flexgate redis test

flexgate health

Configuration Guide

Configuration File

Environment-Specific Configurations

Use Cases

1. EC2 Deployment

2. Docker Container

3. CI/CD Pipeline

4. GitOps Workflow

5. Batch Configuration

Examples

Complete EC2 Setup Script

Production Configuration Template

Troubleshooting

Configuration Not Found

Invalid Configuration Value

Database Connection Failed

Redis Connection Failed

Import Failed

Configuration Precedence

Tips & Best Practices

1. Always Test Connections

2. Backup Before Changes

3. Version Control Configs

4. Use Environment Variables for Secrets

5. Validate After Import

Summary

Additional Resources

`flexgate init`

`flexgate config show`

`flexgate config set`

`flexgate config get`

`flexgate config import`

`flexgate config export`

`flexgate config reset`

`flexgate db test`

`flexgate redis test`

`flexgate health`