telethon-cli

telethon-cli is a separate installable package that exposes:

• a stable command tree for the public TelegramClient API;
• a generic dispatcher for internal telethon and telethon_generator callables;
• env-first client configuration through TG_API_ID and TG_API_HASH, with optional session overrides.

Installation

Install from PyPI:

python -m pip install telethon-cli

For local development, install the package in editable mode:

python -m pip install -e .

Set the required Telethon credentials before running commands. You can export them directly in the shell:

export TG_API_ID=...
export TG_API_HASH=...

You can also keep them in a .env file in the current working directory or at the project root:

TG_API_ID=...
TG_API_HASH=...

Legacy TELETHON_API_ID, TELETHON_API_HASH, TELETHON_SESSION, and TELETHON_PASSWORD are still accepted as compatibility aliases. When both namespaces are present, telethon-cli requires the values to match.

On first login, telethon-cli can create and store a Telethon session in the project automatically. You can create it explicitly:

telethon-cli login

Typical first-run flow:

python -m pip install -e .
telethon-cli login
telethon-cli users get-me --output json

To remove the saved session and force a fresh login next time:

telethon-cli logout

Or just run the first command in an interactive terminal and let the CLI ask for your phone number, login code, and Telegram 2FA password when needed:

telethon-cli users get-me --output json

By default the session is stored in .telethon-cli/session under the project root. You can override it explicitly:

telethon-cli users get-me --session /path/to/session --output json
telethon-cli users get-me --env-file /path/to/telethon.env --output json

telethon-cli reads the current process environment and also loads .env automatically when present. If the same Telethon setting is defined both in the environment and in .env, and the values differ, the command exits with an error instead of silently choosing one. CLI flags such as --api-id, --api-hash, --session, and --2fa-password still override both.

In non-interactive environments, automatic login is not possible. In that case, create the session in advance with telethon-cli login and reuse it later.

Smoke-test the installation:

telethon-cli --help
python -m telethon_cli registry public --output json
telethon-cli users get-me --output json

Dangerous features are gated behind project-wide developer mode. Enable it once from settings and explicitly confirm the warning before using call, registry project, $ref, or $call payload helpers:

telethon-cli settings developer-mode --enable --accept-dangerous-features

Examples:

telethon-cli users get-me --output json
telethon-cli messages send-message --entity me --message "hello"
telethon-cli call telethon.utils.parse_phone --args-json '["+1 234 567"]'
telethon-cli call telethon.tl.functions.help.GetConfigRequest --client-invoke --output json
telethon-cli settings show --output json

Release Process

Build and validate release artifacts locally before uploading:

rm -rf dist build src/*.egg-info
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

Optional local smoke-test from the built wheel:

python -m pip install --force-reinstall dist/*.whl
telethon-cli --help
python -m telethon_cli registry public --output json

Upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Verify installation from TestPyPI:

python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple telethon-cli
telethon-cli --help
python -m telethon_cli registry public --output json

Then upload the same artifacts to PyPI:

python -m twine upload dist/*

When twine prompts for credentials, use username __token__ and your pypi-... API token as the password. Keep PyPI tokens out of the repository and provide them through the environment or twine prompt.

For every subsequent release, bump version in pyproject.toml before building. PyPI rejects uploads for versions that already exist.

You can also keep PyPI credentials in the project-local .env file, because .env is gitignored in this repository. The release helper script reads .env automatically and publishes with twine:

TWINE_USERNAME=__token__
TEST_PYPI_TOKEN=pypi-...
PYPI_TOKEN=pypi-...

chmod +x scripts/release_pypi.sh
./scripts/release_pypi.sh testpypi
./scripts/release_pypi.sh pypi
./scripts/release_pypi.sh all