tello-usage
tello-usage is a Python package and command-line tool that retrieves data balances for every line in a Tello Mobile account. It reports remaining data, percentage available, renewal dates, and days remaining in each billing cycle.
The package uses httpx2 and Beautiful Soup to access Tello Mobile's account pages. It does not require a browser or browser automation software.
This is an independent, unofficial package. It is not developed by, affiliated with, or endorsed by Tello Mobile.
Requirements
The package requires Python 3.11 or later and a Tello Mobile account with an email address and password.
Installation
Install the command-line tool with uv:
uv tool install tello-usage
To use the package in a Python project, add it as a dependency:
uv add tello-usage
The distribution is named tello-usage. The Python import is named tello_usage,
and the command-line executable is named tello-usage.
Command-line usage
Run the following command to retrieve balances:
tello-usage
The command prompts for your Tello Mobile email address and password. The password is hidden while you type.
Each output line includes the account's line label, remaining data, percentage available, and days left in the billing cycle:
(555) 010-0100 - Example: 457.59 MB remaining / 10 GB (4.58% available); 4 days left in billing cycle
Use --json to produce JSON output:
tello-usage --json
The output contains one object for each line:
[
{
"subscription_id": "12345678",
"line": "(555) 010-0100 - Example",
"remaining": "457.59 MB",
"allowance": "10 GB",
"renewal_date": "2026-10-23",
"percentage_available": 4.58,
"days_left": 4
}
]
This example assumes the command runs on October 19, 2026.
If you installed the package as a project dependency, run the command through uv:
uv run tello-usage --json
Credentials
You can supply your email address with --username:
tello-usage --username you@example.com
The command also accepts the following environment variables:
TELLO_USERNAMEsupplies the account email address.TELLO_PASSWORDsupplies the account password.
The --username argument takes precedence over TELLO_USERNAME. Missing credentials are requested through terminal
prompts.
For unattended use, supply both credentials through your process environment. You can also provide the email address
with --username. The command exits with an error if credentials are missing and a terminal prompt is unavailable.
There is no password command-line argument. The package does not load .env files automatically.
Reusing sessions
Use --cookie-file to save the login session and reuse it on later runs:
tello-usage --cookie-file ~/.cache/tello-usage/cookies.json
You can also set the TELLO_COOKIE_FILE environment variable. The --cookie-file argument takes precedence. Cookies are
saved only when you choose a file.
If the saved session is still valid, the command skips the login and does not ask for a password. If the session has
expired or belongs to a different --username, the command uses the usual credentials, logs in, and replaces the file.
The file is written only after balances are retrieved successfully. If it cannot be written, the command prints a
warning and still shows the balances.
The cookie file can be used to access your Tello Mobile account. Protect it like a password. Where the operating system supports it, the file is readable only by the user who created it.
Python usage
Use TelloClient in a with statement so its HTTP connections are closed after use:
import os
from tello_usage import TelloClient
with TelloClient() as client:
balances = client.balances(
os.environ["TELLO_USERNAME"],
os.environ["TELLO_PASSWORD"],
)
for balance in balances:
print(
balance.line,
balance.remaining,
balance.percentage_available,
balance.renewal_date,
balance.days_left,
)
The synchronous balances(username, password) method logs in and returns a list of Balance objects.
The default HTTP timeout is 30 seconds. You can override it when creating the client:
with TelloClient(timeout=60) as client:
balances = client.balances(username, password)
Reusing sessions
Pass cookie_file to load a saved session and save it again after each successful call:
from tello_usage import TelloClient, TelloLoginRequired
with TelloClient(cookie_file="~/.cache/tello-usage/cookies.json") as client:
try:
balances = client.balances() # Reuses the saved session.
except TelloLoginRequired:
balances = client.balances(username, password) # Logs in and saves.
The username and password are optional for balances():
- If a logged-in session exists and belongs to
username, the client reuses it. When no username is given, any saved session is reused. Usernames are compared without regard to case. - Otherwise, the client logs in with the credentials. An expired session is discarded first.
- If a login is needed and the credentials are missing, the client raises
TelloLoginRequired, a subclass ofTelloError.
Passing credentials every time also works. The client then logs in only when the saved session is no longer valid.
If the cookie file cannot be written, balances() issues a RuntimeWarning and still returns the balances. A missing,
unreadable, or unrecognized cookie file is ignored.
To store sessions somewhere else, call the methods directly:
load_cookies(path)replaces the client's cookies with a saved session. It returnsFalseif the file cannot be used.save_cookies(path)saves the current logged-in session. It raisesTelloLoginRequiredif there is no session. The file is written atomically, and only Tello Mobile cookies and the account username are saved.
Balance values
Each Balance object provides the following values. JSON output uses the same names.
subscription_idis Tello Mobile's identifier for the line.lineis the label displayed in the account's line selector.remainingis the displayed remaining data amount, including its unit.allowanceis the displayed data allowance, including its unit.renewal_dateis the data plan's renewal or expiration date inYYYY-MM-DDformat.percentage_availableis the remaining data expressed as a percentage of the displayed allowance.days_leftis the number of calendar days until the renewal date.
The percentage calculation uses the displayed amounts, assumes 1 GB equals 1,000 MB, and rounds the result to two decimal places. The result is limited to 0–100 percent. A rollover balance above the allowance therefore reports 100 percent available.
An unlimited or zero allowance produces None for percentage_available.
Days remaining are calculated using the computer's local date. A renewal date of today or a date in the past produces zero days remaining. This value does not measure the exact number of hours until renewal.
If the account page does not provide a recognized renewal date, renewal_date and days_left are None. Python None
values appear as null in JSON.
Error handling
The client raises TelloError when login fails, required account information is missing, a line cannot be selected, or
a data balance cannot be read. Network and HTTP errors are raised as httpx2 exceptions.
import os
import httpx2
from tello_usage import TelloClient, TelloError
try:
with TelloClient() as client:
balances = client.balances(
os.environ["TELLO_USERNAME"],
os.environ["TELLO_PASSWORD"],
)
except TelloError as error:
print(f"Could not read account balances: {error}")
except httpx2.HTTPError as error:
print(f"The HTTP request failed: {error}")
The command-line tool writes errors to standard error and exits with a nonzero status.
A missing data balance stops the operation without returning partial results. This can occur when a line has no active data plan.
Website access and limitations
The package accesses Tello Mobile's website forms rather than a documented API. It logs in, discovers the account's lines, and selects each line to read its balance. It maintains session cookies and reads fresh form tokens between requests.
The client changes the selected account line while retrieving balances. It does not purchase data or change plan settings.
Changes to Tello Mobile's website, a CAPTCHA, or an additional account verification step may prevent the client from working.
Credentials are held in memory and are never saved by the package. Session cookies are saved only when you choose a cookie file, as described in Reusing sessions.
Development
From a source checkout, install dependencies and run the tests with uv:
uv sync
uv run python -m unittest discover -s tests -v
The tests use generated account pages and simulated HTTP responses. They do not require account credentials or make requests to Tello Mobile.
License
This project is licensed under the MIT License.
Metadata
Release files for tello-usage 2026.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tello_usage-2026.3.tar.gz | 11.8 kB | With provenance | Details for tello_usage-2026.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tello_usage-2026.3-py3-none-any.whl | Python 3 | none | any | Details for tello_usage-2026.3-py3-none-any.whl |
Total release size: 24.9 kB
Release files / tello_usage-2026.3.tar.gz
| Download URL | tello_usage-2026.3.tar.gz |
|---|---|
| Size | 11.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4776ba8757a2d3a5cd0564bdbaefdd29f9d38c40eb0d487e0b8a03ef2e08cd0b
|
|
BLAKE2b-256 checksum How to use checksums |
2b1bd7e391b22292f30518aed4219d0ab02cb9eebf0a60423e235464b91e3405
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
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 Nov 4, 2026.
Transparency logRelease files / tello_usage-2026.3-py3-none-any.whl
| Download URL | tello_usage-2026.3-py3-none-any.whl |
|---|---|
| Size | 13.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ae37acedce17534b5a98ae0134919c55aec7f9dd678541c45cd325f07fdfb0ed
|
|
BLAKE2b-256 checksum How to use checksums |
b34aa4d589d04cd49c410067e414b90d27be97d91d395d7009ac6350d08572d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
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 Nov 4, 2026.
Transparency logSecurity for tello-usage 2026.3
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.
Attestation for tello_usage-2026.3.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 Nov 4, 2026.
Transparency logA 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.