Cli MCP Server

@appfigures/cli

The Appfigures CLI — query app metrics, reviews, and store data from your terminal.

Try it now without installing:

npx @appfigures/cli auth login
npx @appfigures/cli apps search "youtube"

✨ Four ways to use the power of Appfigures AI

Bring Appfigures into your agent however it's built — as tools it calls, code it writes, a CLI, or over MCP. Whichever you pick, you can do the same things and get the same JSON back.

• 🛠️ Agent tools — your agent calls Appfigures as tools while it runs. AI SDK, OpenAI, LangChain. → Add the tools
• 📦 The client — your agent writes code that queries Appfigures and gets typed data back. → Use the client
• 🖥️ CLI — run Appfigures from a terminal or a sandbox. → @appfigures/cli
• 🔌 MCP — connect Appfigures to Claude, ChatGPT, or Cursor. → Connect the hosted server

Install

npm install -g @appfigures/cli

Requires Node.js 22+. Works with pnpm and yarn too.

Quick start

appfigures auth login
appfigures --help

Also available as af alias.

Authentication

• Log in yourself. af auth login --interactive opens your browser in a guided flow; approve and paste the code back.
• Or let your agent guide you. By default, af auth login prints an authorization URL — open it, approve, and finish with af auth login --code <code> using the code shown. An agent can drive this end to end. For unattended use, set APPFIGURES_API_KEY instead: create a token at appfigures.com/developers/keys by clicking Create a New Client, then Create Personal Access Token.

Either login saves the token to your OS credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service). See Environment for APPFIGURES_API_KEY and other overrides.

MCP server

Appfigures runs a hosted Model Context Protocol server at https://mcp.appfigures.com/mcp. Add it to any MCP client that supports remote servers and sign in with your Appfigures account when the client asks. There's nothing to install and no token to manage.

Claude Code. Add it with one command, then run /mcp to sign in:

claude mcp add --transport http appfigures https://mcp.appfigures.com/mcp

Claude (web and desktop). Add the URL as a custom connector. See Add a connector that isn't in the directory.

ChatGPT. Add the URL as a custom MCP server with OAuth. See Connecting Appfigures to ChatGPT.

Other clients. Add a remote (Streamable HTTP) server with the same URL. See your client's MCP documentation for where.

The hosted server shares Public Data access and credits with the API and CLI. For request limits and credit costs, see Appfigures API, CLI, and MCP: Access, Limits, and Public Data.

For scripts and headless agents that authenticate with APPFIGURES_API_KEY, run the af commands directly, or use @appfigures/agent-toolkit from code.

af mcp (deprecated)

af mcp runs the same tools as a local stdio server. It's deprecated and will be removed in the next major release. Existing setups keep working until then, but it won't get new MCP features. Move to the hosted server above.

Commands

Apps

Find apps and look up their identity. Other commands take the app IDs these return.

Explorer

Search and analyze the full app catalog: millions of products across Apple, Google Play, Amazon, and other major stores, with 120+ fields spanning identity, storefront and country availability, categories, ratings, release dates, chart ranks, download and revenue estimates, SDK presence, demographics, and related apps.

Metrics

Query numeric datasets across dimensions.

Store

App store presence: listing content, category ranks, top charts, and featured placements.

Audience

Who an app's users are and what else they use. Covers estimated age and gender, plus audience overlap with other apps.

Reviews

Search, summarize, and reply to iOS and Google Play app store reviews.

Keywords

Keyword visibility, rank tracking, and discovery across organic search (App Store, Google Play) and Apple Ads.

Apple Ads

Manage your Apple Ads campaigns, ad groups, keywords, and performance.

Sdks

Look up the SDKs we track.

Docs

Reference docs and guides for specific actions and common tasks.

API

MCP

Auth

Run af <command> --help for arguments, flags, and examples.

Environment

API Reference

Every command with its full argument and flag list. For the one-line overview, see Commands above.

Global flags. All commands accept:

• -v, --verbose — Log HTTP requests to stderr. Also set via AF_VERBOSE=1.
• -V, --version — Print the CLI version and exit.
• -h, --help — Show usage for the current command.

Output format. Every command emits a single JSON value on stdout — pipe to jq for filtering. Informational messages, hints, and update notices go to stderr so pipelines stay clean.

af apps search

af apps search <q> [flags]

Find apps by name or publisher. Returns one row per unified app. Default returns Apple and Google listings; pass --all-stores to include other storefronts. To filter apps by estimate values (e.g. apps with >100k downloads last month) use explorer list-products. For estimates broken down by time, country, or storefront, use metrics query with datasets estimates.sales or estimates.revenue.

Options

• <q> required string. Search query (app name or publisher).
• --all-stores boolean, default false. Include storefronts beyond Apple and Google: Amazon, Windows, Steam, Roku, LG TV, Samsung TV, and others.
• --count integer, default 10. Number of results to return.
• --page integer, default 1. Page number.

Examples

# Find every Electronic Arts app.
af apps search 'electronic arts'

# Page through long results.
af apps search 'electronic arts' --count=25 --page=2

# Find Minecraft on every storefront (e.g. Amazon, Steam, Windows, Roku; not common).
af apps search minecraft --all-stores

---

af apps get

af apps get <app-id> [flags]

Get an app's record: basic metadata (name, developer, etc) and, if the user tracks it, what data they can access. Pass a product ID for one storefront; unified app ID for all storefronts together.

Options

• <app-id> required integer or string. The app's unified app ID or product ID.
• --all-stores boolean, default false. For a unified app ID: include member products across all storefronts (Amazon, Steam, Windows, Roku, etc.). When false, member_products is restricted to storefronts with app-intelligence coverage (iOS + Google Play). Ignored for product IDs.

Examples

# Get Minecraft's unified-app record (iOS + Google Play by default).
af apps get ua_X7iNgb

# Get Minecraft's Google Play product record.
af apps get 6938219

---

af apps tracked

af apps tracked [flags]

List the apps your Appfigures account tracks.

Options

• --count integer, default 10. Number of results to return.
• --page integer, default 1. Page number.
• --q string. App name to filter by.
• --filter-apps-by-id (integer or string)[]. Only include data about specific apps, by product ID or unified app ID. Takes precedence over the other filterAppsBy* keys when set. Storefront, source, or type filters are better for app sets that can be described by those criteria.
• --filter-apps-by-storefront string[]. Narrow the account's tracked apps to those on these storefronts (e.g. apple:ios, google_play).
• --filter-apps-by-source string[]. Narrow the account's tracked apps by tracking relationship.
• --filter-apps-by-type string[]. Narrow the account's tracked apps to products of these types.

Examples

# List your apps with private-data access.
af apps tracked --filter-apps-by-source=own,shared

# List your tracked fitness apps.
af apps tracked --q=fitness

# List just your iOS apps.
af apps tracked --filter-apps-by-storefront=apple:ios

# Page through long results.
af apps tracked --filter-apps-by-source=own,shared --count=50 --page=2

# List tracked competitors.
af apps tracked --filter-apps-by-source=manual

# Find individual IAPs or subscriptions (not common).
af apps tracked --filter-apps-by-type=inapp,subscription

---

af apps breakdown

af apps breakdown [flags]

Count your tracked apps by data group (e.g. sales, usage, ranks, reviews, keywords), storefront, monetization model, and source (yours vs tracked competitors), plus the total and earliest release date.

Options

• --filter-apps-by-id (integer or string)[]. Only include data about specific apps, by product ID or unified app ID. Takes precedence over the other filterAppsBy* keys when set. Storefront, source, or type filters are better for app sets that can be described by those criteria.
• --filter-apps-by-storefront string[]. Narrow the account's tracked apps to those on these storefronts (e.g. apple:ios, google_play).
• --filter-apps-by-source string[]. Narrow the account's tracked apps by tracking relationship.
• --filter-apps-by-type string[]. Narrow the account's tracked apps to products of these types.

Examples

# Check what data the whole account has.
af apps breakdown

# Limit to apps you own or that were shared with you.
af apps breakdown --filter-apps-by-source=own,shared

# Limit to your iOS apps.
af apps breakdown --filter-apps-by-storefront=apple:ios

---

af explorer list-products

af explorer list-products [flags]

Read catalog fields for one app or many. Fields referenced by query or sort come back automatically; pass --extra-fields for more. Use ["match","product_id",<id>] for a single app, or combine filters for population queries (e.g. iOS apps using Firebase with $1M+ US revenue). The 120+ fields span ranks, ratings, download and revenue estimates, SDKs, demographics, and more; query grammar and field list in docs get catalog_playbook.

Options

• --query array, default []. Explorer query in JSON array format to select matching catalog Products. Defaults to active Products. Include inactive too: ["match","active",["or",true,false]]. The full field list and query syntax are documented in docs get catalog_playbook.
• --extra-fields string[]. Additional fields to include beyond those your query or sort already reference. Find field paths (and which you can read) with explorer describe-fields.
• --sort string. Explorer field name. The full field list is documented in docs get catalog_playbook.
• --order string, default desc. Sort direction.
• --count integer, default 10. Number of results to return.
• --page integer, default 1. Page number.
• --allow-unscoped-nested boolean, default false. Escape hatch for intentionally broad queries. Bypasses the default block on unscoped nested predicates that usually inflate results.

Examples

# Find iOS apps that have Firebase installed.
af explorer list-products --query='["and",["match","storefronts","apple:ios"],["nested","all_sdks",["and",["match","all_sdks.id","firebase"],["match","all_sdks.active",true]]]]'

# Rank the biggest US iOS games by revenue.
af explorer list-products --query='["and",["match","storefronts","apple:ios"],["match","categories.all",6014]]' --sort='custom_meta[country=us].revenue_estimates_sum_30_days' --order=desc --count=25

# Find US iOS apps in the $100k–$1M/month revenue tier.
af explorer list-products --query='["and",["match","storefronts","apple:ios"],["nested","custom_meta",["and",["match","custom_meta.country","us"],["match","custom_meta.revenue_estimates_sum_30_days",["number_range",100000,1000000]]]]]'

# Page through results.
af explorer list-products --query='["and",["match","storefronts","apple:ios"],["match","categories.all",6014]]' --count=50 --page=2

# Pass `--extra-fields` for columns the query doesn't already reference. Common for single-app reads.
af explorer list-products --query='["match","product_id",304004187384]' --extra-fields='custom_meta[country=zz].revenue_estimates_sum_365_days,all_sdks[id=firebase].active'

---

af explorer aggregate-products

af explorer aggregate-products <fields> [flags]

Aggregate across the full catalog of millions of products across Apple, Google Play, Amazon, and other major stores: counts, averages, min/max, and histograms over any set of matching products. Uses the same query grammar as explorer list-products; returns aggregates, not product records. For market sizing, benchmarking, and segment analysis.

Options

• <fields> required string[]. Field+aggregation pairs (e.g. all_rating/stats, storefronts/terms). Aggregations: stats, terms, histogram, date_histogram, cardinality. The full field list is documented in docs get catalog_playbook.
• --query array, default []. Explorer query in JSON array format to select matching catalog Products. Defaults to active Products. Include inactive too: ["match","active",["or",true,false]]. The full field list and query syntax are documented in docs get catalog_playbook.
• --allow-unscoped-nested boolean, default false. Escape hatch for intentionally broad queries. Bypasses the default block on unscoped nested predicates that usually inflate results.
• --terms-count integer, default 20. Maximum buckets returned for each terms aggregation. Other aggregation types ignore it.
• --date-histogram-interval string. Bucket granularity for each date_histogram aggregation. Other aggregation types ignore it.

Examples

# How many monthly downloads does an average iOS app get in Japan?
af explorer aggregate-products 'custom_meta[country=jp].download_estimates_average_30_days/stats' --query='["and",["match","storefronts","apple:ios"],["match","countries","jp"]]'

# What's the rating, category mix, and developer concentration for US iOS apps in the $100k–$10M/mo net-revenue tier?
af explorer aggregate-products all_rating/stats,categories.all/terms,developer_id/cardinality --query='["and",["match","storefronts","apple:ios"],["nested","custom_meta",["and",["match","custom_meta.revenue_estimates_sum_30_days",["number_range",100000,10000000]],["match","custom_meta.country","us"]]]]'

# Are new iOS games still launching at the same rate as two years ago?
af explorer aggregate-products release_date/date_histogram --query='["and",["match","storefronts","apple:ios"],["match","categories.all",6014],["match","release_date",["range","2024-01-01","2025-12-31"]]]'

# What SDKs do apps commonly ship alongside OneSignal?
af explorer aggregate-products 'all_sdks[*].id/terms' --query='["nested","all_sdks",["and",["match","all_sdks.id","onesignal"],["match","all_sdks.active",true]]]'

# How do iOS app ratings distribute?
af explorer aggregate-products all_rating/histogram --query='["match","storefronts","apple:ios"]'

# How many apps are on each storefront?
af explorer aggregate-products storefronts/terms

---

af explorer describe-fields

af explorer describe-fields [flags]

List the catalog fields and the current user's access level for each. Search by keyword to find fields. Same field set explorer list-products and explorer aggregate-products accept.

Options

• --count integer, default 50. Number of results to return.
• --page integer, default 1. Page number.
• --q string. Filter by path, title, description, type.

Examples

# Search for revenue-related fields.
af explorer describe-fields --q=revenue

# List every catalog field with the current user's access level.
af explorer describe-fields

---

af metrics query

af metrics query <dataset> [flags]

Query any numeric dataset for one or more apps. Optionally grouped by up to two dimensions, returned as a nested partition tree, not app records. Independently filterable by country, device type, and date range. filterAppsBy* options narrow the app set (by ID, storefront, source, or type); without one, a query covers every app the account tracks.

Options

• <dataset> required string. Dataset to query (e.g. sales.combined_downloads). See metrics describe-datasets for the full list and which datasets are private data (visible only for apps you own or that were shared).
• --group-by string[]. Dimensions to group by. Max 2: the first slot becomes the outer entity type, the second the inner series. Each dimension multiplies the result size.
• --granularity string. Time granularity when grouping by date
• --count integer. Row cap. With --group-by, top N of the outer entity type by value (earliest N when grouping by date). Without --group-by, single-page preview.
• --countries string[]. Filter to one or more ISO country codes (e.g. US, JP, GB)
• --device-type string. Device type
• --all-time boolean, default false. Opt in to the entire history. Without this flag (and without start/end), the query defaults to the last 30 days. Mutually exclusive with start and end.
• --filter-apps-by-id (integer or string)[]. Only include data about specific apps, by product ID or unified app ID. Takes precedence over the other filterAppsBy* keys when set. Storefront, source, or type filters are better for app sets that can be described by those criteria.
• --filter-apps-by-storefront string[]. Narrow the account's tracked apps to those on these storefronts (e.g. apple:ios, google_play).
• --filter-apps-by-source string[]. Narrow the account's tracked apps by tracking relationship.
• --filter-apps-by-type string[]. Narrow the account's tracked apps to products of these types.
• --start string. Start date (YYYY-MM-DD)
• --end string. End date (YYYY-MM-DD, defaults to today)

Examples

# Get total downloads across your apps with private-data access.
af metrics query sales.combined_downloads --filter-apps-by-source=own,shared

# Get revenue split by storefront, plus a top-level total.
af metrics query sales.combined_revenue --filter-apps-by-source=own,shared --group-by=storefront

# Rank the top 5 tracked competitors by estimated monthly revenue.
af metrics query estimates.revenue --filter-apps-by-source=manual --group-by=product --count=5

# Track Candy Crush Saga's daily download estimates.
af metrics query estimates.sales --filter-apps-by-id=ua_V1Q1uX --group-by=date --granularity=daily

# Track net monthly recurring revenue per app, month over month.
af metrics query subscriptions.mrr --filter-apps-by-source=own,shared --group-by=product,date --granularity=monthly

# Get Minecraft's new ratings.
af metrics query ratings.new_total --filter-apps-by-id=ua_X7iNgb

# Track daily ad spend across your apps.
af metrics query adspend.cost --filter-apps-by-source=own,shared --group-by=date --granularity=daily

# Compare Candy Crush's December 2025 downloads across the US, Japan, and UK.
af metrics query estimates.sales --filter-apps-by-id=ua_V1Q1uX --countries=US,JP,GB --group-by=country --start=2025-12-01 --end=2025-12-31

# Track all-time monthly revenue across your apps with private-data access.
af metrics query sales.combined_revenue --filter-apps-by-source=own,shared --group-by=date --granularity=monthly --all-time

# Get Minecraft's review volume by country.
af metrics query reviews.total --filter-apps-by-id=ua_X7iNgb --group-by=country

---

af metrics describe-datasets

af metrics describe-datasets [flags]

List every numeric dataset metrics query accepts, one row per dataset with its value type and whether it's limited to your own apps.

Options

• --count integer, default 50. Number of results to return.
• --page integer, default 1. Page number.
• --q string. Filter by dataset, value_type, label, description.

Examples

# Search by keyword (matches name, label, or description).
af metrics describe-datasets --q='combined downloads'

# Look up one dataset by its exact name.
af metrics describe-datasets --q=sales.combined_downloads

# List every dataset with its value type and whether it's limited to your own apps.
af metrics describe-datasets

---

af store app-ranks

af store app-ranks <app-ids> [flags]

Trace rank history for one or more apps across countries, device types, category subtypes, and categories, as time-series positions with day-over-day deltas.

Options

• <app-ids> required (integer or string)[]. App identifiers (unified app IDs or product IDs)
• --countries string[]. Country codes to query. Defaults to every country with rank coverage.
• --granularity string, default hourly. Sampling rate. Hourly gives the freshest data; pass --granularity=daily for compact multi-day history.
• --device-types string[], default ["handheld"]. Which device types to include; each ranks in its own chart. Add more to widen the response.
• --subtypes string[], default ["free","paid"]. Which category subtypes to include; each ranks in its own chart. Add more to widen the response.
• --category-ids integer[]. Filter response rows to specific category IDs; omit for all. Category IDs come from store categories.
• --start string. Start date (YYYY-MM-DD)
• --end string. End date (YYYY-MM-DD, defaults to today)
• --count integer, default 10. Number of results to return.
• --page integer, default 1. Page number.

Examples

# Check ChatGPT's current ranks (unified app).
af store app-ranks ua_miTXv6 --countries=US

# Check ChatGPT's current ranks on one storefront.
af store app-ranks 336744124021 --countries=US

# Compare ChatGPT's ranks across the US, UK, and Japan.
af store app-ranks ua_miTXv6 --countries=US,GB,JP

# Check Procreate's paid iPad chart ranks.
af store app-ranks ua_CxA1MS --subtypes=paid --device-types=tablet --countries=US

# Trace ChatGPT's chart history through December 2025.
af store app-ranks ua_miTXv6 --granularity=daily --start=2025-12-01 --end=2025-12-31 --countries=US

# Check ChatGPT's rank in one category (US iOS Productivity).
af store app-ranks 336744124021 --category-ids=6007 --countries=US

---

af store top-charts

af store top-charts [flags]

List the top apps in a category chart for a given country and category, with current positions and day-over-day deltas.

Options

• --country required string. ISO country code (e.g. US, JP, GB)
• --category-id required integer. Category IDs come from store categories.
• --subtype string, default free. Category subtype (chart variant within the category).
• --date string. Snapshot date (YYYY-MM-DD, defaults to current).
• --count integer, default 10. Number of results to return.
• --page integer, default 1. Page number.

Examples

# Find the Games category, then pull its US chart.
af store categories --q=games
af store top-charts --country=US --category-id=6014

# List top paid apps on the US App Store.
af store top-charts --country=US --category-id=25204 --subtype=paid

# List top free apps on the Japan App Store.
af store top-charts --country=JP --category-id=25204

# List top free apps on Google Play in the US.
af store top-charts --country=US --category-id=100

# List top free apps on the US App Store in December 2025.
af store top-charts --country=US --category-id=25204 --date=2025-12-01

---

af store categories

af store categories [flags]

List every store category with its ID. Numeric category IDs required by store app-ranks --category-ids and store top-charts --category-id are available here.

Options

• --count integer, default 50. Number of results to return.
• --page integer, default 1. Page number.
• --q string. Filter by name.
• --sort string. Field to sort by. Omit to order by relevance when q is set, otherwise list order.
• --order string, default desc. Sort direction.
• --category-id integer[]. Only return these category IDs.
• --parent-id integer. Only include subcategories of this parent category (drill-down by id).
• --storefront string[]. Only include categories from these storefronts (e.g. apple:ios, google_play).
• --device-type string[]. Only include categories for these device types (e.g. handheld, tablet).
• --all boolean, default false. Include non-rank stores (roku, vizio, etc.). These have categories but no rank data.

Examples

# Find the Games category.
af store categories --q=games

# List every Apple iOS category.
af store categories --storefront=apple:ios

# List subcategories of a parent category (here, Apple Games).
af store categories --parent-id=6014

# Include categories from non-rank-supporting stores (e.g. Roku, Vizio) (not common).
af store categories --all

---

af store featured

af store featured <app-id> [flags]

List featured and editorial placements for an app or storefront product. Request 0 rows for summary stats only.

Options

Documentation truncated — see the full README on GitHub.