ADR-019: CLI Command Structure Redesign

Status

Proposed

Date

2025-12-07

Deciders

• Project maintainers

Context and Problem Statement

The idempiere-cli has grown organically to serve multiple purposes:

1. Application Dictionary management - Primary use case for iDempiere developers
2. MCP server - AI assistant integration (Claude Code, Claude Desktop)
3. AI entrypoint - Natural language interface to CLI operations
4. M2M API - CI/CD pipelines, scripting, automation (ADR-006)

The current command structure has inconsistencies:

• Hyphenated vs single-word commands (migration-script vs batch)
• Numeric prefixes (2pack)
• Duplicate functionality (export + 2pack generate)
• Scattered related commands (3 IDE configs, 4 server commands)
• Unclear abbreviations (ad for Application Dictionary)

Decision Drivers

• Discoverability: Commands should be intuitive and easy to find
• Consistency: Naming patterns should be uniform across all commands
• Grouping: Related commands should be logically organized
• M2M compatibility: Commands must work well in scripts and CI/CD
• Multi-purpose CLI: Structure must support all four use cases
• AI/LLM native understanding: Commands must be semantically clear for AI assistants

Considered Options

1. Prefix-based grouping with ad - Use short ad prefix for Application Dictionary
2. Prefix-based grouping with dict - Use clearer dict prefix for Dictionary
3. Resource-based naming - Use resource names as top-level commands (table, window, process)
4. Hybrid approach - Domain prefixes for groups, resource-based for common operations

Decision Outcome

Chosen option: "Option 4: Hybrid approach with dict prefix", because it provides clear grouping for Application Dictionary operations while keeping the most common commands accessible and supporting all CLI use cases.

Confirmation

• All commands accessible via idempiere-cli --help
• Each command group has clear description
• No duplicate functionality between commands
• Backward compatibility aliases work for common commands

Command Structure

Top-Level Categories

idempiere-cli
│
├── dev          # Development environment setup
├── dict         # Application Dictionary management
├── gen          # Code generation (Java source files)
├── pack         # 2Pack and migration management
├── ide          # IDE configuration
├── env          # Environment management (staging, restore, deploy)
├── server       # Server management and MCP
├── ai           # AI-powered features
└── util         # Utility commands

Complete Command Tree

idempiere-cli
│
├── dev                              # Development Environment
│   ├── init                         # Scaffold new plugin project
│   ├── doctor                       # Check required tools and dependencies
│   ├── setup                        # Bootstrap iDempiere development environment
│   └── config                       # Configure REST API and database connections
│
├── dict                             # Application Dictionary
│   ├── table                        # Table operations
│   │   ├── add                      # Create AD_Table record
│   │   ├── sync                     # Sync table to database (Process 291)
│   │   ├── query                    # Query table metadata
│   │   └── export                   # Export table to 2Pack/SQL
│   │
│   ├── column                       # Column operations
│   │   ├── add                      # Create AD_Column record
│   │   ├── sync                     # Sync column to database (Process 306)
│   │   └── query                    # Query column metadata
│   │
│   ├── window                       # Window operations
│   │   ├── create                   # Generate Window/Tab/Field from table
│   │   └── query                    # Query window metadata
│   │
│   ├── process                      # Process operations
│   │   ├── add                      # Create AD_Process record
│   │   └── query                    # Query process metadata
│   │
│   ├── reference                    # Reference operations
│   │   ├── add                      # Create AD_Reference record
│   │   ├── list                     # Add AD_Ref_List entries
│   │   └── query                    # Query reference metadata
│   │
│   ├── menu                         # Menu operations
│   │   ├── add                      # Create menu entry
│   │   └── query                    # Query menu structure
│   │
│   ├── validation                   # Validation rule operations
│   │   └── add                      # Create AD_Val_Rule record
│   │
│   ├── element                      # AD_Element operations
│   │   └── query                    # Query elements
│   │
│   ├── translation                  # Translation operations
│   │   ├── export                   # Export translations to XML
│   │   └── import                   # Import translations from XML
│   │
│   └── query                        # General AD queries (shortcut)
│       ├── tables                   # List all tables
│       ├── windows                  # List all windows
│       ├── processes                # List all processes
│       └── references               # List all references
│
├── gen                              # Code Generation (Java files)
│   ├── model                        # Generate X_/I_ model classes
│   ├── callout                      # Generate callout class
│   ├── process                      # Generate process class
│   └── event                        # Generate event handler class
│
├── pack                             # PackOut - Export Plugin Changes
│   ├── out                          # Export AD changes to PackOut.xml
│   │   ├── --table                  # Include table definitions
│   │   ├── --window                 # Include window definitions
│   │   ├── --process                # Include process definitions
│   │   ├── --output, -o             # Save to local file
│   │   └── --push                   # Push to iDempiere server
│   ├── in                           # Import PackOut via REST API (PackIn)
│   ├── validate                     # Validate PackOut file (ZIP or XML)
│   ├── diff                         # Show changes since last packout
│   └── migration                    # Manage migration scripts
│       ├── create                   # Create new migration script
│       ├── list                     # List migration scripts
│       └── apply                    # Apply migration scripts
│
├── ide                              # IDE Configuration
│   ├── eclipse                      # Generate Eclipse PDE configuration
│   ├── intellij                     # Generate IntelliJ IDEA configuration
│   └── vscode                       # Generate VS Code configuration
│
├── env                              # Environment Management (DevOps)
│   ├── backup                       # Backup operations
│   │   ├── create                   # Create database backup
│   │   └── list                     # List available backups
│   ├── restore                      # Restore database from backup
│   ├── deploy                       # Deploy to environment
│   │   ├── staging                  # Deploy to staging
│   │   └── production               # Deploy to production (with safeguards)
│   ├── clone                        # Clone environment
│   │   └── from-production          # Clone production to staging/dev
│   └── status                       # Show environment status
│
├── server                           # Server Management
│   ├── cache                        # Manage server caches
│   │   ├── list                     # List cache entries
│   │   └── reset                    # Reset cache
│   ├── jobs                         # Manage scheduler jobs
│   │   └── list                     # List scheduled jobs
│   ├── workflow                     # Manage workflow activities
│   │   ├── list                     # List pending activities
│   │   └── approve                  # Approve workflow activity
│   └── mcp                          # Start MCP server for AI assistants
│
├── ai                               # AI Features
│   ├── ask                          # Natural language CLI interface (LangChain4j)
│   ├── generate                     # AI-powered code generation
│   ├── models                       # List available AI models
│   └── providers                    # List AI providers
│
└── util                             # Utilities
    ├── batch                        # Execute commands from file
    ├── watch                        # Watch for changes and auto-execute
    └── plugin                       # Manage CLI plugins
        ├── list                     # List installed plugins
        ├── install                  # Install plugin
        └── uninstall                # Uninstall plugin

Command Descriptions

Migration from Current Commands

Backward Compatibility Aliases

To maintain backward compatibility, keep aliases for the most common commands:

Removed Duplicates

Usage Examples

Development Setup

# Initialize new plugin
idempiere-cli dev init org.example.myplugin --name "My Plugin"

# Check environment
idempiere-cli dev doctor

# Configure connections
idempiere-cli dev config --db-url jdbc:postgresql://localhost/idempiere

# Or use top-level aliases (backward compatible)
idempiere-cli init org.example.myplugin
idempiere-cli doctor

Application Dictionary Operations

# Create table
idempiere-cli dict table add XX_MyTable --entity-type "D"

# Add columns
idempiere-cli dict column add XX_MyTable.Name --type String --length 60
idempiere-cli dict column add XX_MyTable.IsActive --type YesNo --default Y

# Sync to database
idempiere-cli dict table sync XX_MyTable

# Query metadata
idempiere-cli dict query tables --filter "XX_%"
idempiere-cli dict table query XX_MyTable

# Create window
idempiere-cli dict window create XX_MyTable --name "My Window"

# Add process
idempiere-cli dict process add ImportProducts --classname "org.example.ImportProducts"

# Add reference list
idempiere-cli dict reference add XX_Status --type List
idempiere-cli dict reference list XX_Status --value "DR" --name "Draft"
idempiere-cli dict reference list XX_Status --value "CO" --name "Completed"

# Export translations
idempiere-cli dict translation export --table XX_MyTable --language es_MX

Code Generation

# Generate model classes
idempiere-cli gen model XX_MyTable -o src/main/java -p org.example.model

# Generate process class
idempiere-cli gen process ImportProducts -o src/main/java -p org.example.process

# Generate callout
idempiere-cli gen callout ValidateOrder -o src/main/java -p org.example.callout

# Generate event handler
idempiere-cli gen event OrderCompletedHandler -o src/main/java -p org.example.event

PackOut - Export Plugin Changes

# Export AD changes to local PackOut.xml
idempiere-cli pack out --table XX_MyTable -o META-INF/2Pack.zip

# Export with multiple elements
idempiere-cli pack out --table XX_MyTable --window "My Window" --process ImportProducts -o plugin.zip

# Push changes directly to iDempiere server
idempiere-cli pack out --table XX_MyTable --push

# Show what changed since last packout
idempiere-cli pack diff

# Validate PackOut file before commit
idempiere-cli pack validate META-INF/2Pack.zip

# Import PackOut to server (PackIn)
idempiere-cli pack in META-INF/2Pack.zip

# Migration scripts (for SQL-based migrations)
idempiere-cli pack migration create "add_xx_status_column"
idempiere-cli pack migration list
idempiere-cli pack migration apply --dry-run

IDE Configuration

# Generate all IDE configs
idempiere-cli ide eclipse
idempiere-cli ide intellij
idempiere-cli ide vscode

Environment Management (DevOps)

# Backup operations
idempiere-cli env backup create --name "pre-migration-backup"
idempiere-cli env backup list

# Restore operations
idempiere-cli env restore --backup "pre-migration-backup" --target staging
idempiere-cli env restore --from-production --target staging

# Deploy to environments
idempiere-cli env deploy staging --version 1.2.0
idempiere-cli env deploy production --version 1.2.0 --confirm

# Clone environment
idempiere-cli env clone from-production --target dev --anonymize
idempiere-cli env clone from-production --target staging

# Environment status
idempiere-cli env status
idempiere-cli env status staging

Server Management

# Cache operations
idempiere-cli server cache list
idempiere-cli server cache reset --table C_BPartner

# Job management
idempiere-cli server jobs list

# Workflow management
idempiere-cli server workflow list --pending
idempiere-cli server workflow approve 12345

# Start MCP server (for Claude Code/Desktop)
idempiere-cli server mcp

AI Features

# Natural language interface
idempiere-cli ai ask "list all tables with audit columns"
idempiere-cli ai ask "show me the structure of C_Order"
idempiere-cli ai ask "how many orders were created this month"

# AI code generation
idempiere-cli ai generate "create a callout to validate order total"

# List AI providers
idempiere-cli ai providers
idempiere-cli ai models

Utilities

# Batch execution
idempiere-cli util batch operations.yaml

# Watch mode
idempiere-cli util watch ./src --on-change "idempiere-cli gen model"

# Plugin management
idempiere-cli util plugin list
idempiere-cli util plugin install my-plugin.jar

Pros and Cons of the Options

Option 1: Prefix-based with ad

• Good, because short to type
• Bad, because ad is ambiguous (advertisement? add?)
• Bad, because not self-explanatory for new users

Option 2: Prefix-based with dict

• Good, because clearer meaning (Dictionary)
• Good, because still short (4 characters)
• Neutral, because requires learning that "dict" = Application Dictionary

Option 3: Resource-based naming

idempiere-cli table add XX_MyTable
idempiere-cli window create XX_MyTable

• Good, because very intuitive for AD operations
• Bad, because doesn't group non-AD commands logically
• Bad, because top-level namespace becomes cluttered

Option 4: Hybrid approach (Chosen)

• Good, because dict clearly indicates Application Dictionary
• Good, because common commands (init, doctor) remain at top level
• Good, because grouped commands improve discoverability
• Good, because supports all four CLI use cases
• Neutral, because slightly longer paths for some commands
• Bad, because migration effort required

AI/LLM Native Understanding

This CLI serves as an MCP server and AI entrypoint. Commands must be designed for native understanding by AI assistants (Claude Code, Claude Desktop, LangChain4j agents).

MCP Tool Naming Conventions

Based on MCP community best practices and SEP-986 specification:

CLI-to-MCP Tool Mapping

CLI commands map to MCP tools with snake_case naming:

Semantic Naming for AI Discovery

Commands should be self-descriptive so LLMs can infer functionality:

✅ Good (AI-friendly):
  dict_table_add          # Clear: dictionary → table → add action
  dict_query_tables       # Clear: query tables from dictionary
  env_backup_create       # Clear: create environment backup
  gen_model               # Clear: generate model code

❌ Bad (AI-unfriendly):
  ad_tbl_a                # Cryptic abbreviations
  do_sync                 # Vague action
  x2p                     # Meaningless
  proc291                 # Implementation detail

Tool Descriptions for LLM Context

Each MCP tool must have a clear description:

{
  "name": "dict_table_add",
  "description": "Create a new table definition in iDempiere Application Dictionary (AD_Table). Creates metadata record, does not create physical database table - use dict_table_sync for that.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "table_name": {
        "type": "string",
        "description": "Table name, must start with prefix (e.g., XX_MyTable)"
      },
      "entity_type": {
        "type": "string",
        "description": "Entity type: D=Dictionary, U=User, A=Application",
        "default": "U"
      }
    },
    "required": ["table_name"]
  }
}

JSON Output for M2M/AI Consumption

All commands support --json flag for structured output:

# Human-readable (default)
idempiere-cli dict query tables --filter "XX_%"

# Machine/AI-readable
idempiere-cli dict query tables --filter "XX_%" --json

{
  "success": true,
  "command": "dict_query_tables",
  "data": [
    {"table_name": "XX_MyTable", "ad_table_id": 1000123, "entity_type": "U"},
    {"table_name": "XX_Config", "ad_table_id": 1000124, "entity_type": "U"}
  ],
  "count": 2
}

Error Messages for AI Recovery

Structured errors help AI assistants recover:

{
  "success": false,
  "command": "dict_table_add",
  "error": {
    "code": "TABLE_EXISTS",
    "message": "Table XX_MyTable already exists",
    "suggestion": "Use dict_table_query to check existing table or choose different name",
    "related_commands": ["dict_table_query", "dict_table_sync"]
  }
}

MCP Server Tool Registration

When running as MCP server (server mcp), tools are registered with:

1. Clear names: snake_case, verb-prefixed
2. Rich descriptions: What it does, when to use it, what it returns
3. Typed schemas: JSON Schema for all parameters
4. Examples: Sample invocations in description

@Tool(name = "dict_table_add",
      description = "Create a new table in iDempiere Application Dictionary. " +
                    "Use when user wants to add a custom table. " +
                    "Returns the created AD_Table_ID. " +
                    "Example: dict_table_add(table_name='XX_MyTable', entity_type='U')")
public ToolResult dictTableAdd(String tableName, String entityType) { ... }

Implementation Plan

Phase 1: Create New Command Structure

1. Create parent command classes (DevCommand, DictCommand, GenCommand, etc.)
2. Reorganize existing commands as subcommands
3. Update help text and descriptions

Phase 2: Add Backward Compatibility

1. Register aliases at top level for common commands
2. Add deprecation warnings for old command paths
3. Update documentation

Phase 3: Consolidate Duplicates

1. Merge export + 2pack generate into pack out
2. Move Java generation from add to gen
3. Remove redundant commands

Phase 4: Update Documentation

1. Update USER_GUIDE.md
2. Update CLAUDE.md
3. Update help text in all commands

More Information

Related ADRs

• ADR-006 - CLI as M2M API
• ADR-010 - MCP Server Architecture
• ADR-013 - LangChain4j Workflow Routing

References

CLI Design

• CLI Guidelines - Best practices for CLI design
• 12 Factor CLI Apps
• Picocli Subcommands
• kubectl Command Structure - Resource-based CLI example

MCP & AI Integration

• MCP Server Naming Conventions - Snake_case standard
• MCP Tool Specification - Official spec
• SEP-986: Tool Name Format - Proposed standard
• MCP API Naming Best Practices - Community guidelines
• Claude Code Best Practices - Agentic coding patterns
• MCP Development Best Practices - Tool design guide