Automatic Tello mobile plan renewal through a real CloakBrowser session, with email reports.
2.3K
中文版 | English Version
Automatic renewal system for Tello mobile plans. It drives a real CloakBrowser Chromium through Patchright, reads the renewal date and account balance, and submits the renewal form (or switches plans if asked). Email notifications report success or failure.
Tello has no JSON API — every action is a server-rendered form POST. The project therefore ships two interchangeable backends that share one CloakBrowser session:
playwright (default) — drives the DOM with selectors, clicks and waits.fetch — loads one page to obtain Cloudflare clearance, then replays Tello's form
endpoints with in-page fetch(). No selectors, widgets or render timing; pick it with
browser.backend: fetch.Both backends need the browser: Cloudflare checks the TLS fingerprint and cookies, not just the request body.
playwright) or form replay (fetch)change-plan --data/--call, with --dry-run--human for text and tablespip install tello-renewal
The patched Chromium (~200 MB) is downloaded on first use into ~/.cloakbrowser. To use an
existing binary or a mirror, set one of these environment variables:
| Variable | Purpose |
|---|---|
CLOAKBROWSER_BINARY | Path to an executable Chromium binary to use instead of downloading |
CLOAKBROWSER_CACHE_DIR | Where downloaded builds are stored (default ~/.cloakbrowser) |
CLOAKBROWSER_MIRROR | Download mirror prefix, e.g. https://ghfast.top |
Create configuration file:
tello-renewal config-init
Edit config.yaml with your Tello credentials:
tello:
email: "[email protected]"
password: "your_password"
card_expiration: "1/27" # MM/YY
Test:
tello-renewal config-validate
tello-renewal email-test
tello-renewal status
Renew:
tello-renewal renew --dry-run # test without charging
tello-renewal renew # real renewal
Optionally switch plans:
tello-renewal change-plan --data "2 GB" --call "300 min" --dry-run
tello-renewal change-plan --data "2 GB" --call "300 min"
tello:
email: "[email protected]"
password: "your_password"
card_expiration: "1/27" # MM/YY, MM/YYYY, or YYYY-MM-DD
base_url: "https://tello.com"
login_timeout: 30
browser:
backend: "playwright" # playwright | fetch
browser_type: "cloakbrowser"
headless: true # false for headed mode (helps with CF)
timeout: 60
# proxy_server: "http://10.0.0.1:7890"
# Expected plan (optional) — status/renew warn on mismatch
plan:
data: "2 GB" # "2 GB", "10 GB", "20 GB", "Unlimited"
call: "Unlimited" # "300 min", "Unlimited"
renewal:
auto_renew: true
days_before_renewal: 1 # start attempting N days before due date
max_retries: 3 # login retries (0 disables; backoff is exponential)
retry_delay: 300 # base retry delay in seconds (capped at 5 s for login)
dry_run: false
state_folder_path: ".tello_state"
smtp:
server: "smtp.gmail.com"
port: 587
username: "[email protected]"
password: "app_password"
from_email: '"Tello Renewal" <[email protected]>'
use_tls: true
notifications:
email_enabled: true
recipients:
- "[email protected]"
send_on_success: true
send_on_failure: true
send_on_not_due: false
logging:
level: "INFO"
format: "detailed" # simple | detailed | json
file: "tello_renewal.log"
max_size: "10MB"
backup_count: 5
console_output: true
browser.backend | How it drives Tello | Breaks when |
|---|---|---|
playwright (default) | UI automation: selectors, carousels, button clicks, waits | The DOM, class names or widgets change |
fetch | One page load for Cloudflare clearance, then in-page fetch() against /account/process_login, /process_buy, /account/checkout, /account/process_order | Tello renames an endpoint or form field |
fetch is opt-in while its real-renewal path is validated across billing cycles. Both backends
use the same parsers for due dates, balances and the plan catalog, and the same notification
pipeline.
tello-renewal renew [--dry-run] [--force] [--refresh] # execute renewal
tello-renewal status # account status and balance
tello-renewal plan-check # list available plan options
tello-renewal change-plan [--data D] [--call C] [--dry-run]
# switch plan (defaults from config)
tello-renewal config-init [--output FILE] # generate example config
tello-renewal config-validate # validate config file
tello-renewal email-test # send test notification
renew --dry-run logs what would be submitted without writing to Tello.renew --force ignores the cached due date and the recorded run state, then decides on the live
due date (still respects --dry-run).renew --refresh re-reads the live due date but still honours a renewal already completed in
this window.change-plan defaults to the plan section and accepts --data / --call overrides for a
single run.Global options: --config FILE, --verbose, --human, --version
Output is JSON by default (machine-readable). Add --human for a
human-friendly table/text view:
tello-renewal status # JSON output
tello-renewal --human status # human-readable text
tello-renewal --human plan-check # plan table
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Configuration error |
| 5 | Renewal failed |
| 6 | Not due for renewal |
| 7 | Skipped (cached date or another run holds the lock) |
The Docker image (python:3.12-slim base) includes the CloakBrowser Chromium pre-downloaded.
docker run --rm --shm-size=256m \
-v /path/to/config:/app/config:ro \
-v /path/to/logs:/app/logs \
oaklight/tello-renewal:latest \
tello-renewal --config /app/config/config.yaml renew
--shm-size=256mis required — Chromium uses/dev/shmfor IPC and crashes with the default 64 MB Docker limit.
make build-package # build Python wheel
make build-docker # build Docker image from local wheel
# Optional overrides
make build-docker MIRROR=https://pypi.tuna.tsinghua.edu.cn/simple
make build-docker REGISTRY_MIRROR=docker.1ms.run
0 0 * * * docker run --rm --shm-size=256m \
-v ~/.config/tello-renewal:/app/config:ro \
-v /var/log/tello-renewal:/app/logs \
oaklight/tello-renewal:latest \
tello-renewal --config /app/config/config.yaml renew >/dev/null 2>&1
A second renew that starts while another is still running returns exit code 7 instead of
renewing twice.
0 0 * * * /path/to/venv/bin/tello-renewal renew >> /var/log/tello-renewal.log 2>&1
# /etc/systemd/system/tello-renewal.service
[Unit]
Description=Tello Plan Auto Renewal
After=network.target
[Service]
Type=oneshot
User=tello
ExecStart=/opt/tello-renewal/venv/bin/tello-renewal renew
# /etc/systemd/system/tello-renewal.timer
[Unit]
Description=Run Tello renewal daily
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
sudo systemctl enable --now tello-renewal.timer
renewal.state_folder_path (default .tello_state) holds DUE_DATE (cached due date),
RUN_STATE (last completed run in the window) and EXEC_STATUS (history)..renew.lock in the same folder makes a concurrent renew return exit code 7 rather than
racing the same account.Chromium download fails:
Set CLOAKBROWSER_MIRROR (e.g. https://ghfast.top) or point CLOAKBROWSER_BINARY at an
existing patched Chromium.
Cloudflare challenge loop:
Try headed mode (browser.headless: false) or a residential proxy (browser.proxy_server). If
status or plan-check returns an interstitial, retry — catalog fetches retry automatically.
Email sending failures:
Use app-specific passwords. Test with tello-renewal email-test.
Debug mode:
tello-renewal --verbose renew --dry-run
git clone https://github.com/Oaklight/Tello-Renewal.git
cd Tello-Renewal
conda activate tello # or any Python 3.10+ environment
pip install -e ".[dev,test]"
pytest tests/ --override-ini="addopts="
ruff check src/ tests/
ruff format src/ tests/
ty check
Pre-commit runs ruff, ruff-format and ty check; src/tello_renewal/_vendor/ is excluded from
linting and type checking.
See CHANGELOG.md.
MIT — see LICENSE.
Provided as-is for personal automation. You are responsible for complying with Tello's terms of service and for the security of your credentials. The authors are not liable for failed renewals or service interruptions.
Content type
Image
Digest
sha256:17cb84537…
Size
388.7 MB
Last updated
about 1 month ago
docker pull oaklight/tello-renewal