@zrelux/search-console-cli

Node CLI for Google Search Console and Bing Webmaster.

Install

Requires Node 20+.

npm install -g @zrelux/search-console-cli
search-console-cli --help

Or run without installing globally:

npx @zrelux/search-console-cli --help

Local Development

This repo uses Bun for local development, testing, and bundling.

bun install
bun run build
bun run src/bin.ts --help

Output Modes

• Default: deterministic table
• Optional: --format json (stable envelope: { meta, data, errors })
• Optional: --format csv

Commands

search-console-cli profile create <name>
search-console-cli profile list
search-console-cli profile use <name>

search-console-cli auth login --provider google [--profile <name>]
search-console-cli auth login --provider bing [--profile <name>] [--api-key <key>]
search-console-cli auth revoke --provider <google|bing> [--profile <name>]
search-console-cli auth status [--profile <name>]

search-console-cli sites list [--provider <google|bing>] [--profile <name>] [--format ...]
search-console-cli performance query [--provider <google|bing>] --site <siteUrl> [--from <YYYY-MM-DD> --to <YYYY-MM-DD> | --range <24h|7d|28d|3m>] [--compare <previous_period|previous_year>] [--dimensions <d1,d2>] [--limit <n>] [--search-type <web|image|video|news|discover>] [--query-contains <text>] [--query-equals <text>] [--page-equals <url>] [--country <code>] [--device <desktop|mobile|tablet>] [--sort-by <field>] [--sort-direction <asc|desc>] [--profile <name>] [--format ...]
search-console-cli sitemaps list [--provider <google|bing>] --site <siteUrl> [--profile <name>] [--format ...]
search-console-cli sitemaps submit [--provider <google|bing>] --site <siteUrl> --sitemap <url> [--profile <name>] [--format ...]
search-console-cli inspect url [--provider <google|bing>] --site <siteUrl> --url <url> [--profile <name>] [--format ...]
search-console-cli submit-url [--provider <google|bing>] --site <siteUrl> --url <url> [--profile <name>] [--format ...]

Default behavior:

• Omit --profile to use the profile named default when it exists; otherwise the active profile is used.
• Omit --provider on data commands to query both providers and merge the results.
• auth login still requires an explicit --provider.
• auth revoke requires an explicit --provider and deletes stored credentials for that provider/profile.
• performance query defaults to --range 3m, --search-type web, --sort-by clicks, and --sort-direction desc.

Quick Start

search-console-cli profile create default
search-console-cli auth login --provider google --profile default
search-console-cli auth login --provider bing --profile default
search-console-cli auth revoke --provider google --profile default
search-console-cli auth status
search-console-cli sites list

Performance Parity

Shared surface across Google and Bing:

• sites list
• performance query
• sitemaps list
• sitemaps submit
• submit-url

Performance features implemented natively or in TypeScript:

• Date presets: 24h, 7d, 28d, 3m
• Explicit date ranges with --from and --to
• Summary metrics in JSON output
• Compare windows with --compare previous_period|previous_year
• Breakdown tabs through --dimensions query|page|country|device|date
• Filters through --query-contains, --query-equals, --page-equals, --country, --device
• Provider-normalized sorting with --sort-by and --sort-direction

Provider-specific limitations:

• Google supports --dimensions searchAppearance and non-web --search-type values.
• Bing supports only --search-type web.
• Bing inspect url is unsupported in this CLI.
• Features without stable public API coverage are intentionally out of scope, including Search Console indexing/Core Web Vitals/security reports and Bing tools like Backlinks, Keyword Research, and Site Scan.

Performance examples:

search-console-cli performance query --site https://www.mondoedile.co.uk/
search-console-cli performance query --site https://www.mondoedile.co.uk/ --range 28d
search-console-cli performance query --site https://www.mondoedile.co.uk/ --compare previous_period --format json
search-console-cli performance query --site https://www.mondoedile.co.uk/ --dimensions page
search-console-cli performance query --site https://www.mondoedile.co.uk/ --dimensions country
search-console-cli performance query --site https://www.mondoedile.co.uk/ --query-contains "piling"
search-console-cli performance query --provider google --site https://www.mondoedile.co.uk/ --dimensions searchAppearance

JSON output for performance query:

• Single provider: { meta, data: { summary, comparison?, rows }, errors }
• Multiple providers: { meta, data: { summaryByProvider, comparisonByProvider?, rows }, errors }

Capability Rules

• Bing inspect url: always returns UNSUPPORTED_PROVIDER_FEATURE.
• Google submit-url: requires profile.google.indexingEnabled = true and an eligible URL pattern (/job, /jobs, /livestream, /broadcast).
• No silent fallback when provider capability is unavailable.

OAuth Login Flow

• auth login now uses a browser redirect flow with a local callback server.
• Google defaults to http://127.0.0.1:3000/oauth/callback/google.
• Bing defaults to http://127.0.0.1:3000/oauth/callback/bing.
• Override provider auth details when needed:
  • --authorize-endpoint <url>
  • --token-endpoint <url>
  • --redirect-uri <url>
  • --scope <scope>

Notes:

• Google clients must support installed-app/browser redirect auth. Device-only clients will not work.
• Google app registrations should allow http://127.0.0.1:3000/oauth/callback/google unless you pass --redirect-uri.
• Bing app registrations should allow http://127.0.0.1:3000/oauth/callback/bing unless you pass --redirect-uri.
• Bing tenants may still require tenant-specific authorize/token endpoints instead of /common.

Auth Prerequisites

You must bring your own provider credentials.

Google setup:

• Create an OAuth client that supports installed-app or loopback browser auth.
• Provide GOOGLE_CLIENT_ID and usually GOOGLE_CLIENT_SECRET, or pass --client-id and --client-secret.
• Allow http://127.0.0.1:3000/oauth/callback/google in the Google app unless you override --redirect-uri.

Bing setup:

• Use either a Bing Webmaster API key or OAuth credentials.
• For OAuth, provide BING_CLIENT_ID and usually BING_CLIENT_SECRET.
• Allow http://127.0.0.1:3000/oauth/callback/bing in the Microsoft app unless you override --redirect-uri.
• Some Microsoft tenants require tenant-specific authorize/token endpoints instead of /common.

Bing API key example:

search-console-cli auth login --provider bing --profile default --api-key '<your-api-key>'

Config and Secrets

• Config file: platform config dir under search-console-cli/config.toml.
• Override config dir: SC_CONFIG_DIR=/path/to/config-root.
• Token storage:
  • Primary: OS keychain (macOS Keychain / Linux secret-tool when available).
  • Fallback: encrypted file (tokens.enc) using SC_MASTER_KEY.

Current auth storage behavior:

• OAuth access tokens and refresh tokens are stored in secure storage.
• Bing API keys are stored in secure storage.
• OAuth client secrets are stored in secure storage when they are supplied for login or refresh.
• config.toml stores only non-secret provider settings such as clientId, OAuth endpoints, redirect URI, and scope.
• Environment variables remain the recommended input for CI and other non-interactive environments.

Platform note:

• Windows currently has no native keychain backend in this project, so encrypted fallback storage depends on SC_MASTER_KEY.

Useful Env Vars

• GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
• BING_CLIENT_ID, BING_CLIENT_SECRET
• SC_MASTER_KEY (required for encrypted-file token fallback)
• SC_CONFIG_DIR (optional config dir override)

Release Checks

bun test
bunx tsc --noEmit
bun run build
node dist/bin.js --help
npm pack --dry-run