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
# 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
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 commandpost
- 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
- Use descriptive names:
build-frontend
instead ofbf
- Add descriptions: Help team members understand what commands do
- Group related commands: Use consistent naming patterns
- Keep commands simple: Break complex workflows into multiple commands
- Use working directories: Keep commands focused on specific parts of your project
- Document complex commands: Use comments in JSON5 format
- 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