io.github.BWB03/catalog-cli-pro

Official

by BWB03 · Python

Amazon catalog auditing tool. 13 quality checks for your listings.

Audit Amazon product listings with 13 automated quality checks.

README.md12 KBView on GitHub

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.

Hosted API available at api.catalogcli.com — persistent storage, unlimited scans, and API access for $9.99/mo. Learn more

What's New in v2.2

Amazon title readiness - New mobile-title-readiness check flags titles over 75 characters for Amazon's mobile title update
Rewrite-ready output - Returns first-75-character title segments, overflow text, significant terms, item highlight status, and recommended next actions
Agent workflow friendly - Aliases title-75 and amazon-title-75 make it easy to call from Claude, MCP clients, and automation workflows
14 built-in checks - Adds a new title triage workflow while keeping the classic 200-character long-titles check unchanged

v2.0 Agent Foundations

Shared core architecture - Business logic separated into catalog/core/, powering both CLI and MCP
MCP server - catalog mcp launches a stdio MCP server with 4 tools, ready for Claude Desktop and any MCP client
JSON input - --json and --stdin flags for structured agent input
Schema introspection - catalog schema --format json returns full request/response schemas
Field masks - --fields sku,severity,details to reduce output size
Pagination - --limit and --offset for controlling result size
NDJSON streaming - --format ndjson for line-by-line streaming of large results
Input hardening - Pydantic validation rejects path traversal, injection, and malformed input
Environment variables - CATALOG_CLI_DEFAULT_FORMAT=json for 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 - 14 built-in catalog health checks
Intent Optimized - COSMO-inspired shopper intent coverage for bullets

Installation

bash

pip install amazon-catalog-cli

Or install from source:

bash

git clone https://github.com/BWB03/amazon-catalog-cli.git
cd amazon-catalog-cli
pip install -e .

Quick Start

For Humans

bash

# Run all catalog checks
catalog scan my-catalog.xlsx

# Detailed results
catalog scan my-catalog.xlsx --show-details

# Run specific check
catalog check intent-bullets my-catalog.xlsx

# Audit titles for Amazon's 75-character mobile title update
catalog check mobile-title-readiness my-catalog.xlsx

# List available queries
catalog list-queries

For AI Agents

bash

# JSON output with field mask and limit
catalog scan my-catalog.xlsx --format json --fields sku,severity,details --limit 20

# Title rewrite triage for agents
catalog check mobile-title-readiness my-catalog.xlsx --format json \
  --fields sku,details,title_char_count,mobile_visible_title,overflow_title,all_significant_terms

# 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.)

bash

# Start MCP server
catalog mcp

Add to Claude Desktop config:

json

{
  "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

intent-bullets - Score bullet points against shopper intent coverage
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)
mobile-title-readiness - Find titles over 75 characters and prepare rewrite inputs
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.

bash

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.

bash

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.

bash

catalog schema [query-name] [OPTIONS]

Options:
  --format [terminal|json]  Output format

`catalog list-queries`

List available queries.

bash

catalog list-queries [OPTIONS]

Options:
  --format [terminal|json]  Output format

`catalog mcp`

Start the MCP server (stdio transport).

bash

catalog mcp

`catalog setup-claude`

Configure Claude Code to use Catalog CLI as an MCP tool server.

bash

# Free (local) — data stays on your machine
catalog setup-claude

# Pro (hosted API) — persistent storage, unlimited scans
catalog setup-claude --pro --api-key YOUR_KEY

# Per-project instead of global
catalog setup-claude --project

After setup, restart Claude Code and try: "Scan my-catalog.xlsx and tell me the biggest issues"

Example JSON Output

json

{
  "timestamp": "2026-03-05T10:30:00Z",
  "marketplace": "US",
  "is_us_marketplace": true,
  "total_queries": 14,
  "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)

python

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)

python

from catalog.core import execute_scan, ScanRequest

request = ScanRequest(
    file="my-catalog.xlsx",
    queries=["missing-attributes", "intent-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.

Intent-Based Bullet Optimization

The intent-bullets query evaluates bullet points against COSMO-inspired shopper intent coverage:

Audience / need fit: Who it is for, preferences, or problem state
Function / use case: The job, activity, event, or use flow
Context / compatibility: Where, when, or what it works with
Decision evidence: Specs, attributes, trust signals, or differentiators
All bullets: Checked for intent coverage, length, vague marketing, ALL CAPS

Scores 1-5 with actionable suggestions. The old rufus-bullets query name still works as a deprecated compatibility alias.

Extending with Custom Queries

python

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 .xlsm or .xlsx file
Run catalog CLI on it

Free vs Pro

	Open Source CLI	Free API	Pro API ($9.99/mo)
14 quality audits	Yes	Yes	Yes
Scans	Unlimited (local)	2 lifetime	Unlimited
Catalogs stored	—	1	Unlimited
Results persistence	—	7 days	Permanent
API access	—	Yes	Yes
Rate limit	—	10 req/min	100 req/min
Claude Code integration	Local MCP	—	Hosted MCP
Variation Creator	—	—	Coming soon

Get started at catalogcli.com | API Docs

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)

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.

Install

Configuration

Environment variables

CATALOG_API_KEYrequiredsecret

Your Catalog CLI Pro API key. Get one free at catalogcli.com/signup

claude_desktop_config.json

{
  "mcpServers": {
    "catalog-cli-pro": {
      "command": "npx",
      "args": [
        "-y",
        "@bwb03/catalog-cli-pro@1.0.0"
      ],
      "env": {
        "CATALOG_API_KEY": "<YOUR_CATALOG_API_KEY>"
      }
    }
  }
}

Catalog CLI

What's New in v2.2

v2.0 Agent Foundations

Features

Installation

Quick Start

For Humans

For AI Agents

MCP Server (for Claude Desktop, CLR Pro, etc.)

Available Queries

Attribute Audits

Content Quality

Catalog Structure

CLI Commands

catalog scan

catalog check

catalog schema

catalog list-queries

catalog mcp

catalog setup-claude

Example JSON Output

Agent Integration

Via CLI (subprocess)

Via Python (direct import)

Via MCP

Intent-Based Bullet Optimization

Extending with Custom Queries

Requirements

How to Get Your CLR

Free vs Pro

Contributing

License

Author

Related Projects

Install

Configuration

`catalog scan`

`catalog check`

`catalog schema`

`catalog list-queries`

`catalog mcp`

`catalog setup-claude`