Skip to main content

aiogram-cmds

CI PyPI Python versions License

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

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.")
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!

🏗️ Architecture

aiogram-cmds provides three levels of complexity:

  1. Auto-Setup: Zero configuration, works out of the box
  2. Simple Mode: Settings-based configuration with policies
  3. 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-cmds.git
cd aiogram-cmds

# Set up development environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Run tests
uv run 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.

Metadata

Release files for aiogram-cmds 0.2.0

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

Source distribution (sdist)

Source distribution for aiogram-cmds 0.2.0
File Size Uploaded Provenance Actions
aiogram_cmds-0.2.0.tar.gz 300.4 kB With provenance Details for aiogram_cmds-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiogram-cmds 0.2.0
File Interpreter ABI Platform Actions
aiogram_cmds-0.2.0-py3-none-any.whl Python 3 none any Details for aiogram_cmds-0.2.0-py3-none-any.whl

Total release size: 323.9 kB

Release files / aiogram_cmds-0.2.0.tar.gz

Download URL aiogram_cmds-0.2.0.tar.gz
Size 300.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5cac1902b709a2336fe901f458dbe71ea5acf8a35ba97979a149d695a87d8ed1
BLAKE2b-256 checksum
How to use checksums
e9e4137192384c0572babfc24ca6971c18cf6aad60d6dc6f9fe3e5155329153e
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 10, 2026.

Transparency log

Release files / aiogram_cmds-0.2.0-py3-none-any.whl

Download URL aiogram_cmds-0.2.0-py3-none-any.whl
Size 23.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aa04fe91eb293ee46ad0e0ccd780fd19df7c587c0cb579f4373a14cf93dab2e0
BLAKE2b-256 checksum
How to use checksums
46d1c16e831c2efe64140a579fe38a1ab73ac92f75d2d1c2e065c6e2af429cb9
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 10, 2026.

Transparency log

Security for aiogram-cmds 0.2.0

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 aiogram_cmds-0.2.0.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 10, 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