Outrank

Outrank CLI

Agent-first CLI for the Outrank agent API, with a built-in MCP server for Claude Code, Cursor and other MCP clients.

Install

Requires Node.js 18+. Works on macOS, Linux, and Windows.

npm install -g outrank-cli

outrank-cli --help

Get an API key

1. Sign in to your Outrank account at https://www.outrank.so.
2. Open Settings → API keys: https://www.outrank.so/dashboard/settings/api-keys.
3. Click Create key, give it a name, and copy the outr_live_... value. The key is shown only once — store it somewhere safe.
4. Revoke a key from the same page if it ever leaks. Generate a fresh one and re-run auth login.

You can also rotate keys at any time; each key is independent and can be revoked without affecting the others.

Current scope

This repo currently targets the agent endpoints that already exist in outrank:

• mcp (the stdio MCP server that exposes the commands below as tools, see MCP server)
• auth login|whoami|status|profiles|logout
• products list|get|create|update|pause|resume
• products integrations providers|prepare|connect|poll|validate|list|create|get|update|test|delete
• products integrations notion databases|schema
• products integrations framer collections|fields
• products integrations webflow sites|collections|fields|items
• products output-settings get|update for product article settings
• products target-audiences list|replace
• products competitors list|replace
• products gsc status|connect|poll|reconnect|disconnect|accounts|properties|set-property|performance|search-analytics|inspect-url|cannibalization
• products linking sources get|update
• products linking detect
• products linking target-config get|update
• products linking targets list|add-manual|upsert|clear-customizations|delete
• products backlinks get|update|credits|earned|unverified|check-removal|reverify|subscription|subscribe-quote
• keywords list|get|export|generation-status|add|update|suggest|generate|bulk-reschedule|delete|bulk-delete
• articles list|create|get|get-content|update|update-content|replace|bulk-replace|upload-image|upload-featured-image|publish|sync|retry-publish|delete|precreate|generate
• products blog ... for a hosted Outrank Blog: posts list|create|get|update|delete|get-content|update-content|publish|unpublish|sync, design get|patch|update|publish|discard, settings, pages, categories, authors, domain, redirects, snippets, subscribers, webhooks, preview and analytics
• improvements settings get|update
• improvements analyze
• improvements candidates list|brief|edit-brief|schedule
• improvements tasks list|reschedule|cancel|edit-brief|execute
• improvements executions list|get|decisions|push
• marketplace seller status|onboard|eligibility|settings|integrations|stripe|complete-onboarding|placements|earnings|content-history
• marketplace notifications list|mark-read
• marketplace buyer status|billing-status|subscription|subscribe-quote|checkout|change-plan|target-pages|participation|placements|article|credits
• ai-cited-lists status|overview|lists|outreach|offers|wins|questions|settings|mailbox|top-up-consent|entry|setup|citations for AI-Cited Lists (Backlinks Enterprise)
• subscription status
• usage stats
• billing portal-url
• billing purchase-products quote|buy

The broader roadmap from the internal implementation plan is larger than the live backend surface. This CLI is structured so new groups can be added cleanly as the server catches up.

Auth

The CLI reads credentials in this order of precedence:

1. --api-key and --base-url on the command line (highest priority, per-call)
2. A profile selected with --profile or OUTRANK_PROFILE. A selected profile is used as-is: OUTRANK_API_KEY and OUTRANK_BASE_URL are ignored, and a profile without a stored key fails with CLI_AUTH_REQUIRED instead of silently using another key
3. OUTRANK_API_KEY and OUTRANK_BASE_URL environment variables
4. The default profile in ~/.outrank/config.json, populated by outrank-cli auth login (lowest priority, persistent)

auth status shows which profile is active and where its key and base URL came from (flag, env, profile, or profile (env ignored) when an environment variable was set but a higher-priority source won).

Pick one. For interactive use on your own machine, auth login is simplest. For CI / ephemeral environments, prefer the env var.

# Sign in through the browser, so no key is ever pasted (also what an AI assistant should use)

outrank-cli auth login --browser

Or store an API key once

outrank-cli auth login outr_live_xxx outrank-cli auth status # confirms the key is stored outrank-cli auth whoami # round-trips it against the server

OR per-shell env var (no config file written)

export OUTRANK_API_KEY="outr_live_xxx" # macOS / Linux (bash, zsh) outrank-cli auth whoami

OR per-call (useful in scripts)

outrank-cli auth whoami --api-key outr_live_xxx

On Windows PowerShell, set the env var with $env:OUTRANK_API_KEY = "outr_live_xxx". On Windows cmd.exe, use set OUTRANK_API_KEY=outr_live_xxx.

Sign out / rotate:

outrank-cli auth logout     # clears apiKey from the default profile in ~/.outrank/config.json

Profiles (one per organization)

API keys are scoped to one organization. Store one profile per organization and switch with --profile:

outrank-cli auth login outr_live_xxx --profile acme               # the first stored key becomes the default profile

outrank-cli auth login outr_live_yyy --profile globex # a second profile; the default does not change outrank-cli auth login outr_live_yyy --profile globex --default # ...unless you ask for it outrank-cli auth profiles # lists profiles with redacted keys, marks the default outrank-cli products list --profile globex # per call export OUTRANK_PROFILE=globex # per shell outrank-cli auth logout --profile globex # clears only that profile's key

auth login and auth logout without --profile act on the default profile. auth login verifies against and stores the base URL it resolves with the same precedence as every other command: --base-url, else OUTRANK_BASE_URL (ignored when a profile is selected), else the profile's stored value, else the default. Re-running auth login for a stored profile therefore keeps that profile's base URL. The config file keeps the default profile mirrored in the top-level apiKey / baseUrl keys, so an older outrank-cli (0.5.x) on the same machine keeps working; it only ever sees the default profile. A config file that cannot be parsed, or that contains a profile name the CLI does not accept, fails every command with CLI_CONFIG_UNREADABLE (the path is in error.details.config_path), and auth login / auth logout never overwrite it. A failed save is CLI_CONFIG_UNWRITABLE and nothing is stored. auth status and auth profiles still work when the selected profile does not exist, so you can always inspect what is stored.

MCP server

outrank-cli mcp starts a Model Context Protocol server on stdio, so Claude Code, Cursor and other MCP clients can call Outrank directly. The server runs on the same command layer as the CLI: every command except auth login, auth logout and auth profiles is a tool, named after the command with underscores (products integrations list → products_integrations_list), and sends exactly the same request.

Requirements: Node.js 18+ (check with node --version), an Outrank API key from https://www.outrank.so/dashboard/settings/api-keys, and an organization on the current Outrank app version. The same guide is on the web at https://www.outrank.so/docs/mcp.

Remote server

Outrank also hosts the same tools at https://www.outrank.so/api/mcp (Streamable HTTP), for clients that connect to a URL instead of starting a command, such as Claude, ChatGPT or Cursor. Sign in with OAuth when the client asks, or send an API key as Authorization: Bearer outr_live_....

• Claude Code plugin: /plugin marketplace add Outrank-SAS/outrank-cli, then /plugin install outrank@outrank.
• Gemini CLI: gemini extensions install https://github.com/Outrank-SAS/outrank-cli.
• Other clients: see llms-install.md. The hosted server always uses the auto toolsets, has no read-only switch and takes images as base64 only: it never reads a file. It is built from createRemoteMcpServer in src/adapters/mcp/remote.js, which takes the key, the Outrank origin and, optionally, the organization's auth whoami envelope so it does not ask for it again.

Claude Code

Run this in the project folder (macOS, Linux, WSL, or the Windows Command Prompt):

claude mcp add outrank --env OUTRANK_API_KEY=outr_live_xxx -- npx -y outrank-cli@latest mcp

If the server does not start on native Windows, use the cmd /c form:

claude mcp add outrank --env OUTRANK_API_KEY=outr_live_xxx -- cmd /c npx -y outrank-cli@latest mcp

In PowerShell, call claude.exe instead of claude (claude.cmd when Claude Code was installed with npm), so that the -- separator is kept.

Check the connection with claude mcp get outrank, then start a new Claude Code session. That command prints the stored key, so do not paste its output anywhere.

To share the server with a team, commit a .mcp.json that takes the key from each developer's environment, so no key lands in git:

{

"mcpServers": { "outrank": { "command": "npx", "args": ["-y", "outrank-cli@latest", "mcp"], "env": { "OUTRANK_API_KEY": "${OUTRANK_API_KEY}" } } } }

Each developer then sets the variable once:

# macOS, Linux: add this line to ~/.zshrc or ~/.bashrc

export OUTRANK_API_KEY=outr_live_xxx

Windows, from the Command Prompt or PowerShell

setx OUTRANK_API_KEY outr_live_xxx

The variable reaches new terminals only, so open a new one before starting Claude Code.

Cursor

Add the server to ~/.cursor/mcp.json, the file for all projects (on Windows: %USERPROFILE%\.cursor\mcp.json). It is in your home folder, outside any repository, so the key in it cannot be committed by accident:

{

"mcpServers": { "outrank": { "command": "npx", "args": ["-y", "outrank-cli@latest", "mcp"], "env": { "OUTRANK_API_KEY": "outr_live_xxx" } } } }

If the server does not start on native Windows, use "command": "cmd" and "args": ["/c", "npx", "-y", "outrank-cli@latest", "mcp"].

For one project or a team, put the server in .cursor/mcp.json inside the project and take the key from the environment, so the file can be committed without it:

{

"mcpServers": { "outrank": { "command": "npx", "args": ["-y", "outrank-cli@latest", "mcp"], "env": { "OUTRANK_API_KEY": "${env:OUTRANK_API_KEY}" } } } }

Set OUTRANK_API_KEY as shown in the Claude Code section, then quit and reopen Cursor. A project server may first have to be switched on in the MCP section of the Cursor settings; a server in the all-projects file starts on its own.

Never commit a file that contains the key. A key written into a project file can end up in git with the next commit: keep the key in the all-projects file or in the environment. If a key was committed, revoke it at https://www.outrank.so/dashboard/settings/api-keys and create a new one. If Cursor does not see the variable, which can happen on macOS when it is started from the Dock, every call returns CLI_AUTH_REQUIRED: use the all-projects file instead.

Other MCP clients

Any client that can start a local MCP server (the stdio transport) works. Give it these three values; many clients read the same JSON a