Skip to content
Keywordee Docskeywordee.app

The keywordee command-line tool

The keywordee command-line tool lets your own scripts and cron jobs use your keywords, the way the MCP server lets an AI agent use them. It ships inside the Mac app.

It works through the Keywordee app on your Mac, so:

  • Keywordee must be open on the Mac where you run it, with the MCP server on.
  • It works only on that Mac. It is not a way to reach Keywordee from a server or another computer.
  • It sees the same tracked apps and keywords as the app, and uses your license like the app does, including the daily fair-use limits and read-only mode after a lapse. See Renewing and read-only.

Install

Section titled “Install”
  1. Open Keywordee › Settings › AI Agents and switch on Let AI agents use Keywordee on this Mac.
  2. Under Command-line tool, press Install next to ~/.local/bin. This links the tool bundled in the app as keywordee. If Terminal says command not found, add ~/.local/bin to your PATH. Install… next to /usr/local/bin does the same for every user and asks for your password.
  3. Uninstall removes the link. A file or link called keywordee that Keywordee didn’t make is never replaced or removed.

The link points into the app, so updating the app updates the tool. If you move the app, press Install again.

The first time, macOS may ask whether keywordee can use the “Keywordee” Keychain item that holds the connection token. Choose Always Allow.

Commands

Section titled “Commands”

keywordee --help lists them. keywordee help <command> or keywordee <command> --help describes one.

Command What it does Needs an active license
keywordee apps The apps tracked on this Mac No
keywordee metrics <term>… (--app <app> | --platform <p> --storefront <cc>) Popularity and difficulty for up to 100 terms, plus the app’s rank Only for terms this Mac doesn’t hold
keywordee history --app <app> [<term>…] [--days <n>] [--points] How rank, popularity and difficulty changed No
keywordee suggest [<seed>…] [--app <app>] [--platform <p> --storefront <cc>] [--limit <n>] Keyword ideas Yes
keywordee gems --app <app> [--platform <p>] [--seed <term>]… [--limit <n>] Untracked keywords that pass your gem rules Yes
keywordee track <term>… --app <app> [--tag <tag>] Track keywords and fetch their metrics Yes
keywordee tag <term>… --app <app> [--add <tag>]… [--remove <tag>]… [--note <text>] Change tags or the note Yes
keywordee export [--app <app>] [--format json|csv] Tracked keywords with their metrics No

An app is its name or id from keywordee apps, or its store app id. A name shared by several tracked apps (one product on iPhone and Android) matches them all: add --platform or --storefront to choose, or use the id. Platforms are iphone, ipad, mac, appletv, applevision and android. Storefronts are two-letter country codes.

Terms Keywordee hasn’t stored yet show as pending. Ask again in a few minutes.

Options on every command

Section titled “Options on every command”
Option What it does
--json Print the answer as JSON. Without it you get a table. Errors go to stderr, as JSON when --json is on.
--port <n> Use another port than the one in Keywordee’s settings.
-h, --help Show help.
--version Show the app’s version.

Options may come before or after the command, as --option value or --option=value. -- ends the options, so a term can start with -.

Examples

Section titled “Examples”
Terminal window
keywordee apps
keywordee metrics "habit tracker" budget --app "My App"
keywordee gems --app "My App" --platform iphone --limit 10
keywordee track "habit streak" "daily habits" --app "My App" --tag core
keywordee export --format csv > keywords.csv
keywordee apps --json | jq -r '.apps[].name'

Exit codes

Section titled “Exit codes”

A script can rely on these numbers.

Code Meaning
0 Success
1 Unexpected error
2 Wrong command line: unknown command or option, missing or invalid value
3 Keywordee isn’t running
4 The MCP server is off in Settings › AI Agents
5 No usable connection token: Keywordee refused it, or the Keychain wouldn’t give it up
6 The command needs an active license, and this Mac’s has lapsed, was disabled or isn’t activated
7 A daily fair-use limit was reached
8 The app or keywords aren’t tracked on this Mac, or the app name matches several
9 Keywordee’s keyword service couldn’t be reached or couldn’t answer

With --json, an error on stderr looks like this:

{ "error": { "code": "fair_use_cap_reached", "exitCode": 7, "message": "You've reached today's keyword fetches limit.", "cap": "keyword_fetches", "resetsAt": "2026-11-05T00:00:00Z" } }

With a lapsed license, metrics still prints what this Mac already holds before reporting the error.

For scripts

Section titled “For scripts”
  • KEYWORDEE_TOKEN supplies the connection token instead of the Keychain, and KEYWORDEE_PORT (or --port) the port. Don’t put the token on a command line: use the environment variable.
  • stdout carries the answer and nothing else. Messages for people go to stderr.
  • The tool talks only to your own Mac (127.0.0.1), with no proxy.

Your tracked keywords can also leave Keywordee as JSON or CSV with export, including on a schedule.