ADR-050: Hierarchical Command Structure

Status: Proposed Date: 2025-12-11 Deciders: CloudEmpiere Technical Team Related: ADR-049 (Project Rebranding)

Context

The current iDempiere AI Hub (v1.59.0) has a flat command structure that has grown organically:

idempiere-cli gen model
idempiere-cli gen process
idempiere-cli dict add table
idempiere-cli pack out
idempiere-cli rag search
idempiere-cli server mcp

Problems with current structure:

Poor Discoverability - Commands don't group logically
Inconsistent Naming - gen, dict, pack, rag lack pattern
Limited Scalability - Hard to add new commands without confusion
Tab Completion Pollution - All commands at same level
Not User-Friendly - Users must memorize unrelated command names

Analysis from vision documents (idempiere-ai-cli-architecture.md) proposes a superior hierarchical structure that groups related commands:

idempiere-cli app generate
idempiere-cli model generate
idempiere-cli metamodel generate
idempiere-cli plugin scaffold
idempiere-cli knowledge query

We must decide: Keep flat structure or adopt hierarchical grouping?

Decision

Adopt hierarchical command structure organized by functional domain, with backward-compatible aliases for existing commands.

New Command Structure (v1.60+):

idempiere-cli
├── app                    # Application generation
│   └── generate          # Full application from requirements
│
├── model                  # Java model generation
│   └── generate          # Generate I_, X_, M_ classes
│
├── metamodel             # Database schema &amp; AD
│   ├── create            # Create new tables (AI-assisted)
│   ├── generate          # Generate from requirements (AI-driven)
│   ├── export            # Export to 2Pack/SQL
│   ├── import            # Import from 2Pack
│   └── sync              # Synchronize AD to database
│
├── code                  # Code generation
│   ├── process           # Generate process class
│   ├── callout           # Generate callout class
│   ├── form              # Generate form class
│   └── validator         # Generate model validator
│
├── plugin                # Plugin scaffolding
│   ├── scaffold          # Create complete plugin structure
│   └── validate          # Validate plugin structure
│
├── knowledge             # Knowledge base operations
│   ├── query             # Semantic search
│   ├── search            # Hybrid search
│   ├── index             # Index documents
│   └── stats             # Knowledge base statistics
│
├── registry              # Application Dictionary registry
│   ├── search            # Smart search (SQL/semantic)
│   ├── list              # List entities (tables, windows, etc.)
│   └── describe          # Describe entity
│
├── db                    # Database operations
│   ├── analyze           # Analyze schema
│   ├── query             # Execute SQL queries
│   └── migration         # Create migration scripts
│
├── server                # Server modes
│   ├── mcp               # MCP server (port 8765)
│   └── chat-api          # Chat API (port 8081)
│
└── dev                   # Developer utilities
    ├── doctor            # Environment health check
    ├── config            # Configuration management
    └── demo              # Demo/test commands

Migration Strategy:

Phase 1 (v1.60): Implement new structure, add aliases
Phase 2 (v1.61-1.65): Deprecation warnings on old commands
Phase 3 (v2.0): Remove aliases, new structure only

Rationale

Why Hierarchical?

1. Better Organization

# OLD - Unclear relationships
idempiere-cli gen model
idempiere-cli gen process
idempiere-cli gen callout

# NEW - Clear grouping
idempiere-cli code process
idempiere-cli code callout
idempiere-cli model generate

2. Improved Discoverability

# User explores naturally
idempiere-cli model --help
  Commands:
    generate    Generate Java model classes

idempiere-cli metamodel --help
  Commands:
    create      Create new table in AD
    generate    Generate from AI requirements
    export      Export to 2Pack/SQL

3. Better Tab Completion

# OLD - All commands at once (overwhelming)
idempiere-cli &lt;TAB&gt;
  gen  dict  pack  rag  server  dev  registry  mig

# NEW - Grouped exploration
idempiere-cli &lt;TAB&gt;
  app  model  metamodel  code  plugin  knowledge  registry  db  server  dev

idempiere-cli model &lt;TAB&gt;
  generate

4. Scalability

# Easy to add new commands without confusion
idempiere-cli code &lt;TAB&gt;
  process  callout  form  validator  docaction  interceptor  # NEW

5. Industry Standard

# Follows patterns from successful CLIs
docker container ls
kubectl get pods
git remote add
aws s3 ls
npm run build

Why Backward Compatible?

Reasoning:

Existing scripts and workflows depend on current commands
Users have muscle memory
Gradual migration reduces friction
We can track deprecation usage via observability

Alias Strategy:

# OLD command (deprecated, aliased)
idempiere-cli gen model XX_Table
# ⚠️  WARNING: &#39;gen model&#39; is deprecated, use &#39;model generate&#39; instead

# NEW command (preferred)
idempiere-cli model generate XX_Table

Implementation

Picocli Structure

@Command(
    name = &quot;idempiere-cli&quot;,
    description = &quot;iDempiere AI Hub - CLI, MCP Server, and Chat API&quot;,
    subcommands = {
        AppCommands.class,
        ModelCommands.class,
        MetamodelCommands.class,
        CodeCommands.class,
        PluginCommands.class,
        KnowledgeCommands.class,
        RegistryCommands.class,
        DatabaseCommands.class,
        ServerCommands.class,
        DevCommands.class,

        // Deprecated aliases (to be removed in v2.0)
        GenCommands.class,       // @Deprecated
        DictCommands.class,      // @Deprecated
        PackCommands.class,      // @Deprecated
        RagCommands.class,       // @Deprecated
        MigCommands.class        // @Deprecated
    }
)
public class IdempiereCli {
    // ...
}

Example: Model Commands

@Command(
    name = &quot;model&quot;,
    description = &quot;Java model class generation&quot;,
    subcommands = {
        ModelGenerateCommand.class
    }
)
public class ModelCommands {
    // Parent command, delegates to subcommands
}

@Command(
    name = &quot;generate&quot;,
    description = &quot;Generate Java model classes (I_, X_, M_) from database table&quot;
)
public class ModelGenerateCommand implements Callable&lt;Integer&gt; {

    @Parameters(description = &quot;Table name (e.g., XX_MyTable)&quot;)
    String tableName;

    @Option(names = {&quot;-p&quot;, &quot;--package&quot;}, description = &quot;Java package name&quot;)
    String packageName;

    @Option(names = {&quot;-o&quot;, &quot;--output&quot;}, description = &quot;Output directory&quot;)
    Path outputDir;

    @Override
    public Integer call() {
        // Implementation
        return 0;
    }
}

Alias Implementation

@Command(
    name = &quot;gen&quot;,
    description = &quot;Code generation (DEPRECATED: use &#39;model&#39;, &#39;code&#39;, or &#39;plugin&#39; instead)&quot;,
    subcommands = {
        GenModelCommand.class,    // Alias to ModelGenerateCommand
        GenProcessCommand.class,  // Alias to CodeProcessCommand
        GenCalloutCommand.class   // Alias to CodeCalloutCommand
    }
)
@Deprecated(since = &quot;1.60&quot;, forRemoval = true)
public class GenCommands {

    @Spec CommandSpec spec;

    @Override
    public Integer call() {
        System.err.println(&quot;⚠️  WARNING: &#39;gen&#39; command is deprecated.&quot;);
        System.err.println(&quot;   Use specific commands instead:&quot;);
        System.err.println(&quot;     gen model    → model generate&quot;);
        System.err.println(&quot;     gen process  → code process&quot;);
        System.err.println(&quot;     gen callout  → code callout&quot;);
        return 0;
    }
}

Help Text

$ idempiere-cli --help

Usage: idempiere-cli [COMMAND]

iDempiere AI Hub - CLI, MCP Server, and Chat API

Commands:
  app         Application generation from requirements
  model       Java model class generation
  metamodel   Database schema and Application Dictionary
  code        Code generation (processes, callouts, forms)
  plugin      Plugin scaffolding and validation
  knowledge   Knowledge base operations (RAG)
  registry    Application Dictionary registry
  db          Database operations
  server      Server modes (MCP, Chat API)
  dev         Developer utilities

Deprecated (use alternatives above):
  gen         → Use &#39;model&#39;, &#39;code&#39;, or &#39;plugin&#39;
  dict        → Use &#39;metamodel&#39; or &#39;registry&#39;
  pack        → Use &#39;metamodel export/import&#39;
  rag         → Use &#39;knowledge&#39;
  mig         → Use &#39;db migration&#39;

Run &#39;idempiere-cli COMMAND --help&#39; for more information.

Consequences

Positive

Better User Experience
- Intuitive command discovery
- Logical grouping reduces cognitive load
- Tab completion becomes useful
Scalability
- Easy to add new commands without confusion
- Clear namespace for each domain
- Subcommands can have subcommands
Consistency
- Follows industry standards (docker, kubectl, git)
- Predictable command patterns
- Clear command hierarchy
Documentation
- Easier to document (organized by domain)
- Help text is hierarchical
- Examples are clearer
MCP Integration
- Tool names map naturally to commands
- model_generate → idempiere-cli model generate
- Better API surface for AI assistants

Negative

Migration Effort
- Need to create new command classes
- Update all documentation
- Communicate changes to users
- Maintain aliases during transition
Verbosity
- Commands are longer
- More typing for users
- Offset by: tab completion, aliases
Breaking Change (v2.0)
- Eventually remove aliases
- Users must update scripts
- Mitigation: 6+ month deprecation period
Implementation Complexity
- More command classes
- Alias routing logic
- Deprecation warnings
- Mitigation: Well-structured codebase

Alternatives Considered

Alternative 1: Keep Flat Structure

Pros:

No migration needed
No breaking changes
Shorter commands

Cons:

Poor discoverability
Hard to scale
Inconsistent naming
Not industry standard

Decision: ❌ Rejected - Technical debt will grow

Alternative 2: Complete Rewrite (No Aliases)

Pros:

Clean break
Simpler implementation
No legacy code

Cons:

Breaks existing scripts
Poor user experience
No migration path

Decision: ❌ Rejected - Too disruptive

Alternative 3: Namespaced Flat Commands

# Example
idempiere-cli model:generate
idempiere-cli code:process
idempiere-cli metamodel:create

Pros:

Less verbose than nested
Still organized
Works with simple CLI parsers

Cons:

Not standard (docker, kubectl use spaces)
Harder tab completion
Looks less professional

Decision: ❌ Rejected - Doesn't follow industry standards

Alternative 4: Hybrid Approach (Selected)

✅ Hierarchical structure + backward-compatible aliases + gradual migration

Balances all concerns:

Modern, scalable structure
Backward compatibility
User-friendly migration
Industry standard patterns

Migration Plan

Phase 1: v1.60 (Q1 2025) - Implement New Structure

Week 1-2: Core Implementation

Create new command hierarchy
Implement all new commands
Add alias routing
Update CLI entry point

Week 3: MCP Integration

Update MCP tool names to match
Maintain backward compatibility
Update tool descriptions

Week 4: Documentation

Update USER_GUIDE.md
Update CLI-GUIDE.md
Update README.md examples
Add migration guide

Week 5: Testing

Test all new commands
Test all aliases
Test tab completion
Integration tests

Phase 2: v1.61-1.65 (Q2 2025) - Deprecation Period

v1.61:

Add deprecation warnings to old commands
Track usage via observability metrics
Monitor user feedback

v1.62-1.65:

Continue monitoring
Assist users with migration
Update community scripts

Phase 3: v2.0 (Q3 2025) - Remove Aliases

Pre-release:

Final migration warnings
Communicate removal timeline
Update all documentation

v2.0.0:

Remove all deprecated commands
Clean codebase
Update version to 2.0

Command Mapping Reference

Old Command	New Command	Alias Until
`gen model`	`model generate`	v2.0
`gen process`	`code process`	v2.0
`gen callout`	`code callout`	v2.0
`gen plugin`	`plugin scaffold`	v2.0
`dict add table`	`metamodel create`	v2.0
`dict list tables`	`registry list tables`	v2.0
`dict describe table`	`registry describe table`	v2.0
`pack out`	`metamodel export`	v2.0
`pack in`	`metamodel import`	v2.0
`rag search`	`knowledge search`	v2.0
`rag ingest`	`knowledge index`	v2.0
`mig create`	`db migration create`	v2.0

Success Metrics

Track via observability:

Command Usage
- New commands: % of total executions
- Old commands: % of total executions
- Target: 80%+ new commands by v1.65
User Feedback
- GitHub issues/discussions
- Survey results
- Support tickets
Tab Completion Usage
- Track via shell hooks (if user consents)
- Measure discoverability improvement
Documentation Views
- Migration guide views
- Command help usage
- Example code copies

ADRs:

ADR-049: Project Rebranding to "iDempiere AI Hub"
ADR-051: Application Generator (proposed)
ADR-052: Enhanced Metamodel Generation (proposed)

Vision Documents:

docs/idempiere-ai-cli-architecture.md - Hierarchical command inspiration
docs/ARCHITECTURE-COMPARISON.md - Gap analysis

Implementation:

src/main/java/org/idempiere/cli/commands/ - Command implementations
docs/interfaces/CLI-GUIDE.md - User guide
USER_GUIDE.md - Comprehensive reference

References

Industry Examples:

Docker CLI - docker container, docker image
Kubernetes kubectl - kubectl get, kubectl create
Git - git remote, git branch
AWS CLI - aws s3, aws ec2
Heroku CLI - heroku apps, heroku logs

Design Principles:

CLI Guidelines - Command-line interface design best practices
Picocli Documentation - Subcommands and command hierarchy

Decision

Approved: [Pending] By: [CloudEmpiere Technical Team] Date: [TBD]

Document Status: Proposed Next Review: After team discussion Implementation Target: v1.60 (Q1 2025)

ADR-050: Hierarchical Command Structure

Context

Decision

Rationale

Why Hierarchical?

Why Backward Compatible?

Implementation

Picocli Structure

Example: Model Commands

Alias Implementation

Help Text

Consequences

Positive

Negative

Alternatives Considered

Alternative 1: Keep Flat Structure

Alternative 2: Complete Rewrite (No Aliases)

Alternative 3: Namespaced Flat Commands

Alternative 4: Hybrid Approach (Selected)

Migration Plan

Phase 1: v1.60 (Q1 2025) - Implement New Structure

Phase 2: v1.61-1.65 (Q2 2025) - Deprecation Period

Phase 3: v2.0 (Q3 2025) - Remove Aliases

Command Mapping Reference

Success Metrics

Related Work

References

Decision