Skip to main content

Tello-Renewal

GitHub release Docker Image

中文版 | English Version

Automatic renewal system for Tello mobile plans. Uses CloakBrowser (headless Chromium with 57 source-level patches) to bypass Cloudflare managed challenges on Tello's checkout endpoint.

Features

  • 🔄 Automatic plan renewal via CloakBrowser
  • 🛡️ Cloudflare bypass via real browser fingerprinting (CloakBrowser)
  • 📋 Plan catalog check — monitor available plans without login
  • 📧 Email notifications for success / failure
  • 🧪 Dry-run mode for safe testing
  • 📡 JSON-first CLI output — machine-readable by default, --human for text
  • ⚙️ YAML configuration with pydantic validation
  • 📊 Structured logging with rotation
  • 🐳 Docker support — single image with CloakBrowser pre-bundled

Installation

From PyPI

pip install tello-renewal
python -m cloakbrowser install   # download patched Chromium (~200 MB, one-time)

Requirements

  • Python 3.10+
  • CloakBrowser's Chromium is self-contained (downloaded via python -m cloakbrowser install)

Quick Start

  1. Create configuration file:

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

    tello:
      email: "you@example.com"
      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
    

Configuration Reference

tello:
  email: "you@example.com"
  password: "your_password"
  card_expiration: "1/27"        # MM/YY, MM/YYYY, or YYYY-MM-DD
  base_url: "https://tello.com"
  login_timeout: 30

browser:
  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
  retry_delay: 300               # seconds between retries
  dry_run: false
  state_folder_path: ".tello_state"

smtp:
  server: "smtp.gmail.com"
  port: 587
  username: "you@gmail.com"
  password: "app_password"
  from_email: '"Tello Renewal" <you@gmail.com>'
  use_tls: true

notifications:
  email_enabled: true
  recipients:
    - "admin@example.com"
  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

CLI Commands

tello-renewal renew [--dry-run] [--force]   # execute renewal
tello-renewal status                         # account status and balance
tello-renewal plan-check                     # list available plan options
tello-renewal config-init [--output FILE]   # generate example config
tello-renewal config-validate               # validate config file
tello-renewal email-test                    # send test notification

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

Code Meaning
0 Success
1 General error
2 Configuration error
5 Renewal failed
6 Not due for renewal
7 Skipped (cached)

Docker

The Docker image (python:3.12-slim base) includes CloakBrowser's 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

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

Troubleshooting

CloakBrowser binary missing:

python -m cloakbrowser install

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
pip install -e ".[dev]"
python -m cloakbrowser install
pytest
ruff check src/

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.

Metadata

Release files for tello-renewal 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tello-renewal 0.6.2
File Size Uploaded Provenance Actions
tello_renewal-0.6.2.tar.gz 80.6 kB With provenance Details for tello_renewal-0.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tello-renewal 0.6.2
File Interpreter ABI Platform Actions
tello_renewal-0.6.2-py3-none-any.whl Python 3 none any Details for tello_renewal-0.6.2-py3-none-any.whl

Total release size: 160.7 kB

Release files / tello_renewal-0.6.2.tar.gz

Download URL tello_renewal-0.6.2.tar.gz
Size 80.6 kB
Tags Source
SHA-256 checksum
How to use checksums
813becca5060c95878b2b3848db3b63c2cffa334dbfd77019a0e3831fa2e14f5
BLAKE2b-256 checksum
How to use checksums
c959de38d325b25b54e329d6f9fcc815f6c36808b5f362072f0cd434066f48ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Release files / tello_renewal-0.6.2-py3-none-any.whl

Download URL tello_renewal-0.6.2-py3-none-any.whl
Size 80.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0791408b02d2809aa8737ff5f41dd08d34a03166f21e72a4851895c92c3e7b5e
BLAKE2b-256 checksum
How to use checksums
11a521bce0bf8491c75c6f32a0f554efbd385ffc16e99c74791da775ea68585d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Security for tello-renewal 0.6.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tello_renewal-0.6.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page