Catalog CLI
Agent-native Amazon catalog auditing tool
The first AI-agent-friendly Amazon catalog analysis tool. Query your CLRs with structured input, integrate via MCP server, and automate catalog audits.
Want more? Check out Catalog Audit Pro for web-based audits, unlimited reports, and client-ready PDFs.
What's New in v2.0
- Shared core architecture - Business logic separated into
catalog/core/, powering both CLI and MCP - MCP server -
catalog mcplaunches a stdio MCP server with 4 tools, ready for Claude Desktop and any MCP client - JSON input -
--jsonand--stdinflags for structured agent input - Schema introspection -
catalog schema --format jsonreturns full request/response schemas - Field masks -
--fields sku,severity,detailsto reduce output size - Pagination -
--limitand--offsetfor controlling result size - NDJSON streaming -
--format ndjsonfor line-by-line streaming of large results - Input hardening - Pydantic validation rejects path traversal, injection, and malformed input
- Environment variables -
CATALOG_CLI_DEFAULT_FORMAT=jsonfor headless/CI use - Backward compatible - All v1.x commands work unchanged
Features
- Agent-Native - CLI + MCP server as equal citizens, JSON/NDJSON output, schema introspection
- Fast - Query 1000+ SKU catalogs in seconds
- Extensible - Plugin system for custom queries
- Comprehensive - 12 built-in catalog health checks
- RUFUS Optimized - Amazon AI shopping assistant bullet scoring
Installation
pip install amazon-catalog-cli
Or install from source:
git clone https://github.com/BWB03/amazon-catalog-cli.git
cd amazon-catalog-cli
pip install -e .
Quick Start
For Humans
# Run all catalog checks
catalog scan my-catalog.xlsx
# Detailed results
catalog scan my-catalog.xlsx --show-details
# Run specific check
catalog check rufus-bullets my-catalog.xlsx
# List available queries
catalog list-queries
For AI Agents
# JSON output with field mask and limit
catalog scan my-catalog.xlsx --format json --fields sku,severity,details --limit 20
# Structured JSON input
catalog scan --json '{"file": "my-catalog.xlsx", "queries": ["missing-attributes"], "limit": 10}'
# Piped input
echo '{"file": "my-catalog.xlsx"}' | catalog scan --stdin --format json
# NDJSON streaming for large results
catalog scan my-catalog.xlsx --format ndjson
# Schema introspection (discover queries, params, response shapes)
catalog schema --format json
MCP Server (for Claude Desktop, CLR Pro, etc.)
# Start MCP server
catalog mcp
Add to Claude Desktop config:
{
"mcpServers": {
"catalog": {
"command": "catalog",
"args": ["mcp"]
}
}
}
MCP tools: catalog_scan, catalog_check, catalog_list_queries, catalog_schema
Available Queries
Attribute Audits
- missing-attributes - Find mandatory attributes missing from listings
- missing-any-attributes - Find all missing attributes (required + conditional)
- new-attributes - Find unused template fields that might add value
Content Quality
- rufus-bullets - Score bullet points against Amazon's RUFUS AI framework
- bullet-prohibited-content - Find bullet points with prohibited chars, emojis, claims, or placeholders
- bullet-formatting - Check bullet formatting (capitalization, length, punctuation)
- bullet-awareness - Soft violations in bullets (excessive caps, problematic chars)
- long-titles - Find titles exceeding 200 characters
- title-prohibited-chars - Find titles with prohibited characters
- prohibited-chars - Find prohibited characters in title/brand
Catalog Structure
- product-type-mismatch - Find mismatched product types and item keywords
- missing-variations - Find products that should be variations but aren't
CLI Commands
catalog scan
Run all queries on a CLR file.
catalog scan <clr-file> [OPTIONS]
Options:
--format [terminal|json|csv|ndjson] Output format (default: terminal)
--output PATH Output file path
--show-details / --no-details Show detailed results
--include-fbm-duplicates Include FBM/MFN duplicates
--json TEXT JSON request body
--stdin Read JSON request from stdin
--queries TEXT Comma-separated query names
--fields TEXT Comma-separated field mask
--limit INTEGER Max issues to return
--offset INTEGER Skip first N issues
catalog check
Run a specific query.
catalog check <query-name> <clr-file> [OPTIONS]
Options:
--format [terminal|json|csv|ndjson] Output format (default: terminal)
--output PATH Output file path
--show-details / --no-details Show detailed results
--json TEXT JSON request body
--stdin Read JSON request from stdin
--fields TEXT Comma-separated field mask
--limit INTEGER Max issues to return
--offset INTEGER Skip first N issues
catalog schema
Show schema for queries, params, and response shapes.
catalog schema [query-name] [OPTIONS]
Options:
--format [terminal|json] Output format
catalog list-queries
List available queries.
catalog list-queries [OPTIONS]
Options:
--format [terminal|json] Output format
catalog mcp
Start the MCP server (stdio transport).
catalog mcp
Example JSON Output
{
"timestamp": "2026-03-05T10:30:00Z",
"marketplace": "US",
"is_us_marketplace": true,
"total_queries": 12,
"total_issues": 47,
"total_affected_skus": 23,
"results": [
{
"query_name": "missing-attributes",
"description": "Find mandatory attributes missing from listings",
"total_issues": 12,
"affected_skus": 8,
"issues": [
{
"row": 7,
"sku": "ABC-123",
"field": "brand",
"severity": "required",
"details": "Missing required field: brand",
"product_type": "HAIR_STYLING_AGENT",
"extra": {}
}
]
}
]
}
Agent Integration
Via CLI (subprocess)
import subprocess, json
result = subprocess.run(
['catalog', 'scan', 'my-catalog.xlsx', '--format', 'json',
'--fields', 'sku,severity,details', '--limit', '20'],
capture_output=True, text=True
)
data = json.loads(result.stdout)
Via Python (direct import)
from catalog.core import execute_scan, ScanRequest
request = ScanRequest(
file="my-catalog.xlsx",
queries=["missing-attributes", "rufus-bullets"],
fields=["sku", "severity", "details"],
limit=20,
)
response = execute_scan(request)
Via MCP
Add the MCP server to any MCP client (Claude Desktop, CLR Pro, etc.) and call catalog_scan, catalog_check, catalog_list_queries, or catalog_schema.
RUFUS Bullet Optimization
The rufus-bullets query evaluates bullet points against Amazon's RUFUS AI framework:
- Bullet 1: Should lead with Hero Benefit (why buy this?)
- Bullet 2: Should state who it's for (target audience)
- Bullet 3: Should differentiate (why this vs. competitors?)
- All bullets: Checked for specifics, length, vague marketing, ALL CAPS
Scores 1-5 with actionable suggestions.
Extending with Custom Queries
from catalog.query_engine import QueryPlugin
class MyCustomQuery(QueryPlugin):
name = "my-custom-check"
description = "My custom catalog check"
def execute(self, listings, clr_parser):
issues = []
for listing in listings:
if some_condition:
issues.append({
'row': listing.row_number,
'sku': listing.sku,
'field': 'FieldName',
'severity': 'warning',
'details': 'Issue description',
'product_type': listing.product_type
})
return issues
Requirements
- Python 3.10+
- openpyxl
- click
- rich
- pydantic
- mcp
How to Get Your CLR
- Go to Amazon Seller Central > Catalog > Category Listing Report
- Click Generate Report
- Download the
.xlsmor.xlsxfile - Run catalog CLI on it
Contributing
This is an open-source project. Contributions welcome!
- Add new query plugins
- Improve parsing logic
- Enhance output formats
- Build integrations
License
MIT License - Free to use, modify, and distribute.
Author
Built by Brett Bohannon (@BWB03)
Related Projects
- amazon-catalog-auditor-skill - OpenClaw skill for agent workflows
- clr-auditor - Original CLR auditing tool
- amazon-tool - Amazon variation creator
Agent-native Amazon catalog tool. Built for the future of catalog management.
Metadata
Release files for amazon-catalog-cli 2.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amazon_catalog_cli-2.1.1.tar.gz | 32.0 kB | Without provenance | Details for amazon_catalog_cli-2.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amazon_catalog_cli-2.1.1-py3-none-any.whl | Python 3 | none | any | Details for amazon_catalog_cli-2.1.1-py3-none-any.whl |
Total release size: 73.4 kB
Release files / amazon_catalog_cli-2.1.1.tar.gz
| Download URL | amazon_catalog_cli-2.1.1.tar.gz |
|---|---|
| Size | 32.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b15c09835be40cd65a91e2d4a7777ced4c3d24093eb622f018046a6e04f66278
|
|
BLAKE2b-256 checksum How to use checksums |
9337f4429b4f0f19f154a1f6b79bce7e09005f62af93f1a26f75592853af85a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / amazon_catalog_cli-2.1.1-py3-none-any.whl
| Download URL | amazon_catalog_cli-2.1.1-py3-none-any.whl |
|---|---|
| Size | 41.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b6cc7756da6ad3cdf5500204b1d28c58cb188d3106611d526ac5d6f2a855a0a
|
|
BLAKE2b-256 checksum How to use checksums |
88d275437a88ebb9e696bb88c8a3c9ec854c28f296fd2c0b6bbe6ec52199fa0e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for amazon-catalog-cli 2.1.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.