Metadata-Version: 2.4
Name: mposcli
Version: 0.7.0
Summary: CLI helper for MicroPythonOS: https://github.com/MicroPythonOS/MicroPythonOS
Project-URL: Documentation, https://github.com/jedie/mposcli
Project-URL: Source, https://github.com/jedie/mposcli
Author-email: Jens Diemer <cookiecutter_templates@jensdiemer.de>
License: GPL-3.0-or-later
Requires-Python: >=3.12
Requires-Dist: bx-py-utils
Requires-Dist: cli-base-utilities>=0.27.4
Requires-Dist: rich
Requires-Dist: tyro
Description-Content-Type: text/markdown

# mposcli

[![tests](https://github.com/jedie/mposcli/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/jedie/mposcli/actions/workflows/tests.yml)
[![codecov](https://codecov.io/github/jedie/mposcli/branch/main/graph/badge.svg)](https://app.codecov.io/github/jedie/mposcli)
[![mposcli @ PyPi](https://img.shields.io/pypi/v/mposcli?label=mposcli%20%40%20PyPi)](https://pypi.org/project/mposcli/)
[![Python Versions](https://img.shields.io/pypi/pyversions/mposcli)](https://github.com/jedie/mposcli/blob/main/pyproject.toml)
[![License GPL-3.0-or-later](https://img.shields.io/pypi/l/mposcli)](https://github.com/jedie/mposcli/blob/main/LICENSE)

Experimental CLI helper for MicroPythonOS: https://github.com/MicroPythonOS/MicroPythonOS

Main Idea: Install it via pipx (see below) and use `mposcli` command in MicroPythonOS repository path.

Install, e.g.:

```
sudo apt install pipx

pipx install mposcli
```

To upgrade an existing installation: Just call: `pipx upgrade PyHardLinkBackup`

Usage e.g.:

```
cd ~/MicroPythonOS
~/MicroPythonOS$ mposcli run-desktop
```


## CLI

[comment]: <> (✂✂✂ auto generated main help start ✂✂✂)
```
usage: mposcli [-h] {build,cp,cp-app,flash,run-desktop,shell,update,update-
submodules,version}



╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help             show this help message and exit                                 │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ──────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                             │
│   • build              Build MicroPythonOS by calling: ./scripts/build_mpos.sh         │
│                        <target> see: https://docs.micropythonos.com/os-development/    │
│   • cp                 Copy/update internal_filesystem/lib/mpos files to the device    │
│                        via "mpremote fs cp". Display a file chooser to select which    │
│                        files to copy/update. But can also be used to copy/update all   │
│                        files. see:                                                     │
│                        https://docs.micropythonos.com/architecture/filesystem/         │
│   • cp-app             Copy/update internal_filesystem/apps to the device via          │
│                        "mpremote fs cp". Display a file chooser to select which app to │
│                        copy/update. But can also be used to copy/update all files.     │
│                        see: https://docs.micropythonos.com/os-development/installing-o │
│                        n-esp32/                                                        │
│   • flash              Flash MicroPythonOS to the device. Display a file chooser to    │
│                        select the image to flash. All lvgl_micropython/build/*.bin     │
│                        files will be shown in the file chooser. see: https://docs.micr │
│                        opythonos.com/os-development/installing-on-esp32/               │
│   • run-desktop        Run MicroPythonOS on desktop. see: https://docs.micropythonos.c │
│                        om/getting-started/running/#running-on-desktop                  │
│   • shell              Start a REPL shell connected to the device using mpremote.      │
│                        Optional reset before starting the REPL. The goal it to try to  │
│                        get a REPL in a loop until it works.                            │
│   • update             Update MicroPythonOS repository. Assume that there is a         │
│                        "origin" and/or "upstream" remote configured. Will also ask if  │
│                        you want to update the submodules as well, which is             │
│                        recommended.                                                    │
│   • update-submodules  Updates MicroPythonOS git submodules only. Use "mposcli update" │
│                        to update the main repository and optionally the submodules as  │
│                        well. see: https://docs.micropythonos.com/os-development/linux/ │
│                        #optional-updating-the-code                                     │
│   • version            Print version and exit                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated main help end ✂✂✂)



## mposcli build

[comment]: <> (✂✂✂ auto generated build start ✂✂✂)
```
usage: mposcli build [-h] [{esp32,esp32s3,unphone,unix,macOS}] [-v]

Build MicroPythonOS by calling: ./scripts/build_mpos.sh <target> see:
https://docs.micropythonos.com/os-development/

╭─ positional arguments ───────────────────────────────────────────────────╮
│ [{esp32,esp32s3,unphone,unix,macOS}]                                     │
│                  Target platform to build for. (default: unix)           │
╰──────────────────────────────────────────────────────────────────────────╯
╭─ options ────────────────────────────────────────────────────────────────╮
│ -h, --help       show this help message and exit                         │
│ -v, --verbosity  Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable) │
╰──────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated build end ✂✂✂)



## mposcli cp

[comment]: <> (✂✂✂ auto generated cp start ✂✂✂)
```
usage: mposcli cp [-h] [CP OPTIONS]

Copy/update internal_filesystem/lib/mpos files to the device via "mpremote fs cp". Display
a file chooser to select which files to copy/update. But can also be used to copy/update
all files. see: https://docs.micropythonos.com/architecture/filesystem/

╭─ positional arguments ─────────────────────────────────────────────────────────────────╮
│ [{None}|PATH]         Optional file or directory path. (default: None)                 │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help            show this help message and exit                                  │
│ --new-file-limit INT  How many of the newest files to show in the file chooser?        │
│                       (default: 10)                                                    │
│ --reset, --no-reset   Reset the device after copy/update? (default: True)              │
│ --repl, --no-repl     After flashing/verify start REPL with mpremote to see the output │
│                       of the device? (default: True)                                   │
│ -v, --verbosity       Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)          │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated cp end ✂✂✂)




## mposcli cp-app

[comment]: <> (✂✂✂ auto generated cp-app start ✂✂✂)
```
usage: mposcli cp-app [-h] [--reset | --no-reset] [--repl | --no-repl] [-v]

Copy/update internal_filesystem/apps to the device via "mpremote fs cp". Display a file
chooser to select which app to copy/update. But can also be used to copy/update all files.
see: https://docs.micropythonos.com/os-development/installing-on-esp32/

╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help           show this help message and exit                                   │
│ --reset, --no-reset  Reset the device after copy/update? (default: True)               │
│ --repl, --no-repl    After flashing/verify start REPL with mpremote to see the output  │
│                      of the device? (default: True)                                    │
│ -v, --verbosity      Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)           │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated cp-app end ✂✂✂)



## mposcli flash

[comment]: <> (✂✂✂ auto generated flash start ✂✂✂)
```
usage: mposcli flash [-h] [FLASH OPTIONS]

Flash MicroPythonOS to the device. Display a file chooser to select the image to flash.
All lvgl_micropython/build/*.bin files will be shown in the file chooser. see:
https://docs.micropythonos.com/os-development/installing-on-esp32/

╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help             show this help message and exit                                 │
│ --port {None}|STR      Port used for esptool and mpremote, e.g.: "/dev/ttyUSB0" or     │
│                        "/dev/ttyACM0" etc. Leave empty for autodetection (default:     │
│                        None)                                                           │
│ --address STR          Address (default: 0x0)                                          │
│ --flash-size STR       Flash Size (default: detect)                                    │
│ --verify, --no-verify  Verify after flashing? (default: True)                          │
│ --repl, --no-repl      After flashing/verify start REPL with mpremote to see the       │
│                        output of the device? (default: True)                           │
│ -v, --verbosity        Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)         │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated flash end ✂✂✂)



## mposcli run-desktop


[comment]: <> (✂✂✂ auto generated run-desktop start ✂✂✂)
```
usage: mposcli run-desktop [-h] [--heapsize INT] [--script {None}|STR] [--binary
{None}|STR] [-v]

Run MicroPythonOS on desktop. see: https://docs.micropythonos.com/getting-
started/running/#running-on-desktop

╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help           show this help message and exit                                   │
│ --heapsize INT       Heap size in MB (default: 8, same as PSRAM on many ESP32-S3       │
│                      boards) (default: 8)                                              │
│ --script {None}|STR  Script file (.py) or app name to run. If omitted, starts          │
│                      normally. (default: None)                                         │
│ --binary {None}|STR  Optional name of the binary to start. If omitted, shows a file    │
│                      chooser to select one from the lvgl_micropython build directory.  │
│                      (default: None)                                                   │
│ -v, --verbosity      Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)           │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated run-desktop end ✂✂✂)



## mposcli shell

[comment]: <> (✂✂✂ auto generated shell start ✂✂✂)
```
usage: mposcli shell [-h] [--reset | --no-reset] [-v]

Start a REPL shell connected to the device using mpremote. Optional reset before starting
the REPL. The goal it to try to get a REPL in a loop until it works.

╭─ options ────────────────────────────────────────────────────────────────────────╮
│ -h, --help           show this help message and exit                             │
│ --reset, --no-reset  Reset the device before starting the REPL? (default: False) │
│ -v, --verbosity      Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)     │
╰──────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated shell end ✂✂✂)




## mposcli update


[comment]: <> (✂✂✂ auto generated update start ✂✂✂)
```
usage: mposcli update [-h] [--cleanup | --no-cleanup] [--shallow-clone | --no-shallow-
clone] [-v]

Update MicroPythonOS repository. Assume that there is a "origin" and/or "upstream" remote
configured. Will also ask if you want to update the submodules as well, which is
recommended.

╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help       show this help message and exit                                       │
│ --cleanup, --no-cleanup                                                                │
│                  Cleanup unnecessary files and optimize the local repository, too?     │
│                  (default: True)                                                       │
│ --shallow-clone, --no-shallow-clone                                                    │
│                  Submodules only a shallow clone with --depth=1? (default: False)      │
│ -v, --verbosity  Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)               │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated update end ✂✂✂)




## mposcli update-submodules


[comment]: <> (✂✂✂ auto generated update-submodules start ✂✂✂)
```
usage: mposcli update-submodules [-h] [--cleanup | --no-cleanup] [--shallow-clone | --no-
shallow-clone] [-v]

Updates MicroPythonOS git submodules only. Use "mposcli update" to update the main
repository and optionally the submodules as well. see: https://docs.micropythonos.com/os-
development/linux/#optional-updating-the-code

╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help       show this help message and exit                                       │
│ --cleanup, --no-cleanup                                                                │
│                  Cleanup unnecessary files and optimize the local repository, too?     │
│                  (default: True)                                                       │
│ --shallow-clone, --no-shallow-clone                                                    │
│                  Submodules only a shallow clone with --depth=1? (default: False)      │
│ -v, --verbosity  Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)               │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated update-submodules end ✂✂✂)






## start development

At least `uv` is needed. Install e.g.: via pipx:
```bash
apt-get install pipx
pipx install uv
```

Clone the project and just start the CLI help commands.
A virtual environment will be created/updated automatically.

```bash
~$ git clone https://github.com/jedie/mposcli.git
~$ cd mposcli
~/mposcli$ ./cli.py --help
~/mposcli$ ./dev-cli.py --help
```

[comment]: <> (✂✂✂ auto generated dev help start ✂✂✂)
```
usage: ./dev-cli.py [-h] {coverage,install,lint,mypy,nox,pip-audit,publish,shell-
completion,test,update,update-readme-history,update-test-snapshot-files,version}



╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help     show this help message and exit                                         │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ──────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                             │
│   • coverage   Run tests and show coverage report.                                     │
│   • install    Install requirements and 'mposcli' via pip as editable.                 │
│   • lint       Check/fix code style by run: "ruff check --fix"                         │
│   • mypy       Run Mypy (configured in pyproject.toml)                                 │
│   • nox        Run nox                                                                 │
│   • pip-audit  Run pip-audit check against current requirements files                  │
│   • publish    Build and upload this project to PyPi                                   │
│   • shell-completion                                                                   │
│                Setup shell completion for this CLI (Currently only for bash shell)     │
│   • test       Run unittests                                                           │
│   • update     Update dependencies (uv.lock) and git pre-commit hooks                  │
│   • update-readme-history                                                              │
│                Update project history base on git commits/tags in README.md Will be    │
│                exited with 1 if the README.md was updated otherwise with 0.            │
│                                                                                        │
│                Also, callable via e.g.:                                                │
│                    python -m cli_base update-readme-history -v                         │
│   • update-test-snapshot-files                                                         │
│                Update all test snapshot files (by remove and recreate all snapshot     │
│                files)                                                                  │
│   • version    Print version and exit                                                  │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```
[comment]: <> (✂✂✂ auto generated dev help end ✂✂✂)


## History

[comment]: <> (✂✂✂ auto generated history start ✂✂✂)

* [v0.7.0](https://github.com/jedie/mposcli/compare/v0.6.0...v0.7.0)
  * 2026-03-24 - Safe diskspace in mposcli update / update-submodules
  * 2026-03-22 - Use "retry loop" for copy, too
* [v0.6.0](https://github.com/jedie/mposcli/compare/v0.5.0...v0.6.0)
  * 2026-03-21 - NEW: "shell" to start the REPL
* [v0.5.0](https://github.com/jedie/mposcli/compare/v0.4.1...v0.5.0)
  * 2026-03-08 - update README
  * 2026-03-05 - Enhance "cp" command and auto restart "mpremote repl"
  * 2026-03-03 - Refactor "cp" command
  * 2026-03-03 - flash command: use port auto detection as default
* [v0.4.1](https://github.com/jedie/mposcli/compare/v0.4.0...v0.4.1)
  * 2026-02-27 - Use "--force" for pulling submodules to overwrite local changes

<details><summary>Expand older history entries ...</summary>

* [v0.4.0](https://github.com/jedie/mposcli/compare/v0.3.0...v0.4.0)
  * 2026-02-24 - NEW command: "cp-app" to install/update internal_filesystem/apps
  * 2026-02-24 - Log skipped files
  * 2026-02-23 - Update requirements and fix code style
  * 2026-02-23 - "build" command: target as positional argument
  * 2026-02-23 - Expand "cp" command and allow optional filesystem path
* [v0.3.0](https://github.com/jedie/mposcli/compare/v0.2.0...v0.3.0)
  * 2026-02-18 - Add "update" beside "update-submodules"
  * 2026-02-17 - Update requirements
  * 2026-02-16 - update README
* [v0.2.0](https://github.com/jedie/mposcli/compare/v0.1.0...v0.2.0)
  * 2026-02-16 - New CLI command: "cp" with convenience features.
  * 2026-02-16 - New command: "flash" with file selector
  * 2026-02-16 - Update README.md
* [v0.1.0](https://github.com/jedie/mposcli/compare/1695026...v0.1.0)
  * 2026-02-16 - Add "update-submodules" command
  * 2026-02-16 - Add "build" command
  * 2026-02-16 - CLI command: "run-desktop"
  * 2026-02-16 - first commit

</details>


[comment]: <> (✂✂✂ auto generated history end ✂✂✂)
