google-search-console-cli 0.1.0__py3-none-any.whl

google_search_console_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: google-search-console-cli
+Version: 0.1.0
+Summary: CLI for Google Search Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.7
+Requires-Dist: google-api-python-client>=2.140.0
+Requires-Dist: google-auth>=2.32.0
+Requires-Dist: google-auth-oauthlib>=1.2.1
+Requires-Dist: requests>=2.32.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+
+# google-search-console-cli
+
+CLI for Google Search Console using the official Google API Python client.
+
+## Highlights
+- Native OAuth login: no mandatory `gcloud` setup
+- `pipx`-friendly install (`gsc` available globally)
+- Site operations: list/get/add
+- Analytics queries by date/query/page with Search Console filters
+- Output formats: table, json, csv
+- Diagnostics: `gsc doctor`
+
+## Install (Recommended)
+
+Install with `pipx` so `gsc` is available on your PATH:
+
+```bash
+pipx install google-search-console-cli
+```
+
+## Install From Source
+
+If you cloned this repository and want to run from source, use one of these options.
+
+Option 1: Local virtualenv (best for development)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Fish shell activation:
+
+```fish
+. .venv/bin/activate.fish
+```
+
+Then run:
+
+```bash
+gsc --help
+```
+
+Option 2: Install from source with `pipx` (best for day-to-day CLI usage)
+
+```bash
+pipx install -e /absolute/path/to/google-search-console-cli
+```
+
+## OAuth Setup (Recommended)
+
+Create a Google OAuth client of type **Desktop app**, then run:
+
+```bash
+gsc auth login --client-secret /absolute/path/to/client_secret.json
+```
+
+Verify:
+
+```bash
+gsc auth whoami
+gsc doctor
+```
+
+## Optional: Set Default Site
+
+```bash
+gsc config set default-site sc-domain:example.com
+gsc config get default-site
+```
+
+After this, you can omit `--site` in commands that need a property.
+
+## Usage
+
+### Sites
+```bash
+gsc site list
+gsc site get --site sc-domain:example.com
+gsc site add --site sc-domain:example.com
+```
+
+### Analytics
+```bash
+gsc analytics query \
+  --site sc-domain:example.com \
+  --start-date 2026-01-01 \
+  --end-date 2026-01-31 \
+  --dimension date \
+  --dimension query \
+  --filter query:contains:brand \
+  --filter device:equals:MOBILE
+```
+
+Save as CSV:
+
+```bash
+gsc analytics query \
+  --site sc-domain:example.com \
+  --start-date 2026-01-01 \
+  --end-date 2026-01-31 \
+  --dimension page \
+  --output csv \
+  --csv-path ./analytics.csv
+```
+
+## Filter Syntax
+
+Use repeatable filters in this format:
+
+```text
+dimension:operator:expression
+```
+
+Supported filter dimensions:
+- `country`
+- `device`
+- `page`
+- `query`
+- `searchAppearance`
+
+Supported operators:
+- `contains`
+- `equals`
+- `notContains`
+- `notEquals`
+- `includingRegex`
+- `excludingRegex`
+
+## Convenience Script (Repo Local)
+
+If you cloned this repo and want one command setup:
+
+```bash
+./scripts/setup.sh /absolute/path/to/client_secret.json
+```
+
+## Credentials and Config Paths
+
+By default:
+- Credentials: `~/.config/gsc-cli/credentials.json`
+- Config: `~/.config/gsc-cli/config.json`
+
+Override with env vars:
+- `GSC_CREDENTIALS_FILE`
+- `GSC_APP_CONFIG_FILE`
+- `GSC_CONFIG_DIR`
+
+## ADC Fallback (Optional)
+
+If you prefer ADC via `gcloud`, the CLI still supports it:
+
+```bash
+gcloud auth application-default login \
+  --client-id-file=/absolute/path/to/client_secret.json \
+  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/webmasters
+```
+
+## Notes
+- Use Search Console property formats like `sc-domain:example.com` or URL-prefix properties.
+- `site add` requires write scope (`webmasters`).
+- `analytics query --aggregation-type byProperty` cannot be combined with `page` grouping/filtering.

google_search_console_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+gsc_cli/__init__.py,sha256=tLT0VSrJ4HK8Agb0I_htNiiLUgLzNWaWbyFtquOpg3I,90
+gsc_cli/analytics.py,sha256=7mG6qFaKUOjFJSttDj23C34lv0KtRHXX3L1ZlMIZewI,5168
+gsc_cli/auth.py,sha256=oZPMZCO04X2Khf4JR01kO5oO7ebeYk4AS6Cq81AxEGQ,6008
+gsc_cli/cli.py,sha256=sUQ_MLtcfN2RzEIOfbCj4U3is-cI0Piw7qhAXo0tcDw,11807
+gsc_cli/client.py,sha256=rmtTnaFdFzL_EzjpPKYgc_9OpwC-HFw_bwIU2sQ7M1c,458
+gsc_cli/config.py,sha256=53vh9O1VDRTgXNxU7FC8GhCt9BRfrDO4a49DsJpWugM,1171
+gsc_cli/output.py,sha256=z0jnng6o-Vfctu-pLiOkq9nQ0SQvc_xtUtPQV0xukGI,2119
+gsc_cli/paths.py,sha256=r7Z4UxqopJs6NFwClJCPhcSxFQTL7S3C8wXcu2-QvEE,683
+google_search_console_cli-0.1.0.dist-info/METADATA,sha256=noIEfDd7FEU7QMudWLOEVhuSi056Da5-BwVD85ZmWbM,3684
+google_search_console_cli-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+google_search_console_cli-0.1.0.dist-info/entry_points.txt,sha256=yLOaaaOa7HmDIfXrYt7c7zgOJp914F3ljaAyktTKnlQ,40
+google_search_console_cli-0.1.0.dist-info/top_level.txt,sha256=hYW7ll0hNbfn96W9Q4p4tCpCe4o98ZDGJEc2GI1iOvc,8
+google_search_console_cli-0.1.0.dist-info/RECORD,,

google_search_console_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

google_search_console_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gsc = gsc_cli.cli:cli

google_search_console_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gsc_cli

gsc_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Google Search Console CLI package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

gsc_cli/analytics.py

@@ -0,0 +1,180 @@
+"""Search Analytics request and parsing helpers."""
+
+from __future__ import annotations
+
+from datetime import date
+
+ALLOWED_DIMENSIONS = {
+    "country",
+    "device",
+    "page",
+    "query",
+    "searchAppearance",
+    "date",
+    "hour",
+}
+
+ALLOWED_FILTER_DIMENSIONS = {
+    "country",
+    "device",
+    "page",
+    "query",
+    "searchAppearance",
+}
+
+ALLOWED_OPERATORS = {
+    "contains",
+    "equals",
+    "notContains",
+    "notEquals",
+    "includingRegex",
+    "excludingRegex",
+}
+
+ALLOWED_TYPES = {"web", "image", "video", "news", "discover", "googleNews"}
+ALLOWED_AGGREGATION_TYPES = {"auto", "byPage", "byProperty", "byNewsShowcasePanel"}
+ALLOWED_DATA_STATES = {"final", "all", "hourly_all"}
+
+
+class ValidationError(ValueError):
+    """Raised for invalid user input before API execution."""
+
+
+def parse_ymd(value: str) -> str:
+    """Validate YYYY-MM-DD format and return unchanged string."""
+    try:
+        date.fromisoformat(value)
+    except ValueError as exc:
+        raise ValidationError(f"Invalid date '{value}'. Use YYYY-MM-DD.") from exc
+    return value
+
+
+def validate_date_range(start_date: str, end_date: str) -> None:
+    start = date.fromisoformat(start_date)
+    end = date.fromisoformat(end_date)
+    if start > end:
+        raise ValidationError("start-date must be <= end-date.")
+
+
+def parse_filter_expression(filter_expression: str) -> dict:
+    """Parse one filter expression in the form dimension:operator:expression."""
+    parts = filter_expression.split(":", 2)
+    if len(parts) != 3:
+        raise ValidationError(
+            "Invalid --filter format. Expected dimension:operator:expression"
+        )
+
+    dimension, operator, expression = parts
+    if dimension not in ALLOWED_FILTER_DIMENSIONS:
+        allowed = ", ".join(sorted(ALLOWED_FILTER_DIMENSIONS))
+        raise ValidationError(
+            f"Unsupported filter dimension '{dimension}'. Allowed: {allowed}"
+        )
+
+    if operator not in ALLOWED_OPERATORS:
+        allowed = ", ".join(sorted(ALLOWED_OPERATORS))
+        raise ValidationError(
+            f"Unsupported filter operator '{operator}'. Allowed: {allowed}"
+        )
+
+    if expression == "":
+        raise ValidationError("Filter expression cannot be empty.")
+
+    return {
+        "dimension": dimension,
+        "operator": operator,
+        "expression": expression,
+    }
+
+
+def build_query_request(
+    *,
+    start_date: str,
+    end_date: str,
+    dimensions: tuple[str, ...],
+    query_type: str,
+    aggregation_type: str,
+    row_limit: int,
+    start_row: int,
+    data_state: str,
+    filters: tuple[str, ...],
+) -> dict:
+    """Build and validate a Search Analytics query request body."""
+    parse_ymd(start_date)
+    parse_ymd(end_date)
+    validate_date_range(start_date, end_date)
+
+    if query_type not in ALLOWED_TYPES:
+        raise ValidationError(f"Unsupported type '{query_type}'.")
+
+    if aggregation_type not in ALLOWED_AGGREGATION_TYPES:
+        raise ValidationError(f"Unsupported aggregation-type '{aggregation_type}'.")
+
+    if data_state not in ALLOWED_DATA_STATES:
+        raise ValidationError(f"Unsupported data-state '{data_state}'.")
+
+    if not (1 <= row_limit <= 25000):
+        raise ValidationError("row-limit must be between 1 and 25000.")
+
+    if start_row < 0:
+        raise ValidationError("start-row must be >= 0.")
+
+    for dimension in dimensions:
+        if dimension not in ALLOWED_DIMENSIONS:
+            allowed = ", ".join(sorted(ALLOWED_DIMENSIONS))
+            raise ValidationError(
+                f"Unsupported dimension '{dimension}'. Allowed: {allowed}"
+            )
+
+    parsed_filters = [parse_filter_expression(item) for item in filters]
+
+    uses_page_dimension = "page" in dimensions
+    uses_page_filter = any(item["dimension"] == "page" for item in parsed_filters)
+    if aggregation_type == "byProperty" and (uses_page_dimension or uses_page_filter):
+        raise ValidationError(
+            "aggregation-type=byProperty cannot be used with page dimension or page filter."
+        )
+
+    body = {
+        "startDate": start_date,
+        "endDate": end_date,
+        "type": query_type,
+        "aggregationType": aggregation_type,
+        "rowLimit": row_limit,
+        "startRow": start_row,
+        "dataState": data_state,
+    }
+
+    if dimensions:
+        body["dimensions"] = list(dimensions)
+
+    if parsed_filters:
+        body["dimensionFilterGroups"] = [
+            {
+                "groupType": "and",
+                "filters": parsed_filters,
+            }
+        ]
+
+    return body
+
+
+def rows_to_records(response: dict, dimensions: tuple[str, ...]) -> list[dict]:
+    """Convert API rows into flat records suitable for output formats."""
+    rows = response.get("rows", [])
+    records: list[dict] = []
+
+    for row in rows:
+        record: dict = {}
+        keys = row.get("keys", [])
+
+        for index, dimension in enumerate(dimensions):
+            record[dimension] = keys[index] if index < len(keys) else None
+
+        for metric in ("clicks", "impressions", "ctr", "position"):
+            if metric in row:
+                record[metric] = row[metric]
+
+        records.append(record)
+
+    return records

gsc_cli/auth.py

@@ -0,0 +1,186 @@
+"""Authentication helpers for Google Search Console."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import google.auth
+from google.auth.exceptions import DefaultCredentialsError, RefreshError, TransportError
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+from gsc_cli.paths import credentials_file
+
+READ_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly"
+WRITE_SCOPE = "https://www.googleapis.com/auth/webmasters"
+CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform"
+
+
+class AuthError(RuntimeError):
+    """Raised when credentials cannot be loaded or refreshed."""
+
+
+def login_with_client_secret(
+    client_secret_path: str,
+    *,
+    write: bool = True,
+    launch_browser: bool = True,
+) -> Path:
+    """Run OAuth installed-app flow and persist credential file."""
+    scope = WRITE_SCOPE if write else READ_SCOPE
+
+    try:
+        flow = InstalledAppFlow.from_client_secrets_file(
+            client_secret_path,
+            scopes=[scope],
+        )
+        credentials = flow.run_local_server(port=0, open_browser=launch_browser)
+    except OSError as exc:
+        raise AuthError(f"Could not read client secret file: {client_secret_path}") from exc
+    except Exception as exc:  # noqa: BLE001
+        raise AuthError(f"OAuth login failed: {exc}") from exc
+
+    path = credentials_file()
+    _persist_credentials(credentials, path)
+    return path
+
+
+def load_credentials(write: bool = False):
+    """Load credentials, preferring local stored OAuth tokens, then ADC fallback."""
+    required_scope = WRITE_SCOPE if write else READ_SCOPE
+
+    stored = _load_stored_credentials(required_scope)
+    if stored is not None:
+        return stored
+
+    return _load_adc_credentials(required_scope)
+
+
+def stored_credentials_info() -> dict | None:
+    """Return metadata about stored credentials if present."""
+    path = credentials_file()
+    if not path.exists():
+        return None
+
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise AuthError(f"Stored credentials are invalid JSON: {path}") from exc
+
+    scopes = payload.get("scopes", [])
+    if not isinstance(scopes, list):
+        scopes = []
+
+    return {
+        "path": str(path),
+        "scopes": scopes,
+        "has_refresh_token": bool(payload.get("refresh_token")),
+        "client_id": payload.get("client_id"),
+    }
+
+
+def _load_stored_credentials(required_scope: str):
+    path = credentials_file()
+    if not path.exists():
+        return None
+
+    try:
+        credentials = Credentials.from_authorized_user_file(str(path))
+    except Exception as exc:  # noqa: BLE001
+        raise AuthError(
+            f"Stored credentials at {path} are unreadable. "
+            "Run `gsc auth login --client-secret <path>` again."
+        ) from exc
+
+    _validate_scope(credentials.scopes, required_scope)
+    return _ensure_valid_credentials(credentials, source_path=path, required_scope=required_scope)
+
+
+def _load_adc_credentials(required_scope: str):
+    try:
+        credentials, _ = google.auth.default(scopes=[required_scope])
+    except DefaultCredentialsError as exc:
+        raise AuthError(_missing_credentials_message(required_scope)) from exc
+
+    return _ensure_valid_credentials(
+        credentials,
+        source_path=None,
+        required_scope=required_scope,
+    )
+
+
+def _ensure_valid_credentials(credentials, source_path: Path | None, required_scope: str):
+    if credentials.valid:
+        return credentials
+
+    if credentials.expired and credentials.refresh_token:
+        try:
+            credentials.refresh(Request())
+        except (RefreshError, TransportError) as exc:
+            if source_path:
+                raise AuthError(
+                    "Stored OAuth credentials could not be refreshed. "
+                    "Run `gsc auth login --client-secret <path>` again."
+                ) from exc
+            raise AuthError(_refresh_failed_message(required_scope)) from exc
+
+        if source_path:
+            _persist_credentials(credentials, source_path)
+        return credentials
+
+    if source_path:
+        raise AuthError(
+            "Stored OAuth credentials are invalid and cannot be refreshed. "
+            "Run `gsc auth login --client-secret <path>` again."
+        )
+
+    raise AuthError(_refresh_failed_message(required_scope))
+
+
+def _persist_credentials(credentials: Credentials, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(credentials.to_json() + "\n", encoding="utf-8")
+
+
+def _validate_scope(granted_scopes: list[str] | None, required_scope: str) -> None:
+    if not granted_scopes:
+        raise AuthError(
+            "Stored credentials missing scopes. "
+            "Run `gsc auth login --client-secret <path>` again."
+        )
+
+    scope_set = set(granted_scopes)
+    if required_scope == READ_SCOPE and WRITE_SCOPE in scope_set:
+        return
+
+    if required_scope in scope_set:
+        return
+
+    raise AuthError(
+        f"Stored credentials do not include required scope '{required_scope}'. "
+        "Run `gsc auth login --client-secret <path>` again."
+    )
+
+
+def _missing_credentials_message(scope: str) -> str:
+    scopes = f"{CLOUD_PLATFORM_SCOPE},{scope}"
+    return (
+        "No usable credentials found. Preferred setup:\n"
+        "gsc auth login --client-secret <path-to-client-secret.json>\n\n"
+        "ADC fallback:\n"
+        "gcloud auth application-default login "
+        "--client-id-file=<path-to-client-secret.json> "
+        f"--scopes={scopes}"
+    )
+
+
+def _refresh_failed_message(scope: str) -> str:
+    scopes = f"{CLOUD_PLATFORM_SCOPE},{scope}"
+    return (
+        "Failed to refresh ADC credentials. Re-run:\n"
+        "gcloud auth application-default login "
+        "--client-id-file=<path-to-client-secret.json> "
+        f"--scopes={scopes}"
+    )

gsc_cli/cli.py

@@ -0,0 +1,392 @@
+"""Click CLI for Google Search Console."""
+
+from __future__ import annotations
+
+import json
+import sys
+from functools import wraps
+
+import click
+from googleapiclient.errors import HttpError
+
+from gsc_cli import __version__
+from gsc_cli.analytics import (
+    ALLOWED_AGGREGATION_TYPES,
+    ALLOWED_DATA_STATES,
+    ALLOWED_DIMENSIONS,
+    ALLOWED_TYPES,
+    ValidationError,
+    build_query_request,
+    rows_to_records,
+)
+from gsc_cli.auth import AuthError, load_credentials, login_with_client_secret, stored_credentials_info
+from gsc_cli.client import build_search_console_service
+from gsc_cli.config import ConfigError, get_default_site, set_default_site
+from gsc_cli.output import render_records
+from gsc_cli.paths import app_config_file, credentials_file
+
+USER_INPUT_EXIT_CODE = 2
+AUTH_EXIT_CODE = 3
+API_EXIT_CODE = 4
+
+
+@click.group()
+@click.version_option(version=__version__)
+def cli() -> None:
+    """Google Search Console CLI."""
+
+
+def command_errors(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except (ValidationError, ValueError, ConfigError) as exc:
+            click.echo(f"Error: {exc}", err=True)
+            raise click.exceptions.Exit(USER_INPUT_EXIT_CODE) from exc
+        except AuthError as exc:
+            click.echo(f"Auth error: {exc}", err=True)
+            raise click.exceptions.Exit(AUTH_EXIT_CODE) from exc
+        except HttpError as exc:
+            status = getattr(exc.resp, "status", "unknown")
+            click.echo(f"API error ({status}): {_extract_http_error(exc)}", err=True)
+            raise click.exceptions.Exit(API_EXIT_CODE) from exc
+
+    return wrapper
+
+
+def _extract_http_error(exc: HttpError) -> str:
+    content = getattr(exc, "content", None)
+    if not content:
+        return str(exc)
+
+    try:
+        payload = json.loads(content.decode("utf-8"))
+    except Exception:  # noqa: BLE001
+        return str(exc)
+
+    if isinstance(payload, dict):
+        error = payload.get("error", {})
+        message = error.get("message")
+        if message:
+            return message
+
+    return str(exc)
+
+
+def _resolve_site(site_url: str | None) -> str:
+    if site_url:
+        return site_url
+
+    default_site = get_default_site()
+    if default_site:
+        return default_site
+
+    raise ValidationError(
+        "No site specified. Pass --site or set one with "
+        "`gsc config set default-site <siteUrl>`."
+    )
+
+
+@cli.group()
+def auth() -> None:
+    """Authenticate and inspect credentials."""
+
+
+@auth.command("login")
+@click.option(
+    "--client-secret",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=str),
+    help="Path to OAuth client secret JSON.",
+)
+@click.option("--readonly", is_flag=True, help="Request readonly scope only.")
+@click.option("--no-launch-browser", is_flag=True, help="Do not auto-open browser.")
+@command_errors
+def auth_login(client_secret: str, readonly: bool, no_launch_browser: bool) -> None:
+    """Run OAuth login and save local credentials."""
+    output_path = login_with_client_secret(
+        client_secret,
+        write=not readonly,
+        launch_browser=not no_launch_browser,
+    )
+    click.echo(f"Saved credentials to {output_path}")
+
+
+@auth.command("whoami")
+@click.option("--output", "output_format", type=click.Choice(["table", "json"]), default="table")
+@command_errors
+def auth_whoami(output_format: str) -> None:
+    """Show locally stored credential details."""
+    info = stored_credentials_info()
+    if info is None:
+        raise ValidationError(
+            "No local OAuth credentials found. Run `gsc auth login --client-secret <path>` first."
+        )
+
+    record = {
+        "path": info["path"],
+        "has_refresh_token": info["has_refresh_token"],
+        "scopes": ",".join(info["scopes"]),
+        "client_id": info.get("client_id") or "",
+    }
+    click.echo(render_records([record], output_format=output_format))
+
+
+@cli.group()
+def config() -> None:
+    """Manage CLI configuration."""
+
+
+@config.group("set")
+def config_set() -> None:
+    """Set config values."""
+
+
+@config_set.command("default-site")
+@click.argument("site_url")
+@command_errors
+def config_set_default_site(site_url: str) -> None:
+    """Set default site used when --site is omitted."""
+    path = set_default_site(site_url)
+    click.echo(f"Set default-site to {site_url}")
+    click.echo(f"Config file: {path}")
+
+
+@config.group("get")
+def config_get() -> None:
+    """Get config values."""
+
+
+@config_get.command("default-site")
+@command_errors
+def config_get_default_site() -> None:
+    """Get default site."""
+    site_url = get_default_site()
+    if not site_url:
+        raise ValidationError("default-site is not set.")
+    click.echo(site_url)
+
+
+@cli.command("doctor")
+def doctor() -> None:
+    """Run diagnostics for environment, auth, and API connectivity."""
+    checks: list[dict] = []
+    failures = 0
+
+    checks.append(
+        {
+            "check": "python",
+            "status": "ok",
+            "detail": sys.version.split()[0],
+        }
+    )
+
+    checks.append(
+        {
+            "check": "config-path",
+            "status": "ok",
+            "detail": str(app_config_file()),
+        }
+    )
+
+    default_site = get_default_site()
+    checks.append(
+        {
+            "check": "default-site",
+            "status": "ok" if default_site else "warn",
+            "detail": default_site or "not set",
+        }
+    )
+
+    info = None
+    try:
+        info = stored_credentials_info()
+    except AuthError as exc:
+        checks.append(
+            {
+                "check": "stored-credentials",
+                "status": "fail",
+                "detail": str(exc),
+            }
+        )
+        failures += 1
+
+    if info is None:
+        checks.append(
+            {
+                "check": "stored-credentials",
+                "status": "warn",
+                "detail": f"not found at {credentials_file()} (ADC fallback may still work)",
+            }
+        )
+    elif info:
+        checks.append(
+            {
+                "check": "stored-credentials",
+                "status": "ok",
+                "detail": info["path"],
+            }
+        )
+
+    try:
+        load_credentials(write=False)
+        checks.append(
+            {
+                "check": "auth-refresh",
+                "status": "ok",
+                "detail": "credentials load and refresh succeeded",
+            }
+        )
+    except AuthError as exc:
+        checks.append(
+            {
+                "check": "auth-refresh",
+                "status": "fail",
+                "detail": str(exc),
+            }
+        )
+        failures += 1
+
+    try:
+        service = build_search_console_service(write=False)
+        response = service.sites().list().execute()
+        count = len(response.get("siteEntry", []))
+        checks.append(
+            {
+                "check": "api-connectivity",
+                "status": "ok",
+                "detail": f"sites.list succeeded ({count} properties)",
+            }
+        )
+    except (AuthError, HttpError, Exception) as exc:  # noqa: BLE001
+        checks.append(
+            {
+                "check": "api-connectivity",
+                "status": "fail",
+                "detail": str(exc),
+            }
+        )
+        failures += 1
+
+    click.echo(render_records(checks, output_format="table"))
+    if failures:
+        raise click.exceptions.Exit(1)
+
+
+@cli.group()
+def site() -> None:
+    """Manage Search Console properties."""
+
+
+@site.command("list")
+@click.option("--output", "output_format", type=click.Choice(["table", "json", "csv"]), default="table")
+@click.option("--csv-path", type=click.Path(dir_okay=False, writable=True, path_type=str), default=None)
+@command_errors
+def site_list(output_format: str, csv_path: str | None) -> None:
+    """List accessible Search Console properties."""
+    service = build_search_console_service(write=False)
+    response = service.sites().list().execute()
+    entries = response.get("siteEntry", [])
+
+    records = [
+        {
+            "siteUrl": item.get("siteUrl"),
+            "permissionLevel": item.get("permissionLevel"),
+        }
+        for item in entries
+    ]
+
+    click.echo(render_records(records, output_format=output_format, csv_path=csv_path))
+
+
+@site.command("get")
+@click.option("--site", "site_url", required=False, help="Site URL, e.g. sc-domain:example.com")
+@click.option("--output", "output_format", type=click.Choice(["table", "json", "csv"]), default="json")
+@click.option("--csv-path", type=click.Path(dir_okay=False, writable=True, path_type=str), default=None)
+@command_errors
+def site_get(site_url: str | None, output_format: str, csv_path: str | None) -> None:
+    """Get one Search Console property."""
+    resolved_site = _resolve_site(site_url)
+    service = build_search_console_service(write=False)
+    item = service.sites().get(siteUrl=resolved_site).execute()
+    records = [item]
+    click.echo(render_records(records, output_format=output_format, csv_path=csv_path))
+
+
+@site.command("add")
+@click.option("--site", "site_url", required=False, help="Site URL, e.g. sc-domain:example.com")
+@command_errors
+def site_add(site_url: str | None) -> None:
+    """Add a Search Console property."""
+    resolved_site = _resolve_site(site_url)
+    service = build_search_console_service(write=True)
+    service.sites().add(siteUrl=resolved_site).execute()
+    click.echo(f"Added site: {resolved_site}")
+
+
+@cli.group()
+def analytics() -> None:
+    """Query Search Analytics."""
+
+
+@analytics.command("query")
+@click.option("--site", "site_url", required=False, help="Site URL, e.g. sc-domain:example.com")
+@click.option("--start-date", required=True, help="Start date in YYYY-MM-DD")
+@click.option("--end-date", required=True, help="End date in YYYY-MM-DD")
+@click.option("--dimension", "dimensions", multiple=True, type=click.Choice(sorted(ALLOWED_DIMENSIONS)))
+@click.option("--type", "query_type", default="web", type=click.Choice(sorted(ALLOWED_TYPES)))
+@click.option(
+    "--aggregation-type",
+    default="auto",
+    type=click.Choice(sorted(ALLOWED_AGGREGATION_TYPES)),
+)
+@click.option("--row-limit", type=click.IntRange(1, 25000), default=1000)
+@click.option("--start-row", type=click.IntRange(min=0), default=0)
+@click.option("--data-state", type=click.Choice(sorted(ALLOWED_DATA_STATES)), default="final")
+@click.option(
+    "--filter",
+    "filters",
+    multiple=True,
+    help="Filter expression in dimension:operator:expression format.",
+)
+@click.option("--output", "output_format", type=click.Choice(["table", "json", "csv"]), default="table")
+@click.option("--csv-path", type=click.Path(dir_okay=False, writable=True, path_type=str), default=None)
+@command_errors
+def analytics_query(
+    site_url: str | None,
+    start_date: str,
+    end_date: str,
+    dimensions: tuple[str, ...],
+    query_type: str,
+    aggregation_type: str,
+    row_limit: int,
+    start_row: int,
+    data_state: str,
+    filters: tuple[str, ...],
+    output_format: str,
+    csv_path: str | None,
+) -> None:
+    """Run a Search Analytics query."""
+    resolved_site = _resolve_site(site_url)
+    request_body = build_query_request(
+        start_date=start_date,
+        end_date=end_date,
+        dimensions=dimensions,
+        query_type=query_type,
+        aggregation_type=aggregation_type,
+        row_limit=row_limit,
+        start_row=start_row,
+        data_state=data_state,
+        filters=filters,
+    )
+
+    service = build_search_console_service(write=False)
+    response = service.searchanalytics().query(siteUrl=resolved_site, body=request_body).execute()
+
+    records = rows_to_records(response, dimensions)
+    click.echo(render_records(records, output_format=output_format, csv_path=csv_path))
+
+
+if __name__ == "__main__":
+    cli()

gsc_cli/client.py

@@ -0,0 +1,18 @@
+"""Google Search Console API client helpers."""
+
+from __future__ import annotations
+
+from googleapiclient.discovery import build
+
+from gsc_cli.auth import load_credentials
+
+
+def build_search_console_service(write: bool = False):
+    """Create a Search Console API service client."""
+    credentials = load_credentials(write=write)
+    return build(
+        "searchconsole",
+        "v1",
+        credentials=credentials,
+        cache_discovery=False,
+    )

gsc_cli/config.py

@@ -0,0 +1,47 @@
+"""Persistent CLI configuration helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from gsc_cli.paths import app_config_file
+
+
+class ConfigError(RuntimeError):
+    """Raised for invalid config state."""
+
+
+def load_config() -> dict:
+    path = app_config_file()
+    if not path.exists():
+        return {}
+
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"Config file is not valid JSON: {path}") from exc
+
+
+def save_config(config: dict) -> Path:
+    path = app_config_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def set_default_site(site_url: str) -> Path:
+    if not site_url.strip():
+        raise ConfigError("default-site cannot be empty")
+
+    config = load_config()
+    config["default_site"] = site_url.strip()
+    return save_config(config)
+
+
+def get_default_site() -> str | None:
+    value = load_config().get("default_site")
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    return value or None

gsc_cli/output.py

@@ -0,0 +1,70 @@
+"""Output rendering helpers for CLI commands."""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+
+
+def render_records(records: list[dict], output_format: str, csv_path: str | None = None) -> str:
+    if output_format == "json":
+        return json.dumps(records, indent=2)
+
+    if output_format == "csv":
+        if not csv_path:
+            raise ValueError("csv_path is required when output format is csv")
+        _write_csv(records, csv_path)
+        return f"Wrote {len(records)} row(s) to {csv_path}"
+
+    if output_format == "table":
+        return _render_table(records)
+
+    raise ValueError(f"Unsupported output format: {output_format}")
+
+
+def _write_csv(records: list[dict], csv_path: str) -> None:
+    path = Path(csv_path)
+    fieldnames: list[str] = []
+
+    if records:
+        for record in records:
+            for key in record.keys():
+                if key not in fieldnames:
+                    fieldnames.append(key)
+
+    with path.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=fieldnames)
+        if fieldnames:
+            writer.writeheader()
+            writer.writerows(records)
+
+
+def _render_table(records: list[dict]) -> str:
+    if not records:
+        return "No rows found."
+
+    headers: list[str] = []
+    for record in records:
+        for key in record.keys():
+            if key not in headers:
+                headers.append(key)
+
+    widths = {key: len(key) for key in headers}
+    for record in records:
+        for key in headers:
+            cell = "" if record.get(key) is None else str(record.get(key))
+            widths[key] = max(widths[key], len(cell))
+
+    header_line = " | ".join(key.ljust(widths[key]) for key in headers)
+    separator_line = "-+-".join("-" * widths[key] for key in headers)
+
+    lines = [header_line, separator_line]
+    for record in records:
+        line = " | ".join(
+            ("" if record.get(key) is None else str(record.get(key))).ljust(widths[key])
+            for key in headers
+        )
+        lines.append(line)
+
+    return "\n".join(lines)

gsc_cli/paths.py

@@ -0,0 +1,27 @@
+"""Filesystem paths used by the CLI."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def config_dir() -> Path:
+    env_value = os.environ.get("GSC_CONFIG_DIR")
+    if env_value:
+        return Path(env_value).expanduser()
+    return Path.home() / ".config" / "gsc-cli"
+
+
+def credentials_file() -> Path:
+    env_value = os.environ.get("GSC_CREDENTIALS_FILE")
+    if env_value:
+        return Path(env_value).expanduser()
+    return config_dir() / "credentials.json"
+
+
+def app_config_file() -> Path:
+    env_value = os.environ.get("GSC_APP_CONFIG_FILE")
+    if env_value:
+        return Path(env_value).expanduser()
+    return config_dir() / "config.json"