Rank Math SEO from the terminal: bulk meta edits, site-wide SEO audits, Search Console analytics, and IndexNow — with no bridge plugin.
Talks to Rank Math's own REST routes on your WordPress site using a WordPress application password. Adds a local store so audit, coverage, and reindex can answer site-wide questions that the Rank Math admin answers one post at a time.
Learn more at Rank Math.
Created by @ElizabethcStone.
Authentication
Rank Math has no hosted API: each WordPress site exposes its own routes under /wp-json/rankmath/v1. Set RANKMATH_SITE to the site host (for example example.com). For commands that need an account, create an Application Password in wp-admin (Users → Profile → Application Passwords) and export RANKMATH_USERNAME and RANKMATH_APP_PASSWORD, or save them with the auth set-credentials subcommand (username, then application password) and check them with auth status. Without credentials, only posts, pages, sync, audit, head get, and doctor modules work. gsc, indexing, coverage, opportunities, portfolio, link-genius, and every meta/schema/redirection/settings write need an account with Rank Math capabilities. The doctor modules subcommand (pass the site hosts) shows which Rank Math modules (Analytics, Instant Indexing, Link Genius, headless getHead) a site exposes.
Quick Start
# Check config and credentials without network access
rankmath-pp-cli doctor --dry-run
# Pull the post inventory into the local store
rankmath-pp-cli sync --resources posts,pages --since 7d
# List SEO tag problems across the synced posts
rankmath-pp-cli audit --agent --select issues.url,issues.issue
# Preview which edited posts would be sent to IndexNow
rankmath-pp-cli reindex --since 7d
Unique Features
Site-wide SEO health
-
audit — One list of every synced post with a missing or duplicate SEO title or description, long title, canonical problem, accidental noindex, or no schema. Works on public pages without credentials; run sync first.
Reach for this before any bulk meta edit to get a structured fix list instead of scraping pages one by one.
rankmath-pp-cli audit --agent --select issues.url,issues.issue
-
coverage — Find published posts Google has not indexed or never inspected, excluding intentionally noindexed pages. Needs credentials and Rank Math Analytics connected to Search Console.
Use it to answer which real content is missing from Google rather than reading raw inspection rows.
rankmath-pp-cli coverage --agent --select gaps.url,gaps.verdict
Edit, verify, index
-
reindex — Preview the posts edited since a given window that are not yet in the IndexNow log; --confirm plus credentials submits them.
Run after a batch of edits to get fresh pages crawled without resubmitting the whole site.
rankmath-pp-cli reindex --since 7d
-
opportunities — Queries ranking in positions 4-20 whose post title or description does not mention the query. Needs credentials and Rank Math Analytics connected to Search Console.
Use it to pick which titles to rewrite next with evidence from real search demand.
rankmath-pp-cli opportunities --min-impressions 100 --agent
Multi-site
-
portfolio — Clicks, impressions, and average position for each site in --sites (or RANKMATH_SITES) in one table. Needs credentials per site.
Use it for a multi-site weekly check instead of logging into each wp-admin.
rankmath-pp-cli portfolio --agent
Recipes
Fix list for an agent
rankmath-pp-cli audit --agent --select issues.url,issues.issue
After sync, a structured list of posts with SEO tag problems, narrowed to the two fields an agent needs.
Post-edit indexing
rankmath-pp-cli reindex --since 24h
Preview which posts edited in the last day would go to IndexNow; add --confirm to send.
What Google is missing
rankmath-pp-cli coverage --agent --select gaps.url,gaps.verdict
Published posts that are not indexed, excluding intentional noindex (needs credentials and Search Console connected).
Search the local post inventory
rankmath-pp-cli search "retreat" --type posts --limit 10
Offline full-text search across posts pulled in by sync.
Bulk-edit SEO titles from a CSV
rankmath-pp-cli meta import --file titles.csv --json
Preview the rows a CSV of id,title,description,focus_keyword would send to Rank Math's bulk meta route; add --apply (with credentials) to write.
Usage
Run rankmath-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
RANKMATH_CONFIG_DIR, RANKMATH_DATA_DIR, RANKMATH_STATE_DIR, or RANKMATH_CACHE_DIR
--home <dir> for this invocationRANKMATH_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export RANKMATH_HOME=/srv/rankmath
rankmath-pp-cli doctor
Under RANKMATH_HOME=/srv/rankmath, the four dirs resolve to /srv/rankmath/config, /srv/rankmath/data, /srv/rankmath/state, and /srv/rankmath/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"rankmath": {
"command": "rankmath-pp-mcp",
"env": {
"RANKMATH_HOME": "/srv/rankmath"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as RANKMATH_DATA_DIR overrides an explicit --home for that kind. Use RANKMATH_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting RANKMATH_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run rankmath-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
rankmath-pp-cli doctor modules - Which Rank Math modules (Analytics, Instant Indexing, Link Genius, headless getHead) each site in --sites exposes, from the public route index
ai_visibility
Manage ai visibility
rankmath-pp-cli ai-visibility brands-generate-queries - Rank Math ai-visibility: brands generate queriesrankmath-pp-cli ai-visibility create-brands - Rank Math ai-visibility: create brandsrankmath-pp-cli ai-visibility get-brands - Rank Math ai-visibility: get brandsrankmath-pp-cli ai-visibility get-brands-insights - Rank Math ai-visibility: get brands insightsrankmath-pp-cli ai-visibility get-brands-queries - Rank Math ai-visibility: get brands queriesrankmath-pp-cli ai-visibility overview - Rank Math ai-visibility: overviewrankmath-pp-cli ai-visibility update-brands - Rank Math ai-visibility: update brandsrankmath-pp-cli ai-visibility update-brands-queries - Rank Math ai-visibility: update brands queries
backup
Manage backup
rankmath-pp-cli backup export-settings - Rank Math backup: export settingsrankmath-pp-cli backup get-view-data - Rank Math backup: get view datarankmath-pp-cli backup run - Rank Math backup: run backup
dashboard
Manage dashboard
rankmath-pp-cli dashboard search-intent - Rank Math dashboard: search intentrankmath-pp-cli dashboard widget - Rank Math dashboard: dashboard widget
gsc
Manage gsc
rankmath-pp-cli gsc add-track-keyword - Rank Math gsc: add track keywordrankmath-pp-cli gsc analytics-summary - Rank Math gsc: analytics summaryrankmath-pp-cli gsc auto-add-focus-keywords - Rank Math gsc: auto add focus keywordsrankmath-pp-cli gsc dashboard - Rank Math gsc: dashboardrankmath-pp-cli gsc delete-tracked-keywords - Rank Math gsc: delete tracked keywordsrankmath-pp-cli gsc get-desktop-pagespeed - Rank Math gsc: get desktop pagespeedrankmath-pp-cli gsc get-keyword-pages - Rank Math gsc: get keyword pagesrankmath-pp-cli gsc get-mobile-pagespeed - Rank Math gsc: get mobile pagespeedrankmath-pp-cli gsc get-page-seoscore - Rank Math gsc: get page seoscorerankmath-pp-cli gsc get-post - Rank Math gsc: get postrankmath-pp-cli gsc get-tracked-keyword-summary - Rank Math gsc: get tracked keyword summaryrankmath-pp-cli gsc get-tracked-keywords - Rank Math gsc: get tracked keywordsrankmath-pp-cli gsc get-tracked-keywords-rows - Rank Math gsc: get tracked keywords rowsrankmath-pp-cli gsc inspection-results - Rank Math gsc: inspection resultsrankmath-pp-cli gsc inspection-stats - Rank Math gsc: inspection statsrankmath-pp-cli gsc keywords-overview - Rank Math gsc: keywords overviewrankmath-pp-cli gsc keywords-rows - Rank Math gsc: keywords rowsrankmath-pp-cli gsc keywords-summary - Rank Math gsc: keywords summaryrankmath-pp-cli gsc posts-overview - Rank Math gsc: posts overviewrankmath-pp-cli gsc posts-rows - Rank Math gsc: posts rowsrankmath-pp-cli gsc posts-rows-by-objects - Rank Math gsc: posts rows by objectsrankmath-pp-cli gsc posts-summary - Rank Math gsc: posts summaryrankmath-pp-cli gsc remove-track-keyword - Rank Math gsc: remove track keywordrankmath-pp-cli gsc tracked-keywords-overview - Rank Math gsc: tracked keywords overview
head
Manage head
rankmath-pp-cli head - Rendered Rank Math head tags for a URL (needs headless support enabled)rankmath-pp-cli head get - Rendered SEO head tags for any URL: uses getHead when headless support is on, otherwise parses the page (no credentials needed)
indexing
Manage indexing
rankmath-pp-cli indexing clear-log - Rank Math indexing: clear logrankmath-pp-cli indexing get-log - Rank Math indexing: get logrankmath-pp-cli indexing submit-urls - Rank Math indexing: submit urls
link_genius
Manage link genius
rankmath-pp-cli link-genius audit-mark-safe - Rank Math link-genius: audit mark saferankmath-pp-cli link-genius audit-recheck - Rank Math link-genius: audit recheckrankmath-pp-cli link-genius audit-start - Rank Math link-genius: audit startrankmath-pp-cli link-genius audit-stats - Rank Math link-genius: audit statsrankmath-pp-cli link-genius bulk-actions-restore - Rank Math link-genius: bulk actions restorerankmath-pp-cli link-genius bulk-update-apply - Rank Math link-genius: bulk update applyrankmath-pp-cli link-genius bulk-update-preview - Rank Math link-genius: bulk update previewrankmath-pp-cli link-genius bulk-update-preview-results - Rank Math link-genius: bulk update preview resultsrankmath-pp-cli link-genius bulk-update-rollback - Rank Math link-genius: bulk update rollbackrankmath-pp-cli link-genius create-keyword-maps - Rank Math link-genius: create keyword mapsrankmath-pp-cli link-genius delete - Rank Math link-genius: deleterankmath-pp-cli link-genius delete-bulk-update-history - Rank Math link-genius: delete bulk update historyrankmath-pp-cli link-genius delete-keyword-maps - Rank Math link-genius: delete keyword mapsrankmath-pp-cli link-genius delete-keyword-maps-variations - Rank Math link-genius: delete keyword maps variationsrankmath-pp-cli link-genius export - Rank Math link-genius: exportrankmath-pp-cli link-genius get-bulk-update-changes - Rank Math link-genius: get bulk update changesrankmath-pp-cli link-genius get-keyword-maps - Rank Math link-genius: get keyword mapsrankmath-pp-cli link-genius get-keyword-maps-variations - Rank Math link-genius: get keyword maps variationsrankmath-pp-cli link-genius get-links-details - Rank Math link-genius: get links detailsrankmath-pp-cli link-genius item-keyword-maps-generate-variations - Rank Math link-genius: item keyword maps generate variationsrankmath-pp-cli link-genius keyword-maps-accept-variations - Rank Math link-genius: keyword maps accept variationsrankmath-pp-cli link-genius keyword-maps-bulk-delete - Rank Math link-genius: keyword maps bulk deleterankmath-pp-cli link-genius keyword-maps-bulk-toggle - Rank Math link-genius: keyword maps bulk togglerankmath-pp-cli link-genius keyword-maps-execute - Rank Math link-genius: keyword maps executerankmath-pp-cli link-genius keyword-maps-generate-variations - Rank Math link-genius: keyword maps generate variationsrankmath-pp-cli link-genius keyword-maps-history - Rank Math link-genius: keyword maps historyrankmath-pp-cli link-genius keyword-maps-preview - Rank Math link-genius: keyword maps previewrankmath-pp-cli link-genius keyword-maps-preview-results - Rank Math link-genius: keyword maps preview resultsrankmath-pp-cli link-genius keyword-maps-variations - Rank Math link-genius: keyword maps variationsrankmath-pp-cli link-genius link-opportunities - Rank Math link-genius: link opportunitiesrankmath-pp-cli link-genius link-suggestions - Rank Math link-genius: link suggestionsrankmath-pp-cli link-genius list-bulk-update-history - Rank Math link-genius: list bulk update historyrankmath-pp-cli link-genius list-keyword-maps - Rank Math link-genius: list keyword mapsrankmath-pp-cli link-genius list-links - Rank Math link-genius: list linksrankmath-pp-cli link-genius operations-cancel - Rank Math link-genius: operations cancelrankmath-pp-cli link-genius operations-clear - Rank Math link-genius: operations clearrankmath-pp-cli link-genius operations-progress - Rank Math link-genius: operations progressrankmath-pp-cli link-genius posts - Rank Math link-genius: postsrankmath-pp-cli link-genius posts-stats - Rank Math link-genius: posts statsrankmath-pp-cli link-genius regenerate - Rank Math link-genius: regeneraterankmath-pp-cli link-genius related-posts - Rank Math link-genius: related postsrankmath-pp-cli link-genius remove-nofollow - Rank Math link-genius: remove nofollowrankmath-pp-cli link-genius stats - Rank Math link-genius: statsrankmath-pp-cli link-genius undo-delete - Rank Math link-genius: undo deleterankmath-pp-cli link-genius update - Rank Math link-genius: updaterankmath-pp-cli link-genius update-keyword-maps - Rank Math link-genius: update keyword maps
meta
Manage meta
rankmath-pp-cli meta update - Rank Math meta: update metarankmath-pp-cli meta update-bulk - Rank Math meta: update meta bulkrankmath-pp-cli meta update-seo-score - Rank Math meta: update seo scorerankmath-pp-cli meta import - Preview, then with --apply send, SEO title/description/focus keyword edits from a CSV (id + columns) via updateMetaBulk (--file)
pages
Manage pages
rankmath-pp-cli pages - List published WordPress pages (id, link, modified)
posts
Manage posts
rankmath-pp-cli posts - List published WordPress posts (id, link, modified)
redirections
Manage redirections
rankmath-pp-cli redirections - Rank Math redirections: update redirection
schema
Manage schema
rankmath-pp-cli schema save-template - Rank Math schema: save templaterankmath-pp-cli schema update - Rank Math schema: update schemas
settings
Manage settings
rankmath-pp-cli settings save-module - Rank Math settings: save modulerankmath-pp-cli settings update - Rank Math settings: update settings
audit
rankmath-pp-cli audit - One list of every synced post with a missing or duplicate SEO title or description, long title, canonical problem, accidental noindex, or no schema. Works on public pages without credentials; run sync first.
coverage
rankmath-pp-cli coverage - Find published posts Google has not indexed or never inspected, excluding intentionally noindexed pages. Needs credentials and Rank Math Analytics connected to Search Console.
opportunities
rankmath-pp-cli opportunities - Queries ranking in positions 4-20 whose post title or description does not mention the query. Needs credentials and Rank Math Analytics connected to Search Console.
portfolio
rankmath-pp-cli portfolio - Clicks, impressions, and average position for each site in --sites (or RANKMATH_SITES) in one table. Needs credentials per site.
reindex
rankmath-pp-cli reindex - Preview the posts edited since a given window that are not yet in the IndexNow log; --confirm plus credentials submits them.
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
rankmath-pp-cli recall <query> - Look up cached resources for a query before running discoveryrankmath-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)rankmath-pp-cli learnings list - Inspect taught rowsrankmath-pp-cli learnings forget <query> - Undo a teachrankmath-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectrankmath-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsrankmath-pp-cli teach-pattern - Install a query/resource template up frontrankmath-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set RANKMATH_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of rankmath-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
rankmath-pp-cli head --url https://example.com/resource
# JSON for scripting and agents
rankmath-pp-cli head --url https://example.com/resource --json
# Filter to specific fields
rankmath-pp-cli head --url https://example.com/resource --json --select head,success
# Dry run — show the request without sending
rankmath-pp-cli head --url https://example.com/resource --dry-run
# Agent mode — JSON + compact + no prompts in one flag
rankmath-pp-cli head --url https://example.com/resource --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Explicit confirmation -
--agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 6 partial failure, 7 rate limited, 10 config error.
Freshness
This CLI owns bounded freshness for registered store-backed read command paths. In --data-source auto mode, covered commands check the local SQLite store before serving results; stale or missing resources trigger a bounded refresh, and refresh failures fall back to the existing local data with a warning. --data-source local never refreshes, and --data-source live reads the API without mutating the local store.
Set RANKMATH_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
rankmath-pp-cli ai_visibilityrankmath-pp-cli ai_visibility getrankmath-pp-cli ai_visibility listrankmath-pp-cli ai_visibility searchrankmath-pp-cli dashboardrankmath-pp-cli dashboard getrankmath-pp-cli dashboard listrankmath-pp-cli dashboard searchrankmath-pp-cli gscrankmath-pp-cli gsc getrankmath-pp-cli gsc listrankmath-pp-cli gsc searchrankmath-pp-cli gsc-dashboardrankmath-pp-cli gsc-dashboard getrankmath-pp-cli gsc-dashboard listrankmath-pp-cli gsc-dashboard searchrankmath-pp-cli gsc-get-keyword-pagesrankmath-pp-cli gsc-get-keyword-pages getrankmath-pp-cli gsc-get-keyword-pages listrankmath-pp-cli gsc-get-keyword-pages searchrankmath-pp-cli gsc-get-tracked-keyword-summaryrankmath-pp-cli gsc-get-tracked-keyword-summary getrankmath-pp-cli gsc-get-tracked-keyword-summary listrankmath-pp-cli gsc-get-tracked-keyword-summary searchrankmath-pp-cli gsc-get-tracked-keywordsrankmath-pp-cli gsc-get-tracked-keywords getrankmath-pp-cli gsc-get-tracked-keywords listrankmath-pp-cli gsc-get-tracked-keywords searchrankmath-pp-cli gsc-get-tracked-keywords-rowsrankmath-pp-cli gsc-get-tracked-keywords-rows getrankmath-pp-cli gsc-get-tracked-keywords-rows listrankmath-pp-cli gsc-get-tracked-keywords-rows searchrankmath-pp-cli gsc-inspection-resultsrankmath-pp-cli gsc-inspection-results getrankmath-pp-cli gsc-inspection-results listrankmath-pp-cli gsc-inspection-results searchrankmath-pp-cli gsc-inspection-statsrankmath-pp-cli gsc-inspection-stats getrankmath-pp-cli gsc-inspection-stats listrankmath-pp-cli gsc-inspection-stats searchrankmath-pp-cli gsc-keywords-overviewrankmath-pp-cli gsc-keywords-overview getrankmath-pp-cli gsc-keywords-overview listrankmath-pp-cli gsc-keywords-overview searchrankmath-pp-cli gsc-keywords-rowsrankmath-pp-cli gsc-keywords-rows getrankmath-pp-cli gsc-keywords-rows listrankmath-pp-cli gsc-keywords-rows searchrankmath-pp-cli gsc-keywords-summaryrankmath-pp-cli gsc-keywords-summary getrankmath-pp-cli gsc-keywords-summary listrankmath-pp-cli gsc-keywords-summary searchrankmath-pp-cli gsc-posts-overviewrankmath-pp-cli gsc-posts-overview getrankmath-pp-cli gsc-posts-overview listrankmath-pp-cli gsc-posts-overview searchrankmath-pp-cli gsc-posts-rowsrankmath-pp-cli gsc-posts-rows getrankmath-pp-cli gsc-posts-rows listrankmath-pp-cli gsc-posts-rows searchrankmath-pp-cli gsc-posts-rows-by-objectsrankmath-pp-cli gsc-posts-rows-by-objects getrankmath-pp-cli gsc-posts-rows-by-objects listrankmath-pp-cli gsc-posts-rows-by-objects searchrankmath-pp-cli gsc-posts-summaryrankmath-pp-cli gsc-posts-summary getrankmath-pp-cli gsc-posts-summary listrankmath-pp-cli gsc-posts-summary searchrankmath-pp-cli gsc-tracked-keywords-overviewrankmath-pp-cli gsc-tracked-keywords-overview getrankmath-pp-cli gsc-tracked-keywords-overview listrankmath-pp-cli gsc-tracked-keywords-overview searchrankmath-pp-cli link_geniusrankmath-pp-cli link_genius getrankmath-pp-cli link_genius listrankmath-pp-cli link_genius searchrankmath-pp-cli link_genius-historyrankmath-pp-cli link_genius-history getrankmath-pp-cli link_genius-history listrankmath-pp-cli link_genius-history searchrankmath-pp-cli link_genius-keyword-mapsrankmath-pp-cli link_genius-keyword-maps getrankmath-pp-cli link_genius-keyword-maps listrankmath-pp-cli link_genius-keyword-maps searchrankmath-pp-cli link_genius-linksrankmath-pp-cli link_genius-links getrankmath-pp-cli link_genius-links listrankmath-pp-cli link_genius-links searchrankmath-pp-cli link_genius-postsrankmath-pp-cli link_genius-posts getrankmath-pp-cli link_genius-posts listrankmath-pp-cli link_genius-posts searchrankmath-pp-cli link_genius-posts-statsrankmath-pp-cli link_genius-posts-stats getrankmath-pp-cli link_genius-posts-stats listrankmath-pp-cli link_genius-posts-stats searchrankmath-pp-cli link_genius-progressrankmath-pp-cli link_genius-progress getrankmath-pp-cli link_genius-progress listrankmath-pp-cli link_genius-progress searchrankmath-pp-cli link_genius-resultsrankmath-pp-cli link_genius-results getrankmath-pp-cli link_genius-results listrankmath-pp-cli link_genius-results searchrankmath-pp-cli link_genius-statsrankmath-pp-cli link_genius-stats getrankmath-pp-cli link_genius-stats listrankmath-pp-cli link_genius-stats searchrankmath-pp-cli pagesrankmath-pp-cli pages getrankmath-pp-cli pages listrankmath-pp-cli pages searchrankmath-pp-cli postsrankmath-pp-cli posts getrankmath-pp-cli posts listrankmath-pp-cli posts search
JSON outputs that use the generated provenance envelope include freshness metadata at meta.freshness. This metadata describes the freshness decision for the covered command path; it does not claim full historical backfill or API-specific enrichment.
Runtime Endpoint
This CLI resolves endpoint placeholders at runtime, so one installed binary can target different tenants or API versions without regeneration.
Endpoint environment variables:
RANKMATH_SITE resolves {site}
Base URL: https://{site}/wp-json
Health Check
rankmath-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run rankmath-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/rank-math-seo-pp-cli/config.toml; --home, RANKMATH_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
RANKMATH_SITE | endpoint | Yes | |
RANKMATH_USERNAME | per_call | Yes | |
RANKMATH_APP_PASSWORD | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, rankmath-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
rankmath-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $RANKMATH_USERNAME
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 rest_forbidden on rankmath routes — Set the WordPress username and application password; the account needs Rank Math capabilities for that module.
- 404 rest_no_route for a Pro route (link-genius, rank tracking) — Run rankmath-pp-cli doctor to see which modules this site exposes; the module is off or Rank Math Pro is not installed.
- head --url returns 404 rest_no_route — Headless support is off (Rank Math → General Settings → Others). Use rankmath-pp-cli head get , which falls back to parsing the rendered page.
- RANKMATH_SITE not set — export RANKMATH_SITE=example.com (host only, no https://).
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press