🛒 allegro-cli

The power-user's gateway to Allegro.

allegro-cli is a high-performance command-line interface for browsing offers, managing carts, and tracking packages on Allegro.pl. It is designed for two types of users: power-users who want to automate their shopping and AI Agents who need structured, token-efficient access to marketplace data.

✨ Key Features

• 🚀 Agent-First Design: Optimized JSON outputs (--compact) to minimize LLM token usage while maximizing data density.
• 🎨 Rich UX: Beautifully formatted, color-coded tables for humans.
• 🔍 Advanced Filtering: Precision search with filters for condition, free shipping, Allegro Smart, and delivery speed.
• 📦 Full Tracking: Detailed package tracking beyond simple summaries.
• 🛡️ Bot Bypass: CloakBrowser (source-patched Chromium) defeats DataDome/Cloudflare with 58+ C++ fingerprint patches — no external solver needed.
• 🛠️ Extensible: Pure Python implementation, easy to integrate into larger automation pipelines.

🚀 Quick Start

Installation

From GitHub Releases (recommended):

pip install https://github.com/pkonowrocki/allegro-cli/releases/latest/download/allegro_cli-0.6.0-py3-none-any.whl

From source (latest):

pip install git+https://github.com/pkonowrocki/allegro-cli.git

Setup

To access personalized data (cart, packages), you need to provide your session cookies:

allegro login

Follow the prompt to paste your cookies from Chrome DevTools (Application $\rightarrow$ Cookies $\rightarrow$ allegro.pl).

📖 Usage

🔍 Search for Products

Find exactly what you need with advanced filters:

# Basic search
allegro search "kawa ziarnista"

# Power-user search: New, with Allegro Smart, delivered in 1 day, sorted by price ascending
allegro search "kawa ziarnista" --condition new --smart --delivery-time one_day --sort p

# Filter by custom criteria (e.g., specific brand or parameter)
allegro search "laptop" --filter "marka=Apple"

# Search on a specific seller's page
allegro search "kawa" --seller Muvepl

# Price range
allegro search "laptop" --price-min 1000 --price-max 3000

# Allegro Pay offers only
allegro search "iphone" --pay

Search Flags:

📦 Manage Your Shopping

Offers:

# Get full details and extracted product specifications
allegro offer 12345678

Cart:

allegro cart list                      # View current items
allegro cart add OFFER_ID              # Add item to cart (seller auto-detected)
allegro cart add OFFER_ID SELLER_ID    # Add item with explicit seller
allegro cart add OFFER_ID --quantity 3 # Add multiple units
allegro cart remove OFFER_ID           # Remove item from cart

Tracking:

allegro packages            # List all active shipments with detailed status

Claude Code Skill:

allegro skill               # Install as a Claude Code skill (auto-discovered by agents)

🤖 For AI Agents (LLM Optimization)

If you are building an AI agent, use the --format json and --compact flags. The compact mode strips unnecessary metadata to save tokens while keeping all critical data points — including the smart field that indicates Allegro Smart eligibility (free delivery).

allegro search "mechanical keyboard" --format json --compact

Compact search output includes: id, name, price, seller, url, smart Compact offer output includes: id, name, price, seller, url, smart, parameters

Allegro Smart

Allegro Smart! is a subscription (59.90 PLN/yr) giving unlimited free delivery on eligible offers above 49.90 PLN. The smart field in compact output shows whether an offer qualifies. Use --smart or --free-shipping to filter for Smart-eligible offers.

Install as a Claude Code Skill

To auto-register the CLI as a Claude Code skill (so AI agents discover it automatically):

allegro skill

🛠️ Development

# Install dev dependencies
pip install -e ".[dev]"

# Run the test suite (including Mock Client tests)
pytest

📜 License

Distributed under the MIT License. See LICENSE for more information.