Ranksy CLI

ranksy is a command-line tool for running Ranksy from your terminal, a shell script, or CI. Every command maps to an API endpoint and prints either a table or raw JSON, so it drops into bash, cron, and pipelines without any glue code.

It's a scriptable alternative to the AI assistant (MCP) connection. Same data, no conversation.

Install

curl -LsSf https://ranksyapp.com/cli-installer.sh | sh

Prebuilt binaries for Linux, macOS, and Windows are published on GitHub Releases. To upgrade later, run ranksy update, or ranksy update --check to see whether a newer version exists without installing it.

Authenticate

The CLI uses the same API key as the Developer API. Create one under Settings → API Keys, then:

ranksy login rk_live_xxx

That writes the key to ~/.config/ranksy/config.toml, readable only by you. For CI, set an environment variable instead:

export RANKSY_API_KEY=rk_live_xxx

If both are set, the --api-key flag wins, then RANKSY_API_KEY, then the config file.

ranksy also reads a .env file in the current directory (walking up parent folders) at startup, so a project-local RANKSY_API_KEY (and RANKSY_BASE_URL) is picked up without exporting it. A variable already exported in your shell still wins over the .env file.

⚠️ Treat the key like a password. Use a key scoped to only what the script needs, and never commit it.

First Commands

ranksy whoami                                  # which apps this key can reach
ranksy apps list
ranksy --app 01HZX9ABCDEF rankings get         # current keyword rankings
ranksy --app 01HZX9ABCDEF keywords list        # tracked keywords
ranksy --app 01HZX9ABCDEF reviews list
ranksy --app 01HZX9ABCDEF installs get

--app takes the app's ID, which you'll find in ranksy apps list. Most commands need it. To stop typing it, add a line to ~/.config/ranksy/config.toml:

app = "01HZX9ABCDEF"

What Else It Can Pull

Beyond rankings and reviews, the CLI reaches the same customer and traffic data as the dashboard:

Run ranksy <command> --help for the flags on any of them.

Scripting and CI

Add --json to any command and you get the raw API response instead of a table:

ranksy --app 01HZX9ABCDEF keywords list --json | jq '.data[0].organic_rank'

Other flags worth knowing:

• --watch 60 re-runs the command every 60 seconds, handy for keeping a ranking check open on a second monitor
• --base-url points the CLI at a different API base, which you'll rarely need
• -q suppresses everything but the result

Exit codes are stable, so CI can gate on them: 0 for success, 2 for a usage mistake, 1 for an API or runtime failure.

Track Keywords and Read Your Listing

The CLI can change what you track, not just read data:

ranksy --app 01HZX9ABCDEF keywords track "email marketing"     # start tracking (needs keywords:write)
ranksy --app 01HZX9ABCDEF keywords untrack "email marketing"   # stop tracking (text or slug)
ranksy --app 01HZX9ABCDEF listing get                          # your store listing (needs apps:read)

untrack accepts either the keyword text or its slug. If a keyword's slug ever collided when it was tracked (a rare hyphen-plus-suffix case), untrack it with the exact slug shown in keywords list.

CLI, API, or AI Assistant?

Three ways into the same data:

• CLI for scripts, cron jobs, and CI checks. One binary, no code to write.
• Developer API for building Ranksy data into your own app. Full request and response reference at api.ranksyapp.com.
• AI assistant (MCP) for asking questions in plain English and getting charts back.