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.
