87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# adb-sideload-free-apps
|
|
|
|
Install free Android apps via ADB from F-Droid, GitHub Releases, GitLab Releases, Codeberg Releases, or generic HTTPS pages.
|
|
|
|
[Français](README.fr.md)
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11+
|
|
- `adb` (Android Debug Bridge) in PATH
|
|
- `aapt2` or `aapt` (Android SDK Build Tools) in PATH
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
python -m pip install -e .
|
|
cp config.example.toml config.toml
|
|
# Edit config.toml to add your apps
|
|
python -m sideload
|
|
```
|
|
|
|
## Usage
|
|
|
|
```
|
|
sideload [APP] [--list] [--update-all] [--device SERIAL] [--dry-run] [--config PATH]
|
|
```
|
|
|
|
- `APP` — app name from config (omit for interactive selection)
|
|
- `--list` — list configured apps
|
|
- `--device`, `-s` — ADB device serial
|
|
- `--dry-run` — resolve, download, validate without installing
|
|
- `--update-all` — inspect every configured app on one selected device and update only
|
|
installed apps whose remote APK has a greater `versionCode` (incompatible with `APP` and `--list`)
|
|
- `--config`, `-c` — path to config.toml (default: ./config.toml)
|
|
|
|
`--update-all` selects the ADB device once, then checks every configured package with
|
|
`adb shell dumpsys package`. Apps that are not installed are reported and skipped without
|
|
downloading anything. Installed apps are updated only when the validated remote APK has a
|
|
strictly greater `versionCode`; equal or lower versions are skipped. Errors for one app do
|
|
not stop the other apps, and the command prints a summary and returns a non-zero status if
|
|
an update failed.
|
|
|
|
## Configuration
|
|
|
|
See `config.example.toml`. Supported sources:
|
|
|
|
| Source | Required fields |
|
|
| -------- | ---------------------------- |
|
|
| `fdroid` | `url` (page F-Droid) |
|
|
| `github` | `url` (repository) |
|
|
| `gitlab` | `url` (project) |
|
|
| `codeberg` | `url` (repository Codeberg) |
|
|
| `generic` | `url`, `asset_pattern` (HTTPS page or directory) |
|
|
|
|
Every application also requires `name` and `package`. For GitHub, GitLab, and Codeberg,
|
|
set `asset_pattern` when a release contains more than one suitable APK. Debug,
|
|
test and unsigned APKs are rejected by default.
|
|
|
|
The `generic` source follows HTTPS anchor links from `url`. Use ordered
|
|
`intermediate_patterns` to navigate directories; when several links match, a
|
|
pattern with numeric capture groups selects the greatest numeric tuple.
|
|
`asset_pattern` is required and must match exactly one final APK. Optional
|
|
`headers` and `sha256` are supported; header values are never logged.
|
|
|
|
`aapt2` is used to validate the APK package ID before installation, with
|
|
`aapt` as a fallback for older Android SDK Build Tools. At least one of them
|
|
must be available in `PATH`. The script refuses to install an APK when neither
|
|
tool can validate it.
|
|
|
|
For `--update-all`, `aapt2 dump badging` (with `aapt dump badging` fallback) also reads the
|
|
remote APK `versionCode` before deciding whether an installation is needed.
|
|
|
|
For Wi-Fi ADB, configure an explicit address after enabling wireless debugging:
|
|
|
|
```toml
|
|
[adb]
|
|
mode = "wifi"
|
|
address = "192.168.1.42:5555"
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
pip install pytest
|
|
python -m pytest tests/ -v
|
|
```
|