aads-cli

aads

CLI tool for analyzing Amazon Ads Sponsored Products campaign performance.

Reads Amazon Ads bulk sheet exports (Excel/CSV) and generates actionable optimization reports — CPC bid recommendations, auto-to-manual promotion candidates, negative keyword suggestions, and SEO ranking integration.

Features

Command	Description
analyze	Aggregate KPIs (CTR, CVR, ACOS, ROAS) from bulk sheet data
summary	Campaign structure overview with layer-level aggregation
cpc-report	CPC bid optimization report with optional SEO ranking integration
promotion-report	Auto-to-Manual promotion candidates + negative keyword suggestions
seo-report	SEO organic ranking vs ad keyword integrated report
generate	Generate Amazon Ads bulk sheet from analysis results
apply-actions	Apply action items (negative KW, keyword, placement) from JSON config
create-campaign	Generate campaign structure bulk sheet from template config
measure-log	Track advertising measures with timestamped notes
measure-compare	Compare before/after KPI snapshots for a measure

Installation

npm install -g aads-cli

Or use without installing:

npx aads --help

Quick Start

# Analyze a bulk sheet export
aads analyze --input "bulk-*.xlsx"

# Generate campaign structure summary
aads summary --input "bulk-*.xlsx"

# Generate CPC optimization report
aads cpc-report --input "bulk-*.xlsx" --output cpc-report.xlsx

# Generate promotion report
aads promotion-report --input "bulk-*.xlsx" --output promotion.xlsx

# Generate SEO-integrated report
aads seo-report --input "bulk-*.xlsx" --ranking-db ranking.db

# Generate bulk sheet for uploading to Amazon Ads
aads generate --input "bulk-*.xlsx" --output bulk-update.xlsx

# Generate only specific blocks (e.g., CPC + Negative keywords)
aads generate --input "bulk-*.xlsx" --output bulk-update.xlsx --blocks 2,4

# Apply action items from JSON config
aads apply-actions --config actions.json --output actions.xlsx

# Create new campaign structure from template
aads create-campaign --config campaign.json --output campaign.xlsx

# Track advertising measures
aads measure-log --add --pattern custom --name "Negative KW cleanup" --date 2026-03-08
aads measure-log --list

# Add notes to a measure
aads measure-log --id <entry-id> --note "ACOS improved 15% → 10%"

# Compare before/after KPIs
aads measure-compare --pattern custom --before "before-*.xlsx" --after "after-*.xlsx"

Commands

analyze

Aggregates campaign KPIs from Amazon Ads bulk sheet exports.

aads analyze --input <pattern> [--layer-policy <file>]

Option	Description
--input <pattern>	Input Excel/CSV path or wildcard pattern (required)
--layer-policy <file>	Campaign layer policy JSON path

summary

Displays campaign structure with ad group details and layer classification.

aads summary --input <pattern> [--layer-policy <file>]

cpc-report

Generates CPC bid optimization recommendations as an Excel report.

aads cpc-report --input <pattern> --output <file> [--ranking-db <path>]

Option	Description
--input <pattern>	Input Excel/CSV path or wildcard pattern (required)
--output <file>	Output xlsx path (required)
--ranking-db <path>	A_rank SQLite DB path for SEO-based CPC adjustment

promotion-report

Identifies auto campaign search terms ready for manual campaign promotion and suggests negative keywords for wasteful terms.

aads promotion-report --input <pattern> --output <file>

seo-report

Cross-references ad keywords with organic SEO ranking data to identify opportunities for bid reduction where organic rankings are strong.

aads seo-report --input <pattern> --ranking-db <path> [--output <file>] [--format <type>]

Option	Description
--input <pattern>	Input Excel/CSV path or wildcard pattern (required)
--ranking-db <path>	A_rank SQLite DB path (required)
--output <file>	Output file path
--format <type>	console | json | xlsx (default: console)

generate

Generates an Amazon Ads bulk sheet (V2.10 format, 27 columns) from analysis results. Runs the full analyze pipeline, then applies selected optimization blocks to produce rows ready for upload.

aads generate --input <pattern> --output <file> [--blocks <list>]

Option	Description
--input <pattern>	Input Excel/CSV path or wildcard pattern (required)
--output <file>	Output xlsx path (required)
--blocks <list>	Comma-separated block numbers to run (default: all)

Available Blocks:

Block	Name	Description
1	Budget	Campaign daily budget adjustments
2	CPC	Keyword bid updates based on ACOS optimization
3	Promotion	Auto-to-Manual keyword promotion (create in manual campaign)
3.5	Negative Sync	Add negative keywords in auto campaign for promoted terms
4	Negative	Negative keywords for wasteful search terms
5	Placement	Placement bid modifier adjustments (Top of Search / Product Pages)

apply-actions

Applies action items from a JSON config to generate a bulk sheet for batch operations — negative keywords, keyword additions, product targeting, and placement adjustments.

aads apply-actions --config <file> --output <file>

Option	Description
--config <file>	Action items JSON config path (required)
--output <file>	Output xlsx path (required)

Supported action types:

Type	Description
negative_keyword	Add negative keyword (ad group or campaign level)
negative_product_targeting	Add negative product targeting (ASIN)
keyword	Add keyword with bid
placement	Adjust placement bid percentage

See data/samples/action-items-sample.json for config format.

create-campaign

Generates campaign structure from a template config. Supports new campaign creation and existing campaign updates.

aads create-campaign --config <file> --output <file> [--mode <create|update>] [--input <file>]

Option	Description
--config <file>	Campaign template JSON config path (required)
--output <file>	Output xlsx path (required)
--mode <mode>	create (default) or update
--input <file>	SC bulk sheet for update mode ID resolution

Campaign types: auto, phrase, broad, asin, manual

Campaign and ad group names are customizable via naming in the config:

{
  "naming": {
    "campaignTemplate": "{brand}_{typeLabel}_{suffix}",
    "adGroupTemplate": "{code}_{descriptor}"
  }
}

See data/samples/campaign-template-sample.json for full config format.

measure-log

Track advertising measures (campaign changes, optimizations) as a log with timestamped notes. Data is stored in ./data/measure-log.json in your working directory.

aads measure-log --list [--format <type>] [--status <status>] [--pattern <id>]
aads measure-log --add --pattern <id> --name <text> --date <yyyy-mm-dd> [--note <text>]
aads measure-log --remove <id>
aads measure-log --id <entry-id> --note <text>

Option	Description
--list	List all entries
--add	Add a new entry
--remove <id>	Remove an entry
--id <entry-id>	Target entry ID (for --note)
--note <text>	Add a note (standalone with --id, or initial note with --add)
--pattern <id>	Measure pattern ID
--name <text>	Measure name
--date <yyyy-mm-dd>	Measure execution date
--status <status>	pending | completed
--format <type>	console | json | markdown (default: console)

measure-compare

Compare before/after KPI snapshots for a measure to evaluate its effectiveness.

aads measure-compare --pattern <id> --before <pattern> --after <pattern> [options]

Option	Description
--pattern <id>	Measure pattern ID
--log-id <id>	Resolve pattern and metadata from measure-log entry
--before <pattern>	Before input file path or wildcard (required)
--after <pattern>	After input file path or wildcard (required)
--campaigns <list>	Comma-separated campaign IDs or names to filter
--asins <list>	Comma-separated ASINs to filter
--name <text>	Measure name
--description <text>	Measure description
--with-llm	Run LLM analysis (requires API key)

Configuration

Configuration is done via environment variables (or a .env file):

Variable	Default	Description
TARGET_ACOS	0.25	Target ACOS for CPC optimization
MIN_CLICKS_CPC	5	Minimum clicks for CPC recommendation
MIN_CLICKS_PROMOTION	5	Minimum clicks for promotion candidate
MIN_CVR_PROMOTION	0.03	Minimum CVR for promotion candidate
NEGATIVE_ACOS_THRESHOLD	0.4	ACOS threshold for negative keyword suggestion
SEO_ENABLED	true	Enable SEO ranking integration
SEO_CPC_CEILING	0	CPC ceiling (0 = auto)
RANKING_DB_PATH	-	Default path to A_rank SQLite DB
LOG_LEVEL	info	Log level (debug | info)

See .env.example for a complete template.

SEO Integration

The cpc-report and seo-report commands can integrate with SEO ranking data stored in a SQLite database.

When an ad keyword has strong organic ranking (positions 1-4), the tool automatically reduces the recommended CPC bid:

Organic Position	SEO Factor	Bid Reduction
#1	0.50	-50%
#2	0.60	-40%
#3	0.70	-30%
#4	0.80	-20%
#5+	1.00	No change

Getting Started with SEO Data

A sample database with dummy data is included for testing:

aads seo-report --input bulk-sheet.xlsx --ranking-db data/sample-ranking.db

To use your own data, create a SQLite database matching the database schema. You can populate it from any source — a custom scraper, third-party API, or manual entry.

Coming soon: A companion Chrome extension for automatically collecting Amazon search ranking data will be released as a separate open-source project.

Campaign Layer Policy

The analyze and summary commands support campaign layer classification using a JSON policy file:

aads summary --input "bulk-*.xlsx" --layer-policy data/campaign-layer-policy.json

See data/campaign-layer-policy.json for the default policy structure.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT