# adb-sideload-free-apps

Install free Android apps via ADB from F-Droid, GitHub Releases, GitLab Releases, Codeberg Releases, or generic HTTPS pages.

## 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] [--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
- `--config`, `-c` — path to config.toml (default: ./config.toml)

## Configuration

See `config.example.toml`. Supported sources:

| Source   | Required fields              |
| -------- | ---------------------------- |
| `fdroid` | `url` (page F-Droid)          |
| `github` | `url` (repository)            |
| `gitlab` | `url` (projet)                |
| `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 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
```