Microsoft Ads CLI Skill

You have access to microsoft-ads-cli, a read-only CLI for the Bing Ads API v13. Use it to query ad accounts, pull campaign/ad group/keyword performance reports, inspect audiences, manage UET conversion goals, and analyze bid strategies across Search, Shopping, Audience, DynamicSearchAds, and PerformanceMax campaigns.

Quick start

# Check if the CLI is available
microsoft-ads-cli --help

# Get authenticated user info
microsoft-ads-cli user

# List accessible ad accounts
microsoft-ads-cli accounts

If the CLI is not installed, install it:

npm install -g microsoft-ads-cli

Authentication

The CLI requires a Microsoft OAuth2 access token and a Developer Token. Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. Environment variables: MICROSOFT_ADS_ACCESS_TOKEN + MICROSOFT_ADS_DEVELOPER_TOKEN (both required), plus optional MICROSOFT_ADS_CUSTOMER_ID and MICROSOFT_ADS_ACCOUNT_ID
3. Auto-detected file: ~/.config/microsoft-ads-cli/credentials.json

The credentials file format:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "developer_token": "YOUR_DEVELOPER_TOKEN",
  "customer_id": "YOUR_CUSTOMER_ID",
  "account_id": "YOUR_DEFAULT_ACCOUNT_ID"
}

access_token and developer_token are required. customer_id and account_id are optional but needed for most campaign management commands.

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

Entity hierarchy

Customer
 +-- Ad Account
      +-- Campaign (Search, Shopping, Audience, DynamicSearchAds, PerformanceMax)
      |    +-- Ad Group
      |         +-- Ad (AppInstall, DynamicSearch, ExpandedText, Hotel, Product, ResponsiveAd, ResponsiveSearch)
      |         +-- Keyword
      |         +-- Negative Keyword
      +-- Budget
      +-- Bid Strategy
      +-- Label
      +-- Audience (RemarketingList, CustomerList, Custom, InMarket, Product, SimilarRemarketingList, CombinedList)
      +-- UET Tag
           +-- Conversion Goal (Url, Duration, PagesViewedPerVisit, Event, AppInstall, OfflineConversion, InStoreTransaction)

Many commands accept --account-id <id> to override the default account from credentials. The campaigns command takes <account-id> as a required positional argument instead.

Monetary values

The Bing Ads API returns monetary values (Spend, AverageCpc, CostPerConversion, Revenue, budgets, bids) in the currency of the ad account. Report values are typically in the major currency unit as strings (e.g., "12.34" means $12.34). Budget and bid amounts from campaign management endpoints may be returned as decimal numbers.

Output format

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