Metadata-Version: 2.4
Name: kctl-gsc
Version: 0.3.0
Summary: Kodemeio Google Search Console CLI — properties, queries, indexing, reports
Author-email: Kodemeio <dev@kodeme.io>
License-Expression: MIT
Keywords: cli,google,kodemeio,search-console,seo
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.12
Requires-Dist: google-api-python-client>=2.149.0
Requires-Dist: google-auth>=2.35.0
Requires-Dist: kctl-lib>=0.5.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.15.0
Provides-Extra: dev
Requires-Dist: google-api-python-client-stubs>=1.28.0; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# kctl-gsc

Kodemeio Google Search Console CLI — manage properties, search queries, URL indexing, and SEO reports.

## Installation

```bash
uv tool install kctl-gsc
```

Requires `kctl-lib>=0.4.0` and Google API client libraries (installed automatically).

## Quick Start

```bash
# Configure a profile (service account credentials)
kctl-gsc config init

# List all GSC properties
kctl-gsc properties list

# Top queries for the last 28 days
kctl-gsc queries top --days 28

# Inspect a URL's index status
kctl-gsc inspect url https://example.com/page

# Generate an overview report
kctl-gsc reports overview

# Export raw search analytics to CSV
kctl-gsc export csv --output analytics.csv
```

## Command Groups

| Group | Description | Key Commands |
|-------|-------------|--------------|
| `properties` | GSC property browsing | `list`, `show` |
| `queries` | Search Analytics (query dimension) | `top`, `search`, `trends` |
| `pages` | Search Analytics by page | `top` |
| `sitemaps` | Sitemap management | `list`, `submit`, `delete` |
| `inspect` | URL Inspection API | `url`, `bulk`, `request-index` |
| `reports` | Opinionated SEO reports | `overview`, `product`, `opportunities`, `drift` |
| `export` | Raw data export | `csv`, `json` |
| `config` | Profile management | `init`, `add`, `use`, `show`, `validate`, `remove`, `set`, `profiles`, `current` |
| `doctor` | Diagnostic checks | API connectivity, auth validation |

## Global Options

| Option | Short | Description |
|--------|-------|-------------|
| `--profile` | `-p` | Config profile name |
| `--property` | | GSC property URI override |
| `--credentials-file` | | Service account JSON file override |
| `--format` | `-f` | Output format: `pretty`, `json`, `csv`, `yaml` |
| `--json` | | Shortcut for `--format json` |
| `--quiet` | `-q` | Suppress info messages |
| `--no-header` | | Omit headers in CSV output |
| `--version` | `-V` | Show version and exit |

## Configuration

Config lives in `~/.config/kodemeio/config.yaml` under the `gsc` service key.

```bash
# Interactive setup
kctl-gsc config init

# Add a named profile
kctl-gsc config add --profile production \
  --property sc-domain:example.com \
  --credentials-file ~/sa-key.json

# Switch active profile
kctl-gsc config use production

# Show current config (secrets masked)
kctl-gsc config show
```

## Development

```bash
cd packages/kctl-gsc
uv sync --all-extras
uv run pytest tests/ -v
uv run mypy src/
uv run ruff check src/
uv build
```
