Point the README and the command docs at plugin packages

Loading a command by path is for local development; a package is how a
command is distributed. The README's summary of what extends MVT now
names plugin packages and nothing else, and the section on loading a
command file says what it is for: keeping a command being written
loadable without reinstalling its package after every change.

README.md

@@ -58,34 +58,31 @@ For alternative installation options and known issues, please refer to the [docu
 
 ## Usage
 
-MVT provides two commands `mvt-ios` and `mvt-android`. [Check out the documentation to learn how to use them!](https://docs.mvt.re/)
+MVT provides three commands: `mvt-ios` and `mvt-android` analyse acquisitions from devices of that platform, and `mvt` hosts what belongs to neither: `version`, `completion` and `download-iocs` (`version` and `download-iocs` remain available on the platform commands for now). Running `mvt` on its own shows the installed version, update notices and the available commands. [Check out the documentation to learn how to use them!](https://docs.mvt.re/)
 
 ### Shell completion
 
-MVT can generate shell completion scripts for Bash, Zsh, and Fish:
+MVT can generate a shell completion script for Bash, Zsh, and Fish which covers `mvt`, `mvt-ios` and `mvt-android`:
 
 ```bash
-mvt-ios completion
-mvt-android completion
+mvt completion
 ```
 
-The commands print setup instructions by default. To generate a completion script directly, pass the shell name:
+The command prints setup instructions by default. To generate the completion script directly, pass the shell name:
 
 ```bash
-mvt-ios completion bash
-mvt-android completion zsh
+mvt completion bash
 ```
 
 MVT only writes completion files or shell configuration when `--install` is passed. See the [command completion documentation](https://docs.mvt.re/en/latest/command_completion/) for details.
-Module-running `check-*` commands can load custom Python modules with
-`--load-module PATH` or from a folder set in `MVT_CUSTOM_MODULES`. See the
-[development documentation](https://docs.mvt.re/en/latest/development/) for
-details.
 
-Users can also add top-level commands to `mvt-ios` and `mvt-android` from
-installed Python packages or local files and folders. See the
-[custom CLI command documentation](https://docs.mvt.re/en/latest/custom_commands/)
-for the plugin entry points and `--load-command` interface.
+Plugin packages extend MVT with additional forensic modules, which run inside
+the `check-*` commands, and with top-level commands on `mvt`, `mvt-ios` and
+`mvt-android`. See the
+[development documentation](https://docs.mvt.re/en/latest/development/) for
+writing and installing them, and the
+[custom CLI command documentation](https://docs.mvt.re/en/latest/development/custom_commands/)
+for the entry points a package registers commands in.
 
 
 ## License

docs/command_completion.md

@@ -6,61 +6,61 @@ Click provides tab completion support for Bash (version 4.4 and up), Zsh, and Fi
 
 To enable it, you need to register a completion script with your shell, which varies depending on the shell you are using.
 
-The following describes how to generate the command completion scripts and add them to your shell configuration.
+`mvt completion` generates one script which covers `mvt`, `mvt-ios` and `mvt-android`. The following describes how to generate that script and add it to your shell configuration.
 
 > **Note: You will need to start a new shell for the changes to take effect.**
 
 ### For Bash
 
 ```bash
-# Generate bash completion scripts
-mvt-ios completion bash > ~/.mvt-ios-complete.bash
-mvt-android completion bash > ~/.mvt-android-complete.bash
+# Generate the bash completion script
+mvt completion bash > ~/.mvt-complete.bash
 ```
 
 Add the following to `~/.bashrc`:
 ```bash
-# source mvt completion scripts
-[ -f ~/.mvt-ios-complete.bash ] && . ~/.mvt-ios-complete.bash
-[ -f ~/.mvt-android-complete.bash ] && . ~/.mvt-android-complete.bash
+# source the mvt completion script
+[ -f ~/.mvt-complete.bash ] && . ~/.mvt-complete.bash
 ```
 
 ### For Zsh
 
 ```bash
-# Generate zsh completion scripts
-mvt-ios completion zsh > ~/.mvt-ios-complete.zsh
-mvt-android completion zsh > ~/.mvt-android-complete.zsh
+# Generate the zsh completion script
+mvt completion zsh > ~/.mvt-complete.zsh
 ```
 
 Add the following to `~/.zshrc`:
 ```bash
-# source mvt completion scripts
-[ -f ~/.mvt-ios-complete.zsh ] && . ~/.mvt-ios-complete.zsh
-[ -f ~/.mvt-android-complete.zsh ] && . ~/.mvt-android-complete.zsh
+# source the mvt completion script
+[ -f ~/.mvt-complete.zsh ] && . ~/.mvt-complete.zsh
 ```
 
 ### For Fish
 
 ```bash
-# Generate fish completion scripts
-mkdir -p ~/.config/fish/completions
-mvt-ios completion fish > ~/.config/fish/completions/mvt-ios.fish
-mvt-android completion fish > ~/.config/fish/completions/mvt-android.fish
+# Generate the fish completion script
+mkdir -p ~/.config/fish/conf.d
+mvt completion fish > ~/.config/fish/conf.d/mvt-completion.fish
 ```
 
-Fish loads completion files from `~/.config/fish/completions` automatically.
+Fish loads the files in `~/.config/fish/conf.d` automatically.
 
 ### Automatic Installation
 
 MVT can write the completion file and update the relevant shell configuration for Bash and Zsh when you pass `--install`:
 
 ```bash
-mvt-ios completion bash --install
-mvt-android completion bash --install
+mvt completion bash --install
 ```
 
-Replace `bash` with `zsh` or `fish` as needed. For Fish, `--install` writes the completion file into `~/.config/fish/completions`.
+Replace `bash` with `zsh` or `fish` as needed. For Fish, `--install` writes the completion file into `~/.config/fish/conf.d` and changes no shell configuration.
+
+!!! note
+
+    Earlier versions generated one script per command, with `mvt-ios completion`
+    and `mvt-android completion`. Files written by them keep working. When you
+    switch to the single script, remove the old files and the lines which load
+    them from your shell configuration.
 
 For more information, visit the official [Click Docs](https://click.palletsprojects.com/en/stable/shell-completion/#enabling-completion).
-

docs/custom_commands.md

@@ -1,107 +0,0 @@
-# Custom CLI Commands
-
-MVT can load additional top-level commands into `mvt-ios` and `mvt-android`.
-Custom commands are different from [custom forensic modules](development.md#custom-modules):
-commands add new CLI operations, while modules add analysis steps to existing
-`check-*` commands.
-
-!!! warning
-
-    Custom commands run as trusted Python code inside the MVT process. Install
-    or load commands only from sources you trust. MVT does not sandbox
-    third-party commands, and the MVT maintainers do not maintain them.
-
-## Install a Command Package
-
-Python packages can register a Click command or group for either MVT CLI. A
-minimal package can expose this command from `my_mvt_plugin.py`:
-
-```python
-import click
-
-
-@click.command()
-@click.argument("path", type=click.Path(exists=True))
-def summarize(path):
-    """Summarize an acquisition."""
-    click.echo(f"Summarizing {path}")
-```
-
-Register the object in the package's `pyproject.toml`. The entry-point name is
-the command users invoke:
-
-```toml
-[project.entry-points."mvt.ios.cli_plugins"]
-summarize = "my_mvt_plugin:summarize"
-
-[project.entry-points."mvt.android.cli_plugins"]
-summarize = "my_mvt_plugin:summarize"
-```
-
-Use only the iOS or Android group if the command is platform-specific. After
-installing the package in the same environment as MVT, it appears directly in
-the appropriate CLI:
-
-```bash
-mvt-ios summarize ./ios-backup
-mvt-android summarize ./androidqf-output
-```
-
-For a `pipx` installation of MVT, inject the plugin into MVT's environment:
-
-```bash
-pipx inject mvt my-mvt-plugin
-```
-
-When MVT is installed in an active virtual environment, install the plugin with
-`pip` in that environment.
-
-## Load a Command File
-
-For local commands that are not packaged, create a Python file that exports one
-Click command or group named `cli`:
-
-```python
-import click
-
-
-@click.command("case-summary")
-@click.argument("path", type=click.Path(exists=True))
-def cli(path):
-    """Summarize a case directory."""
-    click.echo(f"Summarizing {path}")
-```
-
-Pass the file before the custom command name:
-
-```bash
-mvt-ios --load-command ./case_summary.py case-summary ./ios-backup
-```
-
-`--load-command` can be repeated and also accepts a folder. MVT loads
-non-hidden top-level `*.py` files in sorted order and skips `__init__.py`.
-Every loaded file must export one `cli` object.
-
-To load a file or folder on every invocation, set the platform-specific
-environment variable:
-
-```bash
-export MVT_IOS_CUSTOM_COMMANDS=./ios_commands
-export MVT_ANDROID_CUSTOM_COMMANDS=./android_commands
-```
-
-## Naming and Errors
-
-Built-in MVT commands cannot be replaced. External command names must also be
-unique; when installed packages or environment paths collide, MVT keeps the
-first command and logs a warning. A collision from an explicit
-`--load-command` is a usage error.
-
-A package entry point or environment command that cannot be imported appears
-as a marked broken command without preventing other MVT commands from working.
-Invoke that command to see its package or file source and the underlying error.
-An invalid command supplied explicitly with `--load-command` fails immediately
-with a usage error.
-
-Installed command packages use the entry-point name as the CLI command name.
-The entry point must resolve to a `click.Command` or `click.Group`.

docs/development/custom_commands.md

@@ -0,0 +1,143 @@
+# Custom CLI Commands
+
+MVT can load additional top-level commands into `mvt`, `mvt-ios` and
+`mvt-android`. A command package chooses which of the three each of its
+commands is added to.
+Custom commands are different from [custom forensic modules](index.md#custom-modules):
+commands add new CLI operations, while modules add analysis steps to existing
+`check-*` commands.
+
+!!! warning
+
+    Custom commands run as trusted Python code inside the MVT process. Install
+    or load commands only from sources you trust. MVT does not sandbox
+    third-party commands, and the MVT maintainers do not maintain them.
+
+## Install a Command Package
+
+Python packages can register a Click command or group on one or more of the MVT CLIs.
+A minimal package can expose this command from `my_mvt_plugin.py`:
+
+```python
+import click
+
+
+@click.command()
+@click.argument("path", type=click.Path(exists=True))
+def summarize(path):
+    """Summarize an acquisition."""
+    click.echo(f"Summarizing {path}")
+```
+
+Register the object in the package's `pyproject.toml`. The entry-point name is
+the command users invoke:
+
+```toml
+[project.entry-points."mvt.ios.cli_plugins"]
+summarize = "my_mvt_plugin:summarize"
+
+[project.entry-points."mvt.android.cli_plugins"]
+summarize = "my_mvt_plugin:summarize"
+```
+
+Each entry-point group adds the command to one CLI: `mvt.ios.cli_plugins` to
+`mvt-ios`, `mvt.android.cli_plugins` to `mvt-android` and `mvt.cli_plugins` to
+`mvt`. Register the command in the group of every CLI which should offer it: a
+platform-specific command belongs in one platform group, and a command which
+handles acquisitions of both platforms, as above, in both. After installing the
+package in the same environment as MVT, the command appears directly in those
+CLIs:
+
+```bash
+mvt-ios summarize ./ios-backup
+mvt-android summarize ./androidqf-output
+```
+
+For a `pipx` installation of MVT, inject the plugin into MVT's environment:
+
+```bash
+pipx inject mvt my-mvt-plugin
+```
+
+When MVT is installed in an active virtual environment, install the plugin with
+`pip` in that environment.
+
+Command packages that need their own settings, such as an API key, should store
+them in a namespaced [plugin configuration file](plugin_configuration.md)
+rather than in MVT's own `config.yaml`.
+
+### Commands on `mvt`
+
+The `mvt` command hosts what belongs to neither platform: `version`,
+`completion` and `download-iocs`. A plugin command which is not about the
+acquisition of one platform, such as one which configures the plugin or
+synchronizes the indicators it uses, belongs there too, in the
+`mvt.cli_plugins` group:
+
+```toml
+[project.entry-points."mvt.cli_plugins"]
+my-plugin = "my_mvt_plugin:my_plugin"
+```
+
+Commands in this group are added to `mvt` only, so this one is invoked as
+`mvt my-plugin`. A command on `mvt` has nothing but its name to say which
+plugin it belongs to, so name it after the plugin, and make it a Click group
+when the plugin has several operations to offer, such as
+`mvt my-plugin configure`.
+
+## Developing a Command Locally
+
+A package is how a command is distributed. While a command is being written,
+MVT can load it straight from its file instead, so the package need not be
+reinstalled after every change; an editable install of the package does the
+same through its entry points. Create a Python file that exports one Click
+command or group named `cli`:
+
+```python
+import click
+
+
+@click.command("case-summary")
+@click.argument("path", type=click.Path(exists=True))
+def cli(path):
+    """Summarize a case directory."""
+    click.echo(f"Summarizing {path}")
+```
+
+Pass the file before the custom command name:
+
+```bash
+mvt-ios --load-command ./case_summary.py case-summary ./ios-backup
+```
+
+`--load-command` can be repeated and also accepts a folder. MVT loads
+non-hidden top-level `*.py` files in sorted order and skips `__init__.py`.
+Every loaded file must export one `cli` object.
+
+To load a file or folder on every invocation, set the environment variable of
+the CLI the commands belong on. Like the entry-point groups, each variable adds
+its commands to one CLI only:
+
+```bash
+export MVT_CUSTOM_COMMANDS=./commands
+export MVT_IOS_CUSTOM_COMMANDS=./ios_commands
+export MVT_ANDROID_CUSTOM_COMMANDS=./android_commands
+```
+
+## Naming and Errors
+
+Built-in MVT commands cannot be replaced. External command names must also be
+unique on each CLI; when installed packages or environment paths collide, MVT
+keeps the first command and logs a warning. The environment path of a CLI is
+registered before its installed packages, so a command loaded from there wins a
+collision with a package. A collision from an explicit `--load-command` is a
+usage error.
+
+A package entry point or environment command that cannot be imported appears
+as a marked broken command without preventing other MVT commands from working.
+Invoke that command to see its package or file source and the underlying error.
+An invalid command supplied explicitly with `--load-command` fails immediately
+with a usage error.
+
+Installed command packages use the entry-point name as the CLI command name.
+The entry point must resolve to a `click.Command` or `click.Group`.

docs/development/index.md

@@ -35,9 +35,16 @@ class DependentModule(MVTModule):
         prerequisite_results = self.get_dependency_results(PrerequisiteModule)
 ```
 
-Selecting a single module also runs its transitive dependencies. If a dependency
-is unavailable or the dependency graph contains a cycle, the command logs a
-warning and does not run any modules.
+Selecting a single module also runs its transitive dependencies.
+
+A module can only depend on modules the command it runs in also has. When a
+declared dependency is not among them, the command logs a warning naming the
+module and the missing dependency, skips that module and everything depending
+on it, and runs the rest of the analysis. Selecting such a module with
+`--module` therefore leaves nothing to run, which the warning explains.
+
+A cycle in the dependency graph is a programming error rather than a
+configuration problem: the command logs a warning and runs no modules at all.
 
 ## Custom modules
 
@@ -160,6 +167,10 @@ For a `pipx` installation of MVT, inject the package into MVT's environment:
 pipx inject mvt mvt-plugin-amnesty-custom
 ```
 
+Module packages that need their own settings, such as an API key, should store
+them in a namespaced [plugin configuration file](plugin_configuration.md)
+rather than in MVT's own `config.yaml`.
+
 ### Naming module packages
 
 Name module packages `mvt-plugin-<name>` (import package `mvt_plugin_<name>`),

docs/development/plugin_configuration.md

@@ -0,0 +1,149 @@
+# Plugin Configuration
+
+Plugin packages that add [custom CLI commands](custom_commands.md) or
+[modules](index.md#installed-module-packages) often need to store their
+own settings, such as an API key, a server URL or the timestamp of the last
+synchronization. MVT provides a namespaced settings base class so each plugin
+keeps its configuration in its own file, and a data folder for anything else a
+plugin needs to keep on disk.
+
+!!! warning
+
+    Do not write plugin settings to MVT's own `config.yaml`. MVT rewrites that
+    file with the settings it knows about every time it starts, so any other
+    section is deleted.
+
+## Where Settings Are Stored
+
+Each plugin gets one YAML file in a `plugins` folder next to MVT's own
+configuration:
+
+```
+~/.config/mvt/plugins/<plugin name>.yaml
+```
+
+The exact parent folder follows the platform convention used for MVT's
+`config.yaml` (for example `~/Library/Application Support/mvt` on macOS). Use
+`mvt.common.plugin_config.plugin_config_path()` instead of building the path by
+hand.
+
+Plugin names must be lowercase and may only contain letters, digits and dashes,
+matching the `mvt-plugin-<name>` package naming convention. MVT creates the
+`plugins` folder with `0700` permissions and writes the settings files with
+`0600` permissions, because they commonly hold credentials. Files are written
+through a temporary file and moved into place, so an interrupted save never
+leaves a partially written settings file behind.
+
+## Plugin Data Folder
+
+Everything else a plugin keeps on disk, such as a cache, a downloaded artifact
+or synchronization state, belongs in the folder returned by the `data_folder()`
+class method of the plugin's settings class, or by
+`mvt.common.plugin_config.plugin_data_folder()` called with the plugin name if
+the plugin has no settings class:
+
+```
+~/.local/share/mvt/plugin-data/<plugin name>/                # Linux
+~/Library/Application Support/mvt/plugin-data/<plugin name>/ # macOS
+```
+
+The folder sits beside MVT's own data, such as the downloaded indicators. It is
+created if it is missing, with `0700` permissions. Asking for it again returns
+the same path and leaves the contents alone, so a plugin can ask for it every
+time it needs the folder. `ExamplePluginSettings` below is the settings class
+defined in the next section:
+
+```python
+import os
+
+
+def cache_path() -> str:
+    folder = ExamplePluginSettings.data_folder()
+    return os.path.join(folder, "virustotal_lookups_cache.json")
+```
+
+A plugin which has no settings class calls
+`plugin_data_folder("example-plugin")` instead.
+
+Do not fall back on a path of your own such as `~/.cache/example-plugin`: it
+is a Linux-only convention, and MVT will not create it for you.
+
+## Defining Plugin Settings
+
+Subclass `MVTPluginSettings`, set `plugin_name` and declare typed fields with
+defaults:
+
+```python
+from typing import Optional
+
+from mvt.common.plugin_config import MVTPluginSettings
+
+
+class ExamplePluginSettings(MVTPluginSettings):
+    plugin_name = "example-plugin"
+
+    API_KEY: Optional[str] = None
+    MAX_RESULTS: int = 25
+    LAST_SYNC: Optional[str] = None
+```
+
+`load()` returns the current settings and `save()` writes them back:
+
+```python
+from datetime import datetime, timezone
+
+import click
+
+
+def sync():
+    settings = ExamplePluginSettings.load()
+    if not settings.API_KEY:
+        raise click.ClickException(
+            "No API key configured. Set MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY or "
+            "run 'example-plugin configure'."
+        )
+
+    settings.LAST_SYNC = datetime.now(timezone.utc).isoformat()
+    settings.save()
+```
+
+A missing settings file is not an error: the plugin then runs on the field
+defaults and on whatever the environment provides. `save()` only persists the
+values that differ from the defaults, and it never touches MVT's `config.yaml`.
+A settings file that cannot be parsed, or that does not hold a mapping of
+setting names to values, raises a `PluginConfigLoadError` naming the file.
+
+Every subclass that sets its own `plugin_name` gets its own file and its own
+environment namespace. A subclass that does not redefine `plugin_name` inherits
+it, and therefore shares the file and the environment variables of its parent
+class.
+
+## Environment Variables
+
+Every field can also be set with an environment variable. The prefix is
+`MVT_PLUGIN_`, followed by the plugin name upper-cased with dashes replaced by
+underscores, followed by the field name. For the example above:
+
+```bash
+export MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY=...
+export MVT_PLUGIN_EXAMPLE_PLUGIN_MAX_RESULTS=50
+```
+
+Settings resolve in this order, from highest to lowest priority:
+
+1. Arguments passed to the settings class directly, such as
+   `ExamplePluginSettings(API_KEY="...")`
+2. Environment variables
+3. The plugin's YAML file
+4. The field defaults declared on the settings class
+
+!!! tip
+
+    On shared or multi-user machines, prefer passing API keys through
+    environment variables rather than saving them to the plugin file. `save()`
+    skips every value that the environment currently supplies, so a credential
+    provided that way is not copied into the settings file when a plugin saves
+    an unrelated setting.
+
+Unknown keys in a plugin's YAML file are ignored, so a settings file written by
+a newer version of a plugin does not break an older one.

docs/index.md

@@ -9,7 +9,7 @@ Mobile Verification Toolkit (MVT) is a tool to facilitate the [consensual forens
 It has been developed and released by the [Amnesty International Security Lab](https://securitylab.amnesty.org) in July 2021 in the context of the [Pegasus Project](https://forbiddenstories.org/about-the-pegasus-project/) along with [a technical forensic methodology](https://www.amnesty.org/en/latest/research/2021/07/forensic-methodology-report-how-to-catch-nso-groups-pegasus/). It continues to be maintained by Amnesty International and other contributors.
 
 
-In this documentation you will find instructions on how to install and run the `mvt-ios` and `mvt-android` commands, and guidance on how to interpret the extracted results.
+In this documentation you will find instructions on how to install and run the `mvt-ios`, `mvt-android` and `mvt` commands, and guidance on how to interpret the extracted results.
 
 ## Resources
 

docs/install.md

@@ -64,7 +64,7 @@ It is recommended to try installing and running MVT from [Windows Subsystem Linu
    pipx install mvt
    ```
 
-You now should have the `mvt-ios` and `mvt-android` utilities installed. If you run into problems with these commands not being found, ensure you have run `pipx ensurepath` and opened a new terminal window.
+You now should have the `mvt`, `mvt-ios` and `mvt-android` utilities installed. If you run into problems with these commands not being found, ensure you have run `pipx ensurepath` and opened a new terminal window.
 
 ### Installing from PyPI directly into a virtual environment
 You can use `pipenv`, `poetry` etc. for your virtual environment, but the provided example is with the built-in `venv` tool:
@@ -84,7 +84,7 @@ source env/bin/activate
 pip install mvt
 ```
 
-The `mvt-ios` and `mvt-android` utilities should now be available as commands whenever the virtual environment is active.
+The `mvt`, `mvt-ios` and `mvt-android` utilities should now be available as commands whenever the virtual environment is active.
 
 ### Installing from git source with pipx
 If you want to have the latest features in development, you can install MVT directly from the source code in git.
@@ -93,7 +93,7 @@ If you want to have the latest features in development, you can install MVT dire
 pipx install --force git+https://github.com/mvt-project/mvt.git
 ```
 
-You now should have the `mvt-ios` and `mvt-android` utilities installed.
+You now should have the `mvt`, `mvt-ios` and `mvt-android` utilities installed.
 
 **Notes:**
 1. The `--force` flag is necessary to force the reinstallation of the package.

docs/iocs.md

@@ -71,7 +71,7 @@ So far MVT implements only a subset of [STIX2 specifications](https://docs.oasis
 - [This repository](https://github.com/Te-k/stalkerware-indicators) contains IOCs for Android stalkerware including [a STIX MVT-compatible file](https://raw.githubusercontent.com/Te-k/stalkerware-indicators/master/generated/stalkerware.stix2).
 - We are also maintaining [a list of IOCs](https://github.com/mvt-project/mvt-indicators) in STIX format from public spyware campaigns.
 
-You can automaticallly download the latest public indicator files with the command `mvt-ios download-iocs` or `mvt-android download-iocs`. These commands download the list of indicators from the [mvt-indicators](https://github.com/mvt-project/mvt-indicators/blob/main/indicators.yaml) repository and store them in the [appdir](https://pypi.org/project/appdirs/) folder. They are then loaded automatically by MVT.
+You can automatically download the latest public indicator files with the command `mvt download-iocs`. The per-platform forms `mvt-ios download-iocs` and `mvt-android download-iocs` do the same thing. These commands download the list of indicators from the [mvt-indicators](https://github.com/mvt-project/mvt-indicators/blob/main/indicators.yaml) repository and store them in the [appdir](https://pypi.org/project/appdirs/) folder. They are then loaded automatically by MVT.
 
 Please [open an issue](https://github.com/mvt-project/mvt/issues/) to suggest new sources of STIX-formatted IOCs.
 

mkdocs.yml

@@ -50,6 +50,7 @@ nav:
         - Check Android Intrusion Logs: "android/intrusion_logs.md"
     - Indicators of Compromise: "iocs.md"
     - Development:
-        - Development Instructions: "development.md"
-        - Custom CLI Commands: "custom_commands.md"
+        - Development Instructions: "development/index.md"
+        - Custom CLI Commands: "development/custom_commands.md"
+        - Plugin Configuration: "development/plugin_configuration.md"
     - License: "license.md"

pyproject.toml

@@ -44,8 +44,9 @@ homepage = "https://docs.mvt.re/en/latest/"
 repository = "https://github.com/mvt-project/mvt"
 
 [project.scripts]
-mvt-ios = "mvt.ios:cli"
-mvt-android = "mvt.android:cli"
+mvt = "mvt.cli:main"
+mvt-ios = "mvt.ios:main"
+mvt-android = "mvt.android:main"
 
 [dependency-groups]
 dev = [

src/mvt/android/__init__.py

@@ -3,4 +3,4 @@
 # Use of this software is governed by the MVT License 1.1 that can be found at
 #   https://license.mvt.re/1.1/
 
-from .cli import cli
+from .cli import cli, main

src/mvt/android/cli.py

@@ -15,12 +15,6 @@ from mvt.common.cli_plugins import (
     register_cli_plugins,
 )
 from mvt.common.cmd_check_iocs import CmdCheckIOCS
-from mvt.common.completion import (
-    SUPPORTED_SHELLS,
-    completion_instructions,
-    generate_completion_script,
-    install_completion_script,
-)
 from mvt.common.help import (
     HELP_MSG_ANDROID_BACKUP_PASSWORD,
     HELP_MSG_CHECK_ADB_REMOVED,
@@ -31,7 +25,6 @@ from mvt.common.help import (
     HELP_MSG_CHECK_IOCS,
     HELP_MSG_CHECK_INTRUSION_LOGS,
     HELP_MSG_DELAY_CHECKS,
-    HELP_MSG_COMPLETION,
     HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK,
     HELP_MSG_DISABLE_UPDATE_CHECK,
     HELP_MSG_HASHES,
@@ -102,55 +95,20 @@ def cli(ctx, disable_update_check, disable_indicator_update_check):
     ctx.ensure_object(dict)
     ctx.obj["disable_version_check"] = disable_update_check
     ctx.obj["disable_indicator_check"] = disable_indicator_update_check
-    if ctx.invoked_subcommand != "completion":
-        logo(
-            disable_version_check=disable_update_check,
-            disable_indicator_check=disable_indicator_update_check,
-        )
+    logo(
+        disable_version_check=disable_update_check,
+        disable_indicator_check=disable_indicator_update_check,
+    )
 
 
 # ==============================================================================
 # Command: version
 # ==============================================================================
-@cli.command("version", help=HELP_MSG_VERSION)
+@cli.command("version", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_VERSION)
 def version():
     return
 
 
-# ==============================================================================
-# Command: completion
-# ==============================================================================
-@cli.command("completion", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_COMPLETION)
-@click.argument("shell", required=False, type=click.Choice(SUPPORTED_SHELLS))
-@click.option(
-    "--install",
-    is_flag=True,
-    help="Write completion files and update shell configuration.",
-)
-@click.pass_context
-def completion(ctx, shell, install):
-    program_name = "mvt-android"
-
-    if shell is None:
-        if install:
-            raise click.UsageError("A shell is required when using --install.")
-        click.echo(completion_instructions(program_name))
-        return
-
-    root_cli = ctx.find_root().command
-
-    if install:
-        script_path = install_completion_script(root_cli, program_name, shell)
-        click.echo(f"Installed {shell} completion to {script_path}")
-        if shell in ("bash", "zsh"):
-            click.echo(f"Updated ~/.{shell}rc")
-        else:
-            click.echo("Fish loads completion files automatically.")
-        return
-
-    click.echo(generate_completion_script(root_cli, program_name, shell))
-
-
 # ==============================================================================
 # Command: check-adb (removed)
 # ==============================================================================
@@ -514,8 +472,19 @@ def download_indicators():
     ioc_updates.update()
 
 
-register_cli_plugins(
-    cli,
-    entry_point_group=ANDROID_CLI_PLUGIN_GROUP,
-    environment_variable=MVT_ANDROID_CUSTOM_COMMANDS_ENV,
-)
+# ==============================================================================
+# Entry point of the mvt-android console script
+# ==============================================================================
+def main() -> None:
+    """Register the external commands and run the mvt-android CLI.
+
+    External commands are registered here rather than when this module is
+    imported, so that importing MVT never runs third-party code and a plugin
+    importing from MVT cannot re-enter a module that is still initializing.
+    """
+    register_cli_plugins(
+        cli,
+        entry_point_group=ANDROID_CLI_PLUGIN_GROUP,
+        environment_variable=MVT_ANDROID_CUSTOM_COMMANDS_ENV,
+    )
+    cli()

src/mvt/cli.py

@@ -0,0 +1,102 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+import click
+
+from mvt.common.cli_plugins import (
+    MVT_CUSTOM_COMMANDS_ENV,
+    NEUTRAL_CLI_PLUGIN_GROUP,
+    load_cli_commands_option,
+    register_cli_plugins,
+)
+from mvt.common.completion import completion
+from mvt.common.help import (
+    HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK,
+    HELP_MSG_DISABLE_UPDATE_CHECK,
+    HELP_MSG_STIX2,
+    HELP_MSG_VERSION,
+)
+from mvt.common.logo import logo
+from mvt.common.updates import IndicatorsUpdates
+from mvt.common.utils import init_logging
+
+init_logging()
+
+CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
+
+
+# ==============================================================================
+# Main
+# ==============================================================================
+@click.group(invoke_without_command=True)
+@load_cli_commands_option
+@click.option(
+    "--disable-update-check", is_flag=True, help=HELP_MSG_DISABLE_UPDATE_CHECK
+)
+@click.option(
+    "--disable-indicator-update-check",
+    is_flag=True,
+    help=HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK,
+)
+@click.pass_context
+def cli(ctx, disable_update_check, disable_indicator_update_check):
+    """Mobile Verification Toolkit.
+
+    mvt-ios and mvt-android run the forensic analysis of an acquisition: each
+    provides the check-* commands of its platform. This command hosts what
+    belongs to neither platform; run it without a command to see the installed
+    version and the list of what it offers.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["disable_version_check"] = disable_update_check
+    ctx.obj["disable_indicator_check"] = disable_indicator_update_check
+    if ctx.invoked_subcommand != "completion":
+        logo(
+            disable_version_check=disable_update_check,
+            disable_indicator_check=disable_indicator_update_check,
+        )
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ==============================================================================
+# Command: download-iocs
+# ==============================================================================
+@cli.command("download-iocs", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_STIX2)
+def download_iocs():
+    ioc_updates = IndicatorsUpdates()
+    ioc_updates.update()
+
+
+# ==============================================================================
+# Command: completion
+# ==============================================================================
+cli.add_command(completion)
+
+
+# ==============================================================================
+# Command: version
+# ==============================================================================
+@cli.command("version", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_VERSION)
+def version():
+    return
+
+
+# ==============================================================================
+# Entry point of the mvt console script
+# ==============================================================================
+def main() -> None:
+    """Register the external commands and run the mvt CLI.
+
+    External commands are registered here rather than when this module is
+    imported, so that importing MVT never runs third-party code and a plugin
+    importing from MVT cannot re-enter a module that is still initializing.
+    """
+    register_cli_plugins(
+        cli,
+        entry_point_group=NEUTRAL_CLI_PLUGIN_GROUP,
+        environment_variable=MVT_CUSTOM_COMMANDS_ENV,
+    )
+    cli()

src/mvt/common/cli_plugins.py

@@ -17,6 +17,9 @@ import click
 
 IOS_CLI_PLUGIN_GROUP = "mvt.ios.cli_plugins"
 ANDROID_CLI_PLUGIN_GROUP = "mvt.android.cli_plugins"
+# Commands in this group are registered on the platform-neutral mvt command only.
+NEUTRAL_CLI_PLUGIN_GROUP = "mvt.cli_plugins"
+MVT_CUSTOM_COMMANDS_ENV = "MVT_CUSTOM_COMMANDS"
 MVT_IOS_CUSTOM_COMMANDS_ENV = "MVT_IOS_CUSTOM_COMMANDS"
 MVT_ANDROID_CUSTOM_COMMANDS_ENV = "MVT_ANDROID_CUSTOM_COMMANDS"
 
@@ -255,6 +258,16 @@ def register_cli_plugins(
     entry_point_group: str,
     environment_variable: str,
 ) -> None:
+    """Register the external commands of one CLI on its group.
+
+    Each CLI has one entry-point group and one environment variable of its
+    own, so a command package chooses the CLIs its commands are added to.
+
+    :param group: CLI group to register the external commands on.
+    :param entry_point_group: Entry-point group of the CLI.
+    :param environment_variable: Name of the environment variable holding a
+                                 path to load commands from.
+    """
     environment_path = os.environ.get(environment_variable)
     if environment_path:
         register_cli_commands_from_path(group, environment_path)

src/mvt/common/command.py

@@ -317,6 +317,81 @@ class Command:
         console.print("")
         console.print(panel)
 
+    def _skipped_modules(
+        self,
+        required: list[type[MVTModule]],
+        module_indexes: dict[type[MVTModule], int],
+    ) -> dict[type[MVTModule], tuple[type[MVTModule], type[MVTModule]]]:
+        """Return the modules to drop because a dependency is unavailable.
+
+        A module declaring a dependency this command cannot provide is unable
+        to run, and so is every module depending on it. Dropping only those
+        keeps a single wrong declaration - in a module scoped to several
+        commands, for example - from silencing an entire analysis.
+
+        The returned mapping gives, for each skipped module, the module which
+        is missing a dependency and the dependency it is missing.
+        """
+        skipped: dict[type[MVTModule], tuple[type[MVTModule], type[MVTModule]]] = {}
+        # Skipping the one module a run was asked for leaves nothing to run,
+        # which the caller reports instead.
+        remainder = (
+            "" if self.module_name else " The rest of the analysis will still run."
+        )
+
+        # Skipping one module can skip the modules depending on it, which the
+        # pass over the module list may already have gone past, so repeat the
+        # pass until nothing changes.
+        changed = True
+        while changed:
+            changed = False
+            for module in required:
+                if module in skipped:
+                    continue
+
+                for dependency in module.dependencies:
+                    if dependency not in module_indexes:
+                        skipped[module] = (module, dependency)
+                        changed = True
+                        self.log.warning(
+                            "Module %s will be SKIPPED: it depends on module "
+                            "%s, which is not available in this command.%s",
+                            module.__name__,
+                            dependency.__name__,
+                            remainder,
+                        )
+                        break
+
+                    if dependency in skipped:
+                        root, missing = skipped[dependency]
+                        skipped[module] = (root, missing)
+                        changed = True
+                        if dependency is root:
+                            self.log.warning(
+                                "Module %s will be SKIPPED: it depends on "
+                                "module %s, itself skipped for depending on "
+                                "unavailable module %s.%s",
+                                module.__name__,
+                                dependency.__name__,
+                                missing.__name__,
+                                remainder,
+                            )
+                        else:
+                            self.log.warning(
+                                "Module %s will be SKIPPED: it depends on "
+                                "skipped module %s, in a chain starting at "
+                                "module %s, which depends on unavailable "
+                                "module %s.%s",
+                                module.__name__,
+                                dependency.__name__,
+                                root.__name__,
+                                missing.__name__,
+                                remainder,
+                            )
+                        break
+
+        return skipped
+
     def _ordered_modules(self) -> Optional[list[type[MVTModule]]]:
         """Return enabled modules in stable topological order."""
         modules = self._available_modules()
@@ -329,30 +404,34 @@ class Command:
         else:
             selected = [module for module in modules if module.enabled]
 
-        required = set(selected)
+        required: set[type[MVTModule]] = set()
         pending = list(selected)
         while pending:
             module = pending.pop()
+            if module in required:
+                continue
+            required.add(module)
             for dependency in module.dependencies:
-                if dependency not in module_indexes:
-                    self.log.warning(
-                        "Module %s depends on unavailable module %s. "
-                        "No modules will be run.",
-                        module.__name__,
-                        dependency.__name__,
-                    )
-                    return None
-                if dependency not in required:
-                    required.add(dependency)
+                # Unavailable dependencies are reported by _skipped_modules().
+                if dependency in module_indexes:
                     pending.append(dependency)
 
+        ordered_required = sorted(required, key=lambda module: module_indexes[module])
+        skipped = self._skipped_modules(ordered_required, module_indexes)
+        runnable = [module for module in ordered_required if module not in skipped]
+        if skipped and not runnable:
+            self.log.warning(
+                "Every selected module was skipped for an unavailable "
+                "dependency. No modules will be run."
+            )
+
         dependents: dict[type[MVTModule], list[type[MVTModule]]] = {
-            module: [] for module in required
+            module: [] for module in runnable
         }
-        indegree = {module: 0 for module in required}
-        for module in required:
+        indegree = {module: 0 for module in runnable}
+        for module in runnable:
             for dependency in module.dependencies:
-                if dependency not in required:
+                if dependency not in indegree:
                     continue
                 dependents[dependency].append(module)
                 indegree[module] += 1
@@ -371,7 +450,7 @@ class Command:
                 if indegree[dependent] == 0:
                     heappush(ready, (module_indexes[dependent], dependent))
 
-        if len(ordered) != len(required):
+        if len(ordered) != len(runnable):
             cyclic_modules = sorted(
                 (module.__name__ for module, count in indegree.items() if count > 0)
             )

src/mvt/common/completion.py

@@ -9,34 +9,83 @@ import shlex
 import click
 from click.shell_completion import get_completion_class
 
+from .help import HELP_MSG_COMPLETION
+
 
 SUPPORTED_SHELLS = ("bash", "zsh", "fish")
+CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
 
+COMPLETION_INSTRUCTIONS = """Shell completion for mvt, mvt-ios and mvt-android
 
-def completion_instructions(program_name: str) -> str:
-    return f"""Shell completion for {program_name}
-
-Print a completion script:
-  {program_name} completion bash > ~/.{program_name}-complete.bash
-  {program_name} completion zsh > ~/.{program_name}-complete.zsh
-  mkdir -p ~/.config/fish/completions
-  {program_name} completion fish > ~/.config/fish/completions/{program_name}.fish
+Print one completion script covering the three commands:
+  mvt completion bash > ~/.mvt-complete.bash
+  mvt completion zsh > ~/.mvt-complete.zsh
+  mkdir -p ~/.config/fish/conf.d
+  mvt completion fish > ~/.config/fish/conf.d/mvt-completion.fish
 
 Load the generated Bash script from ~/.bashrc:
-  [ -f ~/.{program_name}-complete.bash ] && . ~/.{program_name}-complete.bash
+  [ -f ~/.mvt-complete.bash ] && . ~/.mvt-complete.bash
 
 Load the generated Zsh script from ~/.zshrc:
-  [ -f ~/.{program_name}-complete.zsh ] && . ~/.{program_name}-complete.zsh
+  [ -f ~/.mvt-complete.zsh ] && . ~/.mvt-complete.zsh
 
-Fish loads completion files from ~/.config/fish/completions automatically.
+Fish loads the files in ~/.config/fish/conf.d automatically.
 
-To write these files and update Bash/Zsh shell configuration automatically:
-  {program_name} completion bash --install
-  {program_name} completion zsh --install
-  {program_name} completion fish --install
+To write these files and update the Bash/Zsh shell configuration automatically:
+  mvt completion bash --install
+  mvt completion zsh --install
+  mvt completion fish --install
 """
 
 
+def _mvt_programs() -> list[tuple[str, click.Command]]:
+    """Return the console script name and CLI group of every MVT program.
+
+    The three CLIs are imported here rather than at module level: mvt.cli
+    imports this module while it is being defined, and generating a completion
+    script should not make the start-up of `mvt` import the platform CLIs.
+    """
+    from mvt.android.cli import cli as android_cli
+    from mvt.cli import cli as mvt_cli
+    from mvt.ios.cli import cli as ios_cli
+
+    return [("mvt", mvt_cli), ("mvt-ios", ios_cli), ("mvt-android", android_cli)]
+
+
+@click.command(
+    "completion",
+    context_settings=CONTEXT_SETTINGS,
+    help=HELP_MSG_COMPLETION,
+    short_help="Generate or install shell completion",
+)
+@click.argument("shell", required=False, type=click.Choice(SUPPORTED_SHELLS))
+@click.option(
+    "--install",
+    is_flag=True,
+    help="Write completion files and update shell configuration.",
+)
+def completion(shell, install):
+    if shell is None:
+        if install:
+            raise click.UsageError("A shell is required when using --install.")
+        click.echo(COMPLETION_INSTRUCTIONS)
+        return
+
+    if install:
+        script_path = install_completion_script(shell)
+        click.echo(
+            f"Installed {shell} completion for mvt, mvt-ios and mvt-android "
+            f"to {script_path}"
+        )
+        if shell in ("bash", "zsh"):
+            click.echo(f"Updated ~/.{shell}rc")
+        else:
+            click.echo("Fish loads the files in ~/.config/fish/conf.d automatically.")
+        return
+
+    click.echo(generate_mvt_completion_script(shell))
+
+
 def generate_completion_script(cli: click.Command, program_name: str, shell: str) -> str:
     completion_class = get_completion_class(shell)
     if completion_class is None:
@@ -46,41 +95,49 @@ def generate_completion_script(cli: click.Command, program_name: str, shell: str
     return completion_class(cli, {}, program_name, complete_var).source()
 
 
-def install_completion_script(
-    cli: click.Command,
-    program_name: str,
-    shell: str,
-) -> Path:
-    script = generate_completion_script(cli, program_name, shell)
-    script_path = _completion_script_path(program_name, shell)
+def generate_mvt_completion_script(shell: str) -> str:
+    """Return one script completing every MVT command.
+
+    Click names the completion function of each program after the program, so
+    the scripts of the three commands can simply be concatenated.
+    """
+    scripts = [
+        generate_completion_script(cli, program_name, shell).strip("\n")
+        for program_name, cli in _mvt_programs()
+    ]
+    return "\n\n".join(scripts)
+
+
+def install_completion_script(shell: str) -> Path:
+    script = generate_mvt_completion_script(shell)
+    script_path = _completion_script_path(shell)
     script_path.parent.mkdir(parents=True, exist_ok=True)
-    script_path.write_text(script, encoding="utf-8")
+    script_path.write_text(f"{script}\n", encoding="utf-8")
 
     if shell in ("bash", "zsh"):
-        _install_shell_source_line(program_name, shell, script_path)
+        _install_shell_source_line(shell, script_path)
 
     return script_path
 
 
-def _completion_script_path(program_name: str, shell: str) -> Path:
+def _completion_script_path(shell: str) -> Path:
     home = Path.home()
 
     if shell == "fish":
-        return home / ".config" / "fish" / "completions" / f"{program_name}.fish"
+        # conf.d is sourced when the shell starts, unlike the completions
+        # folder, whose files fish loads on demand by command name.
+        return home / ".config" / "fish" / "conf.d" / "mvt-completion.fish"
 
-    return home / f".{program_name}-complete.{shell}"
+    return home / f".mvt-complete.{shell}"
 
 
-def _install_shell_source_line(program_name: str, shell: str, script_path: Path) -> None:
+def _install_shell_source_line(shell: str, script_path: Path) -> None:
     shell_config_path = Path.home() / f".{shell}rc"
     source_line = (
         f"[ -f {shlex.quote(str(script_path))} ] && "
         f". {shlex.quote(str(script_path))}"
     )
-    block = (
-        f"# MVT shell completion for {program_name}\n"
-        f"{source_line}\n"
-    )
+    block = f"# MVT shell completion\n{source_line}\n"
 
     if shell_config_path.exists():
         shell_config = shell_config_path.read_text(encoding="utf-8")

src/mvt/common/help.py

@@ -21,7 +21,9 @@ HELP_MSG_CHECK_IOCS = "Compare stored JSON results to provided indicators"
 HELP_MSG_STIX2 = "Download public STIX2 indicators"
 HELP_MSG_DISABLE_UPDATE_CHECK = "Disable MVT version update check"
 HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK = "Disable indicators update check"
-HELP_MSG_COMPLETION = "Generate or install shell completion"
+HELP_MSG_COMPLETION = (
+    "Generate or install shell completion for mvt, mvt-ios and mvt-android"
+)
 
 # IOS Specific
 HELP_MSG_DECRYPT_BACKUP = "Decrypt an encrypted iTunes backup"

src/mvt/common/logo.py

@@ -24,7 +24,7 @@ def check_updates(
             latest_version = mvt_updates.check()
         except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
             rich_print(
-                "\t\t[bold]Note: Could not check for MVT updates.[/bold] "
+                "\t[bold]Note: Could not check for MVT updates.[/bold] "
                 "You may be working offline. Please update MVT regularly."
             )
         except Exception as e:
@@ -34,7 +34,7 @@ def check_updates(
         else:
             if latest_version:
                 rich_print(
-                    f"\t\t[bold]Version {latest_version} is available! "
+                    f"\t[bold]Version {latest_version} is available! "
                     "Upgrade mvt with `pip3 install -U mvt` or with `pipx upgrade mvt`[/bold]"
                 )
 
@@ -46,7 +46,7 @@ def check_updates(
         # If not, there's no point in proceeding with the updates check.
         if ioc_updates.get_latest_update() == 0:
             rich_print(
-                "\t\t[bold]You have not yet downloaded any indicators, check "
+                "\t[bold]You have not yet downloaded any indicators, check "
                 "the `download-iocs` command![/bold]"
             )
             return
@@ -57,7 +57,7 @@ def check_updates(
         should_check, hours = ioc_updates.should_check()
         if not should_check:
             rich_print(
-                f"\t\tIndicators updates checked recently, next automatic check "
+                f"\tIndicators updates checked recently, next automatic check "
                 f"in {int(hours)} hours"
             )
             return
@@ -66,7 +66,7 @@ def check_updates(
             ioc_to_update = ioc_updates.check()
         except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
             rich_print(
-                "\t\t[bold]Note: Could not check for indicator updates.[/bold] "
+                "\t[bold]Note: Could not check for indicator updates.[/bold] "
                 "You may be working offline. Please update MVT indicators regularly."
             )
         except Exception as e:
@@ -76,20 +76,20 @@ def check_updates(
         else:
             if ioc_to_update:
                 rich_print(
-                    "\t\t[bold]There are updates to your indicators files! "
+                    "\t[bold]There are updates to your indicators files! "
                     "Run the `download-iocs` command to update![/bold]"
                 )
             else:
-                rich_print("\t\tYour indicators files seem to be up to date.")
+                rich_print("\tYour indicators files seem to be up to date.")
 
 
 def logo(
     disable_version_check: bool = False, disable_indicator_check: bool = False
 ) -> None:
     rich_print("\n")
-    rich_print("\t[bold]MVT[/bold] - Mobile Verification Toolkit")
-    rich_print("\t\thttps://mvt.re")
-    rich_print(f"\t\tVersion: {MVT_VERSION}")
+    rich_print("\t[bold]MVT - Mobile Verification Toolkit[/bold]\n")
+    rich_print("\thttps://mvt.re")
+    rich_print(f"\tVersion: {MVT_VERSION}\n")
 
     check_updates(disable_version_check, disable_indicator_check)
 

src/mvt/common/plugin_config.py

@@ -0,0 +1,299 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+import contextlib
+import json
+import os
+import re
+import tempfile
+from typing import Any, ClassVar, Dict, List, Tuple, Type, TypeVar
+
+import yaml
+from appdirs import user_config_dir, user_data_dir
+from pydantic import ValidationError
+from pydantic_settings import (
+    BaseSettings,
+    EnvSettingsSource,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+PLUGIN_CONFIG_FOLDER_NAME = "plugins"
+# Not "plugins": on macOS the configuration and data folders are the same
+# directory, and that name already holds the settings files.
+PLUGIN_DATA_FOLDER_NAME = "plugin-data"
+PLUGIN_ENV_PREFIX = "MVT_PLUGIN_"
+
+PLUGIN_NAME_PATTERN = re.compile(r"[a-z0-9][a-z0-9-]*")
+
+PluginSettingsType = TypeVar("PluginSettingsType", bound="MVTPluginSettings")
+
+
+class PluginConfigLoadError(Exception):
+    pass
+
+
+def validate_plugin_name(plugin_name: Any) -> str:
+    """
+    Check that a plugin name is safe to use in a file name and an env variable.
+
+    :param plugin_name: Name to validate.
+    :returns: The validated plugin name.
+    """
+    if not isinstance(plugin_name, str):
+        raise TypeError(
+            f"Plugin name must be a string, not {type(plugin_name).__name__}"
+        )
+    if not PLUGIN_NAME_PATTERN.fullmatch(plugin_name):
+        raise ValueError(
+            f"Invalid plugin name {plugin_name!r}: plugin names must start with a "
+            "lowercase letter or a digit and may only contain lowercase letters, "
+            "digits and dashes"
+        )
+    return plugin_name
+
+
+def plugin_config_folder() -> str:
+    """
+    Return the folder where plugins store their configuration files.
+
+    The path is resolved on every call so it always reflects the current
+    environment.
+    """
+    return os.path.join(user_config_dir("mvt"), PLUGIN_CONFIG_FOLDER_NAME)
+
+
+def plugin_config_path(plugin_name: str) -> str:
+    """
+    Return the path of the configuration file of a given plugin.
+
+    :param plugin_name: Name of the plugin.
+    """
+    return os.path.join(
+        plugin_config_folder(), f"{validate_plugin_name(plugin_name)}.yaml"
+    )
+
+
+def plugin_data_folder(plugin_name: str) -> str:
+    """
+    Return the folder where a given plugin stores its data, creating it.
+
+    Plugins should keep whatever they persist, such as caches or downloaded
+    artifacts, in this folder. It is created with owner-only permissions. The
+    path is resolved on every call so it always reflects the current
+    environment. A plugin with a settings class calls
+    `MVTPluginSettings.data_folder()` instead, which passes `plugin_name` here.
+
+    :param plugin_name: Name of the plugin.
+    :returns: The path of the data folder of the plugin.
+    """
+    # Validate the name before anything is created, so an unsafe name cannot
+    # leave a folder behind.
+    name = validate_plugin_name(plugin_name)
+
+    # makedirs() applies its mode only to the last folder of the path, so
+    # MVT's own data folder keeps the default permissions while the two
+    # plugin folders are private.
+    data_folder = os.path.join(user_data_dir("mvt"), PLUGIN_DATA_FOLDER_NAME)
+    os.makedirs(data_folder, mode=0o700, exist_ok=True)
+
+    folder = os.path.join(data_folder, name)
+    os.makedirs(folder, mode=0o700, exist_ok=True)
+    return folder
+
+
+def plugin_env_prefix(plugin_name: str) -> str:
+    """
+    Return the environment variable prefix used by a given plugin.
+
+    Dashes are replaced by underscores. Plugin names cannot contain underscores,
+    so two different plugin names never share an environment namespace.
+
+    :param plugin_name: Name of the plugin.
+    """
+    name = validate_plugin_name(plugin_name).upper().replace("-", "_")
+    return f"{PLUGIN_ENV_PREFIX}{name}_"
+
+
+def _settings_plugin_name(settings_cls: Type[BaseSettings]) -> str:
+    plugin_name = getattr(settings_cls, "plugin_name", None)
+    if plugin_name is None:
+        raise TypeError(
+            f"{settings_cls.__name__} must set a 'plugin_name' class attribute to "
+            "namespace its configuration file and environment variables"
+        )
+    return validate_plugin_name(plugin_name)
+
+
+def _plugin_yaml_source(
+    settings_cls: Type[BaseSettings], config_path: str
+) -> YamlConfigSettingsSource:
+    """
+    Build the YAML settings source of a plugin, reporting unusable files.
+
+    A missing file is not an error, but a file which cannot be parsed or which
+    does not hold a mapping of setting names is reported with its path.
+    """
+    try:
+        return YamlConfigSettingsSource(settings_cls, config_path)
+    except yaml.YAMLError as exc:
+        raise PluginConfigLoadError(
+            f"Invalid plugin configuration file {config_path}: {exc}"
+        ) from exc
+    except (TypeError, ValueError) as exc:
+        raise PluginConfigLoadError(
+            f"Invalid plugin configuration file {config_path}: the file must "
+            "contain a mapping of setting names to values"
+        ) from exc
+
+
+class MVTPluginSettings(BaseSettings):
+    """
+    Base class for plugin-namespaced settings.
+
+    Subclass with typed fields and set `plugin_name`. Values resolve from
+    constructor arguments, then environment variables (MVT_PLUGIN_<NAME>_*),
+    then the plugin's YAML file (~/.config/mvt/plugins/<name>.yaml), then field
+    defaults.
+
+    Plugins must not store their settings in MVT's own configuration file: MVT
+    rewrites it with the fields it knows about, dropping anything else.
+
+    `data_folder()` returns the folder the plugin keeps its data in.
+    """
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    plugin_name: ClassVar[str]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        plugin_name = _settings_plugin_name(cls)
+        # Namespace the environment variables of this plugin. Each pydantic
+        # model gets its own configuration dictionary, so this does not leak
+        # into other plugins.
+        cls.model_config["env_prefix"] = plugin_env_prefix(plugin_name)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: Type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> Tuple[PydanticBaseSettingsSource, ...]:
+        config_path = plugin_config_path(_settings_plugin_name(settings_cls))
+        yaml_source = _plugin_yaml_source(settings_cls, config_path)
+        # Explicit arguments take precedence over environment variables, which
+        # in turn take precedence over the configuration file.
+        return (init_settings, env_settings, yaml_source)
+
+    @classmethod
+    def load(cls: Type[PluginSettingsType]) -> PluginSettingsType:
+        """
+        Load the settings of the plugin.
+
+        A missing configuration file is not an error: the settings then come
+        from the environment and from the field defaults.
+        """
+        return cls()
+
+    @classmethod
+    def data_folder(cls) -> str:
+        """
+        Return the data folder of the plugin, creating it.
+
+        The folder is the one plugin_data_folder() returns for `plugin_name`,
+        so a plugin with a settings class does not repeat its name.
+        """
+        return plugin_data_folder(_settings_plugin_name(cls))
+
+    def _environment_values(self) -> Dict[str, Any]:
+        """
+        Return the settings values currently supplied by the environment.
+
+        Values are validated by the model, so they can be compared with the
+        values held by this instance.
+        """
+        settings_cls = type(self)
+        raw_values = EnvSettingsSource(settings_cls)()
+        names = [name for name in raw_values if name in settings_cls.model_fields]
+        if not names:
+            return {}
+
+        # Fall back on the current values for the fields the environment does
+        # not set, so that required fields do not fail validation here.
+        current_values = json.loads(self.model_dump_json())
+        try:
+            from_environment = settings_cls.model_validate(
+                {**current_values, **raw_values}
+            )
+        except ValidationError:
+            # An environment variable which the model cannot validate must not
+            # stop the other environment values from being recognised, or a
+            # credential would be written to the configuration file.
+            return self._environment_values_by_field(current_values, raw_values, names)
+        return {name: getattr(from_environment, name) for name in names}
+
+    def _environment_values_by_field(
+        self,
+        current_values: Dict[str, Any],
+        raw_values: Dict[str, Any],
+        names: List[str],
+    ) -> Dict[str, Any]:
+        """
+        Validate each environment value on its own, skipping unusable ones.
+
+        :param current_values: Serialized values held by this instance.
+        :param raw_values: Values supplied by the environment.
+        :param names: Names of the fields set by the environment.
+        """
+        settings_cls = type(self)
+        values = {}
+        for name in names:
+            try:
+                from_environment = settings_cls.model_validate(
+                    {**current_values, name: raw_values[name]}
+                )
+            except ValidationError:
+                continue
+            values[name] = getattr(from_environment, name)
+        return values
+
+    def save(self) -> None:
+        """
+        Save the current settings to the configuration file of the plugin.
+
+        Only values which differ from the field defaults are persisted. Values
+        which come from the environment are not written to disk, so credentials
+        passed as environment variables stay out of the configuration file.
+        MVT's own configuration file is never modified.
+        """
+        config_folder = plugin_config_folder()
+        if not os.path.isdir(config_folder):
+            os.makedirs(config_folder, mode=0o700, exist_ok=True)
+
+        values = json.loads(self.model_dump_json(exclude_defaults=True))
+        for name, environment_value in self._environment_values().items():
+            if name in values and getattr(self, name, None) == environment_value:
+                del values[name]
+
+        # Settings files can hold credentials, so write them through a private
+        # temporary file and move it in place. The file is then never partially
+        # written and never briefly readable by other users.
+        config_path = plugin_config_path(self.plugin_name)
+        descriptor, temporary_path = tempfile.mkstemp(
+            dir=config_folder, prefix=f".{self.plugin_name}-", suffix=".yaml"
+        )
+        try:
+            with os.fdopen(descriptor, "w") as config_file:
+                config_file.write(yaml.dump(values, default_flow_style=False))
+            os.replace(temporary_path, config_path)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                os.unlink(temporary_path)
+            raise

src/mvt/ios/__init__.py

@@ -3,4 +3,4 @@
 # Use of this software is governed by the MVT License 1.1 that can be found at
 #   https://license.mvt.re/1.1/
 
-from .cli import cli
+from .cli import cli, main

src/mvt/ios/cli.py

@@ -15,12 +15,6 @@ from mvt.common.cli_plugins import (
     register_cli_plugins,
 )
 from mvt.common.cmd_check_iocs import CmdCheckIOCS
-from mvt.common.completion import (
-    SUPPORTED_SHELLS,
-    completion_instructions,
-    generate_completion_script,
-    install_completion_script,
-)
 from mvt.common.logo import logo
 from mvt.common.options import MutuallyExclusiveOption
 from mvt.common.updates import IndicatorsUpdates
@@ -51,7 +45,6 @@ from mvt.common.help import (
     HELP_MSG_CHECK_SYSDIAGNOSE,
     HELP_MSG_DISABLE_UPDATE_CHECK,
     HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK,
-    HELP_MSG_COMPLETION,
 )
 from mvt.common.module_loader import CustomModuleLoadError, load_custom_modules
 from mvt.common.password import prompt_password
@@ -106,55 +99,20 @@ def cli(ctx, disable_update_check, disable_indicator_update_check):
     ctx.ensure_object(dict)
     ctx.obj["disable_version_check"] = disable_update_check
     ctx.obj["disable_indicator_check"] = disable_indicator_update_check
-    if ctx.invoked_subcommand != "completion":
-        logo(
-            disable_version_check=disable_update_check,
-            disable_indicator_check=disable_indicator_update_check,
-        )
+    logo(
+        disable_version_check=disable_update_check,
+        disable_indicator_check=disable_indicator_update_check,
+    )
 
 
 # ==============================================================================
 # Command: version
 # ==============================================================================
-@cli.command("version", help=HELP_MSG_VERSION)
+@cli.command("version", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_VERSION)
 def version():
     return
 
 
-# ==============================================================================
-# Command: completion
-# ==============================================================================
-@cli.command("completion", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_COMPLETION)
-@click.argument("shell", required=False, type=click.Choice(SUPPORTED_SHELLS))
-@click.option(
-    "--install",
-    is_flag=True,
-    help="Write completion files and update shell configuration.",
-)
-@click.pass_context
-def completion(ctx, shell, install):
-    program_name = "mvt-ios"
-
-    if shell is None:
-        if install:
-            raise click.UsageError("A shell is required when using --install.")
-        click.echo(completion_instructions(program_name))
-        return
-
-    root_cli = ctx.find_root().command
-
-    if install:
-        script_path = install_completion_script(root_cli, program_name, shell)
-        click.echo(f"Installed {shell} completion to {script_path}")
-        if shell in ("bash", "zsh"):
-            click.echo(f"Updated ~/.{shell}rc")
-        else:
-            click.echo("Fish loads completion files automatically.")
-        return
-
-    click.echo(generate_completion_script(root_cli, program_name, shell))
-
-
 # ==============================================================================
 # Command: decrypt-backup
 # ==============================================================================
@@ -532,8 +490,19 @@ def download_iocs():
     ioc_updates.update()
 
 
-register_cli_plugins(
-    cli,
-    entry_point_group=IOS_CLI_PLUGIN_GROUP,
-    environment_variable=MVT_IOS_CUSTOM_COMMANDS_ENV,
-)
+# ==============================================================================
+# Entry point of the mvt-ios console script
+# ==============================================================================
+def main() -> None:
+    """Register the external commands and run the mvt-ios CLI.
+
+    External commands are registered here rather than when this module is
+    imported, so that importing MVT never runs third-party code and a plugin
+    importing from MVT cannot re-enter a module that is still initializing.
+    """
+    register_cli_plugins(
+        cli,
+        entry_point_group=IOS_CLI_PLUGIN_GROUP,
+        environment_variable=MVT_IOS_CUSTOM_COMMANDS_ENV,
+    )
+    cli()

tests/common/test_cli_plugins.py

@@ -3,9 +3,12 @@ from types import SimpleNamespace
 import click
 from click.testing import CliRunner
 
+from mvt.cli import cli as mvt_cli
 from mvt.common.cli_plugins import (
     ANDROID_CLI_PLUGIN_GROUP,
     IOS_CLI_PLUGIN_GROUP,
+    MVT_CUSTOM_COMMANDS_ENV,
+    NEUTRAL_CLI_PLUGIN_GROUP,
     BrokenPluginCommand,
     load_cli_commands_option,
     register_cli_commands_from_path,
@@ -14,6 +17,9 @@ from mvt.common.cli_plugins import (
 )
 
 
+# Keep the banner of the mvt group callback from checking for updates online.
+OFFLINE = ["--disable-update-check", "--disable-indicator-update-check"]
+
 COMMAND_TEMPLATE = """
 import click
 
@@ -345,7 +351,11 @@ def test_platform_entry_point_groups_and_environment_paths_are_separate(
     def entry_points(*, group):
         if group == IOS_CLI_PLUGIN_GROUP:
             return [_entry_point("ios-package", "ios_plugin:cli", ios_package)]
-        return [_entry_point("android-package", "android_plugin:cli", android_package)]
+        if group == ANDROID_CLI_PLUGIN_GROUP:
+            return [
+                _entry_point("android-package", "android_plugin:cli", android_package)
+            ]
+        return []
 
     monkeypatch.setattr(
         "mvt.common.cli_plugins.importlib.metadata.entry_points",
@@ -369,3 +379,187 @@ def test_platform_entry_point_groups_and_environment_paths_are_separate(
 
     assert set(ios_group.commands) == {"ios-file", "ios-package"}
     assert set(android_group.commands) == {"android-file", "android-package"}
+
+
+def test_neutral_entry_point_group_is_not_registered_on_the_platform_clis(
+    monkeypatch,
+):
+    @click.command()
+    def neutral_package():
+        pass
+
+    def entry_points(*, group):
+        if group == NEUTRAL_CLI_PLUGIN_GROUP:
+            return [
+                _entry_point("neutral-package", "neutral_plugin:cli", neutral_package)
+            ]
+        return []
+
+    monkeypatch.setattr(
+        "mvt.common.cli_plugins.importlib.metadata.entry_points",
+        entry_points,
+    )
+    ios_group = click.Group()
+    android_group = click.Group()
+
+    register_cli_plugins(
+        ios_group,
+        entry_point_group=IOS_CLI_PLUGIN_GROUP,
+        environment_variable="TEST_IOS_COMMANDS",
+    )
+    register_cli_plugins(
+        android_group,
+        entry_point_group=ANDROID_CLI_PLUGIN_GROUP,
+        environment_variable="TEST_ANDROID_COMMANDS",
+    )
+
+    assert not ios_group.commands
+    assert not android_group.commands
+
+
+def test_environment_command_wins_collision_with_installed_command(
+    tmp_path, monkeypatch, caplog
+):
+    command_path = _write_command(
+        tmp_path / "duplicate.py",
+        "duplicate",
+        message="environment command ran",
+    )
+
+    @click.command()
+    def installed_command():
+        pass
+
+    def entry_points(*, group):
+        if group == IOS_CLI_PLUGIN_GROUP:
+            return [
+                _entry_point(
+                    "duplicate",
+                    "ios_plugin:cli",
+                    installed_command,
+                    distribution="ios-plugin",
+                )
+            ]
+        return []
+
+    monkeypatch.setattr(
+        "mvt.common.cli_plugins.importlib.metadata.entry_points",
+        entry_points,
+    )
+    monkeypatch.setenv("TEST_IOS_COMMANDS", str(command_path))
+    group = click.Group()
+
+    register_cli_plugins(
+        group,
+        entry_point_group=IOS_CLI_PLUGIN_GROUP,
+        environment_variable="TEST_IOS_COMMANDS",
+    )
+
+    assert group.commands["duplicate"] is not installed_command
+    result = CliRunner().invoke(group, ["duplicate"])
+    assert result.exit_code == 0
+    assert "environment command ran" in result.output
+    assert "the command name is already registered" in caplog.text
+    assert "ios-plugin 1.0 (ios_plugin:cli)" in caplog.text
+
+
+def test_the_mvt_cli_gets_the_neutral_commands_and_no_platform_command(
+    monkeypatch, restore_cli_commands
+):
+    @click.command()
+    def shared_package():
+        click.echo("shared command ran")
+
+    @click.command()
+    def ios_package():
+        pass
+
+    def entry_points(*, group):
+        if group == NEUTRAL_CLI_PLUGIN_GROUP:
+            return [_entry_point("shared-package", "shared_plugin:cli", shared_package)]
+        if group == IOS_CLI_PLUGIN_GROUP:
+            return [_entry_point("ios-package", "ios_plugin:cli", ios_package)]
+        return []
+
+    monkeypatch.setattr(
+        "mvt.common.cli_plugins.importlib.metadata.entry_points",
+        entry_points,
+    )
+
+    register_cli_plugins(
+        mvt_cli,
+        entry_point_group=NEUTRAL_CLI_PLUGIN_GROUP,
+        environment_variable=MVT_CUSTOM_COMMANDS_ENV,
+    )
+
+    assert "ios-package" not in mvt_cli.commands
+    result = CliRunner().invoke(mvt_cli, [*OFFLINE, "shared-package"])
+    assert result.exit_code == 0
+    assert "shared command ran" in result.output
+
+
+def test_builtin_mvt_command_wins_collision_with_neutral_command(
+    monkeypatch, caplog, restore_cli_commands
+):
+    @click.command()
+    def neutral_version():
+        pass
+
+    def entry_points(*, group):
+        if group == NEUTRAL_CLI_PLUGIN_GROUP:
+            return [
+                _entry_point(
+                    "version",
+                    "neutral_plugin:cli",
+                    neutral_version,
+                    distribution="neutral-plugin",
+                )
+            ]
+        return []
+
+    monkeypatch.setattr(
+        "mvt.common.cli_plugins.importlib.metadata.entry_points",
+        entry_points,
+    )
+    builtin_version = mvt_cli.commands["version"]
+
+    register_cli_plugins(
+        mvt_cli,
+        entry_point_group=NEUTRAL_CLI_PLUGIN_GROUP,
+        environment_variable=MVT_CUSTOM_COMMANDS_ENV,
+    )
+
+    assert mvt_cli.commands["version"] is builtin_version
+    assert "the command name is already registered" in caplog.text
+    assert "neutral-plugin 1.0 (neutral_plugin:cli)" in caplog.text
+
+
+def test_broken_neutral_plugin_does_not_break_the_mvt_cli(
+    monkeypatch, restore_cli_commands
+):
+    def entry_points(*, group):
+        if group == NEUTRAL_CLI_PLUGIN_GROUP:
+            return [
+                _entry_point(
+                    "broken",
+                    "broken_plugin:cli",
+                    exception=RuntimeError("missing dependency"),
+                    distribution="broken-plugin",
+                )
+            ]
+        return []
+
+    monkeypatch.setattr(
+        "mvt.common.cli_plugins.importlib.metadata.entry_points",
+        entry_points,
+    )
+
+    register_cli_plugins(
+        mvt_cli,
+        entry_point_group=NEUTRAL_CLI_PLUGIN_GROUP,
+        environment_variable=MVT_CUSTOM_COMMANDS_ENV,
+    )
+
+    assert isinstance(mvt_cli.commands["broken"], BrokenPluginCommand)
+    result = CliRunner().invoke(mvt_cli, [*OFFLINE, "version"])
+    assert result.exit_code == 0

tests/common/test_command.py

@@ -157,7 +157,7 @@ class TestCommand:
         assert not hasattr(cmd, "initialized")
         assert "Circular module dependency detected" in caplog.text
 
-    def test_unavailable_dependency_warns_and_stops(self, caplog):
+    def test_unavailable_dependency_only_skips_the_dependent_module(self, caplog):
         class UnavailableModule(RecordingModule):
             pass
 
@@ -165,14 +165,97 @@ class TestCommand:
             dependencies = (UnavailableModule,)
 
         cmd = RecordingCommand()
-        cmd.modules = [DependentModule]
+        cmd.modules = [DependentModule, IndependentModule, FirstModule]
+
+        with caplog.at_level(logging.WARNING):
+            cmd.run()
+
+        assert RecordingModule.run_order == ["IndependentModule", "FirstModule"]
+        assert cmd.initialized
+        assert "Module DependentModule will be SKIPPED" in caplog.text
+        assert "depends on module UnavailableModule" in caplog.text
+
+    def test_modules_depending_on_a_skipped_module_are_skipped_too(self, caplog):
+        class UnavailableModule(RecordingModule):
+            pass
+
+        class SkippedModule(RecordingModule):
+            dependencies = (UnavailableModule,)
+
+        class DependsOnSkippedModule(RecordingModule):
+            dependencies = (SkippedModule,)
+
+        class DependsOnTheChain(RecordingModule):
+            dependencies = (DependsOnSkippedModule,)
+
+        cmd = RecordingCommand()
+        cmd.modules = [
+            DependsOnTheChain,
+            DependsOnSkippedModule,
+            SkippedModule,
+            IndependentModule,
+        ]
+
+        with caplog.at_level(logging.WARNING):
+            cmd.run()
+
+        assert RecordingModule.run_order == ["IndependentModule"]
+        skip_warnings = [
+            record.getMessage()
+            for record in caplog.records
+            if "will be SKIPPED" in record.getMessage()
+        ]
+        assert len(skip_warnings) == 3
+        assert [warning.split()[1] for warning in skip_warnings] == [
+            "SkippedModule",
+            "DependsOnSkippedModule",
+            "DependsOnTheChain",
+        ]
+        # Every warning names the root cause: the module missing a dependency
+        # and the dependency it is missing.
+        assert all("UnavailableModule" in warning for warning in skip_warnings)
+        assert all("module SkippedModule" in warning for warning in skip_warnings[1:])
+
+    def test_explicitly_selected_module_with_missing_dependency_runs_nothing(
+        self, caplog
+    ):
+        class UnavailableModule(RecordingModule):
+            pass
+
+        class DependentModule(RecordingModule):
+            dependencies = (UnavailableModule,)
+
+        cmd = RecordingCommand(module_name="DependentModule")
+        cmd.modules = [DependentModule, IndependentModule]
 
         with caplog.at_level(logging.WARNING):
             cmd.run()
 
         assert RecordingModule.run_order == []
-        assert not hasattr(cmd, "initialized")
-        assert "depends on unavailable module UnavailableModule" in caplog.text
+        assert "Module DependentModule will be SKIPPED" in caplog.text
+        assert "No modules will be run" in caplog.text
+        # Nothing else was selected, so the warning must not promise that the
+        # analysis continues right before saying that it does not.
+        assert "The rest of the analysis will still run" not in caplog.text
+
+    def test_unaffected_dependency_chains_keep_their_order(self, caplog):
+        class UnavailableModule(RecordingModule):
+            pass
+
+        class SkippedModule(RecordingModule):
+            dependencies = (UnavailableModule,)
+
+        cmd = RecordingCommand()
+        cmd.modules = [ThirdModule, SkippedModule, SecondModule, FirstModule]
+
+        with caplog.at_level(logging.WARNING):
+            cmd.run()
+
+        assert RecordingModule.run_order == [
+            "FirstModule",
+            "SecondModule",
+            "ThirdModule",
+        ]
 
     def test_custom_modules_are_filtered_before_ordering(self):
         cmd = RecordingCommand()

tests/common/test_plugin_config.py

@@ -0,0 +1,391 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+import os
+import stat
+import sys
+from typing import Optional
+
+import pytest
+import yaml
+
+from mvt.common.plugin_config import (
+    MVTPluginSettings,
+    PluginConfigLoadError,
+    plugin_config_folder,
+    plugin_config_path,
+    plugin_data_folder,
+    plugin_env_prefix,
+)
+
+
+class ExamplePluginSettings(MVTPluginSettings):
+    plugin_name = "example-plugin"
+
+    API_KEY: Optional[str] = None
+    CACHE_FOLDER: str = "cache"
+    MAX_RESULTS: int = 25
+
+
+class OtherPluginSettings(MVTPluginSettings):
+    plugin_name = "other-plugin"
+
+    API_KEY: Optional[str] = None
+
+
+@pytest.fixture
+def config_folder(tmp_path, monkeypatch):
+    monkeypatch.setattr(
+        "mvt.common.plugin_config.user_config_dir",
+        lambda *args, **kwargs: str(tmp_path),
+    )
+    return tmp_path
+
+
+@pytest.fixture
+def data_folder(tmp_path, monkeypatch):
+    folder = tmp_path / "data"
+    monkeypatch.setattr(
+        "mvt.common.plugin_config.user_data_dir",
+        lambda *args, **kwargs: str(folder),
+    )
+    return folder
+
+
+def _write_plugin_file(plugin_name, values):
+    config_path = plugin_config_path(plugin_name)
+    os.makedirs(os.path.dirname(config_path), exist_ok=True)
+    content = values if isinstance(values, str) else yaml.dump(values)
+    with open(config_path, "w") as config_file:
+        config_file.write(content)
+    return config_path
+
+
+def test_plugin_paths_and_prefixes_are_namespaced(config_folder):
+    assert plugin_config_folder() == str(config_folder / "plugins")
+    assert plugin_config_path("example-plugin") == str(
+        config_folder / "plugins" / "example-plugin.yaml"
+    )
+    assert plugin_env_prefix("example-plugin") == "MVT_PLUGIN_EXAMPLE_PLUGIN_"
+    assert plugin_env_prefix("other-plugin") == "MVT_PLUGIN_OTHER_PLUGIN_"
+
+
+def test_defaults_are_used_without_file_or_environment(config_folder):
+    settings = ExamplePluginSettings.load()
+
+    assert settings.API_KEY is None
+    assert settings.CACHE_FOLDER == "cache"
+    assert settings.MAX_RESULTS == 25
+    assert not os.path.exists(plugin_config_path("example-plugin"))
+
+
+def test_values_are_loaded_from_the_plugin_file(config_folder):
+    _write_plugin_file("example-plugin", {"API_KEY": "from-file", "MAX_RESULTS": 5})
+
+    settings = ExamplePluginSettings.load()
+
+    assert settings.API_KEY == "from-file"
+    assert settings.MAX_RESULTS == 5
+    assert settings.CACHE_FOLDER == "cache"
+
+
+def test_environment_overrides_the_plugin_file(config_folder, monkeypatch):
+    _write_plugin_file("example-plugin", {"API_KEY": "from-file", "MAX_RESULTS": 5})
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY", "from-environment")
+
+    settings = ExamplePluginSettings.load()
+
+    assert settings.API_KEY == "from-environment"
+    assert settings.MAX_RESULTS == 5
+
+
+def test_arguments_override_the_environment_and_the_plugin_file(
+    config_folder, monkeypatch
+):
+    _write_plugin_file("example-plugin", {"API_KEY": "from-file", "MAX_RESULTS": 5})
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY", "from-environment")
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_MAX_RESULTS", "10")
+
+    settings = ExamplePluginSettings(API_KEY="from-argument")
+
+    assert settings.API_KEY == "from-argument"
+    assert settings.MAX_RESULTS == 10
+
+
+def test_save_and_load_round_trip(config_folder):
+    settings = ExamplePluginSettings.load()
+    settings.API_KEY = "saved-key"
+    settings.MAX_RESULTS = 100
+
+    settings.save()
+
+    config_path = plugin_config_path("example-plugin")
+    assert os.path.isfile(config_path)
+    with open(config_path) as config_file:
+        assert yaml.safe_load(config_file) == {
+            "API_KEY": "saved-key",
+            "MAX_RESULTS": 100,
+        }
+
+    reloaded = ExamplePluginSettings.load()
+    assert reloaded.API_KEY == "saved-key"
+    assert reloaded.MAX_RESULTS == 100
+    assert reloaded.CACHE_FOLDER == "cache"
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32", reason="POSIX file permissions are not available"
+)
+def test_saved_file_is_only_readable_by_the_user(config_folder):
+    settings = ExamplePluginSettings.load()
+    settings.API_KEY = "saved-key"
+
+    settings.save()
+
+    config_path = plugin_config_path("example-plugin")
+    assert stat.S_IMODE(os.stat(config_path).st_mode) == 0o600
+    folder_mode = stat.S_IMODE(os.stat(plugin_config_folder()).st_mode)
+    assert folder_mode & 0o077 == 0
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32", reason="POSIX file permissions are not available"
+)
+def test_save_restricts_the_permissions_of_an_existing_file(config_folder):
+    config_path = _write_plugin_file("example-plugin", {"API_KEY": "from-file"})
+    os.chmod(config_path, 0o644)
+
+    settings = ExamplePluginSettings.load()
+    settings.MAX_RESULTS = 100
+    settings.save()
+
+    assert stat.S_IMODE(os.stat(config_path).st_mode) == 0o600
+    assert os.listdir(plugin_config_folder()) == ["example-plugin.yaml"]
+
+
+def test_save_only_persists_non_default_values(config_folder):
+    settings = ExamplePluginSettings.load()
+    settings.CACHE_FOLDER = "another-cache"
+
+    settings.save()
+
+    with open(plugin_config_path("example-plugin")) as config_file:
+        assert yaml.safe_load(config_file) == {"CACHE_FOLDER": "another-cache"}
+
+
+def test_save_does_not_persist_values_coming_from_the_environment(
+    config_folder, monkeypatch
+):
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY", "environment-secret")
+
+    settings = ExamplePluginSettings.load()
+    assert settings.API_KEY == "environment-secret"
+    settings.MAX_RESULTS = 100
+    settings.save()
+
+    with open(plugin_config_path("example-plugin")) as config_file:
+        assert yaml.safe_load(config_file) == {"MAX_RESULTS": 100}
+
+
+def test_an_invalid_environment_variable_still_protects_the_other_values(
+    config_folder, monkeypatch
+):
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY", "environment-secret")
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_MAX_RESULTS", "not-an-int")
+
+    settings = ExamplePluginSettings(MAX_RESULTS=100)
+    assert settings.API_KEY == "environment-secret"
+    settings.save()
+
+    with open(plugin_config_path("example-plugin")) as config_file:
+        saved_values = yaml.safe_load(config_file)
+    assert saved_values == {"MAX_RESULTS": 100}
+    assert "API_KEY" not in saved_values
+
+
+def test_save_persists_values_which_differ_from_the_environment(
+    config_folder, monkeypatch
+):
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY", "environment-secret")
+
+    settings = ExamplePluginSettings.load()
+    settings.API_KEY = "chosen-key"
+    settings.save()
+
+    with open(plugin_config_path("example-plugin")) as config_file:
+        assert yaml.safe_load(config_file) == {"API_KEY": "chosen-key"}
+
+
+def test_save_does_not_write_the_mvt_configuration_file(config_folder):
+    settings = ExamplePluginSettings.load()
+    settings.API_KEY = "saved-key"
+
+    settings.save()
+
+    assert os.listdir(config_folder) == ["plugins"]
+
+
+def test_unknown_keys_in_the_plugin_file_are_ignored(config_folder):
+    _write_plugin_file(
+        "example-plugin",
+        {"API_KEY": "from-file", "UNKNOWN_SETTING": "ignored"},
+    )
+
+    settings = ExamplePluginSettings.load()
+
+    assert settings.API_KEY == "from-file"
+    assert not hasattr(settings, "UNKNOWN_SETTING")
+
+
+def test_unparsable_plugin_file_is_reported_with_its_path(config_folder):
+    config_path = _write_plugin_file("example-plugin", "API_KEY: [unclosed\n")
+
+    with pytest.raises(PluginConfigLoadError) as raised:
+        ExamplePluginSettings.load()
+
+    assert config_path in str(raised.value)
+
+
+def test_plugin_file_which_is_not_a_mapping_is_reported_with_its_path(config_folder):
+    config_path = _write_plugin_file("example-plugin", "- one\n- two\n")
+
+    with pytest.raises(PluginConfigLoadError) as raised:
+        ExamplePluginSettings.load()
+
+    assert config_path in str(raised.value)
+    assert "mapping of setting names" in str(raised.value)
+
+
+def test_plugins_do_not_interfere_with_each_other(config_folder, monkeypatch):
+    _write_plugin_file("other-plugin", {"API_KEY": "other-file-key"})
+    monkeypatch.setenv("MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY", "example-environment-key")
+
+    example_settings = ExamplePluginSettings.load()
+    other_settings = OtherPluginSettings.load()
+
+    assert example_settings.API_KEY == "example-environment-key"
+    assert other_settings.API_KEY == "other-file-key"
+
+    example_settings.MAX_RESULTS = 100
+    example_settings.save()
+    assert sorted(os.listdir(plugin_config_folder())) == [
+        "example-plugin.yaml",
+        "other-plugin.yaml",
+    ]
+    with open(plugin_config_path("other-plugin")) as config_file:
+        assert yaml.safe_load(config_file) == {"API_KEY": "other-file-key"}
+
+
+def test_subclass_without_plugin_name_is_rejected():
+    with pytest.raises(TypeError, match="plugin_name"):
+
+        class MissingNameSettings(MVTPluginSettings):
+            API_KEY: Optional[str] = None
+
+
+def test_subclass_with_invalid_plugin_name_is_rejected():
+    with pytest.raises(ValueError, match="Invalid plugin name"):
+
+        class InvalidNameSettings(MVTPluginSettings):
+            plugin_name = "Bad/Name"
+
+
+def test_underscores_are_not_allowed_in_plugin_names():
+    # Underscores are replaced by dashes in the environment prefix, so allowing
+    # both would let two plugin names share one environment namespace.
+    with pytest.raises(ValueError, match="Invalid plugin name"):
+
+        class UnderscoreNameSettings(MVTPluginSettings):
+            plugin_name = "under_score"
+
+    with pytest.raises(ValueError, match="Invalid plugin name"):
+        plugin_config_path("under_score")
+    with pytest.raises(ValueError, match="Invalid plugin name"):
+        plugin_env_prefix("under_score")
+
+
+@pytest.mark.parametrize(
+    "plugin_name", ["../escape", "folder/name", "UPPER", "-dash", ""]
+)
+def test_unsafe_plugin_names_have_no_configuration_path(plugin_name):
+    with pytest.raises(ValueError, match="Invalid plugin name"):
+        plugin_config_path(plugin_name)
+
+
+def test_data_folder_is_namespaced_and_created(data_folder):
+    folder = plugin_data_folder("example-plugin")
+
+    assert folder == str(data_folder / "plugin-data" / "example-plugin")
+    assert os.path.isdir(folder)
+
+
+def test_data_folder_can_be_requested_repeatedly(data_folder):
+    folder = plugin_data_folder("example-plugin")
+    with open(os.path.join(folder, "kept.json"), "w") as data_file:
+        data_file.write("{}")
+
+    assert plugin_data_folder("example-plugin") == folder
+    assert os.listdir(folder) == ["kept.json"]
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32", reason="POSIX file permissions are not available"
+)
+def test_data_folder_is_only_accessible_by_the_user(data_folder):
+    folder = plugin_data_folder("example-plugin")
+
+    assert stat.S_IMODE(os.stat(folder).st_mode) & 0o077 == 0
+    parent_mode = stat.S_IMODE(os.stat(os.path.dirname(folder)).st_mode)
+    assert parent_mode & 0o077 == 0
+
+
+def test_plugins_get_their_own_data_folder(data_folder):
+    example_folder = plugin_data_folder("example-plugin")
+    other_folder = plugin_data_folder("other-plugin")
+
+    assert example_folder != other_folder
+    assert sorted(os.listdir(data_folder / "plugin-data")) == [
+        "example-plugin",
+        "other-plugin",
+    ]
+
+
+def test_data_folder_does_not_touch_the_configuration_folder(
+    config_folder, data_folder
+):
+    plugin_data_folder("example-plugin")
+
+    assert not os.path.exists(plugin_config_folder())
+
+
+@pytest.mark.parametrize(
+    "plugin_name", ["../escape", "folder/name", "UPPER", "-dash", ""]
+)
+def test_unsafe_plugin_names_have_no_data_folder(data_folder, plugin_name):
+    with pytest.raises(ValueError, match="Invalid plugin name"):
+        plugin_data_folder(plugin_name)
+
+    assert not os.path.exists(data_folder)
+
+
+def test_settings_class_knows_its_data_folder(data_folder):
+    folder = ExamplePluginSettings.data_folder()
+
+    assert folder == plugin_data_folder("example-plugin")
+    assert os.path.isdir(folder)
+    assert OtherPluginSettings.data_folder() != folder
+
+
+def test_settings_instance_uses_the_same_data_folder(config_folder, data_folder):
+    settings = ExamplePluginSettings.load()
+
+    assert settings.data_folder() == ExamplePluginSettings.data_folder()
+
+
+def test_subclass_without_its_own_name_shares_the_data_folder(data_folder):
+    class InheritingSettings(ExamplePluginSettings):
+        pass
+
+    assert InheritingSettings.data_folder() == ExamplePluginSettings.data_folder()

tests/conftest.py

@@ -8,6 +8,11 @@ import os
 
 import pytest
 
+from mvt.common.cli_plugins import (
+    MVT_ANDROID_CUSTOM_COMMANDS_ENV,
+    MVT_CUSTOM_COMMANDS_ENV,
+    MVT_IOS_CUSTOM_COMMANDS_ENV,
+)
 from mvt.common.indicators import Indicators
 
 from .artifacts.generate_stix import generate_test_stix_file
@@ -58,3 +63,33 @@ def indicators_factory(indicator_file):
         return ind
 
     return f
+
+
+@pytest.fixture()
+def restore_cli_commands(monkeypatch):
+    """Keep the external commands a test registers out of the next test.
+
+    Each CLI group is a module-level object shared by every test, so a test
+    registering plugin or environment commands on one has to put it back. The
+    groups are imported here rather than at the top of the file, so that
+    collecting the tests does not import three CLIs for the sake of one
+    fixture.
+    """
+    from mvt.android.cli import cli as android_cli
+    from mvt.cli import cli as neutral_cli
+    from mvt.ios.cli import cli as ios_cli
+
+    groups = (neutral_cli, ios_cli, android_cli)
+    for variable in (
+        MVT_CUSTOM_COMMANDS_ENV,
+        MVT_IOS_CUSTOM_COMMANDS_ENV,
+        MVT_ANDROID_CUSTOM_COMMANDS_ENV,
+    ):
+        monkeypatch.delenv(variable, raising=False)
+    originals = [dict(group.commands) for group in groups]
+    yield
+    for group, commands in zip(groups, originals):
+        group.commands.clear()
+        group.commands.update(commands)
+        if hasattr(group, "_mvt_external_command_sources"):
+            delattr(group, "_mvt_external_command_sources")

tests/plugin_fixtures.py

@@ -0,0 +1,85 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+"""Helpers building throwaway plugin distributions for the tests.
+
+Some plugin behaviour only shows up in a fresh interpreter: what an import
+executes, and what a plugin sees when MVT is imported before or after it.
+These helpers write an importable distribution with a real entry point and
+run a script against it in a subprocess, with a temporary home so that the
+subprocess cannot touch the configuration of whoever runs the tests.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+FIXTURE_COMMAND_NAME = "fixture-plugin"
+FIXTURE_MODULE_NAME = "fixture_cli_plugin"
+FIXTURE_DISTRIBUTION_NAME = "fixture-cli-plugin"
+
+
+def write_cli_plugin_distribution(
+    site_path: Path,
+    entry_point_group: str,
+    module_source: str,
+) -> Path:
+    """Write a distribution registering a CLI plugin entry point.
+
+    :param site_path: Folder to write the distribution into, to be added to
+                      the import path of the interpreter loading it.
+    :param entry_point_group: Entry-point group to register the command in.
+    :param module_source: Source of the plugin module, which must define a
+                          Click command named `cli`.
+    :returns: The folder the distribution was written to.
+    """
+    site_path.mkdir(parents=True, exist_ok=True)
+    (site_path / f"{FIXTURE_MODULE_NAME}.py").write_text(
+        module_source, encoding="utf-8"
+    )
+
+    dist_info = (
+        site_path / f"{FIXTURE_DISTRIBUTION_NAME.replace('-', '_')}-1.0.dist-info"
+    )
+    dist_info.mkdir(exist_ok=True)
+    (dist_info / "METADATA").write_text(
+        f"Metadata-Version: 2.1\nName: {FIXTURE_DISTRIBUTION_NAME}\nVersion: 1.0\n",
+        encoding="utf-8",
+    )
+    (dist_info / "entry_points.txt").write_text(
+        f"[{entry_point_group}]\n{FIXTURE_COMMAND_NAME} = {FIXTURE_MODULE_NAME}:cli\n",
+        encoding="utf-8",
+    )
+    return site_path
+
+
+def run_isolated_python(
+    script: str,
+    home: Path,
+    site_path: Optional[Path] = None,
+    **environment: str,
+) -> subprocess.CompletedProcess:
+    """Run a script in a fresh interpreter with its own configuration folder.
+
+    Importing MVT writes its configuration file, so the subprocess gets a
+    temporary home and no MVT environment variables from the test session.
+    """
+    isolated_environment = {
+        key: value for key, value in os.environ.items() if not key.startswith("MVT_")
+    }
+    isolated_environment["HOME"] = str(home)
+    isolated_environment["XDG_CONFIG_HOME"] = str(home / "config")
+    if site_path is not None:
+        isolated_environment["PYTHONPATH"] = str(site_path)
+    isolated_environment.update(environment)
+
+    return subprocess.run(
+        [sys.executable, "-c", script],
+        capture_output=True,
+        text=True,
+        env=isolated_environment,
+    )

tests/test_cli.py

@@ -0,0 +1,49 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+from click.testing import CliRunner
+
+from mvt.cli import cli
+from mvt.common.updates import IndicatorsUpdates
+from mvt.common.version import MVT_VERSION
+
+# Keep the banner of the group callback from checking for updates online.
+OFFLINE = ["--disable-update-check", "--disable-indicator-update-check"]
+
+
+class TestMvtCommand:
+    def test_running_mvt_alone_shows_the_logo_and_the_commands(self):
+        result = CliRunner().invoke(cli, OFFLINE)
+
+        assert result.exit_code == 0
+        logo_at = result.output.index("Mobile Verification Toolkit")
+        usage_at = result.output.index("Usage:")
+        assert logo_at < usage_at
+        assert "mvt-ios" in result.output and "mvt-android" in result.output
+
+    def test_help_reminds_where_the_analysis_runs(self):
+        result = CliRunner().invoke(cli, ["--help"])
+
+        assert result.exit_code == 0
+        assert "mvt-ios" in result.output
+        assert "mvt-android" in result.output
+        assert "check-*" in result.output
+
+    def test_version_prints_the_installed_version(self):
+        result = CliRunner().invoke(cli, [*OFFLINE, "version"])
+
+        assert result.exit_code == 0
+        assert f"Version: {MVT_VERSION}" in result.output
+
+    def test_download_iocs_updates_the_indicators(self, monkeypatch):
+        updates = []
+        monkeypatch.setattr(
+            IndicatorsUpdates, "update", lambda self: updates.append(self)
+        )
+
+        result = CliRunner().invoke(cli, [*OFFLINE, "download-iocs"])
+
+        assert result.exit_code == 0
+        assert len(updates) == 1

tests/test_cli_entry_points.py

@@ -0,0 +1,280 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+import sys
+from types import SimpleNamespace
+
+import click
+import pytest
+
+import mvt.android
+import mvt.cli
+import mvt.ios
+from mvt.android.cli import cli as android_cli
+from mvt.android.cli import main as android_main
+from mvt.cli import cli as mvt_cli
+from mvt.cli import main as mvt_main
+from mvt.common.cli_plugins import (
+    ANDROID_CLI_PLUGIN_GROUP,
+    IOS_CLI_PLUGIN_GROUP,
+    MVT_ANDROID_CUSTOM_COMMANDS_ENV,
+    MVT_CUSTOM_COMMANDS_ENV,
+    MVT_IOS_CUSTOM_COMMANDS_ENV,
+    NEUTRAL_CLI_PLUGIN_GROUP,
+)
+from mvt.ios.cli import cli as ios_cli
+from mvt.ios.cli import main as ios_main
+
+from .plugin_fixtures import (
+    FIXTURE_COMMAND_NAME,
+    run_isolated_python,
+    write_cli_plugin_distribution,
+)
+
+MARKER_PLUGIN_TEMPLATE = """
+import os
+
+import click
+
+# Touched when this module is imported, so a test can tell whether loading MVT
+# executed the plugin.
+open(os.environ["FIXTURE_PLUGIN_MARKER"], "a").close()
+
+
+@click.command()
+def cli():
+    click.echo("fixture plugin ran")
+"""
+
+PROGRAMS = {
+    "mvt": (mvt.cli, mvt_cli, NEUTRAL_CLI_PLUGIN_GROUP, MVT_CUSTOM_COMMANDS_ENV),
+    "mvt-ios": (mvt.ios, ios_cli, IOS_CLI_PLUGIN_GROUP, MVT_IOS_CUSTOM_COMMANDS_ENV),
+    "mvt-android": (
+        mvt.android,
+        android_cli,
+        ANDROID_CLI_PLUGIN_GROUP,
+        MVT_ANDROID_CUSTOM_COMMANDS_ENV,
+    ),
+}
+
+CASE_SUMMARY_COMMAND = """
+import click
+
+
+@click.command("case-summary")
+def cli():
+    click.echo("case summary ran")
+"""
+
+# The entry-point group of another program, for each program: no group may add
+# its commands to a CLI other than its own.
+OTHER_PROGRAMS_GROUP = {
+    "mvt": IOS_CLI_PLUGIN_GROUP,
+    "mvt-ios": NEUTRAL_CLI_PLUGIN_GROUP,
+    "mvt-android": NEUTRAL_CLI_PLUGIN_GROUP,
+}
+
+
+def _install_fixture_entry_point(monkeypatch, entry_point_group, command):
+    def entry_points(*, group):
+        if group != entry_point_group:
+            return []
+        return [
+            SimpleNamespace(
+                name=FIXTURE_COMMAND_NAME,
+                value="fixture_cli_plugin:cli",
+                load=lambda: command,
+                dist=SimpleNamespace(
+                    metadata={"Name": "fixture-cli-plugin"}, version="1.0"
+                ),
+            )
+        ]
+
+    monkeypatch.setattr(
+        "mvt.common.cli_plugins.importlib.metadata.entry_points", entry_points
+    )
+
+
+def _offline_argv(program, *arguments):
+    """Build an argument list which keeps the CLI from checking for updates."""
+    return [
+        program,
+        "--disable-update-check",
+        "--disable-indicator-update-check",
+        *arguments,
+    ]
+
+
+@pytest.mark.parametrize("program", sorted(PROGRAMS))
+def test_main_registers_installed_plugins_before_running_the_cli(
+    program, monkeypatch, capsys, restore_cli_commands
+):
+    package, group, entry_point_group, _ = PROGRAMS[program]
+
+    @click.command()
+    def fixture_command():
+        click.echo("fixture plugin ran")
+
+    _install_fixture_entry_point(monkeypatch, entry_point_group, fixture_command)
+    monkeypatch.setattr(sys, "argv", _offline_argv(program, FIXTURE_COMMAND_NAME))
+
+    with pytest.raises(SystemExit) as exit_info:
+        package.main()
+
+    assert exit_info.value.code == 0
+    assert "fixture plugin ran" in capsys.readouterr().out
+    assert FIXTURE_COMMAND_NAME in group.commands
+
+
+@pytest.mark.parametrize("program", sorted(PROGRAMS))
+def test_main_completes_plugin_command_names(
+    program, monkeypatch, capsys, restore_cli_commands
+):
+    package, _, entry_point_group, _ = PROGRAMS[program]
+
+    @click.command()
+    def fixture_command():
+        pass
+
+    _install_fixture_entry_point(monkeypatch, entry_point_group, fixture_command)
+    complete_variable = f"_{program.upper().replace('-', '_')}_COMPLETE"
+    monkeypatch.setenv(complete_variable, "bash_complete")
+    monkeypatch.setenv("COMP_WORDS", f"{program} fixture")
+    monkeypatch.setenv("COMP_CWORD", "1")
+    monkeypatch.setattr(sys, "argv", [program])
+
+    with pytest.raises(SystemExit):
+        package.main()
+
+    assert f"plain,{FIXTURE_COMMAND_NAME}" in capsys.readouterr().out
+
+
+@pytest.mark.parametrize("program", sorted(PROGRAMS))
+def test_main_still_loads_commands_from_a_file(
+    program, monkeypatch, capsys, tmp_path, restore_cli_commands
+):
+    package, _, entry_point_group, _ = PROGRAMS[program]
+    command_path = tmp_path / "case_summary.py"
+    command_path.write_text(CASE_SUMMARY_COMMAND, encoding="utf-8")
+    _install_fixture_entry_point(
+        monkeypatch, entry_point_group, click.Command("unused")
+    )
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        _offline_argv(program, "--load-command", str(command_path), "case-summary"),
+    )
+
+    with pytest.raises(SystemExit) as exit_info:
+        package.main()
+
+    assert exit_info.value.code == 0
+    assert "case summary ran" in capsys.readouterr().out
+
+
+@pytest.mark.parametrize("program", sorted(PROGRAMS))
+def test_main_loads_commands_from_the_environment_variable(
+    program, monkeypatch, capsys, tmp_path, restore_cli_commands
+):
+    # Each CLI reads its own variable, so a main() reading another CLI's would
+    # go unnoticed without this.
+    package, _, _, environment_variable = PROGRAMS[program]
+    command_path = tmp_path / "case_summary.py"
+    command_path.write_text(CASE_SUMMARY_COMMAND, encoding="utf-8")
+    monkeypatch.setenv(environment_variable, str(command_path))
+    monkeypatch.setattr(sys, "argv", _offline_argv(program, "case-summary"))
+
+    with pytest.raises(SystemExit) as exit_info:
+        package.main()
+
+    assert exit_info.value.code == 0
+    assert "case summary ran" in capsys.readouterr().out
+
+
+@pytest.mark.parametrize("program", sorted(PROGRAMS))
+def test_main_ignores_the_entry_point_groups_of_the_other_programs(
+    program, monkeypatch, capsys, restore_cli_commands
+):
+    package, group, _, _ = PROGRAMS[program]
+    _install_fixture_entry_point(
+        monkeypatch,
+        OTHER_PROGRAMS_GROUP[program],
+        click.Command(FIXTURE_COMMAND_NAME),
+    )
+    monkeypatch.setattr(sys, "argv", _offline_argv(program, "--help"))
+
+    with pytest.raises(SystemExit) as exit_info:
+        package.main()
+
+    assert exit_info.value.code == 0
+    assert FIXTURE_COMMAND_NAME not in group.commands
+    assert FIXTURE_COMMAND_NAME not in capsys.readouterr().out
+
+
+def test_the_console_script_targets_are_importable():
+    # [project.scripts] points at these, so they must stay where they are.
+    assert mvt.cli.main is mvt_main
+    assert mvt.ios.main is ios_main
+    assert mvt.android.main is android_main
+
+
+def test_importing_mvt_does_not_import_a_cli(tmp_path):
+    # The mvt package deliberately re-exports nothing of mvt.cli, so that
+    # importing MVT stays cheap and free of side effects.
+    result = run_isolated_python(
+        "import sys\n"
+        "import mvt\n"
+        "print('imported a cli' if 'mvt.cli' in sys.modules else 'imported mvt')\n",
+        home=tmp_path / "home",
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "imported mvt"
+
+
+def test_importing_mvt_does_not_run_installed_plugins(tmp_path):
+    site_path = write_cli_plugin_distribution(
+        tmp_path / "site", IOS_CLI_PLUGIN_GROUP, MARKER_PLUGIN_TEMPLATE
+    )
+    marker = tmp_path / "plugin-imported"
+
+    result = run_isolated_python(
+        "import mvt.ios.cli\nimport mvt.android.cli\nprint('imported')",
+        home=tmp_path / "home",
+        site_path=site_path,
+        FIXTURE_PLUGIN_MARKER=str(marker),
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "imported" in result.stdout
+    assert not marker.exists()
+
+
+def test_registering_the_plugins_runs_the_entry_point(tmp_path):
+    site_path = write_cli_plugin_distribution(
+        tmp_path / "site", IOS_CLI_PLUGIN_GROUP, MARKER_PLUGIN_TEMPLATE
+    )
+    marker = tmp_path / "plugin-imported"
+
+    result = run_isolated_python(
+        "import click\n"
+        "from mvt.common.cli_plugins import (\n"
+        "    IOS_CLI_PLUGIN_GROUP,\n"
+        "    BrokenPluginCommand,\n"
+        "    register_installed_cli_commands,\n"
+        ")\n"
+        "group = click.Group()\n"
+        "register_installed_cli_commands(group, IOS_CLI_PLUGIN_GROUP)\n"
+        f"command = group.commands[{FIXTURE_COMMAND_NAME!r}]\n"
+        "assert not isinstance(command, BrokenPluginCommand), command.help\n"
+        "print('registered')\n",
+        home=tmp_path / "home",
+        site_path=site_path,
+        FIXTURE_PLUGIN_MARKER=str(marker),
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "registered" in result.stdout
+    assert marker.exists()

tests/test_completion.py

@@ -6,56 +6,60 @@
 from click.testing import CliRunner
 
 from mvt.android.cli import cli as android_cli
+from mvt.cli import cli as mvt_cli
 from mvt.ios.cli import cli as ios_cli
 
 
 class TestCompletionCommand:
     def test_completion_prints_instructions_by_default(self):
         runner = CliRunner()
-        result = runner.invoke(ios_cli, ["completion"])
+        result = runner.invoke(mvt_cli, ["completion"])
 
         assert result.exit_code == 0
-        assert "Shell completion for mvt-ios" in result.output
-        assert "mvt-ios completion bash > ~/.mvt-ios-complete.bash" in result.output
+        assert "Shell completion for mvt, mvt-ios and mvt-android" in result.output
+        assert "mvt completion bash > ~/.mvt-complete.bash" in result.output
         assert "Mobile Verification Toolkit" not in result.output
 
-    def test_completion_prints_bash_script(self):
+    def test_completion_bash_script_covers_every_cli(self):
         runner = CliRunner()
-        result = runner.invoke(ios_cli, ["completion", "bash"])
+        result = runner.invoke(mvt_cli, ["completion", "bash"])
 
         assert result.exit_code == 0
+        assert "_MVT_COMPLETE=bash_complete" in result.output
         assert "_MVT_IOS_COMPLETE=bash_complete" in result.output
+        assert "_MVT_ANDROID_COMPLETE=bash_complete" in result.output
         assert "complete -o nosort" in result.output
-        assert "mvt-ios" in result.output
         assert "Mobile Verification Toolkit" not in result.output
 
-    def test_completion_prints_fish_script(self):
+    def test_completion_fish_script_covers_every_cli(self):
         runner = CliRunner()
-        result = runner.invoke(android_cli, ["completion", "fish"])
+        result = runner.invoke(mvt_cli, ["completion", "fish"])
 
         assert result.exit_code == 0
-        assert "_MVT_ANDROID_COMPLETE=fish_complete" in result.output
+        assert "complete --no-files --command mvt-ios" in result.output
         assert "complete --no-files --command mvt-android" in result.output
+        assert "complete --no-files --command mvt " in result.output
         assert "Mobile Verification Toolkit" not in result.output
 
     def test_completion_install_updates_bashrc_once(self, tmp_path, monkeypatch):
         monkeypatch.setenv("HOME", str(tmp_path))
         runner = CliRunner()
 
-        result = runner.invoke(ios_cli, ["completion", "bash", "--install"])
+        result = runner.invoke(mvt_cli, ["completion", "bash", "--install"])
         assert result.exit_code == 0
 
-        script_path = tmp_path / ".mvt-ios-complete.bash"
+        script_path = tmp_path / ".mvt-complete.bash"
         bashrc_path = tmp_path / ".bashrc"
         assert script_path.exists()
-        assert "_MVT_IOS_COMPLETE=bash_complete" in script_path.read_text(
-            encoding="utf-8"
-        )
+        script = script_path.read_text(encoding="utf-8")
+        assert "_MVT_COMPLETE=bash_complete" in script
+        assert "_MVT_IOS_COMPLETE=bash_complete" in script
+        assert "_MVT_ANDROID_COMPLETE=bash_complete" in script
         bashrc = bashrc_path.read_text(encoding="utf-8")
         assert "[ -f" in bashrc
-        assert ".mvt-ios-complete.bash" in bashrc
+        assert ".mvt-complete.bash" in bashrc
 
-        result = runner.invoke(ios_cli, ["completion", "bash", "--install"])
+        result = runner.invoke(mvt_cli, ["completion", "bash", "--install"])
         assert result.exit_code == 0
         assert bashrc_path.read_text(encoding="utf-8") == bashrc
 
@@ -65,14 +69,30 @@ class TestCompletionCommand:
         monkeypatch.setenv("HOME", str(tmp_path))
         runner = CliRunner()
 
-        result = runner.invoke(android_cli, ["completion", "fish", "--install"])
+        result = runner.invoke(mvt_cli, ["completion", "fish", "--install"])
 
         assert result.exit_code == 0
-        script_path = (
-            tmp_path / ".config" / "fish" / "completions" / "mvt-android.fish"
-        )
+        script_path = tmp_path / ".config" / "fish" / "conf.d" / "mvt-completion.fish"
         assert script_path.exists()
-        assert "_MVT_ANDROID_COMPLETE=fish_complete" in script_path.read_text(
-            encoding="utf-8"
-        )
+        script = script_path.read_text(encoding="utf-8")
+        assert "_MVT_COMPLETE=fish_complete" in script
+        assert "_MVT_IOS_COMPLETE=fish_complete" in script
+        assert "_MVT_ANDROID_COMPLETE=fish_complete" in script
         assert not (tmp_path / ".fishrc").exists()
+        assert not (tmp_path / ".bashrc").exists()
+        assert not (tmp_path / ".zshrc").exists()
+
+    def test_completion_install_without_shell_is_a_usage_error(self):
+        runner = CliRunner()
+        result = runner.invoke(mvt_cli, ["completion", "--install"])
+
+        assert result.exit_code == 2
+        assert "A shell is required when using --install." in result.output
+
+    def test_completion_is_not_a_command_of_the_platform_clis(self):
+        runner = CliRunner()
+
+        assert "completion" not in ios_cli.commands
+        assert "completion" not in android_cli.commands
+        assert runner.invoke(ios_cli, ["completion"]).exit_code == 2
+        assert runner.invoke(android_cli, ["completion"]).exit_code == 2