{"id":35377265,"url":"https://github.com/tzechuen/appstore-earnings-cli","last_synced_at":"2026-01-29T18:02:19.177Z","repository":{"id":330721226,"uuid":"1123564032","full_name":"tzechuen/appstore-earnings-cli","owner":"tzechuen","description":"Free CLI tool to view your App Store Connect earnings by month. A simple alternative to appFigures.","archived":false,"fork":false,"pushed_at":"2025-12-27T13:41:19.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-29T09:21:32.491Z","etag":null,"topics":["app-store-connect","app-store-connect-api","apple","cli","developer-tools","earnings","financial-reports","ios","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tzechuen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T06:15:49.000Z","updated_at":"2025-12-27T13:41:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tzechuen/appstore-earnings-cli","commit_stats":null,"previous_names":["tzechuen/appstore-earnings-cli"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tzechuen/appstore-earnings-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzechuen%2Fappstore-earnings-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzechuen%2Fappstore-earnings-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzechuen%2Fappstore-earnings-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzechuen%2Fappstore-earnings-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tzechuen","download_url":"https://codeload.github.com/tzechuen/appstore-earnings-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzechuen%2Fappstore-earnings-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28882016,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T16:41:59.663Z","status":"ssl_error","status_checked_at":"2026-01-29T16:39:39.641Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app-store-connect","app-store-connect-api","apple","cli","developer-tools","earnings","financial-reports","ios","nodejs","typescript"],"created_at":"2026-01-02T04:44:26.213Z","updated_at":"2026-01-29T18:02:19.171Z","avatar_url":"https://github.com/tzechuen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# App Store Earnings CLI\n\nA free, open-source CLI tool to view your App Store earnings by month. A simple alternative to paid services like appFigures for basic earnings tracking.\n\n![Demo](demo.gif)\n\n## Features\n\n- **Standalone binary** - No runtime dependencies required\n- View monthly earnings in a clean tree format (apps with their IAPs grouped together)\n- **Payment info display** - see when Apple paid you and how much was deposited\n- Configurable target currency (USD, EUR, GBP, SGD, etc.)\n- Automatic currency conversion using ECB exchange rates\n- Groups In-App Purchases and subscriptions under their parent apps\n- Caches reports locally to avoid repeated API calls\n- Shows the last 24 months for selection\n- **Interactive setup wizard** for first-time configuration\n\n## Example Output\n\n```\n  App Store Earnings CLI\n\n? Select month: September 2025\n\nFetching financial report for September 2025...\nConverting currencies to USD...\n\n  Earnings for September 2025\n\n├── My Awesome App                          $128.45\n│   ├── Pro Upgrade                          $89.99\n│   ├── Premium Features                     $28.50\n│   └── Remove Ads                            $9.96\n│\n├── Photo Editor Pro                         $67.22\n│   ├── Monthly Subscription                 $45.00\n│   └── Yearly Subscription                  $22.22\n│\n└── Simple Utility                           $12.99\n    └── (App Sales)                          $12.99\n\n─────────────────────────────────────────────────────\n                                  TOTAL      $208.66\n\n  Payment Status: Paid (estimated)\n  Payment Date: ~Oct 5, 2025\n  Amount: ~$208.66\n```\n\n## Installation\n\n### Option 1: Standalone Binary (Recommended)\n\nDownload and install with a single command:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/tzechuen/appstore-earnings-cli/main/install.sh | bash\n```\n\nThis will:\n- Detect your OS and architecture\n- Download the appropriate binary from GitHub Releases\n- Install to `/usr/local/bin` (or `~/.local/bin` if no sudo access)\n\n### Option 2: Manual Download\n\nDownload the appropriate binary from the [Releases page](https://github.com/tzechuen/appstore-earnings-cli/releases):\n\n| Platform | Binary |\n|----------|--------|\n| macOS (Apple Silicon) | `appstore-earnings-darwin-arm64` |\n| macOS (Intel) | `appstore-earnings-darwin-x64` |\n| Linux x64 | `appstore-earnings-linux-x64` |\n| Linux ARM64 | `appstore-earnings-linux-arm64` |\n| Windows x64 | `appstore-earnings-windows-x64.exe` |\n\nThen make it executable and move to your PATH:\n\n```bash\nchmod +x appstore-earnings-darwin-arm64\nsudo mv appstore-earnings-darwin-arm64 /usr/local/bin/appstore-earnings\n```\n\n### Option 3: Build from Source\n\nRequires [Bun](https://bun.sh) installed.\n\n```bash\ngit clone https://github.com/tzechuen/appstore-earnings-cli.git\ncd appstore-earnings-cli\nbun install\nbun run build\n# Binary is now at ./bin/appstore-earnings\n```\n\n## Setup\n\n### First-Time Configuration\n\nRun the setup wizard to configure your API credentials:\n\n```bash\nappstore-earnings --setup\n```\n\nThe wizard will guide you through:\n1. Entering your App Store Connect API credentials\n2. Copying your `.p8` key files to a secure location\n3. Setting your preferred currency\n\n### Configuration Options\n\nConfiguration is loaded in priority order:\n\n1. **Environment variables** (highest priority)\n2. **`.env` file** in current working directory\n3. **Config file** at `~/.config/appstore-earnings-cli/config.json`\n\n#### Environment Variables\n\n```bash\n# Required: Finance API Key\nexport ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nexport ASC_KEY_ID=XXXXXXXXXX\nexport ASC_PRIVATE_KEY_PATH=/path/to/AuthKey_XXXXXXXXXX.p8\nexport ASC_VENDOR_NUMBER=12345678\n\n# Optional: App Manager API Key (for grouping IAPs under apps)\nexport ASC_APP_MANAGER_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nexport ASC_APP_MANAGER_KEY_ID=YYYYYYYYYY\nexport ASC_APP_MANAGER_PRIVATE_KEY_PATH=/path/to/AuthKey_YYYYYYYYYY.p8\n\n# Optional: Target currency (default: USD)\nexport TARGET_CURRENCY=USD\n\n# Optional: Custom cache directory\nexport ASC_CACHE_DIR=/path/to/cache\n```\n\n#### Config File Format\n\n`~/.config/appstore-earnings-cli/config.json`:\n\n```json\n{\n  \"issuerId\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n  \"keyId\": \"XXXXXXXXXX\",\n  \"privateKeyPath\": \"keys/AuthKey_XXXXXXXXXX.p8\",\n  \"vendorNumber\": \"12345678\",\n  \"targetCurrency\": \"USD\",\n  \"appManagerIssuerId\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n  \"appManagerKeyId\": \"YYYYYYYYYY\",\n  \"appManagerPrivateKeyPath\": \"keys/AuthKey_YYYYYYYYYY.p8\"\n}\n```\n\n### Private Key Handling\n\nThe CLI supports multiple ways to provide your private key:\n\n1. **Absolute path**: `/Users/me/keys/AuthKey.p8`\n2. **Relative to config directory**: `keys/AuthKey.p8` (relative to `~/.config/appstore-earnings-cli/`)\n3. **Relative to current directory**: `./AuthKey.p8`\n4. **Base64 encoded** (for CI/CD): `base64:LS0tLS1CRUdJTi...`\n\n### Creating API Keys\n\nYou need **one required key** and **one optional key**:\n\n#### Required: Finance API Key\n\nThis key is used to download financial reports.\n\n1. Go to [App Store Connect](https://appstoreconnect.apple.com)\n2. Navigate to **Users and Access** \u003e **Integrations** \u003e **App Store Connect API**\n3. Click **+** to generate a new API key\n4. Name it something like \"Earnings CLI - Finance\"\n5. Select **Finance** access level\n6. Click **Generate**\n7. **Download the `.p8` file immediately** - you can only download it once!\n8. Note the **Key ID** and **Issuer ID**\n\n#### Optional: App Manager API Key\n\nThis key enables grouping of In-App Purchases under their parent apps. Without it, earnings are shown as a flat list.\n\n1. Create another API key following the same steps\n2. Name it \"Earnings CLI - App Manager\"\n3. Select **App Manager** access level (or **Admin** if you prefer)\n4. Download and save the `.p8` file separately\n\n### Finding Your Vendor Number\n\n1. In App Store Connect, go to **Payments and Financial Reports**\n2. Click on **Payments** or **Financial Reports**\n3. Your Vendor Number is displayed in the top-right area (it's a numeric ID like `12345678`)\n\n## Usage\n\n### Basic Usage\n\n```bash\nappstore-earnings\n```\n\nThis will:\n1. Show an interactive menu to select a month\n2. Download (or use cached) financial report for that month\n3. Convert all proceeds to your target currency\n4. Display earnings grouped by app\n\n### CLI Options\n\n```bash\n# Bypass cache and re-download the report\nappstore-earnings --no-cache\n\n# Refresh the app/IAP mapping cache\nappstore-earnings --refresh-mapping\n\n# Run the setup wizard\nappstore-earnings --setup\n\n# Show configuration status\nappstore-earnings --status\n\n# Enable debug output\nDEBUG=1 appstore-earnings\n```\n\n### Cache Locations\n\nCache files are stored in XDG-compliant locations:\n\n- **Reports**: `~/.cache/appstore-earnings-cli/reports/`\n- **Product mapping**: `~/.cache/appstore-earnings-cli/product-mapping.json`\n\nYou can override the cache location with `ASC_CACHE_DIR`.\n\n## How It Works\n\n### Data Source\n\nThe CLI uses Apple's [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi) to download **Financial Reports**. These reports contain actual payment amounts that match what Apple deposits to your bank account.\n\n### Two API Keys Explained\n\nApple's API requires different access levels for different endpoints:\n\n| Endpoint | Required Role | Purpose |\n|----------|---------------|---------|\n| Financial Reports | Finance | Download monthly earnings data |\n| Apps, IAPs, Subscriptions | App Manager | Fetch app/IAP relationships for grouping |\n\nIf you only configure the Finance key, earnings will be shown as a flat list without grouping IAPs under their parent apps.\n\n### Currency Conversion\n\nProceeds from App Store sales come in different currencies depending on the storefront. The CLI fetches exchange rates from the [Frankfurter API](https://www.frankfurter.app/) (uses European Central Bank rates) and converts everything to your target currency.\n\n**Note:** Exchange rates may differ slightly from Apple's actual conversion rates, so totals may not match your bank deposits exactly.\n\n### Payment Info\n\nThe CLI displays estimated payment date and status for each month. Payment information is automatically extracted from the financial report.\n\n**Important:** Apple's Finance Reports API does not include actual payment dates - this information is only visible in the App Store Connect web interface. The CLI **estimates** payment status based on Apple's typical payment schedule (~33 days after the fiscal month ends). Actual payment dates may vary slightly.\n\n## Troubleshooting\n\n### \"No report available for this period\"\n\nFinancial reports take a few days to become available after a month ends. Try selecting an earlier month.\n\n### \"Missing required configuration\"\n\nMake sure you've configured your credentials using one of:\n- `appstore-earnings --setup` (recommended)\n- Environment variables\n- `.env` file in current directory\n\n### \"Error reading private key\"\n\n- Check that the `.p8` file path is correct\n- Make sure the file exists and is readable\n- Try using an absolute path\n\n### \"401 Unauthorized\" or \"403 Forbidden\"\n\n- Verify your API key credentials are correct\n- Check that the API key has the required access level (Finance for reports)\n- Ensure the API key hasn't been revoked in App Store Connect\n\n### Flat list instead of grouped tree\n\nThis happens when the App Manager API key is not configured. Add the optional App Manager credentials to enable grouping.\n\n### Debug mode\n\nFor detailed error messages and API response previews:\n\n```bash\nDEBUG=1 appstore-earnings\n```\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh) 1.0 or higher\n\n### Running locally\n\n```bash\nbun install\nbun run start\n```\n\n### Building\n\n```bash\n# Build for current platform\nbun run build\n\n# Build for all platforms\nbun run build:all\n```\n\n## Security Notes\n\n- Never commit your `.env` file or `.p8` key files to version control\n- The `.gitignore` is configured to exclude these files\n- Store your `.p8` files securely - they provide access to your App Store Connect data\n- When using the setup wizard, keys are stored in `~/.config/appstore-earnings-cli/keys/`\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftzechuen%2Fappstore-earnings-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftzechuen%2Fappstore-earnings-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftzechuen%2Fappstore-earnings-cli/lists"}