Commands

mvx provides both built-in commands for tool management and the ability to define custom commands specific to your project.

Built-in Commands

Tool Wrapper Commands

mvx provides transparent wrapper commands for managed tools, allowing you to use them with their native syntax:

Maven Integration

# Use Maven with natural syntax - all flags work
./mvx mvn -V                    # Show Maven version
./mvx mvn -X clean install      # Debug mode with clean install
./mvx mvn -Pproduction package  # Activate profile and package
./mvx mvn help:effective-pom    # Any Maven goal or plugin

# Combine mvx global flags with Maven flags
./mvx --verbose mvn -V          # mvx verbose output + Maven version
./mvx --quiet mvn test          # mvx quiet mode + Maven test

# Backward compatibility (with migration warnings)
./mvx mvn -- -V                 # Still works, shows helpful migration tip

Key Features:

• 🎯 Transparent wrapper: Acts like mvnw but with enhanced tool management
• 🔄 Natural syntax: Use Maven flags exactly as you would with mvn
• ⚡ No learning curve: Existing Maven knowledge applies directly
• 🛡️ Backward compatible: Scripts using -- separator continue to work

Project Management

# Initialize mvx in current directory
mvx init

# Show mvx version
mvx version

# Show help
mvx help
mvx --help

Tool Management

# Install all configured tools
./mvx setup

# List all supported tools
./mvx tools list

# Search for tools
./mvx tools search java
./mvx tools search maven

# Show available versions for a tool
./mvx tools versions java

# Install specific tool
./mvx tools install java
./mvx tools install maven

# Show tool information
./mvx tools info java

# Verify tool installation
./mvx tools verify java

# Uninstall tool
./mvx tools uninstall java

Environment Management

# Execute shell commands in mvx environment
./mvx shell 'echo $JAVA_HOME'
./mvx shell 'java -version'
./mvx shell env

# Show environment information
./mvx env

# Show tool paths
./mvx env paths

# Export environment variables
./mvx env export

# Clean tool cache
./mvx clean cache

# Clean all tools
./mvx clean tools

The shell command is particularly useful for:

• Testing tool installations and environment setup
• Running ad-hoc commands with mvx-managed tools
• Debugging environment variable issues
• Accessing tools interactively without defining custom commands

See the Shell Command page for detailed examples and usage patterns.

Custom Commands

Define custom commands in your .mvx/config.json5 file. These become available as top-level commands.

Basic Custom Commands

{
  commands: {
    build: {
      description: "Build the project",
      script: "mvn clean install"
    },
    test: {
      description: "Run tests",
      script: "mvn test"
    },
    clean: {
      description: "Clean build artifacts",
      script: "mvn clean"
    }
  }
}

Usage:

./mvx build
./mvx test
./mvx clean

Multi-Step Commands

Commands can execute multiple steps:

{
  commands: {
    "full-build": {
      description: "Complete build with quality checks",
      script: [
        "echo 'Starting full build...'",
        "mvn clean",
        "mvn compile",
        "mvn test",
        "mvn package",
        "echo 'Build completed!'"
      ]
    }
  }
}

Platform-Specific Commands

Note: Platform-specific script syntax is not yet implemented. See issue #21 for planned cross-platform script support.

For now, use platform detection within scripts:

{
  commands: {
    "open-logs": {
      description: "Open log directory",
      script: "if [[ \"$OSTYPE\" == \"msys\" || \"$OSTYPE\" == \"win32\" ]]; then explorer logs; elif [[ \"$OSTYPE\" == \"darwin\"* ]]; then open logs; else xdg-open logs; fi"
    }
  }
}

Commands with Working Directory

Execute commands in specific directories:

{
  commands: {
    "build-frontend": {
      description: "Build frontend application",
      script: "npm run build",
      workingDirectory: "frontend"
    },
    "build-backend": {
      description: "Build backend services",
      script: "mvn clean install",
      workingDirectory: "backend"
    }
  }
}

Commands with Environment Variables

Set environment variables for commands:

{
  commands: {
    "build-prod": {
      description: "Build for production",
      script: "mvn clean install",
      environment: {
        MAVEN_OPTS: "-Xmx2g",
        SPRING_PROFILES_ACTIVE: "production"
      }
    },
    "dev-server": {
      description: "Start development server",
      script: "npm run dev",
      environment: {
        NODE_ENV: "development",
        PORT: "3000"
      }
    }
  }
}

Command Hooks

Add pre and post hooks to built-in mvx commands by defining them within the command configuration:

{
  commands: {
    // Add hooks to built-in 'setup' command
    setup: {
      description: "Setup with custom hooks",
      pre: "echo 'Preparing environment...'",
      post: [
        "echo 'Verifying tools...'",
        "./mvx tools verify java",
        "./mvx tools verify maven"
      ]
    },

    // Add hooks to built-in 'build' command
    build: {
      description: "Build with pre-checks",
      pre: "echo 'Running pre-build checks...'",
      post: "echo 'Build completed successfully!'"
    }
  }
}

Hook properties:

• pre - Script to run before the built-in command
• post - Script to run after the built-in command
• Both support single strings or arrays of commands

Command Overrides

Override built-in mvx commands with custom implementations:

{
  commands: {
    // Override the built-in 'setup' command
    setup: {
      description: "Custom setup with additional steps",
      script: [
        "echo 'Running custom setup...'",
        "mvx tools install",
        "echo 'Installing additional dependencies...'",
        "npm install -g typescript",
        "echo 'Setup completed!'"
      ]
    },
    
    // Override the built-in 'clean' command
    clean: {
      description: "Custom clean with extra cleanup",
      script: [
        "mvx clean tools",
        "rm -rf node_modules",
        "rm -rf target",
        "echo 'Deep clean completed!'"
      ]
    }
  }
}

Maven Wrapper Integration

mvx provides enhanced Maven wrapper functionality that goes beyond traditional mvnw:

Direct Maven Usage

# All Maven commands work naturally
./mvx mvn clean install
./mvx mvn -V                    # Show version
./mvx mvn -X test              # Debug mode
./mvx mvn -Pproduction package # Profile activation
./mvx mvn help:effective-pom   # Plugin goals
./mvx mvn dependency:tree      # Dependency analysis

# Complex Maven commands work seamlessly
./mvx mvn org.springframework.boot:spring-boot-maven-plugin:run
./mvx mvn versions:set -DnewVersion=2.0.0

Enhanced Features vs Traditional mvnw

Feature	Traditional mvnw	mvx Maven Integration
Maven version management	✅ Fixed version	✅ Configurable version
Java version management	❌ System Java only	✅ Automatic Java setup
Tool isolation	❌ Global tools	✅ Project-specific tools
Environment setup	❌ Manual	✅ Automatic
Cross-platform	✅ Yes	✅ Enhanced
Argument passing	✅ Basic	✅ Hybrid parsing
Global flags	❌ No	✅ --verbose, --quiet

Migration from mvnw

Replace your existing Maven Wrapper with mvx:

# Before (traditional mvnw)
./mvnw clean install
./mvnw -V
./mvnw spring-boot:run

# After (mvx - same commands work)
./mvx mvn clean install
./mvx mvn -V
./mvx mvn spring-boot:run

# Plus enhanced capabilities
./mvx --verbose mvn -X test     # mvx verbose + Maven debug
./mvx setup                     # Auto-install Java + Maven

Backward Compatibility

Existing scripts using the -- separator continue to work:

# Old syntax (still works with helpful warnings)
./mvx mvn -- -V
./mvx mvn -- clean install

# New syntax (recommended)
./mvx mvn -V
./mvx mvn clean install

Command Examples

Java/Maven Project

{
  commands: {
    compile: {
      description: "Compile source code",
      script: "mvn compile"
    },
    test: {
      description: "Run unit tests",
      script: "mvn test"
    },
    "integration-test": {
      description: "Run integration tests",
      script: "mvn verify -P integration-tests"
    },
    package: {
      description: "Package application",
      script: "mvn package -DskipTests"
    },
    run: {
      description: "Run Spring Boot application",
      script: "mvn spring-boot:run"
    },
    "docker-build": {
      description: "Build Docker image",
      script: "docker build -t myapp:latest ."
    }
  }
}

Go Project

{
  commands: {
    build: {
      description: "Build Go binary",
      script: "go build -o bin/app ."
    },
    test: {
      description: "Run tests with coverage",
      script: "go test -v -cover ./..."
    },
    "test-race": {
      description: "Run tests with race detection",
      script: "go test -race ./..."
    },
    fmt: {
      description: "Format Go code",
      script: "go fmt ./..."
    },
    vet: {
      description: "Run go vet",
      script: "go vet ./..."
    },
    mod: {
      description: "Download dependencies",
      script: "go mod download"
    },
    run: {
      description: "Run the application",
      script: "go run ."
    }
  }
}

Node.js Project

{
  commands: {
    install: {
      description: "Install dependencies",
      script: "npm install"
    },
    build: {
      description: "Build for production",
      script: "npm run build"
    },
    dev: {
      description: "Start development server",
      script: "npm run dev"
    },
    test: {
      description: "Run tests",
      script: "npm test"
    },
    "test-watch": {
      description: "Run tests in watch mode",
      script: "npm run test:watch"
    },
    lint: {
      description: "Run ESLint",
      script: "npm run lint"
    },
    "lint-fix": {
      description: "Fix ESLint issues",
      script: "npm run lint:fix"
    }
  }
}

Full-Stack Project

{
  commands: {
    "install-all": {
      description: "Install all dependencies",
      script: [
        "cd frontend && npm install",
        "cd backend && mvn dependency:resolve"
      ]
    },
    "build-all": {
      description: "Build frontend and backend",
      script: [
        "cd frontend && npm run build",
        "cd backend && mvn clean install"
      ]
    },
    "dev-frontend": {
      description: "Start frontend dev server",
      script: "npm run dev",
      workingDirectory: "frontend"
    },
    "dev-backend": {
      description: "Start backend dev server",
      script: "mvn spring-boot:run",
      workingDirectory: "backend"
    },
    "test-all": {
      description: "Run all tests",
      script: [
        "cd frontend && npm test",
        "cd backend && mvn test"
      ]
    }
  }
}

Command Best Practices

1. Use descriptive names: build-frontend instead of bf
2. Add descriptions: Help team members understand what commands do
3. Group related commands: Use consistent naming patterns
4. Keep commands simple: Break complex workflows into multiple commands
5. Use working directories: Keep commands focused on specific parts of your project
6. Document complex commands: Use comments in JSON5 format
7. Test on all platforms: Ensure commands work on Windows, macOS, and Linux

Command Discovery

# List all available commands
./mvx help

# Show command details
./mvx help build
./mvx help test

Next Steps

• Learn about configuration
• Explore supported tools
• Check out examples