@appfigures/cli

@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"

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

Run af auth login in an interactive terminal to sign in. Two ways:

• Browser (default): opens your browser, approve, paste the code shown back into the CLI. The resulting token is stored in your OS credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service).
• Personal access token: pick "Personal access token" at the prompt for instructions. Create a token at appfigures.com/developers/keys, then export APPFIGURES_API_KEY=<your-token>.

For CI or any non-interactive context, af auth login will not run — see Environment below.

Built for agents

Designed to be driven by LLM agents as much as by humans.

• JSON on stdout, everything else on stderr. Every command emits a single JSON value on stdout — jq-ready, no interleaved logs, hints, or update notices.
• Auto-detected agent mode. When stdout isn't a TTY (piped, redirected, or captured by an agent harness) the CLI switches to non-interactive: no prompts, no spinners, and errors include an agent-directed NOTE: hint on stderr to steer the next action.
• Self-describing, offline. af docs get catalog_playbook and af docs get numeric_metrics print the full query grammar and dataset catalog without hitting the API — plan queries without round-trips or stale training data.
• Unattended auth. Set APPFIGURES_API_KEY in the environment; every command runs without a browser or prompt.
• Raw API escape hatch. af api <path> proxies any endpoint the first-class commands don't cover.

Commands

Apps

Find and identify apps.

Command	Description
af apps search	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 query. For estimates broken down by time, country, or storefront, use metrics query with datasets estimates.sales or estimates.revenue.
af apps tracked	List the apps your Appfigures account tracks.
af apps get	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.

Explorer

Search and analyze the app catalog — 3M+ apps, 120+ queryable fields.

Command	Description
af explorer query	Advanced search across the 3M-app catalog — filter and sort by any of 120+ fields (download/revenue estimates, SDK presence, demographics, ratings, ranks, pricing, release dates, ad activity). Uses a simple array query grammar. The full field list and query syntax are documented in docs get catalog_playbook.
af explorer aggregate	Advanced aggregation across the 3M-app catalog — counts, averages, min/max, and histograms over any set of matching apps. Uses the same bespoke JSON query grammar as explorer query; returns aggregates, not app records. For market sizing, benchmarking, and segment analysis.
af explorer fields	List the catalog fields and the current user's access level for each. Same field set explorer query and explorer aggregate accept.

Metrics

Query numeric datasets across dimensions.

Command	Description
af metrics query	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). Some datasets require app ownership, some work for any app.

Store

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

Command	Description
af store app‑ranks	Rank history for one or more apps across countries, device types, subtypes, and categories. Returns time-series positions and day-over-day deltas.
af store top‑charts	Top apps in a category chart — for a given country and category. Returns ranked entries with current positions and day-over-day deltas.
af store categories	Lists 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.
af store featured	Featured and editorial placement history for an app.
af store app‑listing	Full store listing for one storefront — localized text (name, subtitle, description, release notes) plus screenshots, video, categories, monetization, supported devices, country availability, price, file size, and age rating. Takes a numeric product ID (one storefront at a time; a unified app has one product per storefront). One locale per request.

Reviews

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

Command	Description
af reviews list	Search and filter reviews for one or more apps by star rating, date range, country, language, and app version.
af reviews breakdown	Review volume breakdown for one or more apps, by star rating, date, or country.
af reviews reply	Reply to a specific review.

Keywords

Organic keyword visibility and tracking.

Command	Description
af keywords list	List tracked keywords with their opaque IDs.
af keywords rankings	Current organic keyword rankings for one or more apps. Returns which keywords each app ranks for, with position, popularity, and competitiveness. Works for any app.
af keywords results	Apps ranking for a specific keyword in organic search results. Returns the ranked list of apps appearing for that keyword, with keyword popularity and competitiveness scores.
af keywords related	Find related and suggested keywords for ASO research.

Apple Ads

Apple Search Ads intelligence.

Command	Description
af apple‑ads keywords	Paid keyword data for one or more apps — which keywords each app has ad impressions for, with impression share and organic rank.
af apple‑ads advertisers	Apps advertising on a specific keyword, with impression share, organic rank, first/last seen dates, and lifetime data.

Docs

Reference docs for composing requests and interpreting responses.

Command	Description
af docs get	Returns a reference doc by slug.

API

Command	Description
af api	Make a raw API request. See the API reference at https://docs.appfigures.com.

Auth

Command	Description
af auth login	Sign in to Appfigures
af auth logout	Remove stored credentials
af auth status	Show authentication and account status

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

Environment

Variable	Purpose
APPFIGURES_API_KEY	API key; skips interactive auth
AF_VERBOSE	Log HTTP to stderr (same as -v)
NO_COLOR	Disable ANSI color
NO_UPDATE_NOTIFIER	Skip the npm-registry update check
CI	Also skips the update check (any CI system)

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 <query> [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 query. For estimates broken down by time, country, or storefront, use metrics query with datasets estimates.sales or estimates.revenue.

Options

• <query> 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 (1-indexed)

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 (1-indexed)
• --q string. Substring match on app name.
• --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.

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. App identifier — 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 app-intelligence storefronts (iOS + Google Play). Ignored for product IDs.

af explorer query

af explorer query [query] [flags]

Advanced search across the 3M-app catalog — filter and sort by any of 120+ fields (download/revenue estimates, SDK presence, demographics, ratings, ranks, pricing, release dates, ad activity). Uses a simple array query grammar. The full field list and query syntax are documented in docs get catalog_playbook.

Options

• [query] array. Explorer query in JSON array format to select matching catalog Products. Missing values and [] match every Product across every storefront. The full field list and query syntax are documented in docs get catalog_playbook.
• --fields string[]. Explorer field names. The full field list is documented in docs get catalog_playbook.
• --sort string. Explorer field name. The full field list is documented in docs get catalog_playbook.
• --order string. Sort direction
• --count integer, default 10. Number of results to return
• --page integer, default 1. Page number (1-indexed)
• --allow-unscoped-nested boolean, default false. Escape hatch: only pass true after a query error says the unscoped nested semantics are intentional.

af explorer aggregate

af explorer aggregate <fields> [flags]

Advanced aggregation across the 3M-app catalog — counts, averages, min/max, and histograms over any set of matching apps. Uses the same bespoke JSON query grammar as explorer query; returns aggregates, not app records. For market sizing, benchmarking, and segment analysis.

Options

• --query array. Explorer query in JSON array format to select matching catalog Products. Missing values and [] match every Product across every storefront. The full field list and query syntax are documented in docs get catalog_playbook.
• <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.
• --allow-unscoped-nested boolean, default false. Escape hatch: only pass true after a query error says the unscoped nested semantics are intentional.

af explorer fields

af explorer fields

List the catalog fields and the current user's access level for each. Same field set explorer query and explorer aggregate accept.

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). Some datasets require app ownership, some work for any app.

Options

• <dataset> required string. Dataset to query (e.g. sales.combined_downloads). The full list is documented in docs get numeric_metrics.
• --group-by string[]. Dimensions to group by. Max 2: the first slot becomes the outer entity type, the second the inner series.
• --granularity string. Time granularity when grouping by date
• --include-total boolean, default false. Return a single total alongside the breakdowns. Skips client-side summation for dashboard-style asks.
• --count integer. Cap the number of rows returned. Without this option, paginated datasets auto-paginate every page; a small count returns a preview instead of the full series.
• --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)

af store app-ranks

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

Rank history for one or more apps across countries, device types, subtypes, and categories. Returns time-series positions and 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"]. Filter response rows by device type.
• --subtypes string[], default ["free"]. Filter response rows by subtype.
• --category-ids integer[]. Filter response rows by category ID.
• --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 (1-indexed)

af store top-charts

af store top-charts [flags]

Top apps in a category chart — for a given country and category. Returns ranked entries with current positions and day-over-day deltas.

Options

• --country required string. ISO country code (e.g. US, JP, GB)
• --category-id required integer. Store category ID
• --subtype string, default free. Which list 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 (1-indexed)

af store categories

af store categories [flags]

Lists 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

• --all boolean, default false. Include non-rank stores (roku, vizio, etc.) — they have categories but no rank data
• --ids integer[]. Only return these category IDs.
• --q string. Substring match on category name.

af store featured

af store featured <app-id> [flags]

Featured and editorial placement history for an app.

Options

• <app-id> required integer or string. App identifier — unified app ID or product ID
• --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 (1-indexed)

af store app-listing

af store app-listing <product-id> [flags]

Full store listing for one storefront — localized text (name, subtitle, description, release notes) plus screenshots, video, categories, monetization, supported devices, country availability, price, file size, and age rating. Takes a numeric product ID (one storefront at a time; a unified app has one product per storefront). One locale per request.

Options

• <product-id> required integer. Numeric product ID for one storefront. Not a unified app ID. Member product_id values are available from apps get '<unified-app-id>'.
• --language string. Locale (e.g. en, ja, zh-Hans) for name, subtitle, description, release notes, and screenshots. Defaults to en; falls back to the first available locale when the requested one has no metadata. The response echoes the resolved language.
• --device-type string, default handheld. Relevant to Apple apps. Pick handheld for iPhone-specific metadata, tablet for iPad, desktop for Mac, etc.

af reviews list

af reviews list [flags]

Search and filter reviews for one or more apps by star rating, date range, country, language, and app version.

Options

• --stars number[]. Filter by star rating
• --language string. Filter by language code (e.g. en, ja)
• --version string. Filter by app version
• --country string. ISO country code (e.g. US, JP, GB)
• --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.
• --count integer, default 10. Number of results to return
• --page integer, default 1. Page number (1-indexed)

af reviews breakdown

af reviews breakdown [flags]

Review volume breakdown for one or more apps, by star rating, date, or country.

Options

• --country string. ISO country code (e.g. US, JP, GB)
• --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)

af reviews reply

af reviews reply <review-id> [flags]

Reply to a specific review.

Options

• <review-id> required string. Review ID to reply to
• --body required string. Reply text

af keywords list

af keywords list

List tracked keywords with their opaque IDs.

af keywords rankings

af keywords rankings [flags]

Current organic keyword rankings for one or more apps. Returns which keywords each app ranks for, with position, popularity, and competitiveness. Works for any app.

Options

• --product-ids integer[]. Product identifiers (numeric, single-store products).
• --country required string. ISO country code (e.g. US, JP, GB)
• --device-type string. Device type
• --count integer, default 10. Number of results to return
• --page integer, default 1. Page number (1-indexed)

af keywords results

af keywords results <keyword-name> [flags]

Apps ranking for a specific keyword in organic search results. Returns the ranked list of apps appearing for that keyword, with keyword popularity and competitiveness scores.

Options

• <keyword-name> required string. Keyword to look up
• --country string. ISO country code (e.g. US, JP, GB)
• --storefront string. App store platform — e.g. apple:ios, google_play, amazon_appstore, steam, windows10, apple:mac, apple:tv, apple:imessage (and others the API may add)
• --device-type string. Device type
• --count integer, default 10. Number of results to return
• --page integer, default 1. Page number (1-indexed)

af keywords related

af keywords related <keyword-name> [flags]

Find related and suggested keywords for ASO research.

Options

• <keyword-name> required string. Seed keyword to find related terms for
• --country string. ISO country code (e.g. US, JP, GB)
• --storefront string. App store platform — e.g. apple:ios, google_play, amazon_appstore, steam, windows10, apple:mac, apple:tv, apple:imessage (and others the API may add)
• --device-type string. Device type

af apple-ads keywords

af apple-ads keywords <product-ids> [flags]

Paid keyword data for one or more apps — which keywords each app has ad impressions for, with impression share and organic rank.

Options

• <product-ids> required integer[]. Product identifiers (numeric, single-store products).
• --days integer, default 180. Lookback period in days. Common values: 7, 14, 30, 90, 180, 365.
• --country string. ISO country code (e.g. US, JP, GB)
• --device-type string. Device type
• --count integer, default 10. Number of results to return
• --page integer, default 1. Page number (1-indexed)

af apple-ads advertisers

af apple-ads advertisers <keyword-name> [flags]

Apps advertising on a specific keyword, with impression share, organic rank, first/last seen dates, and lifetime data.

Options

• <keyword-name> required string. Keyword to look up advertisers for
• --days integer, default 180. Lookback period in days. Common values: 7, 14, 30, 90, 180, 365.
• --country string. ISO country code (e.g. US, JP, GB)
• --device-type string. Device type
• --count integer, default 10. Number of results to return
• --page integer, default 1. Page number (1-indexed)

af docs get

af docs get <slug>

Returns a reference doc by slug.

Options

• <slug> required string. Which reference to return

af api

af api <path> [flags]

Make a raw API request. See the API reference at https://docs.appfigures.com.

Options

• <path> required string. API path (e.g. /users, /products)
• --method string, default GET. HTTP method (one of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
• --body string. Request body (JSON string)

af auth login

af auth login [flags]

Sign in to Appfigures

Prints a URL to authorize this CLI. Open it, approve access, then re-run with --code <code> using the code shown after approval.

For unattended use (CI, scripts), set APPFIGURES_API_KEY in the environment instead — no browser flow needed.

Options

• --code string. Authorization code from the OAuth consent page. Second step of af auth login — exchanges the code, saves the token, exits.

af auth logout

af auth logout

Remove stored credentials

af auth status

af auth status

Show authentication and account status

Support

• Issues: github.com/appfigures/cli/issues
• API docs: docs.appfigures.com

Contributing

This package is developed in a private monorepo and published here as a mirror. To report bugs or request features, open an issue.

We're also hiring AI-native devs. If you want to help build the future of AI App Intelligence apply at appfigures.com/careers.

License

Apache 2.0