telecom-platform/apps/cli/README.md

Telecom Platform CLI

A comprehensive command-line interface for managing the Telecom Platform, built with Go and enhanced with Bubbletea for interactive TUI features.

Features

• Subscriber Management: Create, read, update, and delete subscribers
• Service Management: Monitor and manage platform services
• Billing Operations: Handle invoices, payments, and billing reports
• Configuration Management: Manage CLI profiles and settings
• Monitoring: Real-time service health and metrics
• Enhanced UI: Beautiful terminal interface with colors and icons
• Multi-format Output: Support for table, JSON, and CSV formats
• Plugin System: Extensible architecture for custom commands

Installation

From Source

git clone https://github.com/nutcas3/telecom-platform.git
cd telecom-platform/apps/cli
go build -o telecom-cli main.go
sudo mv telecom-cli /usr/local/bin/

Using Go Install

go install github.com/nutcas3/telecom-platform/apps/cli@latest

From Binary Release

# Download the latest release for your platform
curl -L https://github.com/nutcas3/telecom-platform/releases/latest/download/telecom-cli-linux-amd64.tar.gz | tar xz
sudo mv telecom-cli /usr/local/bin/

Quick Start

Initial Setup

# Configure the CLI
telecom-cli config set api-endpoint http://localhost:8000
telecom-cli config set api-token your-api-token

# Test connection
telecom-cli health

# List subscribers
telecom-cli subscribers list

Interactive Dashboard

# Launch the interactive dashboard
telecom-cli dashboard

Commands Reference

Global Options

Option	Short	Description
--help	-h	Show help for command
--version	-v	Show version information
--verbose	-V	Enable verbose output
--no-color		Disable colored output
--format	-f	Output format (table, json, csv)
--profile	-p	Use specific profile

Configuration

config

Manage CLI configuration and profiles.

# Show current configuration
telecom-cli config show

# Set configuration values
telecom-cli config set api-endpoint http://api.telecom.local
telecom-cli config set api-token your-token
telecom-cli config set timeout 30

# Get configuration values
telecom-cli config get api-endpoint

# List all profiles
telecom-cli config profiles list

# Create new profile
telecom-cli config profiles create production
telecom-cli config profiles set production.api-endpoint https://api.telecom.com

# Switch profiles
telecom-cli config profiles use production

# Delete profile
telecom-cli config profiles delete staging

Configuration Options

Option	Description	Default
api-endpoint	API server URL	http://localhost:8000
api-token	Authentication token	""
timeout	Request timeout in seconds	30
theme	UI theme	default
colors	Enable colored output	true
pager	Use pager for long output	true

Subscribers

subscribers

Manage platform subscribers.

# List all subscribers
telecom-cli subscribers list

# List with filters
telecom-cli subscribers list --status active
telecom-cli subscribers list --limit 10
telecom-cli subscribers list --format json

# Show subscriber details
telecom-cli subscribers show 123

# Create new subscriber
telecom-cli subscribers create \
  --name "John Doe" \
  --email "[email protected]" \
  --phone "+1234567890"

# Update subscriber
telecom-cli subscribers update 123 \
  --name "John Smith" \
  --email "[email protected]"

# Delete subscriber
telecom-cli subscribers delete 123

# Enhanced listing with styling
telecom-cli subscribers list --enhanced

Subscriber Fields

Field	Type	Required	Description
name	string	Yes	Subscriber name
email	string	Yes	Email address
phone	string	Yes	Phone number
status	string	No	Account status (active, inactive, suspended)
balance	float	No	Current balance

Services

services

Monitor and manage platform services.

# List all services
telecom-cli services list

# Show service details
telecom-cli services show api-server

# Enhanced service monitoring
telecom-cli services list --enhanced

# Service health check
telecom-cli services health

# Service metrics
telecom-cli services metrics --service api-server

# Restart service
telecom-cli services restart api-server

Service Status

Status	Description
running	Service is operational
stopped	Service is not running
degraded	Service is running with issues
maintenance	Service is under maintenance

Billing

billing

Manage billing operations and invoices.

# List invoices
telecom-cli billing invoices

# Show invoice details
telecom-cli billing invoices show INV-001

# Generate invoice
telecom-cli billing generate --subscriber 123 --amount 100.50

# Process payment
telecom-cli billing pay INV-001 --method credit_card

# Billing reports
telecom-cli billing reports --month 2023-12
telecom-cli billing reports --subscriber 123 --year 2023

# Enhanced billing view
telecom-cli billing invoices --enhanced

Payment Methods

Method	Description
credit_card	Credit card payment
bank_transfer	Bank transfer
paypal	PayPal payment
crypto	Cryptocurrency payment

Monitoring

monitoring

Real-time monitoring and metrics.

# System health
telecom-cli monitoring health

# Service metrics
telecom-cli monitoring metrics --service api-server

# Resource usage
telecom-cli monitoring resources

# Alert status
telecom-cli monitoring alerts

# Logs
telecom-cli monitoring logs --service api-server --tail 100

# Real-time monitoring
telecom-cli monitoring watch --refresh 5

Metrics Categories

Category	Description
cpu	CPU usage percentage
memory	Memory usage in MB
network	Network I/O
storage	Disk usage
requests	HTTP request metrics
errors	Error rates

Deployment

deploy

Deploy and manage platform deployments.

# Deploy to environment
telecom-cli deploy --environment staging

# Check deployment status
telecom-cli deploy status --environment staging

# Rollback deployment
telecom-cli deploy rollback --environment staging --version v1.0.1

# List deployments
telecom-cli deploy list

# Deployment history
telecom-cli deploy history --environment production

Dashboard

dashboard

Launch interactive TUI dashboard.

# Start dashboard
telecom-cli dashboard

# Dashboard with specific theme
telecom-cli dashboard --theme dark

# Dashboard with auto-refresh
telecom-cli dashboard --refresh 10

Dashboard Features

• Service Status: Real-time service health
• Metrics Charts: CPU, memory, and network usage
• Subscriber Overview: Active subscribers and statistics
• Billing Summary: Revenue and payment status
• Logs Viewer: Real-time log streaming
• Alerts Panel: Active alerts and notifications

Output Formats

Table Format (Default)

telecom-cli subscribers list

+----+------------+-------------------+--------------+--------+
| ID | Name       | Email             | Phone        | Status |
+----+------------+-------------------+--------------+--------+
| 1  | John Doe   | [email protected]  | +1234567890  | active |
| 2  | Jane Smith | [email protected]  | +0987654321  | active |
+----+------------+-------------------+--------------+--------+

JSON Format

telecom-cli subscribers list --format json

{
  "subscribers": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "status": "active",
      "balance": 100.50
    }
  ],
  "total": 1
}

CSV Format

telecom-cli subscribers list --format csv

id,name,email,phone,status,balance
1,John Doe,[email protected],+1234567890,active,100.50

Profiles

Profile Management

Profiles allow you to switch between different configurations (development, staging, production).

# Create production profile
telecom-cli config profiles create production
telecom-cli config profiles set production.api-endpoint https://api.telecom.com
telecom-cli config profiles set production.api-token prod-token

# Switch to production profile
telecom-cli config profiles use production

# List profiles
telecom-cli config profiles list

Profile Structure

production:
  api:
    endpoint: https://api.telecom.com
    token: prod-token
    timeout: 60
  ui:
    theme: dark
    colors: true
    pager: false
  logging:
    level: warn
    format: json

Themes

Available Themes

Theme	Description
default	Standard terminal colors
dark	Dark theme for better contrast
light	Light theme for bright terminals
minimal	Minimal styling without colors

Custom Themes

Create custom themes by modifying the configuration:

telecom-cli config set ui.theme custom
telecom-cli config set ui.colors.primary blue
telecom-cli config set ui.colors.success green
telecom-cli config set ui.colors.error red

Plugins

Installing Plugins

# Install plugin from repository
telecom-cli plugins install telecom-cli-aws

# Install from local file
telecom-cli plugins install ./custom-plugin.so

# List installed plugins
telecom-cli plugins list

# Enable/disable plugins
telecom-cli plugins enable aws
telecom-cli plugins disable aws

Creating Plugins

Create custom plugins using the plugin API:

package main

import (
    "github.com/nutcas3/telecom-platform/apps/cli/internal/plugin"
)

type AWSPlugin struct{}

func (p *AWSPlugin) Name() string {
    return "aws"
}

func (p *AWSPlugin) Commands() []plugin.Command {
    return []plugin.Command{
        {
            Name:        "deploy",
            Description: "Deploy to AWS",
            Handler:     p.deploy,
        },
    }
}

func (p *AWSPlugin) deploy(args []string) error {
    // Plugin implementation
    return nil
}

Environment Variables

Variable	Description	Default
TELECOM_API_ENDPOINT	API server URL	""
TELECOM_API_TOKEN	Authentication token	""
TELECOM_CONFIG_FILE	Configuration file path	~/.telecom/config.yaml
TELECOM_NO_COLOR	Disable colors	false
TELECOM_VERBOSE	Enable verbose output	false

Configuration File

The CLI configuration is stored in ~/.telecom/config.yaml:

profiles:
  default:
    api:
      endpoint: http://localhost:8000
      token: ""
      timeout: 30
    ui:
      theme: default
      colors: true
      pager: true
    logging:
      level: info
      format: text

current_profile: default
plugins:
  enabled: []
  disabled: []

Examples

Common Workflows

1. Daily Operations

# Check system health
telecom-cli health

# Review new subscribers
telecom-cli subscribers list --status new --enhanced

# Check service status
telecom-cli services list --enhanced

# Review billing
telecom-cli billing invoices --unpaid

2. Troubleshooting

# Check service logs
telecom-cli monitoring logs --service api-server --tail 100

# View metrics
telecom-cli monitoring metrics --service api-server

# Check system resources
telecom-cli monitoring resources

3. Deployment

# Deploy to staging
telecom-cli deploy --environment staging

# Monitor deployment
telecom-cli deploy status --environment staging

# Check health after deployment
telecom-cli health --environment staging

Advanced Usage

Batch Operations

# Export subscribers to CSV
telecom-cli subscribers list --format csv > subscribers.csv

# Bulk update subscribers
while read line; do
  telecom-cli subscribers update $line
done < updates.txt

Automation Scripts

#!/bin/bash
# health-check.sh

# Check system health
if ! telecom-cli health; then
  echo "System unhealthy!" >&2
  exit 1
fi

# Check critical services
services=("api-server" "charging-engine" "packet-gateway")
for service in "${services[@]}"; do
  if ! telecom-cli services show $service | grep -q "running"; then
    echo "Service $service not running!" >&2
    exit 1
  fi
done

echo "All systems healthy"

Troubleshooting

Common Issues

Connection Issues

# Check API endpoint
telecom-cli config get api-endpoint

# Test connection
telecom-cli health --verbose

# Check timeout settings
telecom-cli config get timeout

Authentication Issues

# Verify API token
telecom-cli config get api-token

# Test with different token
TELECOM_API_TOKEN=new-token telecom-cli health

Performance Issues

# Check response times
telecom-cli health --verbose

# Use JSON format for faster processing
telecom-cli subscribers list --format json

Debug Mode

Enable debug mode for detailed troubleshooting:

# Enable verbose output
telecom-cli --verbose subscribers list

# Set debug log level
telecom-cli config set logging.level debug

# Enable request tracing
telecom-cli config set api.trace true

Contributing

Development Setup

# Clone repository
git clone https://github.com/nutcas3/telecom-platform.git
cd telecom-platform/apps/cli

# Install dependencies
go mod download

# Run tests
go test ./...

# Build development version
go build -o telecom-cli main.go

Running Tests

# Run all tests
go test ./...

# Run integration tests
go test ./tests/... -v

# Run benchmarks
go test ./tests/... -bench=.

# Test coverage
go test ./... -cover

Code Style

The project uses the standard Go formatting tools:

# Format code
go fmt ./...

# Run linter
golangci-lint run

# Run static analysis
go vet ./...

Support

• Documentation: https://docs.telecom-platform.com
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Community: Discord Server

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v1.0.0 (2023-12-01)

• Initial release
• Core subscriber and service management
• Enhanced UI with Bubbletea
• Multi-format output support
• Profile management
• Plugin system
• Interactive dashboard

v1.1.0 (2023-12-15)

• Added billing commands
• Enhanced monitoring features
• Improved error handling
• Performance optimizations

v1.2.0 (2024-01-01)

• Added deployment commands
• Enhanced plugin system
• New themes and styling options
• Better configuration management