Sign inSign up

oaklight/tello-renewal

By oaklight

•Updated about 1 month ago

Automatic Tello mobile plan renewal through a real CloakBrowser session, with email reports.

Image
0

2.3K

oaklight/tello-renewal repository overview

⁠Tello-Renewal

中文版⁠ | 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.

⁠Features

  • 🔄 Automatic, due-date-aware renewal, guarded by a run lock so overlapping schedules are safe
  • 🧭 Two backends: DOM automation (playwright) or form replay (fetch)
  • 🛡️ Cloudflare bypass via a real, patched Chromium fingerprint (CloakBrowser + Patchright)
  • 📋 Plan catalog check — inspect available plans without logging in
  • 🔁 Plan switching — change-plan --data/--call, with --dry-run
  • 🔐 Login retries with bounded exponential backoff
  • 📧 Email notifications for success / failure / not-due
  • 🧪 Dry-run mode for safe testing, including the client's own no-submit path
  • 📡 JSON-first CLI output — machine-readable by default, --human for text and tables
  • ⚙️ YAML configuration with pydantic validation
  • 📊 Structured logging with rotation and credential redaction
  • 🐳 Docker support — single image with the CloakBrowser Chromium pre-bundled

⁠Installation

⁠From PyPI
pip 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:

VariablePurpose
CLOAKBROWSER_BINARYPath to an executable Chromium binary to use instead of downloading
CLOAKBROWSER_CACHE_DIRWhere downloaded builds are stored (default ~/.cloakbrowser)
CLOAKBROWSER_MIRRORDownload mirror prefix, e.g. https://ghfast.top
⁠Requirements
  • Python 3.10+
  • Network access on first run to fetch the Chromium build (or a pre-installed binary)

⁠Quick Start

  1. Create configuration file:

    tello-renewal config-init
    
  2. Edit config.yaml with your Tello credentials:

    tello:
      email: "[email protected]"
      password: "your_password"
      card_expiration: "1/27"      # MM/YY
    
  3. Test:

    tello-renewal config-validate
    tello-renewal email-test
    tello-renewal status
    
  4. Renew:

    tello-renewal renew --dry-run   # test without charging
    tello-renewal renew             # real renewal
    
  5. 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"
    

⁠Configuration Reference

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
⁠Backends
browser.backendHow it drives TelloBreaks when
playwright (default)UI automation: selectors, carousels, button clicks, waitsThe DOM, class names or widgets change
fetchOne page load for Cloudflare clearance, then in-page fetch() against /account/process_login, /process_buy, /account/checkout, /account/process_orderTello 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.

⁠CLI Commands

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

⁠Exit Codes

CodeMeaning
0Success
1General error
2Configuration error
5Renewal failed
6Not due for renewal
7Skipped (cached date or another run holds the lock)

⁠Docker

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=256m is required — Chromium uses /dev/shm for IPC and crashes with the default 64 MB Docker limit.

⁠Build from source
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
⁠Cron with Docker
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.

⁠Scheduling (without Docker)

⁠Cron
0 0 * * * /path/to/venv/bin/tello-renewal renew >> /var/log/tello-renewal.log 2>&1
⁠Systemd timer
# /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

⁠State and concurrency

  • 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.
  • Renewal submission is never retried automatically; only login and read steps retry.

⁠Troubleshooting

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

⁠Development

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.

⁠Changelog

See CHANGELOG.md⁠.

⁠License

MIT — see LICENSE⁠.

⁠Disclaimer

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.

Tag summary

Content type

Image

Digest

sha256:17cb84537…

Size

388.7 MB

Last updated

about 1 month ago

docker pull oaklight/tello-renewal