KanmiLabs / GSC CLI

🔍 GSC CLI

Google Search Console Command Line Tool

🚀 Quick Installation

npm install -g kanmi-gsc-cli

Or install as part of the complete KanmiLabs suite:

npm install -g kanmi-suite-cli

✨ Features

🔐 OAuth2 Authentication

Secure authentication with Google Search Console using OAuth2 flow with automatic token management.

📊 Search Analytics Data

Retrieve comprehensive search performance data including clicks, impressions, CTR, and position.

🏗️ Site Management

List properties, verify sites, and manage Search Console site configurations.

📈 Advanced Filtering

Apply custom filters by device, search type, country, and date ranges for precise data analysis.

📁 Multiple Export Formats

Export data as JSON, CSV, or formatted tables for different workflows and integrations.

⚡ Batch Processing

Process multiple sites and date ranges in batch operations for efficient data collection.

🔧 Setup Requirements

Prerequisites

Google Cloud Setup

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google Search Console API
  4. Create OAuth2 credentials:
    • Go to APIs & Services → Credentials
    • Create credentials → OAuth client ID
    • Application type: Desktop application
    • Download the JSON file
  5. Configure authorized redirect URIs (if needed):
    • Add http://localhost:3000/oauth/callback
⚠️ Important: Ensure your Google account has access to the Search Console properties you want to query.

📖 Usage

Available Commands

Command Description Key Options
gsc-cli auth Authenticate with Google Search Console --reset, --credentials
gsc-cli sites List accessible Search Console properties --format
gsc-cli query Query search analytics data --site, --dimensions, --filters, --date-range
gsc-cli inspect URL inspection data --site, --url
gsc-cli sitemaps List and manage sitemaps --site, --submit, --delete

Basic Examples

1. Authentication

gsc-cli auth
Opens browser for OAuth flow and saves authentication tokens locally.

2. List Sites

gsc-cli sites --format table
Lists all Search Console properties you have access to with verification status.

3. Basic Search Analytics Query

gsc-cli query \ --site "https://example.com" \ --dimensions "query,page" \ --date-range "last-7-days" \ --format json

4. Advanced Query with Filters

gsc-cli query \ --site "https://example.com" \ --dimensions "query,country,device" \ --filters "country:usa,device:mobile" \ --date-range "2024-01-01:2024-01-31" \ --limit 1000 \ --format csv \ --output search-data.csv

5. URL Inspection

gsc-cli inspect \ --site "https://example.com" \ --url "https://example.com/important-page" \ --format json

6. Sitemap Management

# List sitemaps gsc-cli sitemaps --site "https://example.com" # Submit new sitemap gsc-cli sitemaps --site "https://example.com" --submit "sitemap.xml"
💡 Pro Tip: Use the --output flag to save results to files for further analysis or integration with other tools.

⚙️ Configuration Options

Environment Variables

# Optional: Custom credentials path GSC_CREDENTIALS_PATH=/path/to/credentials.json # Optional: Custom token storage path GSC_TOKENS_PATH=/path/to/tokens.json # Optional: Default site GSC_DEFAULT_SITE=https://example.com

Available Dimensions

Available Metrics

Date Range Formats

Filter Examples

# Filter by country --filters "country:usa" # Filter by device type --filters "device:mobile" # Multiple filters --filters "country:usa,device:mobile,searchType:web" # Query pattern matching --filters "query:contains:brand"

🔄 Integration Examples

Daily SEO Monitoring Script

#!/bin/bash # Daily SEO monitoring script # Get yesterday's data gsc-cli query \ --site "https://example.com" \ --dimensions "query,page,position" \ --date-range "yesterday" \ --limit 100 \ --format csv \ --output "daily-seo-$(date +%Y-%m-%d).csv" # Get mobile vs desktop comparison gsc-cli query \ --site "https://example.com" \ --dimensions "device" \ --date-range "last-7-days" \ --format json \ --output "device-performance.json"

Automated Reporting

# Weekly report generation gsc-cli query \ --site "https://example.com" \ --dimensions "query,clicks,impressions,ctr,position" \ --date-range "last-7-days" \ --limit 50 \ --format csv \ --output "weekly-seo-report.csv" # Email the report (requires additional setup) # mail -s "Weekly SEO Report" team@company.com < weekly-seo-report.csv

🔗 Related Tools

🚨 Troubleshooting

Common Issues

Authentication Errors

# Clear stored tokens and re-authenticate gsc-cli auth --reset

API Quota Limits

If you hit API quota limits, consider:

Permission Issues

Ensure your Google account has the appropriate permissions:

📞 Support