Command-Line Tools & Automation Suite

Comprehensive interactive guide for all operational tools, background scrapers, catalog seeding pipelines, and API key management utilities under calpamos.cli.

Global CLI Command (Auto-resolves virtualenv): calpamos --help
SERVER calpamos serve
Runs the production Uvicorn ASGI server powering the REST API, Server-Sent Events (SSE) price streams, and Swagger UI.
OptionTypeDefaultDescription
--hoststring0.0.0.0Network interface to bind
--portinteger8000TCP port to listen on
--reloadflagfalseEnable auto-reload on code modifications
Command Line
calpamos serve --host 0.0.0.0 --port 8000
TUI calpamos monitor
Launches the Bloomberg-style interactive terminal decision cockpit and real-time market monitor built with Textual and Rich. Provides an all-in-one single-screen buy/no-buy investment decision dashboard for any given LEGO set ID, featuring a high-density sub-pixel Braille spark-matrix price trajectory chart, Part-Out Value (POV) minifigure arbitrage breakdown, live connected retailer inventory, and autonomous refresh scheduler sentinels with live countdowns.
Argument / FlagTypeDefaultDescription
item_nostring75192-1Canonical or bare LEGO set number (e.g. 75192, 10307, 75389)
--country, -cchoiceAETarget regional market country code: AE (UAE / AED) or US (USA / USD)
Command Line Examples
calpamos monitor 75192
calpamos monitor 10333 --country US
calpamos monitor
SYSTEM calpamos status
Diagnostic utility verifying SQLite WAL connectivity, table sizes across all retail source tables, catalog count, and active ScrapingBee credit balances. Supports --detailed to trigger a full fleet health audit.
Argument / FlagTypeDefaultDescription
-d, --detailedflagfalseDisplay detailed multi-section fleet health check and execution audit ledger (delegates to health)
-H, --hoursinteger24Historical lookback window in hours for telemetry audit
--jsonflagfalseOutput status telemetry payload as structured JSON
Command Line Examples
calpamos status
calpamos status --detailed
calpamos status --json
AUDIT calpamos health
Runs a comprehensive operational health check, fleet cadence matrix, daemon telemetry (calpamos-scheduler & calpamos-api), live stock fill rates, automated integration anomaly detection (FLEET_ANOMALY_WATCHDOG), and execution audit ledger across all background sweepers. Adheres strictly to the Cyberpunk VT220 Terminal Aesthetic.
Argument / FlagTypeDefaultDescription
-H, --hoursinteger24Historical lookback window in hours for sweep history, valuation velocity, and inventory metrics
-s, --sourcestringnullFilter health check to a specific source or market ID (e.g. firstcry, lego_me, toycorner)
-d, --detailedflagfalseExpand execution audit ledger to 25 items and display full itemized rows
--jsonflagfalseOutput complete fleet health and audit telemetry payload as structured JSON
Command Line Examples
calpamos health
calpamos health --source firstcry --hours 12
calpamos health --detailed
calpamos health --json
SECURITY calpamos keys
Manages subscriber API keys, plan entitlements (buyer, collector, pro), revocations, and the aggregated utilization ledger.
Argument / FlagTypeDefaultDescription
actionchoicelistcreate, list, revoke, or usage
--userstringnullSubscriber email or unique account ID (Required for create)
--planchoicecollectorPlan entitlement: buyer, collector, or pro
--daysintegernullValidity period in days (omitted = lifetime)
--providerstringmanualProvider tag: manual, revenuecat, app_store, google_play
Command Line Examples
calpamos keys create --user power_user@example.com --plan pro
calpamos keys usage
calpamos keys list
DAEMON calpamos scheduler
Controls the autonomous background refresh loop, watchdog, and execution history. Updates buyable retail prices, catalog synchronization, and BrickLink secondary depth. Supports 5-minute stagger schedule alignment (align / stagger) to protect ScrapingBee concurrency limits, execution audit trail queries (history / audit) with failure filtering, per-source interval tuning, setting job status (DISABLED, PAUSED, IDLE), and removing or registering scheduled entries.
Argument / FlagTypeDefaultDescription
actionchoicestatusstatus, align, stagger, history, audit, run, start, alter, remove, or add
sourcechoicenullTarget: lego_me, firstcry, borders, centrepoint, mumzworld, alab, noon, carrefour, amazon_ae, toycorner, virginmegastore, kinokuniya, littlethings, jarir, brandsforless, lego_us, target_us, barnesandnoble_us, booksamillion_us, amazon_us, walmart_us, bricklink_enrich, catalog_sync, or all
--limitinteger20Max execution history records to display (for history / audit)
--failedflagfalseFilter history to only show failed runs and HTTP / scrape error reasons
--intervalfloatnullCycle frequency in hours (e.g. 12, 6, 0.5)
--interval-secondsintegernullCycle frequency in seconds (e.g. 43200)
--statuschoicenullExecution state: IDLE, DISABLED, PAUSED, SUCCESS, FAILED
--next-runstringnullNext trigger timestamp (YYYY-MM-DD HH:MM:SS or now)
Command Line Examples
calpamos scheduler status
calpamos scheduler align
calpamos scheduler history catalog_sync --limit 10
calpamos scheduler history --failed
calpamos scheduler alter borders --interval 12
calpamos scheduler alter amazon_ae --status DISABLED
calpamos scheduler remove catalog_sync
calpamos scheduler add catalog_sync --interval 24
TELEMETRY calpamos enrichment-report
Telemetry dashboard reporting BrickLink API quota consumption (5,000/day limit), ScrapingBee proxy pool health, and liquidity tier distribution across sets.
Command Line
calpamos enrichment-report
INTELLIGENCE calpamos demand
Executive buyer demand intelligence analyzing high-frequency user search volume from application logs, correlated with canonical catalog metadata and active 30-day market price fluctuations (increases, retail discounts, trends).
Argument / FlagTypeDefaultDescription
actionstringsummaryReport view: summary (default), top, gainers, drops, themes
--limitintegerNoneNumber of sets to return (default: 100 for top, 20 for summary, 25 for gainers/drops)
--themestringNoneFilter sets by specific theme (e.g. Star Wars, Icons, Ideas)
--daysinteger30Historical price lookback window in days
--jsonflagfalseOutput structured telemetry payload as raw JSON
--syncflagfalseSynchronize metrics directly into OpenObserve calpamos_buyer_demand stream
Command Line Snippet
calpamos demand
AUDIT calpamos gaps
Audits catalog data completeness across liquidity tiers (Tiers 1–4) and individual sets, surfacing key gaps such as missing official MSRP benchmarks, missing manufacturer barcodes (EAN-13 / UPC-12), lack of active retail price signals, and missing set artwork. Automatically resolves theme names (e.g. STARWARS → Star Wars), diagnoses non-retail sets (GWP, Promotional, Polybag) and multi-set retailer-exclusive bundles (e.g. Walmart, Costco, Target exclusives), and renders a Targeted Record Repair Guide with exact bulk and single-set CLI remediation commands.
Argument / FlagTypeDefaultDescription
targetstringNoneSpecific set number (e.g. 71043) or liquidity tier (1–4) to audit (optional positional)
--tierstringNoneFilter by liquidity tier: 1, 2, 3, 4, or all (default: Tier 1 for drilldowns)
--missingchoiceNoneFilter by missing dimension: all, msrp, barcode, market, image
--themestringNoneFilter sets by LEGO theme; supports case-insensitive and unspaced inputs (e.g. STARWARS, Star Wars)
--yearintegerNoneFilter sets by release year (e.g. 2025, 2024)
--countrystringNoneFilter market valuation checks by country code (US, AE, ALL)
--limitinteger25Number of sets to return in drilldown table
--jsonflagfalseOutput structured audit telemetry payload as raw JSON
Command Line Snippets
calpamos gaps --theme STARWARS --tier 2
calpamos gaps --tier 1 --missing msrp
calpamos gaps 71043
ON-DEMAND calpamos scrape
Triggers an immediate live scrape for a specific LEGO set number across all retail marketplaces and BrickLink secondary depth.
Argument / FlagTypeDefaultDescription
item_nostringrequiredCanonical (e.g. 75192-1) or bare (e.g. 75192) set number
--sourcechoiceallSpecific marketplace or all
Command Line
calpamos scrape 75192 --source bricklink
BULK calpamos sweep
Runs a concurrent asynchronous sweep against a target retailer to discover newly listed sets, price drops, and stock updates.
Argument / FlagTypeDefaultDescription
sourcechoicerequiredborders, firstcry, lego_me, amazon_ae, alab, mumzworld, centrepoint, noon, carrefour, toycorner, virginmegastore, kinokuniya, littlethings, jarir, brandsforless, lego_us, target_us, barnesandnoble_us, booksamillion_us, amazon_us, walmart_us
--concurrencyinteger4Concurrent async scraper workers
--limitintegernullMaximum sets to process
--themestringnullFilter sweep by theme name (e.g. 'Star Wars')
Command Line
calpamos sweep borders --concurrency 6 --limit 200
INSPECT calpamos inspect
Terminal inspector rendering historical price signals, store stock, and raw source records directly from SQLite without invoking the HTTP API. Supports regional country filtering (US, AE, ALL). Automatically detects multi-variant sibling sequence numbers (e.g. 75188-1, -2, -3), renders a Rich status roster (OBSOLETE, ★ GRAIL, ACTIVE), and auto-inspects the primary active release.
Argument / FlagTypeDefaultDescription
item_nostringrequiredBare (e.g. 75188), canonical (e.g. 75188-2), or barcode
countrystringnullTarget market country code (US, AE, ALL; optional positional argument)
--countrystringnullTarget country code flag alias (US, AE, ALL)
--daysinteger30Historical lookback window in days
--jsonflagfalseOutput results as structured JSON
Command Line Examples
calpamos inspect 76345 US
calpamos inspect 75188 --days 30
INTELLIGENCE calpamos trend
Renders a visual price intelligence report anchored to Brickset Global US MSRP and official retail anchors. Supports multi-market country targeting (US, AE, ALL), dynamically switching native currencies (USD for US, AED for AE), benchmarking connected retailers (LEGO Store US, Target US vs LEGO Certified Store UAE, Amazon UAE, Noon), 2x4 sub-pixel Braille curves, stepped 1/8th sparklines with flat mid-lines, Part-Out Value (POV) minifigure equity buffers, normalized distribution bars with stock/seller badges, BrickLink secondary depth, and per-retailer LAG() price delta tracking.
Argument / FlagTypeDefaultDescription
item_nostringrequiredBare (e.g. 76345) or canonical set number (e.g. 76345-1)
countrystringAETarget market country code (US, AE, ALL; optional positional argument)
--countrystringnullTarget country code flag alias (US, AE, ALL)
--daysinteger30Historical lookback window in days (use 0 for all available history)
--sourcestringallFilter by source (lego_us, target_us, lego_me, amazon_ae, etc. or all)
--widthinteger52Horizontal column width of Braille trend plot (default: 52)
--heightinteger9Vertical row height of Braille trend plot
--jsonflagfalseOutput trend analytics, arbitrage, and chart as structured JSON
Command Line Examples
calpamos trend 76345 US
calpamos trend 75192 --country US
calpamos trend 76178
calpamos trend 42172 US --days 60 --width 52 --height 12
STREAMING calpamos poll
Polls newly recorded market valuations since a given ISO timestamp, or connects directly to the live Server-Sent Events (SSE) market ticker stream.
Argument / FlagTypeDefaultDescription
--sincestringnullISO timestamp to poll valuations since (e.g. 2026-09-27 12:00:00)
--liveflagfalseConnect to live SSE ticker stream (/v1/stream/market-ticker)
--hoststring127.0.0.1API server hostname or IP address
--portinteger8000API server port
Command Line Examples
calpamos poll --live
calpamos poll --since "2026-09-27 12:00:00"
CATALOG calpamos themes
Explores active canonical LEGO retail themes from Brickset with release years, piece distributions, set counts, and automated Amazon search query mappings.
Argument / FlagTypeDefaultDescription
--yearsinteger5Lookback window in years for active themes (default: 5)
Command Line
calpamos themes --years 5
CATALOG calpamos seed-catalog
Performs targeted single-set enrichment or bulk seeding of canonical catalog sets, release years, piece counts, manufacturer MSRPs, and retail barcodes (EAN-13 / UPC-12) from Brickset into catalog_sets.
Argument / FlagTypeDefaultDescription
targetstringnullTarget specific set number (e.g. 71043) to seed directly
--setstringnullExplicit flag to seed a specific set number
--start-yearinteger2021Starting release year for bulk ingest
--end-yearinteger2026Ending release year for bulk ingest
Command Line Examples
calpamos seed-catalog 71043
calpamos seed-catalog --start-year 2018 --end-year 2018
CATALOG calpamos sync-catalog
Downloads and ingests daily gzipped database dumps from Rebrickable and BrickLink into raw staging tables.
Argument / FlagTypeDefaultDescription
--sourcechoiceallTarget catalog source: all, rebrickable, or bricklink
Command Line
calpamos sync-catalog --source all
CATALOG calpamos promote-staging
Promotes reconciled catalog sets from staging_catalog_sets view into operational catalog_sets table.
Argument / FlagTypeDefaultDescription
--yearintegernullTarget specific release year (e.g. 2026)
--dry-runflagfalseSimulate promotion without writing to database
--overwrite-namesflagfalseOverwrite existing names with canonical catalog titles
Command Line
calpamos promote-staging --year 2026 --dry-run
PIPELINE calpamos hydrate
Core catalog hydration pipeline. Decomposes sets into constituent minifigures via BrickLink Subsets API and scrapes 4-quadrant secondary market valuations for an entire release year.
Argument / FlagTypeDefaultDescription
--yearinteger2026Target release year
--limitintegernullLimit number of sets to process (pilot runs)
--concurrencyinteger4ScrapingBee worker concurrency pool
--skip-valuationsflagfalseOnly map minifigures (consumes 0 ScrapingBee credits)
--skip-minifigsflagfalseSkip minifigure valuations scrape
Command Line
calpamos hydrate --year 2026 --concurrency 4
POV / ARBITRAGE calpamos arbitrage
Audits Minifigure Part-Out Value (POV) and +EV retail arbitrage opportunities. Connects constituent figures from set_minifigures with BrickLink 6-month historical sales averages, comparing total figure market value against live retail set prices and MSRP.
Argument / FlagTypeDefaultDescription
targetstringnullSpecific set number (e.g. 75383) or theme to inspect
--themestringnullFilter sets by canonical LEGO theme
--countrystringnullTarget country market for live retail pricing (US, AE, ALL)
--min-ratiofloat70.0Minimum POV ratio percentage threshold (minifig value / set cost * 100)
--buyable-onlyflagfalseOnly include sets with live in-stock retail store offers
--limitinteger25Maximum number of sets to display in ranking table
--jsonflagfalseOutput structured JSON telemetry payload
Command Line
calpamos arbitrage 75383
DEALS / FLOOR calpamos discounts
Monitors cross-retailer discounts, all-time lows (ATL), and historical price floor proximity. Evaluates live prices against historical price distributions to verify authentic markdowns vs MSRP.
Argument / FlagTypeDefaultDescription
targetstringnullSpecific set number (e.g. 75192) or theme to inspect
--themestringnullFilter sets by canonical LEGO theme
--countrystringnullFilter by country market code (US, AE, ALL)
--storestringnullFilter by specific retailer source (e.g. amazon_ae, lego_me)
--min-discountfloat15.0Minimum percentage discount vs official MSRP
--floor-onlyflagfalseOnly show offers within 5% of their recorded historical all-time low
--in-stockflagfalseOnly show deals confirmed in-stock at retailer (excludes out-of-stock listings)
--limitinteger25Maximum number of discount opportunities to display
--jsonflagfalseOutput structured JSON telemetry payload
Command Line
calpamos discounts --floor-only --min-discount 20
CONTRACT SENTINEL calpamos drift
Continuous contract verification and drift detection engine for retail scraper profiles (Calpamos Drift Sentinel Framework v3.2.0). Executes single-page non-destructive probes to validate transport connectivity, WAF perimeter bypass, structural container stability, schema key drift, semantic data yields, and catalog disambiguation.
Argument / FlagTypeDefaultDescription
targetstringnullTarget market identifier to probe (e.g. carrefour, alab, noon)
--allflagfalseRun continuous probe sweep across all 17 registered retail target profiles
--listflagfalseDisplay summary table of registered target profiles and latest audit rows
--sample-sizeinteger20Maximum number of sample items evaluated for semantic quality metrics
--timeoutfloat15.0Network probe transport timeout in seconds
--no-auditflagfalseSkip appending verification row to target profile markdown audit history
--reportflagfalseGenerate and export exhaustive Markdown drift audit report to logs/
--jsonflagfalseOutput structured Drift Summary JSON payload to stdout
Command Line
calpamos drift --all --report