How to Use the Open-SEO CLI: A Complete Command-Line Guide

The open-seo CLI lets you execute SEO workflows—including keyword research, rank tracking, and site audits—directly from your terminal by authenticating with a DataForSEO API key and invoking the server-side functions defined in the every-app/open-seo repository.

The open-seo CLI is a thin wrapper around the Next.js server functions that power the web application, enabling scriptable SEO analyses without browser interaction. Built within a pnpm workspace and bundled using a Vite-lean-worker configuration, the CLI routes terminal commands to specific modules under src/serverFunctions/ and returns results as JSON or formatted tables.

Installation and Build Process

Before executing commands, you must compile the CLI from the TypeScript source.

Clone and Install Dependencies

The repository is organized as a pnpm workspace. Clone the repository and install all dependencies:

git clone https://github.com/every-app/open-seo.git
cd open-seo
pnpm install

Compile the CLI

The build process uses the Vite-lean-worker bundle defined in vite-plugin-lean-worker-bundle.ts. Generate the production build with:

pnpm run build

For active development, use pnpm run dev to enable watch mode and automatic recompilation.

Authentication Configuration

The CLI requires a DataForSEO API key to communicate with external SEO data providers.

In cli-auth.ts, the application reads the DATAFORSEO_API_KEY environment variable (or loads it from a local .env file) to instantiate a metered DataForSEO client. This credential is the only secret required to operate the CLI.

Export your key in the terminal before running commands:

export DATAFORSEO_API_KEY=your-dataforseo-api-key

Core CLI Commands

The open-seo CLI follows the syntax pattern open-seo <command> [options]. Each command maps directly to a corresponding server function in src/serverFunctions/.

Keyword Research

Fetch keyword ideas for a target domain:

pnpm exec open-seo keyword-research example.com --json

This invokes the logic in src/serverFunctions/keyword-research.ts to retrieve and process keyword data.

Rank Tracking

Initiate a rank tracking job for a domain:

pnpm exec open-seo rank-track example.com --json

The command returns a task ID. Check the status of a running job:

pnpm exec open-seo rank-track status <task-id> --json

The rank-tracking implementation resides in src/serverFunctions/rank-tracking.ts and orchestrates background processing via src/server/workflows/RankCheckWorkflow.ts.

Backlink Analysis

Retrieve backlink data for a domain:

pnpm exec open-seo backlinks example.com --json

This command delegates to src/serverFunctions/backlinks.ts.

Site Audit

Trigger a comprehensive site audit:

pnpm exec open-seo site-audit example.com --json

The audit logic is implemented in src/serverFunctions/site-audit.ts.

Output Formats

By default, the CLI renders results as human-readable tables. For integration with scripts and external tools, append the --json flag to receive machine-parseable JSON output that can be piped into utilities like jq.

Summary

• The open-seo CLI provides terminal access to the same SEO workflows available in the web UI.
• Install dependencies with pnpm install and compile the tool with pnpm run build utilizing the Vite-lean-worker bundle configuration.
• Authentication relies on the DATAFORSEO_API_KEY environment variable handled by cli-auth.ts.
• Available commands include keyword-research, rank-track, backlinks, and site-audit, each delegating to specific files in src/serverFunctions/.
• Use --json for API-like responses suitable for automation, or omit the flag for formatted terminal tables.

Frequently Asked Questions

How do I install the open-seo CLI?

Clone the every-app/open-seo repository, execute pnpm install to resolve workspace dependencies, then run pnpm run build to compile the CLI using the Vite-lean-worker bundle system.

What API key does the open-seo CLI require?

The CLI requires a valid DataForSEO API key. Set the DATAFORSEO_API_KEY environment variable or store it in a .env file; the cli-auth.ts module reads this value to create a metered client for every API interaction.

Where are the CLI commands implemented in the source code?

Each command delegates to a dedicated server function: src/serverFunctions/keyword-research.ts, src/serverFunctions/rank-tracking.ts, src/serverFunctions/backlinks.ts, and src/serverFunctions/site-audit.ts. The rank-tracking workflow additionally utilizes src/server/workflows/RankCheckWorkflow.ts for job orchestration.

Can I automate the open-seo CLI in CI/CD pipelines?

Yes. The CLI is designed for automation—export DATAFORSEO_API_KEY in your pipeline environment, build once with pnpm run build, then execute commands with the --json flag to receive parseable output suitable for downstream processing in continuous integration scripts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}