RankNest CLI

The RankNest CLI gives you terminal access to the same data the dashboard shows: clients, SEO tests, link maps, tasks, and more. It returns JSON, so it suits scripted and repeatable work (nightly reports, bulk edits, piping results into another tool) rather than day-to-day browsing.

The CLI authenticates with a Personal Access Token and inherits your account's access exactly. It can never read or change anything you couldn't reach in the dashboard, and it counts against the same plan limits.

Where to find it

Open Account Settings, go to the Integrations tab, and click Developer API, then select the CLI tab. It shows the two setup steps with your details filled in and a copy button on each block.

Before you start

You need three things:

• Node.js installed on the machine you'll run commands from.
• A local copy of the RankNest project, since you run the CLI through its npm run cli script. If you don't have one, use the REST API instead. See Personal Access Tokens.
• A User-scope Personal Access Token. Create one in the same Developer API area; the steps are in Personal Access Tokens.

How to authenticate

The CLI reads two environment variables. These are the only settings it needs.

1. Set the base URL and your token in your shell:

   export RANKNEST_API_URL=https://www.ranknest.io
   export RANKNEST_TOKEN=rnk_live_XXXXXXXXXXXXXXXX
   

2. Confirm the connection:

   npm run cli -- health --pretty
   

   A JSON summary comes back. If you get an error instead, see Troubleshooting below.

Always use the www subdomain in RANKNEST_API_URL. Requests to the bare domain are redirected in a way that strips your authorization header. If you omit RANKNEST_API_URL entirely, the CLI assumes a local development server rather than the live site.

How to run commands

Every command follows the same shape. The -- separator passes everything after it to the CLI rather than to npm:

npm run cli -- <group> <action> [arguments] [--flags]

For example:

npm run cli -- clients list --pretty
npm run cli -- clients get <client-id> --pretty
npm run cli -- experiments list --client-id <client-id> --pretty

Useful global flags:

• --pretty: indent the JSON output so it's readable on screen. Leave it off when piping into another tool.
• --help: list the available groups, or the actions within one group. Run npm run cli -- clients --help to see everything a group accepts.
• --version: print the CLI version.

Most groups support the same five actions: list, get, create, update, and delete. List actions accept --page and --limit for paging, plus filters specific to that group. Update actions take the changed fields as JSON:

npm run cli -- clients update <client-id> --body '{"status": "inactive"}'

Command groups

Link map sub-groups

Everything inside a link map is addressed through its map ID:

npm run cli -- link-maps nodes list <map-id> --pretty
npm run cli -- link-maps edges list <map-id> --source-id <node-id>
npm run cli -- link-maps topic-groups list <map-id> --pretty
npm run cli -- link-maps recommendations list <map-id> --status pending

• nodes: the pages on the map. --node-type filters to one page type; the types are explained in Page Types & Clusters.
• edges: the links between pages. Filter with --source-id or --target-id.
• topic-groups: topic clusters and categories.
• recommendations: Linking Plan recommendations. Filter with --status, --type, or --priority. You can update a recommendation's status or delete it, but recommendations are generated rather than created by hand. See Linking Plan.

Site Connector sub-commands

npm run cli -- site-connectors pages <connector-id> --search "pricing"
npm run cli -- site-connectors queue <connector-id> --status pending

pages lists the pages the connector has reported, and queue lists the link changes waiting to be applied to the site.

Longer operations

The functions group starts work that the dashboard normally triggers with a button. Each takes a JSON body:

npm run cli -- functions crawl-site --body '{"url": "https://acme.com", "maxPages": 100}'
npm run cli -- functions audit-site --body '{"url": "https://acme.com", "maxPages": 30}'
npm run cli -- functions generate-linking-plan --body '{"map_id": "<map-id>"}'
npm run cli -- functions gsc-data --body '{"property": "sc-domain:acme.com"}'
npm run cli -- functions generate-seo-variation --body '{"experiment_id": "<id>"}'

These correspond to Crawling Your Site, Running an Audit, Linking Plan, Google Search Console, and the AI variation generator in Creating Tests.

Example: set up a client and generate a Linking Plan

# 1. Create the client
npm run cli -- clients create --name "Acme Corp" --domain "acme.com" --pretty

# 2. Create a link map for it
npm run cli -- link-maps create --client-id <client-id> --name "Acme Main" --domain "acme.com" --pretty

# 3. Crawl the site
npm run cli -- functions crawl-site --body '{"url": "https://acme.com", "maxPages": 100}' --pretty

# 4. Generate the Linking Plan
npm run cli -- functions generate-linking-plan --body '{"map_id": "<map-id>"}' --pretty

# 5. Review what it found
npm run cli -- link-maps recommendations list <map-id> --status pending --pretty

Tips

• Pipe compact output into jq to pull out single fields. For example, npm run cli -- link-maps nodes list <map-id> | jq '.data[].url' prints just the URLs. Drop --pretty when you do this.
• List responses are paged. The response includes a pagination block with the total count, so a script can loop with --page until it has everything.
• --help at any level is faster than guessing a flag name. Multi-word flags are hyphenated: --client-id, not --client_id.
• Give the CLI a token created specifically for it, named after the machine it runs on. If that machine is retired, you revoke one token instead of auditing every script you own.

Troubleshooting

"RANKNEST_TOKEN environment variable is required". The variable isn't set in the shell you're running from. Export it again, or add it to your shell profile so new terminal sessions pick it up.

"Invalid or expired token" or a 401 status. The token was revoked or mistyped, or you're using a raw dashboard session token that has since expired. Create a fresh User-scope Personal Access Token and export it again.

Commands hit a local address or time out. RANKNEST_API_URL is unset, so the CLI is pointing at a local development server. Set it to https://www.ranknest.io.

Errors appear as JSON and the command exits non-zero. That's intended. The CLI prints errors to standard error as JSON with a status code and exits with code 1, so scripts can detect failures. Read the error field for the cause.

A flag is rejected as unknown. Check the spelling with npm run cli -- <group> <action> --help. Multi-word flags are hyphenated.

Related

• Personal Access Tokens
• MCP Server Setup
• Site Connector & WordPress Plugin