用途：x-ads-cli 是面向 X Ads API（v12）的只读 CLI，用于检查 X/Twitter 广告表现、拉取 campaign/line item/推广推文等数据的统计分析、查看素材、审查定向、检查支付工具以及估算覆盖人数。
安装与认证：未安装时可运行 npm install -g x-ads-cli。需要四项 OAuth 1.0a 凭据：API Key、API Secret、Access Token、Access Token Secret，按以下顺序解析：--credentials <path>、环境变量 X_ADS_API_KEY、X_ADS_API_SECRET、X_ADS_ACCESS_TOKEN、X_ADS_ACCESS_TOKEN_SECRET，以及自动检测文件 ~/.config/x-ads-cli/credentials.json。Access Token 须属于至少可访问一个 X Ads 账户的用户，Ads API 访问需在 X 开发者门户单独申请。
主要命令：accounts / account 查询广告账户；campaigns、line-items、promoted-tweets、media-creatives、cards、targeting-criteria、custom-audiences、funding-instruments、conversion-events 列出各类实体；reach-estimate 按 line item 估算覆盖；stats 提供同步分析，支持 --entity（CAMPAIGN、LINE_ITEM、PROMOTED_TWEET、MEDIA_CREATIVE、FUNDING_INSTRUMENT、ORGANIC_TWEET）、--entity-ids、--start-time、--end-time 必填项，可选 --granularity（HOUR/DAY/TOTAL，默认 DAY）、--metric-groups（如 ENGAGEMENT、BILLING、VIDEO、WEB_CONVERSION 等）、--placement。
输出与限制：命令默认输出格式化 JSON，可用 --format compact 输出单行 JSON；列表命令用游标分页，取响应中的 next_cursor。金额以微货币返回，需除以 1,000,000。stats 每次请求最多 7 天数据，更长区间需按连续 7 天窗口多次请求合并。funding-instruments 与 conversion-events 不支持 --cursor 分页。错误处理：认证失败、无凭据、空结果、HTTP 403（无账户权限）、HTTP 429（限流后重试）、日期范围过大需拆分窗口。