The repository or configuration that created this release differ from a previous release. View details.
aiogram-cmds
Source development and releases are maintained in the aiogram-kit monorepo. See the workspace contributing guide; package examples live under packages/aiogram-cmds/.
Command management library for aiogram v3 - Manage Telegram bot commands with i18n support, user profiles, and dynamic scopes.
✨ Features
- Simple & Advanced Modes: Start simple, scale to complex configurations
- i18n Integration: Built-in support for aiogram i18n with fallback handling
- User Profiles: Dynamic command sets based on user status (guest, registered, etc.)
- Multiple Scopes: Support for all Telegram command scopes (private, group, admin, etc.)
- Auto-Setup: One-call setup with sensible defaults
- Type-Safe: Full type hints and strict type checking
- Verified behavior: Contract tests, CI and documented failure semantics
📦 Installation
# Basic installation
pip install aiogram-cmds
# Optional Redis client for application-owned integrations
pip install aiogram-cmds[redis]
The Redis extra installs a client only. This library provides no Redis backend, distributed lock, command cache or multi-worker coordination. Applications own those concerns; installing the extra does not make updates atomic.
⚡ Quick Start
Auto-Setup (Recommended)
from aiogram import Bot, Dispatcher
from aiogram_cmds.auto_setup import setup_commands_auto
async def on_startup():
# Automatically set up commands with sensible defaults
command_manager = await setup_commands_auto(bot)
# Commands are ready to use!
# Your handlers
@dp.message(Command("start"))
async def handle_start(message: Message):
await message.answer("Welcome! Use /help to see available commands.")
Application-selected profiles (recommended)
from aiogram_cmds import CmdsConfig, CommandDef, ProfileDef, ScopeDef, MenuButtonDef
# Define your command configuration
config = CmdsConfig(
languages=["en", "ru", "es"],
commands={
"start": CommandDef(i18n_key="start.desc"),
"help": CommandDef(i18n_key="help.desc"),
"profile": CommandDef(i18n_key="profile.desc"),
"admin": CommandDef(i18n_key="admin.desc"),
},
profiles={
"guest": ProfileDef(include=["start", "help"]),
"user": ProfileDef(include=["start", "help", "profile"]),
"admin": ProfileDef(include=["start", "help", "profile", "admin"]),
},
scopes=[
ScopeDef(scope="all_private_chats", profile="guest"),
ScopeDef(scope="chat", chat_id=12345, profile="admin"),
],
menu_button=MenuButtonDef(mode="commands"),
)
# Select profiles in your application using its own roles and state.
manager = CommandScopeManager(bot, config=config)
await manager.setup_all()
await manager.update_profile(user_id=12345, profile="admin", language="en")
Legacy flag-based compatibility
from aiogram import Bot, Dispatcher
from aiogram_cmds import CommandScopeManager, load_settings, build_translator_from_i18n
# Load settings from pyproject.toml or use defaults
settings = load_settings()
translator = build_translator_from_i18n(i18n) # Your aiogram i18n instance
# Create manager
manager = CommandScopeManager(bot, settings=settings, translator=translator)
# Set up all command scopes
await manager.setup_all()
# Update user commands dynamically
await manager.update_user_commands(
user_id=12345,
is_registered=True,
has_vehicle=False,
user_language="en"
)
Failure handling
Manager methods return True only after all Telegram operations finish. They
propagate the original error by default. Code that relied on the old silent
failure behavior can opt into CommandScopeManager(bot, best_effort=True) and
check the returned boolean (False on failure). Cancellation always propagates.
setup_commands_auto also propagates startup failures.
A multi-scope update is sequential: an error can leave earlier scopes updated. There is no rollback or automatic retry. Retry deliberately after inspecting the error; command-setting calls replace the target scope's commands.
Flags and update_user_commands remain supported for legacy integrations.
Generic applications should select a profile themselves and use update_profile.
🎯 Use Cases
E-commerce Bot
# Different commands for different user states
profiles = {
"visitor": ProfileDef(include=["start", "catalog", "help"]),
"customer": ProfileDef(include=["start", "catalog", "cart", "orders", "help"]),
"vip": ProfileDef(include=["start", "catalog", "cart", "orders", "vip_offers", "help"]),
}
Admin Bot
# Admin commands only for specific users
scopes = [
ScopeDef(scope="all_private_chats", profile="user"),
ScopeDef(scope="chat_member", chat_id=12345, user_id=67890, profile="admin"),
]
Multi-Language Bot
# Commands in multiple languages
config = CmdsConfig(
languages=["en", "ru", "es", "fr"],
commands={
"start": CommandDef(i18n_key="commands.start"),
"help": CommandDef(i18n_key="commands.help"),
}
)
📚 Documentation
👉 Full Documentation ← Start here!
- Quickstart - Get started in 5 minutes
- Configuration - Complete configuration guide
- API Reference - Full API documentation
- Tutorials - Step-by-step guides
- Examples - Complete working examples
🏗️ Architecture
aiogram-cmds provides three levels of complexity:
- Auto-Setup: Zero configuration, works out of the box
- Simple Mode: Settings-based configuration with policies
- Advanced Mode: Full control with profiles, scopes, and custom resolvers
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Auto-Setup │ │ Simple Mode │ │ Advanced Mode │
│ │ │ │ │ │
│ setup_commands_ │ │ CmdsSettings + │ │ CmdsConfig + │
│ auto() │ │ CommandPolicy │ │ ProfileResolver │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌──────────────────┐
│ CommandScopeMgr │
│ │
│ • setup_all() │
│ • update_user() │
│ • clear_user() │
└──────────────────┘
🤝 Contributing
We welcome contributions! See our Contributing Guide for details.
Development Setup
# Clone the repository
git clone https://github.com/ArmanAvanesyan/aiogram-kit.git
cd aiogram-kit
uv sync --frozen --all-packages --all-groups --all-extras --python 3.12
cd packages/aiogram-cmds
# Run tests
uv run --no-sync pytest
# Run linting
uv run ruff check .
uv run ruff format .
💬 Community & Support
- 💬 Discussions - Questions, ideas, and community chat
- 🐛 Issues - Bug reports and feature requests
- 📖 Documentation - Complete guides and API reference
🔒 Security
For security issues, see SECURITY.md.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Built for aiogram v3 - Modern Telegram Bot API framework
- Inspired by the need for robust command management in production environments
📊 Project Status
- ✅ Core Features: Command management, i18n, profiles, scopes
- ✅ Documentation: Comprehensive guides and API reference
- ✅ Testing: Unit, integration, and performance tests
- ✅ CI: Automated verification; deliberate package releases and manual documentation publication
- 🚧 Examples: Working bot examples (in progress)
- 🔮 Future: Rate limiting, caching, advanced analytics
Made with ❤️ for the aiogram community
Contributing and maintenance
See CONTRIBUTING.md for repository conventions and checks, SECURITY.md for private vulnerability reporting, and docs/releasing.md for maintainer release instructions.
Compatibility and 0.2 migration
| Component | Supported / tested |
|---|---|
| Python | 3.10–3.13 in CI |
| aiogram | >=3.0.0,<4; minimum 3.0.0 and latest resolvable 3.x in CI |
| Redis | Optional client extra >=5.0.8,<8; no Redis server/backend is implemented |
See the 0.2 migration guide for independent rendering
locale/menu slots, default-language fallback, explicit language cleanup,
confirmed payload fingerprints and partial batch outcomes. Run
uv run python examples/application_profiles.py --dry-run for a network-free
example. The library never configures application logging.
Compiled immutable profiles and explicit optional engines are described in performance guidance. Python remains the default; native publication is benchmark-gated.
The recorded 0.3.0 native candidate did not pass its release performance gate. Native publication, native tags and a dependency extra are withheld. Rust code remains available to build from source; the Python 0.3.1 distribution can release independently. Use compiled Python profiles for explicit snapshot reuse.
Metadata
Release files for aiogram-cmds 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Change of provenance
The repository or configuration that created these release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiogram_cmds-0.3.1.tar.gz | 359.7 kB | With provenance | Details for aiogram_cmds-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiogram_cmds-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for aiogram_cmds-0.3.1-py3-none-any.whl |
Total release size: 390.2 kB
Release files / aiogram_cmds-0.3.1.tar.gz
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | aiogram_cmds-0.3.1.tar.gz |
|---|---|
| Size | 359.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1652c5c10f745b84249da5aa07e5189d55ffa6b48bc97017eff3b69401ef67d
|
|
BLAKE2b-256 checksum How to use checksums |
43358e260b29bb37f069bfb2edb02c26bb61bd03f0ed49c44dd5ad7a94f48412
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 11, 2026.
Transparency logRelease files / aiogram_cmds-0.3.1-py3-none-any.whl
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | aiogram_cmds-0.3.1-py3-none-any.whl |
|---|---|
| Size | 30.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2ea5ab0c0267264d7a4d1756f86d55b991603dacc1e0cf7e40a07a4322396ba
|
|
BLAKE2b-256 checksum How to use checksums |
4ff928d5449d01c8a7155e01273b1fddb1cff1eec7ebaa4a73dfe4bd8398c615
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 11, 2026.
Transparency logSecurity for aiogram-cmds 0.3.1
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.
Change of provenance
The repository and configuration that created this release differ from a previous release.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Repository
- Removed 0.3.0 github.com/ArmanAvanesyan/aiogram-cmds
- Added 0.3.1 github.com/ArmanAvanesyan/aiogram-kit
Attestation for aiogram_cmds-0.3.1.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 11, 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.