MVX Interpreters
MVX supports multiple interpreters for executing commands, allowing you to choose the best execution environment for your specific needs.
Available Interpreters
1. Native Interpreter (native
)
The native interpreter uses the system's default shell (bash on Unix systems, cmd on Windows) to execute commands. This is the recommended interpreter for commands that:
- Use external tools and binaries
- Require complex shell features like pipes, redirects, or advanced scripting
- Need access to system-specific functionality
Example:
{
commands: {
"build": {
description: "Build the project",
script: "go build -o dist/myapp .",
interpreter: "native"
}
}
}
2. MVX Shell Interpreter (mvx-shell
)
The mvx-shell interpreter is a cross-platform command interpreter built into MVX. It provides:
- Cross-platform compatibility
- Built-in commands (cd, echo, mkdir, rm, cp)
- Environment variable expansion
- Basic command chaining with
&&
,||
, and;
Example:
{
commands: {
"setup": {
description: "Setup project directories",
script: "mkdir -p dist && echo 'Directories created'",
interpreter: "mvx-shell"
}
}
}
Interpreter Selection
Automatic Selection
MVX automatically selects the appropriate interpreter based on your script configuration:
- Simple string scripts default to
mvx-shell
for cross-platform compatibility - Platform-specific scripts default to
native
for system integration
Explicit Selection
You can explicitly specify the interpreter using the interpreter
field:
{
commands: {
"format": {
description: "Format code",
script: "go fmt ./...",
interpreter: "native" // Explicitly use native interpreter
},
"clean": {
description: "Clean build artifacts",
script: "rm -rf dist && echo 'Cleaned'",
interpreter: "mvx-shell" // Explicitly use mvx-shell
}
}
}
Environment Variables
Both interpreters support environment variables with different capabilities:
Global Environment Variables
Set in the environment
section of your configuration:
{
environment: {
BUILD_MODE: "production",
LOG_LEVEL: "info"
}
}
Command-Specific Environment Variables
Set per command using the environment
field:
{
commands: {
"test": {
description: "Run tests",
script: "go test ./...",
interpreter: "native",
environment: {
GO_ENV: "test",
VERBOSE: "true"
}
}
}
}
Variable Expansion
Both interpreters support comprehensive variable expansion with multiple syntax options:
Supported Syntax
- Simple Variables:
$VARIABLE_NAME
- Braced Variables:
${VARIABLE_NAME}
(useful when followed by other characters)
MVX-Shell Variable Expansion
The mvx-shell interpreter provides comprehensive variable expansion for all commands:
{
commands: {
"setup-project": {
description: "Setup project structure",
script: "mkdir $PROJECT_NAME && cd $PROJECT_NAME && echo 'Created ${PROJECT_NAME}_config.json'",
environment: {
PROJECT_NAME: "myapp"
}
},
"deploy": {
description: "Deploy application",
script: "echo 'Deploying $PROJECT_NAME in $BUILD_MODE mode to ${DEPLOY_ENV}_server'",
environment: {
PROJECT_NAME: "myapp",
BUILD_MODE: "production",
DEPLOY_ENV: "staging"
}
}
}
}
Variable Expansion Features
- Command Names: Variables are expanded in command names
- Arguments: Variables are expanded in all command arguments
- Built-in Commands: All mvx-shell built-in commands support variable expansion
- External Commands: Variables are expanded before executing external commands
- Environment Override: Command-specific environment variables override global ones
Examples
# These all work with variable expansion in mvx-shell:
mkdir $PROJECT_DIR # Create directory with variable name
echo "Hello $USER_NAME" # Print with variable expansion
rm ${TEMP_DIR}/cache # Remove with braced variable syntax
cd $PROJECT_DIR && echo "In project" # Chain commands with variables
PATH Management
MVX automatically manages the PATH environment variable to ensure mvx-managed tools are available:
Tool PATH Integration
When you have tools configured in your .mvx/config.json5
:
{
tools: {
go: { version: "1.24.2" },
java: { version: "17", distribution: "zulu" },
maven: { version: "3.9.11" }
}
}
MVX automatically prepends the tool bin directories to PATH:
~/.mvx/tools/go/1.24.2/go/bin
~/.mvx/tools/java/17-zulu/bin
~/.mvx/tools/maven/3.9.11/bin
Interpreter-Specific PATH Handling
- Native interpreter: Full PATH integration with system shell
- MVX-shell interpreter: Limited PATH support for external commands
For commands that use external tools (like go
, mvn
, node
), it's recommended to use the native
interpreter to ensure proper PATH resolution.
Best Practices
When to Use Native Interpreter
Use interpreter: "native"
for commands that:
- Execute external tools (
go
,mvn
,npm
, etc.) - Use complex shell features (pipes, redirects, loops)
- Require system-specific functionality
- Need reliable PATH resolution
{
commands: {
"build": {
script: "go build -o dist/app .",
interpreter: "native"
},
"test": {
script: "go test -v ./...",
interpreter: "native"
},
"deps": {
script: "go mod download && go mod tidy",
interpreter: "native"
}
}
}
When to Use MVX-Shell Interpreter
Use interpreter: "mvx-shell"
for commands that:
- Use only built-in commands
- Need cross-platform compatibility
- Perform simple file operations
- Don't require external tools
{
commands: {
"clean": {
script: "rm -rf dist && mkdir -p dist",
interpreter: "mvx-shell"
},
"setup": {
script: "mkdir -p src test docs && echo 'Project structure created'",
interpreter: "mvx-shell"
}
}
}
Debugging
Verbose Logging
Enable verbose logging to debug interpreter and PATH issues:
MVX_VERBOSE=true mvx your-command
This will show:
- Environment setup details
- PATH modifications
- Interpreter selection
- Command execution details
Common Issues
-
"executable file not found" errors: Usually indicates PATH issues. Use
interpreter: "native"
for external tools. -
Cross-platform compatibility: Use
mvx-shell
for simple commands that need to work across different operating systems. -
Environment variable not found: Check that variables are properly defined in global or command-specific environment sections.
Migration Guide
If you're experiencing PATH issues with existing commands, add interpreter: "native"
to commands that use external tools:
// Before (may have PATH issues)
{
"fmt": {
"script": "go fmt ./..."
}
}
// After (fixed)
{
"fmt": {
"script": "go fmt ./...",
"interpreter": "native"
}
}