AppClimb

<p align="center"> <img src="Website/public/assets/appclimb-icon.png" width="96" alt="AppClimb app icon"> </p> <h1 align="center">AppClimb</h1> <p align="center"><strong>Know what to fix next in the App Store.</strong></p> <p align="center"> AppClimb turns live rankings, competitors, reviews, metadata and revenue signals into a focused growth workspace for indie developers and small app teams. </p> <p align="center"> <a href="https://github.com/skverall/AppClimb/releases/latest/download/AppClimb-macOS.dmg"><strong>Download AppClimb v0.3.5</strong></a> · <a href="https://appclimb.app">Website</a> · <a href="#ai-ready-workflows">AI workflows</a> </p> <p align="center"> <a href="https://github.com/skverall/AppClimb/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/skverall/AppClimb?style=flat-square&color=6c3df4"></a> <img alt="macOS 14 or later" src="https://img.shields.io/badge/macOS-14%2B-15142b?style=flat-square&logo=apple"> <img alt="Universal Apple Silicon and Intel" src="https://img.shields.io/badge/Mac-Apple%20Silicon%20%2B%20Intel-6c3df4?style=flat-square"> <img alt="Swift 5.9" src="https://img.shields.io/badge/Swift-5.9-f05138?style=flat-square&logo=swift&logoColor=white"> <img alt="MCP stdio" src="https://img.shields.io/badge/MCP-stdio-35a76e?style=flat-square"> </p> <p align="center"> <img src="docs/assets/appclimb-overview-v0.3.2.png" alt="AppClimb Overview showing App Store rank, next move, business pulse and growth history" width="1200"> </p> <p align="center">_{One signed and notarized Universal download for Apple Silicon and Intel Macs.}</p> ## Your App Store growth loop, in one place Most ASO tools give you more charts. AppClimb connects the signals and tells you what deserves attention now: a keyword gap, a slipping rank, a weak storefront, or the next metadata experiment worth running. - **See the whole climb.** Rankings, reviews, revenue and website conversion sit beside each other instead of living in separate dashboards. - **Move from signal to action.** The ASO Command Center turns real changes into a short, prioritized next-move list. - **Keep control of your data.** The complete local toolkit works for free; optional Pro hosting adds sync, server monitoring and alerts while your Mac is off. - **Bring your AI agent.** The included CLI and MCP server let Codex, Claude Code and other compatible tools read the same workspace without scraping the UI. ## What AppClimb does - **Live App Store rank tracking & Historical Charts** Pulls real iTunes Search API results for tracked keywords, up to the public top-200 depth, visualized with beautiful interactive charts powered by SwiftUI Swift Charts. - **Apple Search Ads Campaigns Integration** Track search campaigns, target keyword bids, impressions, conversion rates, and spend metrics. Supports secure JWT authentication with certificate key uploads. - **CoreGraphics PDF & CSV Reporting** Export your keyword rankings and campaign summaries as beautifully formatted, branded PDF reports or raw CSV logs for stakeholder review. - **Web Analytics (DataFast-style)** Track your landing pages without cookies: visitors, traffic channels (search, social, AI assistants, email, paid), top pages, devices, browsers, live visitors, custom goals, and automatic site→App Store click tracking. One script tag to install — see [docs/web-analytics.md](docs/web-analytics.md). - **ASO Command Center** Converts live rank gaps, suggestions, competitor pressure, and regional health into next-best-action cards. - **Localized Metadata Studio** Draft App Name, Subtitle, Keywords, Promotional Text, and Description by storefront and language. Switch languages, track character limits, preview keyword chips, and copy fields directly into App Store Connect. - **Competitor discovery** See which apps appear across your tracked searches, where they outrank you, and which gaps deserve metadata space. - **Customer reviews and rating health** Read the latest App Store reviews per storefront, filter by stars, and keep an eye on the listing-wide rating — critical reviews are highlighted. - **Background monitoring with alerts** While AppClimb runs, every tracked app and region is re-checked on a schedule. Significant rank moves, top-200 entries/drops and new 1–2★ reviews arrive as macOS notifications and collect in a menu-bar panel alongside live website visitors. - **Business pulse on one screen** The app Overview shows rating, RevenueCat revenue, website visitors, conversion and site→App Store clicks next to your rankings, so the whole funnel is visible at once. - **Experiment timeline** Start ASO experiments with baseline rank metrics, affected metadata fields, target keywords, review dates, and status tracking. - **AI-ready access** `appclimbctl` and `appclimb-mcp` expose your local workspace to AI coding agents without scraping the UI. - **First-run setup and demo workspace** New users can connect their own AI provider, choose a storefront, add a real App Store listing, or open a complete demo workspace before touching live data. ## Download AppClimb ### Recommended: Universal Mac app Download the latest signed Universal build. The same installer runs natively on Apple Silicon and Intel Macs: [**Download AppClimb v0.3.5 (.dmg)**](https://github.com/skverall/AppClimb/releases/latest/download/AppClimb-macOS.dmg) · [ZIP alternative](https://github.com/skverall/AppClimb/releases/latest/download/AppClimb-macOS.zip) · [Release notes](https://github.com/skverall/AppClimb/releases/latest) Open `AppClimb.app`, then follow **First Launch Setup** to choose your AI provider, save your API key in Keychain, and add your first app. Published downloads are signed with Developer ID and notarized by Apple, so they open normally without a right-click workaround. ### Build and run from source ```bash git clone https://github.com/skverall/AppClimb.git cd AppClimb ./script/build_and_run.sh ``` The app stores its workspace at: ```text ~/Library/Application Support/AppClimb/workspace.json ``` ### Install CLI And MCP Tools ```bash PREFIX=/usr/local ./script/install_tools.sh ``` If `/usr/local/bin` needs admin rights: ```bash sudo PREFIX=/usr/local ./script/install_tools.sh ``` The script installs: ```text /usr/local/bin/appclimbctl /usr/local/bin/appclimb-mcp ``` ## CLI Examples List tracked apps: ```bash appclimbctl apps ``` Get the ASO action plan: ```bash appclimbctl aso-plan --app Vaqt --region US ``` Inspect the same deterministic actions shown on Mac and iPhone: ```bash appclimbctl actions --app Vaqt --region US appclimbctl action-status --write --id ACTION_ID --status snoozed ``` Read the versioned ecosystem demo without touching production data: ```bash appclimbctl demo ``` Read Russian metadata draft: ```bash appclimbctl metadata --app Vaqt --region US --lang ru ``` Update one localized field: ```bash appclimbctl set-metadata --write \ --app Vaqt \ --region US \ --lang ru \ --field description \ --value "Localized App Store description..." ``` Export copy-ready App Store Connect metadata: ```bash appclimbctl export-metadata --app Vaqt --region US --lang ru ``` Use another workspace file: ```bash APPCLIMB_WORKSPACE_PATH=/path/to/workspace.json appclimbctl apps ``` ## AI-ready workflows ### MCP for Codex and Claude AppClimb includes a stdio MCP server: ```bash appclimb-mcp ``` ### Codex ```bash codex mcp add appclimb -- /usr/local/bin/appclimb-mcp ``` ### Claude Desktop Add this to your Claude Desktop MCP config: ```json { "mcpServers": { "appclimb": { "command": "/usr/local/bin/appclimb-mcp" } } } ``` ### MCP Tools The server exposes: - `list_apps` - `get_aso_plan` - `get_keywords` - `get_competitors` - `get_metadata_draft` - `update_metadata_draft` - `export_metadata` - `list_experiments` - `start_experiment` Example prompt for an AI agent: ```text Use AppClimb MCP. Read Vaqt in US, inspect the ASO plan and Russian metadata draft, then propose a better Russian subtitle and description. Do not update anything until I approve. ``` ## Bring Your Own AI Key Keyword Suggestions and the weekly Digest work with OpenAI-compatible `/chat/completions` providers. Open the macOS app, go to **Settings -> AI Model**, choose a provider, paste your own API key, save it to Keychain, and press **Test**. Included presets: - DeepSeek: `https://api.deepseek.com` / `deepseek-v4-flash` - OpenRouter: `https://openrouter.ai/api/v1` / `~openai/gpt-latest` - OpenAI: `https://api.openai.com/v1` / `gpt-5.5` - Z.AI / GLM: `https://api.z.ai/api/paas/v4` / `glm-5.2` - xAI Grok: `https://api.x.ai/v1` - Together AI: `https://api.together.xyz/v1` / `MiniMaxAI/MiniMax-M3` - Custom: any OpenAI-compatible base URL and model name API keys are stored in the macOS Keychain, not in the workspace JSON or Git repo. If you prefer environment variables, AppClimb checks: ```text APPCLIMB_AI_API_KEY DEEPSEEK_API_KEY OPENROUTER_API_KEY OPENAI_API_KEY ZAI_API_KEY XAI_API_KEY TOGETHER_API_KEY ``` CLI and MCP features do not require an AI key unless a future tool explicitly runs an AI-backed operation. ## Cloud Accounts And Integrations The app includes a native Account window with Google OAuth through the self-hosted AppClimb API on Hostinger. Supabase and Appwrite Cloud are not runtime dependencies. The API uses Authorization Code + PKCE, stores only hashed refresh tokens, and keeps each account's data in a private PostgreSQL database. See [`docs/cloud-accounts.md`](docs/cloud-accounts.md) for the public contract and [`Backend/README.md`](Backend/README.md) for operations. The Keychain-backed Integration Center supports App Store Connect, RevenueCat, and Apple Search Ads credentials locally. Production configuration and security rules are documented in [`docs/cloud-accounts.md`](docs/cloud-accounts.md). App Store Connect credentials are loaded from Keychain first. For development and release automation, AppClimb also supports `~/Library/Application Support/AppClimb/asc-credentials.json` as a fallback; keep it user-only (`chmod 600`) and prefer `privateKeyPath` over embedding the private key. Notarized releases can be produced with `./script/release.sh`; see [`docs/releasing.md`](docs/releasing.md). ### Cloud Sync (macOS) After signing in to your AppClimb account (Account window → Continue with Google), open the **Cloud Sync** section. On first connect, choose: - **Upload local to cloud** — pushes your current local workspace to the cloud (creates the first cloud copy at revision 0). - **Download from cloud** — replaces your local workspace with the cloud copy. A timestamped local backup is written to `~/Library/Application Support/AppClimb/Backups/` first. After setup, the app syncs local changes automatically with a short debounce, and a **Sync Now** button is always available. Sync uses optimistic concurrency via `expected_revision`: if another device saved a newer revision, the app surfaces a **conflict** and asks you to choose *Keep local* or *Keep cloud* — it never silently overwrites. Integration credentials and AI API keys are stored in Keychain and are never included in the workspace JSON that syncs to the cloud. ## Cloud Sync Contract AppClimb cloud sync is designed around four invariants: 1. **Identity.** Every workspace document carries a `workspaceID` and an `ownerAccountID`. The backend stores a server-side `workspace_id` that is immutable after first upload. If the client's id ever diverges from the server's, sync stops and surfaces a "needs initial decision" state rather than risking cross-account data leakage. 2. **Persisted base.** Each account has a local `sync-metadata.json` recording the last cloud revision and document hash the client has acknowledged. Absence of this file means local and cloud histories have not been reconciled, and **no automatic upload is issued** until the user explicitly chooses Upload or Download. 3. **No silent overwrite.** When the cloud moves ahead while local also has changes, sync surfaces a conflict. Picking a side first downloads a backup of the side being replaced and archives it server-side in `workspace_revisions`. The destructive action is gated behind an explicit "I understand" toggle. 4. **Archive before overwrite.** Every successful cloud PUT, including `keep_local`, `keep_cloud`, and `restore`, archives the prior document into `workspace_revisions` with a timestamp, source device id, and operation tag. Revisions are listable via `GET /v1/workspace/revisions` and restorable via `POST /v1/workspace/revisions/{id}/restore`. Local workspace files are account-scoped under `~/Library/Application Support/AppClimb/Accounts/<accountID>/`. Signing out never deletes them; signing in as a different account loads that account's own files. ## Development Build everything: ```bash swift build ``` Run the app bundle: ```bash ./script/build_and_run.sh ``` Verify the app launches: ```bash ./script/build_and_run.sh --verify ``` Package a local release using the canonical version in [`VERSION`](VERSION): ```bash ./script/package_release.sh ``` ### Website ```bash cd Website npm install npm run dev ``` Create a production build with `npm run build`. The early-access form posts to the AppClimb backend's `POST /v1/waitlist` endpoint. The API base URL is configured via the `VITE_API_URL` environment variable (see `Website/.env.example`). For local development against a running Go backend: ```bash cp Website/.env.example Website/.env.local # defaults to http://localhost:8080 cd Website && npm run dev ``` For production, set `VITE_API_URL` to the deployed API URL before building. **Note:** the waitlist endpoint only accepts real signups once the backend is deployed and migrated — see [Backend/README.md](Backend/README.md). Until then the form surfaces an error on submit. ### iPhone app The iOS companion app lives in `iOS/AppClimbMobile`. It is a **read-only** view of your cloud ASO workspace: sign in with Google, see your tracked apps, keyword ranks, and experiments, with offline cache and pull-to-refresh. ```bash cd iOS/AppClimbMobile xcodegen generate open AppClimbMobile.xcodeproj ``` Build and run tests from the command line (DerivedData on an external volume): ```bash cd iOS/AppClimbMobile xcodebuild -project AppClimbMobile.xcodeproj -scheme AppClimbMobile \ -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \ -derivedDataPath /Volumes/LexarDev/Developer/Temp/AppClimbDerivedData build ``` The app includes the Today dashboard, keyword movement, experiment tracking, settings, the AppClimb mascot, and the production icon master. A clearly labelled **Demo Mode** loads sample data without signing in. Editing metadata and starting experiments is not available on iPhone in this beta — those actions show an honest "Continue on Mac" prompt. Release artifacts are written to: ```text dist/release/ ``` Publish a signed, notarized Universal GitHub Release through the release workflow: ```bash gh workflow run notarized-release.yml -f version="$(< VERSION)" ``` The workflow creates the version tag and GitHub Release, then uploads the notarized `.dmg`, app `.zip`, stable latest-download assets, and CLI/MCP tools. Build release tools: ```bash swift build -c release --product appclimbctl swift build -c release --product appclimb-mcp ``` ## Data Safety AppClimb keeps all workspace data locally by default. When you enable Cloud Sync (see above), the workspace JSON syncs to your private AppClimb cloud workspace; account sessions, AI API keys, and integration credentials always stay in Keychain and are never included in the synced document. The MCP server and CLI read the same local JSON file as the app. They do not upload your data anywhere by themselves. For safe testing, copy the workspace and point tools at the copy: ```bash cp "$HOME/Library/Application Support/AppClimb/workspace.json" /tmp/workspace.json APPCLIMB_WORKSPACE_PATH=/tmp/workspace.json appclimbctl set-metadata --write ... ``` ## Known Limitations (First Beta) - **iOS intentionally supports only low-risk edits.** It can triage actions, move an experiment review date, add an observation note, record a review decision, and quickly watch a keyword through the revision-protected cloud API. Metadata, integrations, bulk research, and conflict resolution remain Mac workflows. Cached/offline work never reports a false successful save. - **Cloud sync is opt-in.** Local-only operation remains the default; sync activates only after you sign in and choose an initial upload or download. - **Auto-sync debounces.** Rapid edits are batched into one upload after a short delay; conflicts are surfaced, never silently overwritten. ## Requirements - macOS 14+ - Swift 5.9+ - App Store data access through Apple's public iTunes Search API - Optional: your own AI API key for keyword Suggestions and the weekly Digest