| name | krankie-rankings |
| description | Pull VivaDicta App Store keyword rankings via krankie (free, self-hosted), compare against the previous check, and write a dated rankings report to the Obsidian vault. Krankie-based replacement for asc-aso-rankings (no Astro subscription required). |
| argument-hint | ["optional notes","e.g. \"2 week check\""] |
ASO Rankings Check (krankie)
Pull keyword rankings with krankie instead of Astro MCP, compare against the previous check, and save a dated rankings file to the Obsidian vault.
This is the no-subscription replacement for asc-aso-rankings. krankie is MIT-licensed, stores history in local SQLite, and reads ranks from the public App Store search API. The trade-off vs Astro: krankie reports rank position only - no popularity or difficulty scores, and tracks the top 200 (Astro tracked top 250).
Architecture: VPS is the source of truth
- VPS (
lobster@openclawtail) runs krankie under a daily cron (krankie cron), so the SQLite DB there holds the continuous day-over-day history. This is canonical.
- MacBook also has krankie installed for ad-hoc local peeks, but its DB only has data from whenever it was last run - do not use it for the historical comparison.
- The vault is bidirectionally synced between the VPS (
/home/lobster/vault) and the MacBook (/Users/antonnovoselov/Documents/Vault), so a report written on either side appears on both.
Because the VPS holds the history and the previous_rank/rank_change columns krankie computes between checks, run the check + report on the VPS.
Tracked set (the documented strategy)
Track the 41 canonical keywords from the ASO strategy (see app-store-keywords.md change log) plus the brand term vivadicta, for the app 6758147238, on stores us, gb, ca, au. The same 41 keywords are tracked for 3 competitors on us only:
- Otter
1276437113
- Wispr Flow
6497229487
- Whisper Transcription
1668083311
The keyword list and competitor set live in ~/.krankie/ setup on the VPS; the report generator is ~/.krankie/kr_report.mjs.
Steps
1. Run a fresh check + generate the report (VPS)
ssh lobster@openclawtail 'export PATH="$HOME/.bun/bin:$PATH"; \
krankie check run --force >/dev/null 2>&1; \
REPORT_VERSION="<live-version>" bun ~/.krankie/kr_report.mjs'
krankie check run --force re-checks every tracked keyword now (ignores the 24h throttle).
kr_report.mjs reads krankie rankings --json, writes rankings/rankings-YYYY-MM-DD.md to the vault, and appends a row to the app-store-keywords.md index. Pass REPORT_VERSION to stamp the live metadata version (default 3.7.0).
- The generator prints the output path and a one-line summary.
2. Read the produced report
The file syncs to the MacBook at:
/Users/antonnovoselov/Documents/Vault/Projects/VivaDicta/ASO/rankings/rankings-YYYY-MM-DD.md
If sync lag is a problem, scp it back: scp lobster@openclawtail:/home/lobster/vault/Projects/VivaDicta/ASO/rankings/rankings-YYYY-MM-DD.md /tmp/.
3. Compare against the previous check
The report's Change column already reflects krankie's previous_rank (the prior check, i.e. yesterday under cron). For a longer-horizon comparison, read the previous dated rankings-*.md and diff:
- Improved: rank moved closer to #1 (or entered top 200 =
NEW)
- Declined: rank moved away from #1 (or fell out of top 200 =
DROPPED)
- Stable: unchanged or +/- a few positions
4. Present the comparison report
### Rankings Check: YYYY-MM-DD (krankie) (vs previous: YYYY-MM-DD)
**Overall:** X/41 ranked (was A/41)
**Improved:** keywords that moved up
**Declined:** keywords that moved down
**New rankings:** keywords that entered top 200
**Best performer:** "{keyword}" at #{rank}
**Biggest gain:** "{keyword}" +{positions}
### vs Competitors (US)
| Keyword | VivaDicta | Otter | Wispr Flow | Whisper Trans. |
...
### Gap opportunities (competitors rank, we don't)
- keywords where a competitor is top-50 and VivaDicta is unranked
Report format
kr_report.mjs emits three sections:
- VivaDicta Rankings (US store) -
| Keyword | Rank | Prev | Change |, sorted ranked-first then unranked by best-competitor-rank (gap priority).
- Competitors (US store) -
| Keyword | VivaDicta | Otter | Wispr Flow | Whisper Trans. |.
- International reach - VivaDicta US/GB/CA/AU for any keyword ranked in any store.
No frontmatter (raw reference file), matching the existing rankings-*.md convention.
Fallback: MacBook-local (VPS unreachable / Tailscale down)
krankie is also installed on the MacBook (~/.bun/bin/krankie). You can run an ad-hoc check locally, but it lacks the VPS's day-over-day history, so Change will be empty/NEW:
krankie check run --force
krankie rankings --json
Then hand-build the report in the April format.
Notes
- Rankings take 1-2 weeks to settle after a metadata change.
- krankie ranks 1-200; blank = not in top 200. Lower is better.
- Recommended cadence: the VPS cron checks daily; generate a vault report weekly, or on demand right after a metadata change.
- No popularity/difficulty - prioritize gaps by competitor rank (a keyword Otter/Wispr win and we don't) instead of by Astro popularity.
- Related:
krankie-audit (offline metadata checks + competitor rank-gap analysis).