Custom CLI v1.0.0 🚀

Create Your Own Custom CLI Commands

A custom CLI tool where anyone can create their own commands to run one or multiple chained apps using a simple YAML file to arrange the apps and the CLI alias name. Build personalized development workflows with dependency management, health monitoring, and complete customization.

✨ Features

• 🎯 Create Custom Commands - Design your own CLI with any name you want
• 🔧 Simple YAML Configuration - Define your apps and commands in one file
• ⚡ Chain Multiple Apps - Start multiple services with dependencies in correct order
• 🏥 Smart Health Monitoring - Real health checks, not just port availability
• 📊 Automatic Orchestration - Services start and stop in dependency order with rollback
• 🛠️ npm/yarn Integration - Run any npm scripts or shell commands
• 🔄 Unlimited Flexibility - Create as many custom CLI tools as you need

🚀 Quick Start

1. Installation

# Clone or download the CLI to your preferred locationcd~/Repos/custom-cli
# Run the installation script
./install.sh
# Reload your shellsource~/.bashrc # or ~/.zshrc

2. Setup Configuration

# Copy the sample configuration and customize it
cp config.yaml.sample config.yaml
# Edit config.yaml to add your projects and services# Key things to customize:# - Change 'reposDir' to your projects directory (e.g., ${HOME}/Projects)# - Update service directories to match your project paths# - Modify service names, ports, and commands for your apps# - Set your preferred CLI name in global.cliName

3. Test Installation

# Test the CLI
./bin/custom-cli --version
./bin/custom-cli help

🎯 Creating Custom Aliases

Method 1: Shell Alias (Recommended)

Create a custom alias to run the CLI with your preferred name:

# Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profilealias my-dev-cli="~/Repos/custom-cli/bin/custom-cli"alias frontend-tools="~/Repos/custom-cli/bin/custom-cli"alias project-manager="~/Repos/custom-cli/bin/custom-cli"# Reload your shellsource~/.bashrc # or ~/.zshrc# Now use your custom name
my-dev-cli help
frontend-tools start webapp
project-manager status api

Method 2: Custom Wrapper Script

Create a dedicated wrapper script for your project:

#!/bin/bash# ~/bin/my-project-cliexec~/Repos/custom-cli/bin/custom-cli "$@"

# Make it executable and add to PATH
chmod +x ~/bin/my-project-cli
echo'export PATH="$HOME/bin:$PATH"'>>~/.bashrc
source~/.bashrc
# Use your custom CLI
my-project-cli help

Method 3: Symlink

# Create a symlink with your preferred name
ln -s ~/Repos/custom-cli/bin/custom-cli ~/bin/my-cli
echo'export PATH="$HOME/bin:$PATH"'>>~/.bashrc
source~/.bashrc
# Use the symlinked name
my-cli --version

🔧 Configuration Guide

Getting Started with config.yaml

Use the provided sample file as your starting point:

# Copy the sample configuration
cp config.yaml.sample config.yaml
# Customize for your projects
nano config.yaml # or your preferred editor

Understanding config.yaml

All services and environments are defined in config.yaml. Here's the basic structure:

# Individual service definitionsservices:
my-frontend:
port: 3000directory: ${REPOS_DIR}/my-frontendcommand: npm run devtimeout: 60healthUrl: http://localhost:3000displayName: Frontend Appdependencies: []my-api:
port: 8080directory: ${REPOS_DIR}/my-apicommand: npm run start:devtimeout: 30healthUrl: http://localhost:8080/healthdisplayName: API Serverdependencies: []# Composite service environmentscomposites:
fullstack:
services:
- my-api
- my-frontenddisplayName: Complete Fullstack Environmentdescription: API server + Frontend application# Global configurationglobal:
reposDir: ${HOME}/ProjectscliName: my-custom-cliversion: 1.0.0

📦 Adding npm-based Web Applications

The config.yaml.sample file includes many examples of common web applications. You can use these as templates for your own projects.

Step 1: Define the Service

Add your npm-based application to the services section in config.yaml. Here are some examples (also available in config.yaml.sample):

services:
# React App Examplereact-app:
port: 3000directory: ${REPOS_DIR}/my-react-appcommand: npm starttimeout: 60healthUrl: http://localhost:3000displayName: React Applicationdependencies: []# Vite App Examplevite-app:
port: 5173directory: ${REPOS_DIR}/my-vite-appcommand: npm run devtimeout: 45healthUrl: http://localhost:5173displayName: Vite Development Serverdependencies: []# Next.js App Examplenextjs-app:
port: 3000directory: ${REPOS_DIR}/my-nextjs-appcommand: npm run devtimeout: 60healthUrl: http://localhost:3000displayName: Next.js Applicationdependencies: []# Express API Exampleexpress-api:
port: 8080directory: ${REPOS_DIR}/my-express-apicommand: npm run devtimeout: 30healthUrl: http://localhost:8080/api/healthdisplayName: Express API Serverdependencies: []# Vue.js App Examplevue-app:
port: 8080directory: ${REPOS_DIR}/my-vue-appcommand: npm run servetimeout: 45healthUrl: http://localhost:8080displayName: Vue.js Applicationdependencies: []

Step 2: Create Composite Environments

Group related services into environments:

composites:
# Frontend-only environmentfrontend:
services:
- react-appdisplayName: Frontend Developmentdescription: React application only# Full-stack environment with dependenciesfullstack:
services:
- express-api
- react-appdisplayName: Complete Development Environmentdescription: Express API + React frontend (API starts first)# Multi-app environmentmulti-frontend:
services:
- react-app
- vue-app
- vite-appdisplayName: Multi-Frontend Testingdescription: Multiple frontend frameworks running simultaneously

Step 3: Configure Dependencies

Services can depend on others, ensuring they start in the correct order:

services:
database:
port: 5432directory: ${REPOS_DIR}/databasecommand: npm run start:localtimeout: 30healthUrl: ""# Uses port-based health checkdisplayName: Local Databasedependencies: []api-server:
port: 8080directory: ${REPOS_DIR}/api-servercommand: npm run devtimeout: 30healthUrl: http://localhost:8080/healthdisplayName: API Serverdependencies:
- database # Waits for database to be healthy firstfrontend-app:
port: 3000directory: ${REPOS_DIR}/frontend-appcommand: npm starttimeout: 60healthUrl: http://localhost:3000displayName: Frontend Applicationdependencies:
- api-server # Waits for API to be healthy first

🎮 Usage Examples

Using Your Custom CLI

After creating an alias called my-dev-cli:

# Start individual services
my-dev-cli start react-app
my-dev-cli start express-api
# Start composite environments
my-dev-cli start fullstack # Starts API, then React app
my-dev-cli start frontend # Starts just the React app# Check status
my-dev-cli status fullstack
my-dev-cli status react-app
# Stop services
my-dev-cli stop fullstack
my-dev-cli stop react-app
# View logs
my-dev-cli logs
# Get help
my-dev-cli help

Real-world Examples

E-commerce Development Stack

services:
postgres-db:
port: 5432directory: ${REPOS_DIR}/ecommerce-dbcommand: npm run start:localtimeout: 30displayName: PostgreSQL Databasedependencies: []ecommerce-api:
port: 3001directory: ${REPOS_DIR}/ecommerce-apicommand: npm run devtimeout: 30healthUrl: http://localhost:3001/api/healthdisplayName: E-commerce APIdependencies:
- postgres-dbadmin-dashboard:
port: 3002directory: ${REPOS_DIR}/admin-dashboardcommand: npm starttimeout: 60healthUrl: http://localhost:3002displayName: Admin Dashboarddependencies:
- ecommerce-apicustomer-frontend:
port: 3000directory: ${REPOS_DIR}/customer-appcommand: npm run devtimeout: 60healthUrl: http://localhost:3000displayName: Customer Frontenddependencies:
- ecommerce-apicomposites:
ecommerce:
services:
- postgres-db
- ecommerce-api
- admin-dashboard
- customer-frontenddisplayName: Complete E-commerce Stackdescription: Database + API + Admin Dashboard + Customer Frontendapi-only:
services:
- postgres-db
- ecommerce-apidisplayName: Backend Services Onlydescription: Database + API for backend development

Microservices Development

services:
user-service:
port: 3001directory: ${REPOS_DIR}/user-servicecommand: npm run devhealthUrl: http://localhost:3001/healthdisplayName: User Servicedependencies: []product-service:
port: 3002directory: ${REPOS_DIR}/product-servicecommand: npm run devhealthUrl: http://localhost:3002/healthdisplayName: Product Servicedependencies: []order-service:
port: 3003directory: ${REPOS_DIR}/order-servicecommand: npm run devhealthUrl: http://localhost:3003/healthdisplayName: Order Servicedependencies:
- user-service
- product-serviceapi-gateway:
port: 8080directory: ${REPOS_DIR}/api-gatewaycommand: npm run devhealthUrl: http://localhost:8080/healthdisplayName: API Gatewaydependencies:
- user-service
- product-service
- order-servicecomposites:
microservices:
services:
- user-service
- product-service
- order-service
- api-gatewaydisplayName: Complete Microservices Stackdescription: All services + API Gateway

🔧 Advanced Configuration

Environment Variables

Use environment variables in your configuration:

global:
reposDir: ${HOME}/ProjectslogsDir: ${REPOS_DIR}/custom-cli/.logsservices:
my-app:
port: ${PORT:-3000} # Use PORT env var, default to 3000directory: ${REPOS_DIR}/${APP_NAME:-my-app}command: npm run ${NODE_ENV:-dev}

Custom Health Checks

Configure different types of health checks:

services:
# HTTP health checkapi-with-health:
port: 8080command: npm run devhealthUrl: http://localhost:8080/api/health# Port-based health check (no URL)simple-service:
port: 3000command: npm starthealthUrl: ""# Will check if port is responding# No health check (careful!)background-service:
port: ""# No port to checkcommand: npm run backgroundhealthUrl: ""

Timeouts and Retry Logic

Configure startup timeouts:

services:
slow-service:
port: 3000command: npm run build-and-serve # Takes longertimeout: 120# Wait up to 2 minutesfast-service:
port: 8080command: npm run quick-starttimeout: 15# Should start quickly

🛠️ CLI Commands

# Version information
my-cli --version # Show version
my-cli version-debug # Detailed system info# Service management
my-cli start <environment># Start service environment
my-cli stop <environment># Stop service environment
my-cli status <environment># Check service status
my-cli logs # View log files# Debug commands
my-cli config-debug # Show configuration
my-cli test-dependencies # Test dependency resolution
my-cli test-service-interface # Validate service definitions
my-cli test-logging # Test logging system# Help
my-cli help# Show help

🏗️ Architecture

custom-cli/
├── bin/custom-cli # Main executable
├── config.yaml # Service & environment definitions
├── lib/ # Core modules
│ ├── config.sh # Configuration management
│ ├── logging.sh # Structured logging
│ ├── service_orchestrator.sh # Service management
│ ├── yaml.sh # YAML parsing
│ └── ... # Other utility modules
├── legacy/ # Legacy script support
└── tests/ # Unit tests

🔍 Troubleshooting

Common Issues

Services not found:

# Check your configuration
my-cli config-debug
# Verify service names match config.yaml
my-cli test-dependencies

Health checks failing:

# Check if the service actually provides a health endpoint
curl http://localhost:3000/health
# Use port-based health checks if no endpoint exists
healthUrl: ""# In config.yaml

Dependencies not working:

# Test dependency resolution
my-cli test-dependencies
# Check service startup order in logs
my-cli logs

📝 Examples Repository

For more examples and templates, check out:

• React + Express fullstack setup
• Microservices with API Gateway
• Multi-database development environment
• Frontend testing with multiple frameworks

🤝 Contributing

1. Fork the repository
2. Add your service configurations to config.yaml
3. Test with ./bin/custom-cli test-dependencies
4. Submit a pull request

📄 License

This project is licensed under the MIT License.

---

Need help? Run my-cli help or check the configuration with my-cli config-debug