Moai Domain CLI Tool

Enterprise CLI Tool Architecture - v4.0.0

Level 1: Quick Reference

Core CLI Patterns

Rust Clap v4.5 Foundation:

use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "myapp")]
#[command(about = "A great CLI tool")]
#[command(version)]
struct Args {
    #[command(subcommand)]
    command: Option<Commands>,
    #[arg(short, long)]
    verbose: bool,
    #[arg(short, long)]
    config: Option<String>,
}

#[derive(Subcommand)]
enum Commands {
    Run {
        #[arg(value_name = "FILE")]
        input: String,
        #[arg(short, long)]
        output: Option<String>,
    },
    Status,
}

fn main() {
    let args = Args::parse();
    match args.command {
        Some(Commands::Run { input, output }) => {
            println!("Running with input: {}", input);
            if let Some(out) = output {
                println!("Output to: {}", out);
            }
        }
        Some(Commands::Status) => println!("Status: OK"),
        None => println!("No command provided"),
    }
}

Go Cobra v1.8 Foundation:

package main

import (
	"fmt"
	"github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
	Use:   "myapp",
	Short: "A great CLI tool",
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("myapp running")
	},
}

func init() {
	rootCmd.AddCommand(runCmd)
	runCmd.Flags().StringP("output", "o", "", "Output file")
}

func main() {
	if err := rootCmd.Execute(); err != nil {
		fmt.Println(err)
	}
}

Node Commander v14.x Foundation:

import { program } from 'commander';

program
  .name('myapp')
  .description('A great CLI tool')
  .version('1.0.0');

program
  .command('run <file>')
  .description('Run the application')
  .option('-o, --output <file>', 'Output file')
  .action((file, options) => {
    console.log(`Running with: ${file}`);
    if (options.output) {
      console.log(`Output to: ${options.output}`);
    }
  });

program.parse();

Core Principles:

• ✅ Clear subcommand structure
• ✅ Type safety (Rust/Go)
• ✅ Auto help generation
• ✅ Version management
• ✅ Consistent flag naming

Level 2: Core Implementation

Advanced CLI Features

Plugin Architecture (Rust):

use std::fs;
use std::path::PathBuf;

pub trait CliPlugin: Send + Sync {
    fn name(&self) -> &str;
    fn version(&self) -> &str;
    fn execute(&self, args: &[String]) -> Result<(), String>;
}

pub struct PluginLoader {
    plugin_dir: PathBuf,
}

impl PluginLoader {
    pub fn discover_plugins(&self) -> Result<Vec<String>, String> {
        let entries = fs::read_dir(&self.plugin_dir)
            .map_err(|e| e.to_string())?;
        
        let mut plugins = Vec::new();
        for entry in entries.flatten() {
            let path = entry.path();
            if path.extension().and_then(|s| s.to_str()) == Some("so") {
                if let Some(name) = path.file_stem() {
                    if let Some(name_str) = name.to_str() {
                        plugins.push(name_str.to_string());
                    }
                }
            }
        }
        Ok(plugins)
    }
}

Configuration Management (Go + YAML):

type Config struct {
	App struct {
		Name    string `yaml:"name"`
		Version string `yaml:"version"`
		Debug   bool   `yaml:"debug"`
	} `yaml:"app"`
	Database struct {
		Host     string `yaml:"host"`
		Port     int    `yaml:"port"`
		Database string `yaml:"database"`
	} `yaml:"database"`
}

func LoadConfig(path string) (*Config, error) {
	data, err := ioutil.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("failed to read config: %w", err)
	}
	
	var cfg Config
	if err := yaml.Unmarshal(data, &cfg); err != nil {
		return nil, fmt.Errorf("failed to parse config: %w", err)
	}
	
	return &cfg, nil
}

Shell Completion (Node.js):

class ShellCompletion {
  generateBashCompletion(commands, options) {
    const template = `
_myapp_completion() {
  local cur prev commands
  COMPREPLY=()
  cur="\${COMP_WORDS[COMP_CWORD]}"
  commands="${commands.join(' ')}"
  
  if [[ \${cur} == -* ]]; then
    COMPREPLY=($(compgen -W "${options.join(' ')}" -- \${cur}))
  else
    COMPREPLY=($(compgen -W "\${commands}" -- \${cur}))
  fi
}
complete -F _myapp_completion myapp`;
    return template.trim();
  }
}

Error Handling & UX:

type CliError struct {
	Code    int
	Message string
	Details string
}

func (e *CliError) Error() string {
	return fmt.Sprintf("[ERROR %d] %s: %s", e.Code, e.Message, e.Details)
}

func exitWithError(code int, message string, details string) {
	err := &CliError{Code: code, Message: message, Details: details}
	log.Printf("FATAL: %v", err)
	fmt.Fprintf(os.Stderr, "%v\n", err)
	os.Exit(code)
}

Level 3: Advanced Features

Production-Grade CLI Architecture

Complete Enterprise CLI (Rust):

use clap::{Parser, Subcommand};
use anyhow::{Result, Context};

#[derive(Parser)]
#[command(name = "enterprise-cli")]
#[command(version = "1.0.0")]
struct Args {
    #[command(subcommand)]
    command: Commands,
    #[arg(global = true, short, long)]
    config: Option<PathBuf>,
    #[arg(global = true, short, long)]
    verbose: u8,
}

#[derive(Subcommand)]
enum Commands {
    Init {
        #[arg(value_name = "PROJECT")]
        name: String,
        #[arg(short, long)]
        template: Option<String>,
    },
    Build {
        #[arg(short, long)]
        release: bool,
        #[arg(short, long)]
        target: Option<String>,
    },
    Deploy {
        #[arg(value_name = "ENV")]
        environment: String,
        #[arg(short, long)]
        dry_run: bool,
    },
}

async fn handle_init(name: String, template: Option<String>) -> Result<()> {
    fs::create_dir_all(&name)?;
    
    let config = ProjectConfig {
        name: name.clone(),
        version: "0.1.0".to_string(),
        targets: vec!["x86_64-unknown-linux-gnu".to_string()],
    };
    
    let config_content = serde_yaml::to_string(&config)?;
    fs::write(format!("{}/.cli-config.yaml", name), config_content)?;
    
    println!("Project '{}' initialized successfully!", name);
    Ok(())
}

Multi-Platform Deployment:

name: Release CLI
on:
  push:
    tags: ['v*']
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo build --release
      - uses: softprops/action-gh-release@v2
        with:
          files: target/release/myapp

Docker Distribution:

FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/myapp /usr/local/bin/
ENTRYPOINT ["myapp"]

Level 4: Reference & Integration

Best Practices

User Experience (UX):

• ✅ Clear error messages with hints
• ✅ Progress indicators for long operations
• ✅ Consistent command structure
• ✅ Auto-completion support

Developer Experience (DX):

• ✅ Type-safe argument parsing
• ✅ Comprehensive error handling
• ✅ Modular architecture
• ✅ Plugin system support

Performance Guidelines:

• ✅ < 100ms startup time (native)
• ✅ 100-500ms acceptable (Node.js/Python)
• ✅ > 2s requires optimization

Framework Versions

• Rust Clap: 4.5 (latest)
• Go Cobra: 1.8 (stable)
• Node Commander: 14.x (current)

Related Skills:

• Skill("moai-domain-devops") for deployment patterns
• Skill("moai-essentials-perf") for performance optimization
• Skill("moai-security-backend") for CLI security

Version: 4.0.0 Enterprise
Last Updated: 2025-11-13
Status: Production Ready