sensortower

A JSON-first CLI for Sensor Tower iOS market data
Read-only · Scriptable · CI-friendly · Built for market intelligence workflows

⚠️ Status

This project is in early public beta. The current release is intentionally small and read-only, focused on a few high-value Sensor Tower iOS endpoints. The HTTP/config layer already supports optional cookie/header injection for future session-backed usage, but no login automation is included in v1.

✨ Why sensortower?

Pull Sensor Tower data from your terminal without rebuilding ad-hoc scripts every time.

📦 Installation

brew tap FerdiKT/tap
brew install sensortower

go install github.com/ferdikt/sensortower-cli@latest

git clone https://github.com/FerdiKT/sensortower-cli.git
cd sensortower-cli
make tidy
make build VERSION=0.1.0
./bin/sensortower version

🚀 Quickstart

1️⃣ List a publisher's apps

sensortower publishers apps \
  --publisher-id 1619264551 \
  --limit 25 \
  --offset 0 \
  --sort-by downloads

2️⃣ Fetch a single app

sensortower apps get \
  --app-id 6478631467 \
  --country US

3️⃣ Fetch iOS category rankings

sensortower charts category-rankings \
  --country US \
  --category 0 \
  --date 2026-04-16 \
  --device iphone \
  --limit 25

JSON mode

sensortower charts category-rankings \
  --country US \
  --category 0 \
  --date 2026-04-16 \
  --device iphone \
  --output json | jq '.data.free[0]'

🗺️ Command Map

⚙️ Configuration

Default config path:

~/Library/Application Support/sensortower/config.json

Example:

{
  "base_url": "https://app.sensortower.com",
  "timeout_seconds": 30,
  "output": "table",
  "cookie": "sensor_tower_session=...",
  "headers": {
    "X-Custom-Header": "value"
  }
}

Environment overrides:

export SENSORTOWER_BASE_URL="https://app.sensortower.com"
export SENSORTOWER_TIMEOUT_SECONDS=30
export SENSORTOWER_OUTPUT=json
export SENSORTOWER_COOKIE="sensor_tower_session=..."
export SENSORTOWER_HEADERS_JSON='{"X-Custom-Header":"value"}'

Current global flags:

sensortower --config /path/to/config.json --output json ...

Useful automation flags:

sensortower --context team-a \
  --retry-429 --retry-max 8 --retry-wait 60 \
  --cache-ttl 300 \
  --output-format jsonl \
  --output-file ./out.jsonl ...

🔎 Batch, Workflow, ASO

Autocomplete search:

sensortower search apps --term ferdi --output json
sensortower search publishers --term ferdi --output json

Batch app metadata:

sensortower apps get \
  --app-ids-file ids.txt \
  --country US \
  --fields name,subtitle,description.full_description \
  --output-format jsonl \
  --output-file ./apps.jsonl

Competitor workflow:

sensortower workflow competitors \
  --country US \
  --categories 7018,7019 \
  --top 200 \
  --output-format json \
  --output-file ./competitors.json

ASO helpers:

sensortower aso metadata-audit --app-id 6478631467 --country US --output json
sensortower aso keyword-gap --app-id 6478631467 --competitor-ids-file competitor_ids.txt --country US --output json

Contexts:

sensortower contexts add --name team-a --cookie 'sensor_tower_session=...' --headers-json '{"X-Custom":"1"}'
sensortower contexts use --name team-a
sensortower contexts list --output json

🤖 Agent Workflow

Repo-local guidance lives in AGENTS.md and the bundled skill at skills/sensortower-cli/SKILL.md.

To install the bundled Codex skill directly from the CLI:

sensortower agent install-skill

For local development, if you want a symlink instead of a copied install:

sensortower agent link-skill --source ./skills/sensortower-cli

To inspect the target install path:

sensortower agent show-skill-path

🧪 Development

make tidy
make test
make build VERSION=0.1.0
make dist VERSION=0.1.0

Smoke checks:

go run . publishers apps --publisher-id 1619264551 --output json
go run . apps get --app-id 6478631467 --country US --output json
go run . charts category-rankings --country US --category 0 --date 2026-04-16 --device iphone --output json

📄 License

MIT