250-cli

CLI Application Engineering Ruleset

Goal: Build secure, user-friendly, debuggable command-line interfaces that follow platform conventions.

Core Principles

• User Experience First: Clear error messages, helpful usage, intuitive flags
• Debuggability: Always provide debug mode for troubleshooting
• Security: Never log secrets, validate inputs, fail fast
• Platform Conventions: Follow platform-specific CLI patterns

Debug Mode Patterns

Environment Variable Pattern

# Enable debug mode
DEBUG=1 my-cli command

# Or with specific namespaces
DEBUG=my-cli:* my-cli command

Command-Line Flag Pattern

# Enable debug mode
my-cli --debug command

# Verbose mode (different from debug)
my-cli --verbose command

# Quiet mode
my-cli --quiet command

Implementation Examples

Python

import os
import logging
import sys

# Setup logging
log_level = logging.INFO
if os.getenv("DEBUG") == "1" or "--debug" in sys.argv:
    log_level = logging.DEBUG

logging.basicConfig(
    level=log_level,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

def main():
    logger.debug("Debug mode enabled")
    # ... rest of CLI logic

Node.js / JavaScript

Use the debug library:

import debug from 'debug';

// Enable debug via environment variable
// DEBUG=1 npm start
// DEBUG=my-cli:* npm start
// DEBUG=my-cli:auth npm start

const debugLog = debug('my-cli:main');
const authDebug = debug('my-cli:auth');

function main() {
  debugLog('Starting CLI application');
  authDebug('Authenticating user');
  // ... rest of CLI logic
}

// Enable debug output
if (process.env.DEBUG || process.env.AI_DEBUG_ENABLE === "1") {
  debug.enabled = true;
}

Go

package main

import (
    "flag"
    "log"
    "os"
)

var (
    debugFlag = flag.Bool("debug", false, "Enable debug logging")
    verboseFlag = flag.Bool("verbose", false, "Enable verbose output")
)

func main() {
    flag.Parse()

    // Check environment variable
    debugMode := *debugFlag || os.Getenv("DEBUG") == "1"

    if debugMode {
        log.SetFlags(log.LstdFlags | log.Lshortfile)
        log.SetOutput(os.Stderr)
    }

    log.Printf("Debug mode: %v", debugMode)
    // ... rest of CLI logic
}