Description

Amazon Ads data retrieval and reporting via amazon-ads-open-cli. Use when the user wants to check Amazon ad performance, pull Sponsored Products/Brands/Displ...

README (SKILL.md)

Amazon Ads CLI Skill

Name: Amazon Ads CLI
Author: bin-huang

You have access to amazon-ads-open-cli, a read-only CLI for the Amazon Advertising API (v2/v3). Use it to list advertising profiles, inspect Sponsored Products/Brands/Display campaigns and their hierarchy, browse DSP orders and creatives, manage audiences, and request async performance reports across Amazon marketplaces.

Quick start

# Check if the CLI is available
amazon-ads-open-cli --help

# List advertising profiles (marketplaces)
amazon-ads-open-cli profiles

# List Sponsored Products campaigns
amazon-ads-open-cli sp-campaigns

If the CLI is not installed, install it:

npm install -g amazon-ads-open-cli

Authentication

The CLI requires an Amazon OAuth2 access token and client ID from a Login with Amazon app. Credentials are resolved in this order:

--credentials \x3Cpath> flag (per-command) -- reads the specified JSON file
Auto-detected file: ~/.config/amazon-ads-open-cli/credentials.json
Environment variables: AMAZON_ADS_ACCESS_TOKEN + AMAZON_ADS_CLIENT_ID

Note: when a credentials file is found (either via --credentials or at the default path), its profile_id can be overridden by the AMAZON_ADS_PROFILE_ID environment variable if the file does not contain one. If the credentials file is not found or does not contain valid access_token + client_id, the CLI falls through to environment variables.

The credentials JSON file format:

{
  "access_token": "your_access_token",
  "client_id": "your_client_id",
  "profile_id": "your_profile_id"
}

Environment variables:

AMAZON_ADS_ACCESS_TOKEN -- OAuth2 access token
AMAZON_ADS_CLIENT_ID -- Login with Amazon client ID
AMAZON_ADS_PROFILE_ID -- marketplace profile ID (required for most commands)

Before running any command, verify credentials are configured by running amazon-ads-open-cli profiles. If it fails with a credentials error, ask the user to set up authentication.

Most commands require a profile ID (marketplace-specific). Use the profiles command first to discover profile IDs, then set AMAZON_ADS_PROFILE_ID.

Entity hierarchy

Profile (marketplace: US, UK, DE, JP, etc.)
 +-- Sponsored Products
 |    +-- Campaign -> Ad Group -> Product Ad / Keyword / Target
 +-- Sponsored Brands
 |    +-- Campaign -> Ad Group -> Keyword / Target
 +-- Sponsored Display
 |    +-- Campaign -> Ad Group -> Product Ad / Target
 +-- DSP (programmatic)
      +-- Advertiser -> Order -> Line Item -> Creative
      +-- Audience (configured at Line Item level)

Output format

All commands output pretty-printed JSON (2-space indent) by default. Use --format compact for single-line JSON (useful for piping).

Global options available on every command:

--format \x3Cformat> -- output format: json (default) or compact
--credentials \x3Cpath> -- path to credentials JSON file

All listing commands support offset-based pagination via --start-index and --count parameters.

Commands reference

Profiles

# List all advertising profiles (marketplaces) -- no profile ID required
amazon-ads-open-cli profiles

# Get a specific profile -- no profile ID required
amazon-ads-open-cli profile 1234567890

The profiles and profile commands do not require AMAZON_ADS_PROFILE_ID to be set. All other commands do.

Performance reports (async)

Reports are requested asynchronously. You submit a report request and receive a report ID, then poll for completion.

Report status

# Check report status and get download URL
amazon-ads-open-cli report-status amzn1.report.abc123

The response includes the report status and, when complete, a download URL. Poll this command until the status indicates the report is ready.

DSP orders

# List DSP orders (programmatic display/video)
amazon-ads-open-cli dsp-orders
amazon-ads-open-cli dsp-orders --start-index 0 --count 50

# Get a specific DSP order
amazon-ads-open-cli dsp-order 123456

Options for dsp-orders:

--start-index \x3Cn> -- start index for pagination (default 0)
--count \x3Cn> -- results per page (default 100)

DSP commands use the v3 API endpoint.

DSP line items

# List DSP line items
amazon-ads-open-cli dsp-line-items
amazon-ads-open-cli dsp-line-items --order-id 123456

Options for dsp-line-items:

--order-id \x3Cid> -- filter by order ID
--start-index \x3Cn> -- start index for pagination (default 0)
--count \x3Cn> -- results per page (default 100)

DSP creatives

# List DSP creatives
amazon-ads-open-cli dsp-creatives
amazon-ads-open-cli dsp-creatives --start-index 0 --count 50

Options for dsp-creatives:

--start-index \x3Cn> -- start index for pagination (default 0)
--count \x3Cn> -- results per page (default 100)

Audiences

# List DSP audiences
amazon-ads-open-cli audiences
amazon-ads-open-cli audiences --start-index 0 --count 50

# Get a specific audience
amazon-ads-open-cli audience 123456

Options for audiences:

--start-index \x3Cn> -- start index for pagination (default 0)
--count \x3Cn> -- results per page (default 100)

Brand safety

# List brand safety deny lists
amazon-ads-open-cli brand-safety-lists

The brand-safety-lists command has no pagination options. It returns all deny lists.

Workflow guidance

When the user asks for an account overview

Run amazon-ads-open-cli profiles to discover accessible marketplaces
Set the desired profile ID, then list campaigns across ad types:
- amazon-ads-open-cli sp-campaigns --state enabled
- amazon-ads-open-cli sb-campaigns --state enabled
- amazon-ads-open-cli sd-campaigns --state enabled
Present campaign counts and statuses

When the user asks for performance data

Use report commands to request async reports:
- amazon-ads-open-cli sp-report --record-type campaigns --start-date YYYYMMDD
Poll with amazon-ads-open-cli report-status \x3Creport-id> until complete
Download and present the report data from the returned URL

When the user asks about campaign structure

List campaigns: amazon-ads-open-cli sp-campaigns
Drill into ad groups: amazon-ads-open-cli sp-adgroups --campaign-id \x3Cid>
Inspect ads: amazon-ads-open-cli sp-ads --adgroup-id \x3Cid>
Review keywords: amazon-ads-open-cli sp-keywords --adgroup-id \x3Cid>
Check targets: amazon-ads-open-cli sp-targets --adgroup-id \x3Cid>

When the user asks about keyword performance

List keywords: amazon-ads-open-cli sp-keywords --campaign-id \x3Cid>
Check negative keywords: amazon-ads-open-cli sp-negative-keywords --campaign-id \x3Cid>
Request a keyword-level report: amazon-ads-open-cli sp-report --record-type keywords --start-date YYYYMMDD

When the user asks about DSP/programmatic

List orders: amazon-ads-open-cli dsp-orders
Drill into line items: amazon-ads-open-cli dsp-line-items --order-id \x3Cid>
Review creatives: amazon-ads-open-cli dsp-creatives
Check audiences: amazon-ads-open-cli audiences
Review brand safety: amazon-ads-open-cli brand-safety-lists

When the user wants to compare ad types

Pull campaigns for each type side by side:
- amazon-ads-open-cli sp-campaigns --state enabled
- amazon-ads-open-cli sb-campaigns --state enabled
- amazon-ads-open-cli sd-campaigns --state enabled
Request reports for each type with the same date range
Compare metrics across Sponsored Products, Brands, and Display

Error handling

"No credentials found" -- ask the user to set AMAZON_ADS_ACCESS_TOKEN + AMAZON_ADS_CLIENT_ID env vars, or create ~/.config/amazon-ads-open-cli/credentials.json
"Profile ID required" -- the command needs AMAZON_ADS_PROFILE_ID. Run profiles first to discover available profile IDs
HTTP 401 -- access token is expired or invalid; ask the user to refresh their OAuth token
HTTP 403 -- the profile may not have access to the requested resource, or the API scope is insufficient
"Unknown command" -- verify the command name matches the reference above
Empty results -- check that the profile ID corresponds to the correct marketplace and that campaigns/entities exist

All errors are output as JSON to stderr in the format: {"error": "message"}

API documentation references

Usage Guidance

This skill appears to be a thin wrapper around an Amazon Ads CLI and will need your Amazon OAuth access token, client ID, and a profile ID (either via a credentials JSON or environment variables). The registry metadata does not declare these requirements — ask the publisher to declare required env vars. Before installing or using it: 1) Verify the npm package (amazon-ads-open-cli) source and author on npm/github; prefer an official or well-known repository. 2) If you must provide credentials, use the least-privilege, short-lived tokens possible and avoid reusing highly privileged credentials. 3) Consider running the npm install in an isolated environment (container/VM) and inspect the package contents. 4) Create the credentials file at a dedicated path with restrictive permissions if using a file, and monitor network calls while first using the CLI. 5) If you cannot verify the package/source, do not install it; request that the skill metadata be updated to list required env vars and provide a homepage/source link for auditing.

Capability Analysis

Type: OpenClaw Skill Name: amazon-ads-open-cli Version: 1.0.0 The skill bundle provides instructions and a command reference for using the 'amazon-ads-open-cli' tool to interact with the Amazon Advertising API. It includes standard procedures for installation via npm, authentication using OAuth2 tokens, and data retrieval for various Amazon ad types (Sponsored Products, Brands, Display, and DSP). No evidence of malicious intent, data exfiltration, or prompt injection was found; the instructions are consistent with the stated purpose of reporting and data retrieval. The use of a future date (2026) in examples and metadata appears to be a stylistic choice by the author rather than a sign of malice.

Capability Tags

requires-oauth-token

Capability Assessment

⚠ Purpose & Capability

The skill's stated purpose (interacting with Amazon Advertising API) legitimately requires OAuth credentials and a profile ID. However, the registry metadata lists no required environment variables or primary credential while the SKILL.md documents AMAZON_ADS_ACCESS_TOKEN, AMAZON_ADS_CLIENT_ID, and AMAZON_ADS_PROFILE_ID plus an on-disk credentials file. The absence of these declared requirements in metadata is an inconsistency.

ℹ Instruction Scope

The SKILL.md instructs the agent to run the amazon-ads-open-cli commands and to read credentials from ~/.config/amazon-ads-open-cli/credentials.json or environment variables. The instructions stay within the advertised domain (listing campaigns, profiles, reports) and do not ask for unrelated system files, but they do direct reading of a user config file and use of OAuth tokens (sensitive).

ℹ Install Mechanism

There is no install spec in the skill bundle; SKILL.md tells users to run `npm install -g amazon-ads-open-cli`. Installing an npm package globally is a reasonable way to obtain a CLI, but it carries the normal risk of executing third-party code from the npm registry. The skill bundle itself does not provide a vetted install artifact or homepage to verify the package source.

⚠ Credentials

The runtime requires sensitive credentials (OAuth access token and client ID, plus a profile ID) but the skill metadata declares none. That mismatch hides the need for secrets from the metadata surface. Requesting these credentials is proportionate to the skill's purpose, but the lack of explicit declaration is a transparency and security concern.

✓ Persistence & Privilege

The skill is not always-enabled and does not request system-wide persistence or modifications to other skills. Model invocation is allowed (default) but that is expected for user-invokable skills.

Version History

v1.0.0

amazon-ads-open-cli 1.0.0 – Initial release - Provides CLI access to Amazon Ads reporting and entity data (Sponsored Products, Brands, Display, DSP) - Supports listing and inspecting campaigns, ad groups, ads, keywords, and audiences - Enables async performance report generation via command line - Detailed instructions for authentication using credentials file or environment variables - Pretty-printed JSON output with pagination and filtering options for all major entities - Full command reference included in documentation

Metadata

Slug amazon-ads-open-cli

Version 1.0.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is Amazon Ads CLI?

Amazon Ads data retrieval and reporting via amazon-ads-open-cli. Use when the user wants to check Amazon ad performance, pull Sponsored Products/Brands/Displ... It is an AI Agent Skill for Claude Code / OpenClaw, with 75 downloads so far.

How do I install Amazon Ads CLI?

Run "/install amazon-ads-open-cli" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Amazon Ads CLI free?

Yes, Amazon Ads CLI is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Amazon Ads CLI support?

Amazon Ads CLI is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Amazon Ads CLI?

It is built and maintained by Bin-Huang (@bin-huang); the current version is v1.0.0.

More Skills

Amazon Ads CLI

Amazon Ads CLI Skill

Quick start

Authentication

Entity hierarchy

Output format

Commands reference

Profiles

Sponsored Products campaigns

Sponsored Brands campaigns

Sponsored Display campaigns

Sponsored Products ad groups

Sponsored Brands ad groups

Sponsored Display ad groups

Sponsored Products ads

Sponsored Display ads

Sponsored Products keywords

Sponsored Products negative keywords

Sponsored Products targets

Sponsored Brands targets

Sponsored Display targets