Getting Started

Get up and running with muxa in minutes.

Basic Usage

The simplest way to use muxa is to run multiple commands in parallel:

muxa 'npm run dev' 'npm run test:watch'

This will:

Start both commands in separate terminal panes
Show live output from each command
Allow you to switch between panes with keyboard shortcuts
Automatically handle process cleanup on exit

Understanding Modes

muxa supports two distinct modes:

Basic Mode

Direct command arguments without flags:

muxa 'npm run dev' 'npm run test' 'npm run lint:watch'

Advanced Mode

Using flags for more control:

muxa -c 'npm run dev' api -c 'npm run test' tests

Important: You cannot mix these modes. Choose one style and use it consistently in a single command.

Common Workflows

Development Server + Tests

# Run your dev server and tests in watch mode
muxa -c 'npm run dev' server -c 'npm run test:watch' tests

Multiple Services

# Start frontend, backend, and database
muxa -c 'npm run frontend:dev' web \
     -c 'npm run backend:dev' api \
     -c 'docker-compose up postgres' db

Monorepo Development

If you're working in a monorepo, muxa makes it easy to run scripts from different packages:

# Run dev scripts in specific workspaces
muxa -s frontend dev -s backend dev -s shared build:watch

Interactive Features

Once muxa is running, you can:

Switch panes: Use arrow keys or click
Scroll output: Mouse wheel or keyboard
Copy text: Select with mouse
Exit: Press Ctrl+C or q

All your tools' interactive features are preserved:

Vite's dev server shortcuts work normally
Expo QR codes display correctly
Interactive prompts function as expected

Tips

Name your processes

Give processes meaningful names for easier identification:

muxa -c 'npm run dev' frontend -c 'npm run api' backend

List available workspaces

In a monorepo, see all detected packages:

muxa workspaces

Use shell features

Commands with shell operators are automatically handled:

muxa -c 'npm run build && npm test' -c 'echo "Starting..." && npm run dev'

Next Steps

Explore usage examples for more patterns
Learn about workspace commands for monorepos
Check the CLI reference for all options