CLI Reference and Configuration

# Device connection
mpremote connect [device]    # Connect to device (auto-detect if no device specified)
mpremote disconnect          # Disconnect from current device
mpremote resume             # Resume previous session without auto soft-reset
mpremote soft-reset         # Perform soft reset of connected device

# Device shortcuts
mpremote devs               # List available serial devices
mpremote a0, a1, a2, a3     # Connect to /dev/ttyACM0-3
mpremote u0, u1, u2, u3     # Connect to /dev/ttyUSB0-3
mpremote c0, c1, c2, c3     # Connect to COM0-3

# Execute code
mpremote exec "code"        # Execute Python code string
mpremote eval "expression"  # Evaluate Python expression
mpremote run script.py      # Run local Python script on device

# Execution options
mpremote exec --follow "code"       # Follow output until completion (default)
mpremote exec --no-follow "code"    # Return immediately

# File operations (shortcuts for 'fs' commands)
mpremote ls [path]          # List directory contents
mpremote cat file           # Display file contents
mpremote cp src dest        # Copy files between local/remote
mpremote rm file            # Remove files
mpremote mkdir dir          # Create directory
mpremote rmdir dir          # Remove directory
mpremote touch file         # Create empty file or update timestamp
mpremote tree [path]        # Display directory tree

# Filesystem options
mpremote ls -l              # Detailed listing
mpremote cp -r src/ dest/   # Recursive copy
mpremote cp -f src dest     # Force overwrite
mpremote rm -r directory    # Recursive remove
mpremote tree -s            # Show file sizes
mpremote tree -h            # Human-readable sizes

# Hash verification
mpremote sha256sum file     # Calculate SHA256 hash

# System operations
mpremote df                 # Show disk usage/free space
mpremote reset              # Hard reset device
mpremote bootloader         # Enter bootloader mode
mpremote sleep <seconds>    # Sleep/delay before next command

# Time synchronization
mpremote rtc                # Get device RTC time
mpremote rtc --set          # Set device RTC to system time

# Interactive REPL
mpremote repl                           # Enter REPL mode
mpremote repl --escape-non-printable    # Escape non-printable chars
mpremote repl --capture session.log     # Save session to file
mpremote repl --inject-code "setup()"   # Code to run with Ctrl-J
mpremote repl --inject-file script.py   # File to run with Ctrl-K

# MIP package operations
mpremote mip install package           # Install package from micropython-lib
mpremote mip install --target lib pkg  # Install to specific directory
mpremote mip install --index url pkg   # Install from custom index
mpremote mip install github:user/repo  # Install from GitHub
mpremote mip install gitlab:user/repo  # Install from GitLab

# Mount local directories
mpremote mount .                    # Mount current directory
mpremote mount /path/to/project     # Mount specific directory
mpremote mount --unsafe-links dir   # Follow symbolic links
mpremote umount                     # Unmount current mount

# ROMFS operations
mpremote romfs query                    # Query ROM partitions
mpremote romfs query --partition 1      # Query specific partition
mpremote romfs build src/               # Build ROMFS from directory
mpremote romfs build --output app.img src/     # Build with custom output
mpremote romfs build --no-mpy src/      # Build without bytecode compilation
mpremote romfs deploy app.img           # Deploy to default partition
mpremote romfs deploy --partition 1 app.img    # Deploy to specific partition

# Edit files on device
mpremote edit :main.py              # Edit single file
mpremote edit :boot.py :main.py     # Edit multiple files

# Help and version
mpremote help                       # Show help information
mpremote version                    # Show version information

# Basic chaining
mpremote connect auto + exec "print('hello')" + disconnect

# Complex workflows
mpremote connect /dev/ttyUSB0 + rtc --set + mount . + exec "import main; main.run()" + umount + disconnect

# Development cycle
mpremote connect auto + cp main.py : + exec "import main" + repl

# Automated deployment
mpremote connect auto + romfs build src/ --output app.img + romfs deploy app.img + soft-reset + disconnect

# ~/.config/mpremote/config.py

commands = {
    # Simple command shortcuts
    "myboard": "connect id:334D335C3138",
    "setup": "connect auto rtc --set mount .",
    "deploy": "cp main.py : exec 'import main'",
    
    # Complex commands with help text
    "test": {
        "command": "connect auto + mount . + exec 'import unittest; unittest.main()' + umount + disconnect",
        "help": "Run unit tests on connected device"
    },
    
    # Parameterized commands
    "flash x": {
        "command": "connect auto + cp {x} : + exec 'import {x}' + disconnect", 
        "help": "Flash and run Python file on device"
    }
}

# Use custom shortcuts
mpremote myboard                    # Connects to specific device
mpremote setup                      # Setup development environment
mpremote deploy                     # Deploy current project

# Use parameterized commands
mpremote flash main.py              # Flash main.py file
mpremote test                       # Run test suite

# Advanced ~/.config/mpremote/config.py

commands = {
    # Development workflow
    "dev": {
        "command": "connect auto + rtc --set + mount . + repl",
        "help": "Start development session with time sync and mounted directory"
    },
    
    # Production deployment
    "prod-deploy": {
        "command": "connect auto + romfs build --mpy src/ --output prod.img + romfs deploy prod.img + soft-reset",
        "help": "Build and deploy production ROM filesystem"
    },
    
    # Device information gathering
    "info": {
        "command": "connect auto + exec 'import sys; print(sys.implementation)' + exec 'import micropython; micropython.mem_info()' + disconnect",
        "help": "Get device system information"
    },
    
    # Backup device code
    "backup": {
        "command": "connect auto + cp :main.py backup_main.py + cp :boot.py backup_boot.py + disconnect",
        "help": "Backup main device files"
    },
    
    # Multi-device deployment
    "deploy-all x": {
        "command": "a0 + cp {x} : + disconnect + a1 + cp {x} : + disconnect + u0 + cp {x} : + disconnect",
        "help": "Deploy file to multiple connected devices"
    }
}

# Editor for file editing
export EDITOR=nano
mpremote edit :main.py              # Uses nano editor

# Custom configuration directory
export MPREMOTE_CONFIG_DIR=/custom/path
# Looks for config.py in /custom/path/config.py

# Serial port timeout
export MPREMOTE_TIMEOUT=30          # 30 second timeout

# Verbose output
mpremote -v command                 # Enable verbose mode
mpremote --verbose command          # Enable verbose mode

# Configuration file
mpremote --config custom.py cmd     # Use custom config file

# Connection parameters
mpremote connect /dev/ttyUSB0:115200    # Specify baud rate
mpremote connect COM3:9600              # Windows with custom baud rate
mpremote connect auto:timeout=10        # Custom connection timeout

# Detailed filesystem operations
mpremote fs ls -l -v                # Long format, verbose
mpremote fs cp -r -f src/ :dst/      # Recursive, force overwrite
mpremote fs tree -s -h               # Show sizes, human readable

# Group related commands
mpremote connect auto + rtc --set + mount . + exec "print('Ready for development')"

# Use meaningful delays
mpremote connect auto + sleep 2 + exec "import main" + sleep 1 + repl

# Clean disconnection
mpremote connect auto + exec "your_code()" + umount + disconnect

# Organize config by project
commands = {
    # Project A commands
    "proj-a-setup": "connect auto + mount /path/to/project-a + rtc --set",
    "proj-a-deploy": "connect auto + cp /path/to/project-a/main.py :",
    
    # Project B commands  
    "proj-b-setup": "connect auto + mount /path/to/project-b + rtc --set",
    "proj-b-deploy": "connect auto + romfs build /path/to/project-b --output proj-b.img + romfs deploy proj-b.img",
    
    # Utility commands
    "clean-device": "connect auto + rm :main.py + rm :boot.py + soft-reset + disconnect"
}

# Use soft operations that won't break chains
mpremote connect auto + exec "try: import main\nexcept: print('main.py not found')" + disconnect

# Verify operations
mpremote connect auto + cp main.py : + exec "import os; print('main.py' in os.listdir())" + disconnect

# Permission denied on serial port
sudo usermod -a -G dialout $USER    # Add user to dialout group (Linux)
# Then logout and login again

# Device not detected
mpremote devs                       # List available devices
mpremote connect list               # List MicroPython devices

# Connection timeout
mpremote connect /dev/ttyUSB0:timeout=30    # Increase timeout

# Command not found in config
mpremote help                       # List available commands including custom ones

# Enable verbose output for debugging
mpremote -v connect auto + exec "print('debug')" + disconnect

# Test configuration
python -c "
import sys
sys.path.append('~/.config/mpremote')
import config
print(config.commands)
"