0
# CLI Reference and Configuration
1

2
Complete command-line interface reference for mpremote, including built-in shortcuts, command chaining, and user configuration system.
3

4
## Core Commands
5

6
### Connection Commands
7

8
```bash
9
# Device connection
10
mpremote connect [device]    # Connect to device (auto-detect if no device specified)
11
mpremote disconnect          # Disconnect from current device
12
mpremote resume             # Resume previous session without auto soft-reset
13
mpremote soft-reset         # Perform soft reset of connected device
14

15
# Device shortcuts
16
mpremote devs               # List available serial devices
17
mpremote a0, a1, a2, a3     # Connect to /dev/ttyACM0-3
18
mpremote u0, u1, u2, u3     # Connect to /dev/ttyUSB0-3
19
mpremote c0, c1, c2, c3     # Connect to COM0-3
20
```
21

22
### Code Execution Commands
23

24
```bash
25
# Execute code
26
mpremote exec "code"        # Execute Python code string
27
mpremote eval "expression"  # Evaluate Python expression
28
mpremote run script.py      # Run local Python script on device
29

30
# Execution options
31
mpremote exec --follow "code"       # Follow output until completion (default)
32
mpremote exec --no-follow "code"    # Return immediately
33
```
34

35
### Filesystem Commands
36

37
```bash
38
# File operations (shortcuts for 'fs' commands)
39
mpremote ls [path]          # List directory contents
40
mpremote cat file           # Display file contents
41
mpremote cp src dest        # Copy files between local/remote
42
mpremote rm file            # Remove files
43
mpremote mkdir dir          # Create directory
44
mpremote rmdir dir          # Remove directory
45
mpremote touch file         # Create empty file or update timestamp
46
mpremote tree [path]        # Display directory tree
47

48
# Filesystem options
49
mpremote ls -l              # Detailed listing
50
mpremote cp -r src/ dest/   # Recursive copy
51
mpremote cp -f src dest     # Force overwrite
52
mpremote rm -r directory    # Recursive remove
53
mpremote tree -s            # Show file sizes
54
mpremote tree -h            # Human-readable sizes
55

56
# Hash verification
57
mpremote sha256sum file     # Calculate SHA256 hash
58
```
59

60
### Device Management Commands
61

62
```bash
63
# System operations
64
mpremote df                 # Show disk usage/free space
65
mpremote reset              # Hard reset device
66
mpremote bootloader         # Enter bootloader mode
67
mpremote sleep <seconds>    # Sleep/delay before next command
68

69
# Time synchronization
70
mpremote rtc                # Get device RTC time
71
mpremote rtc --set          # Set device RTC to system time
72
```
73

74
### REPL Interface
75

76
```bash
77
# Interactive REPL
78
mpremote repl                           # Enter REPL mode
79
mpremote repl --escape-non-printable    # Escape non-printable chars
80
mpremote repl --capture session.log     # Save session to file
81
mpremote repl --inject-code "setup()"   # Code to run with Ctrl-J
82
mpremote repl --inject-file script.py   # File to run with Ctrl-K
83
```
84

85
### Package Management
86

87
```bash
88
# MIP package operations
89
mpremote mip install package           # Install package from micropython-lib
90
mpremote mip install --target lib pkg  # Install to specific directory
91
mpremote mip install --index url pkg   # Install from custom index
92
mpremote mip install github:user/repo  # Install from GitHub
93
mpremote mip install gitlab:user/repo  # Install from GitLab
94
```
95

96
### File System Mounting
97

98
```bash
99
# Mount local directories
100
mpremote mount .                    # Mount current directory
101
mpremote mount /path/to/project     # Mount specific directory
102
mpremote mount --unsafe-links dir   # Follow symbolic links
103
mpremote umount                     # Unmount current mount
104
```
105

106
### ROM Filesystem Management
107

108
```bash
109
# ROMFS operations
110
mpremote romfs query                    # Query ROM partitions
111
mpremote romfs query --partition 1      # Query specific partition
112
mpremote romfs build src/               # Build ROMFS from directory
113
mpremote romfs build --output app.img src/     # Build with custom output
114
mpremote romfs build --no-mpy src/      # Build without bytecode compilation
115
mpremote romfs deploy app.img           # Deploy to default partition
116
mpremote romfs deploy --partition 1 app.img    # Deploy to specific partition
117
```
118

119
### File Editing
120

121
```bash
122
# Edit files on device
123
mpremote edit :main.py              # Edit single file
124
mpremote edit :boot.py :main.py     # Edit multiple files
125
```
126

127
### Help and Information
128

129
```bash
130
# Help and version
131
mpremote help                       # Show help information
132
mpremote version                    # Show version information
133
```
134

135
## Command Chaining
136

137
Use the `+` operator to chain multiple commands in sequence:
138

139
```bash
140
# Basic chaining
141
mpremote connect auto + exec "print('hello')" + disconnect
142

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

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

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

153
## Configuration System
154

155
### User Configuration File
156

157
Create `~/.config/mpremote/config.py` to define custom commands and shortcuts:
158

159
```python
160
# ~/.config/mpremote/config.py
161

162
commands = {
163
    # Simple command shortcuts
164
    "myboard": "connect id:334D335C3138",
165
    "setup": "connect auto rtc --set mount .",
166
    "deploy": "cp main.py : exec 'import main'",
167
    
168
    # Complex commands with help text
169
    "test": {
170
        "command": "connect auto + mount . + exec 'import unittest; unittest.main()' + umount + disconnect",
171
        "help": "Run unit tests on connected device"
172
    },
173
    
174
    # Parameterized commands
175
    "flash x": {
176
        "command": "connect auto + cp {x} : + exec 'import {x}' + disconnect", 
177
        "help": "Flash and run Python file on device"
178
    }
179
}
180
```
181

182
### Using Custom Commands
183

184
```bash
185
# Use custom shortcuts
186
mpremote myboard                    # Connects to specific device
187
mpremote setup                      # Setup development environment
188
mpremote deploy                     # Deploy current project
189

190
# Use parameterized commands
191
mpremote flash main.py              # Flash main.py file
192
mpremote test                       # Run test suite
193
```
194

195
### Advanced Configuration Examples
196

197
```python
198
# Advanced ~/.config/mpremote/config.py
199

200
commands = {
201
    # Development workflow
202
    "dev": {
203
        "command": "connect auto + rtc --set + mount . + repl",
204
        "help": "Start development session with time sync and mounted directory"
205
    },
206
    
207
    # Production deployment
208
    "prod-deploy": {
209
        "command": "connect auto + romfs build --mpy src/ --output prod.img + romfs deploy prod.img + soft-reset",
210
        "help": "Build and deploy production ROM filesystem"
211
    },
212
    
213
    # Device information gathering
214
    "info": {
215
        "command": "connect auto + exec 'import sys; print(sys.implementation)' + exec 'import micropython; micropython.mem_info()' + disconnect",
216
        "help": "Get device system information"
217
    },
218
    
219
    # Backup device code
220
    "backup": {
221
        "command": "connect auto + cp :main.py backup_main.py + cp :boot.py backup_boot.py + disconnect",
222
        "help": "Backup main device files"
223
    },
224
    
225
    # Multi-device deployment
226
    "deploy-all x": {
227
        "command": "a0 + cp {x} : + disconnect + a1 + cp {x} : + disconnect + u0 + cp {x} : + disconnect",
228
        "help": "Deploy file to multiple connected devices"
229
    }
230
}
231
```
232

233
## Environment Variables
234

235
mpremote respects the following environment variables:
236

237
```bash
238
# Editor for file editing
239
export EDITOR=nano
240
mpremote edit :main.py              # Uses nano editor
241

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

246
# Serial port timeout
247
export MPREMOTE_TIMEOUT=30          # 30 second timeout
248
```
249

250
## Command-Line Options
251

252
### Global Options
253

254
```bash
255
# Verbose output
256
mpremote -v command                 # Enable verbose mode
257
mpremote --verbose command          # Enable verbose mode
258

259
# Configuration file
260
mpremote --config custom.py cmd     # Use custom config file
261
```
262

263
### Device Connection Options
264

265
```bash
266
# Connection parameters
267
mpremote connect /dev/ttyUSB0:115200    # Specify baud rate
268
mpremote connect COM3:9600              # Windows with custom baud rate
269
mpremote connect auto:timeout=10        # Custom connection timeout
270
```
271

272
### Filesystem Command Options
273

274
```bash
275
# Detailed filesystem operations
276
mpremote fs ls -l -v                # Long format, verbose
277
mpremote fs cp -r -f src/ :dst/      # Recursive, force overwrite
278
mpremote fs tree -s -h               # Show sizes, human readable
279
```
280

281
## Best Practices
282

283
### Command Organization
284

285
```bash
286
# Group related commands
287
mpremote connect auto + rtc --set + mount . + exec "print('Ready for development')"
288

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

292
# Clean disconnection
293
mpremote connect auto + exec "your_code()" + umount + disconnect
294
```
295

296
### Configuration Management
297

298
```python
299
# Organize config by project
300
commands = {
301
    # Project A commands
302
    "proj-a-setup": "connect auto + mount /path/to/project-a + rtc --set",
303
    "proj-a-deploy": "connect auto + cp /path/to/project-a/main.py :",
304
    
305
    # Project B commands  
306
    "proj-b-setup": "connect auto + mount /path/to/project-b + rtc --set",
307
    "proj-b-deploy": "connect auto + romfs build /path/to/project-b --output proj-b.img + romfs deploy proj-b.img",
308
    
309
    # Utility commands
310
    "clean-device": "connect auto + rm :main.py + rm :boot.py + soft-reset + disconnect"
311
}
312
```
313

314
### Error Handling in Chains
315

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

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

324
## Troubleshooting
325

326
### Common Issues
327

328
```bash
329
# Permission denied on serial port
330
sudo usermod -a -G dialout $USER    # Add user to dialout group (Linux)
331
# Then logout and login again
332

333
# Device not detected
334
mpremote devs                       # List available devices
335
mpremote connect list               # List MicroPython devices
336

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

340
# Command not found in config
341
mpremote help                       # List available commands including custom ones
342
```
343

344
### Debug Mode
345

346
```bash
347
# Enable verbose output for debugging
348
mpremote -v connect auto + exec "print('debug')" + disconnect
349

350
# Test configuration
351
python -c "
352
import sys
353
sys.path.append('~/.config/mpremote')
354
import config
355
print(config.commands)
356
"
357
```