Google Search Console CLI 技能

使用此技能来操作和排查此仓库中的 gsc CLI。

使用时机

当任务涉及以下任何内容时，使用此技能：

• - 为 Google Search Console 设置 OAuth 凭据
• 验证此 CLI
• 列出属性、管理站点地图、URL 检查或搜索分析查询
• 诊断身份验证/配置/API 连接问题

前提条件

• - 已安装此项目的 Python 环境（gsc 命令可用）
• 拥有至少一个 Search Console 属性访问权限的 Google 账号
• 为 OAuth 使用的 Google Cloud 项目启用 Search Console API

安装此 CLI

推荐方式（pipx，全局 gsc 命令）：

bash
python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install google-search-console-cli
gsc --version

从源码安装（开发模式）：

bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
gsc --help

从源码安装（pipx，可编辑模式）：

bash
pipx install -e /absolute/path/to/google-search-console-cli
gsc --help

在 Google Cloud 中设置 OAuth 客户端（桌面应用）

截至 2026 年 2 月 26 日，按照以下步骤在 Google Cloud Console 中创建 OAuth 客户端凭据：

1. 1. 打开 Google Cloud Console 并选择/创建一个项目。
2. 为该项目启用 Search Console API。
3. 配置 OAuth 同意屏幕：

- 个人/测试用途选择 External（仅限 Workspace 组织选择 Internal） - 填写必填应用字段（应用名称、支持邮箱、开发者联系方式） - 如果应用处于测试模式，将您的 Google 账号添加为测试用户

1. 4. 进入 APIs & Services -> Credentials。
2. 点击 Create credentials -> OAuth client ID。
3. 选择应用类型 Desktop app。
4. 创建并下载 OAuth 客户端 JSON 文件（clientsecret*.json）。

注意：

• - UI 标签可能会变化，但最终必须获得桌面 OAuth 客户端 JSON 文件。
• 请妥善保管下载的 JSON 文件。

验证此 CLI

推荐登录流程：

bash
gsc auth login --client-secret /absolute/path/to/client_secret.json

有用的身份验证选项：

• - --readonly：仅请求只读范围（webmasters.readonly）
• --no-launch-browser：打印身份验证 URL 而不自动打开浏览器

验证凭据：

bash
gsc auth whoami
gsc doctor

默认存储路径：

• - 凭据：~/.config/gsc-cli/credentials.json
• 应用配置：~/.config/gsc-cli/config.json

环境变量覆盖：

• - GSCCREDENTIALSFILE
• GSCAPPCONFIGFILE
• GSCCONFIG_DIR

可选：设置默认属性

bash
gsc config set default-site sc-domain:example.com
gsc config get default-site

设置后，接受 --site 的命令可以省略该参数。

命令参考

顶层命令：

• - gsc --version
• gsc --help
• gsc doctor

auth

• - gsc auth login --client-secret FILE [--readonly] [--no-launch-browser]
• gsc auth whoami [--output table|json]

config

• - gsc config set default-site SITE_URL
• gsc config get default-site

site

• - gsc site list [--output table|json|csv] [--csv-path FILE]
• gsc site get [--site SITE] [--output table|json|csv] [--csv-path FILE]
• gsc site add [--site SITE]

SITE 示例：sc-domain:example.com。

sitemap

• - gsc sitemap list [--site SITE] [--sitemap-index TEXT] [--output table|json|csv] [--csv-path FILE]
• gsc sitemap get [--site SITE] --feedpath TEXT [--output table|json|csv] [--csv-path FILE]
• gsc sitemap submit [--site SITE] --feedpath TEXT
• gsc sitemap delete [--site SITE] --feedpath TEXT

--feedpath 别名：--path。

url

• - gsc url inspect [--site SITE] --url URL [--language-code CODE] [--output table|json|csv] [--csv-path FILE]

默认值：

• - --language-code en-US

analytics

• - gsc analytics query --start-date YYYY-MM-DD --end-date YYYY-MM-DD [options]

选项：

• - --site SITE
• --dimension country|date|device|hour|page|query|searchAppearance（可重复）
• --type discover|googleNews|image|news|video|web
• --aggregation-type auto|byNewsShowcasePanel|byPage|byProperty
• --row-limit 1..25000
• --start-row >=0
• --data-state all|final|hourly_all
• --filter dimension:operator:expression（可重复）
• --output table|json|csv
• --csv-path FILE

支持的筛选维度：

• - country、device、page、query、searchAppearance

支持的筛选运算符：

• - contains、equals、notContains、notEquals、includingRegex、excludingRegex

约束：

• - --aggregation-type byProperty 不能与 page 维度或 page 筛选器同时使用。

快速示例

bash

列出属性

gsc site list

获取单个属性

gsc site get --site sc-domain:example.com

列出站点地图

gsc sitemap list --site sc-domain:example.com

检查单个 URL

gsc url inspect --site sc-domain:example.com --url https://example.com/page --output json

分析查询

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

故障排除

• - Auth error: Stored credentials do not include required scope ...

- 使用所需范围重新运行登录。对于写入命令，运行登录时不加 --readonly。

• - No local OAuth credentials found...

- 运行：gsc auth login --client-secret

• - No site specified. Pass --site or set one...

- 传递 --site 或通过 gsc config set default-site ... 设置默认值

• - API 失败/设置状态不确定

- 首先运行 gsc doctor，然后处理失败的检查。