---
title: "Run your first Search Console query"
description: "Connect a Site and read live clicks, impressions, and position from Google Search Console."
canonical_url: "https://gscdump.com/gscdump-cli/guides/start/first-result"
last_updated: "2026-10-03T07:15:31.645Z"
---

# Run your first Search Console query

Start with one query. You need Node.js 22.13 or later in the 22 release line, or Node.js 24 or later. You also need access to a Google Search Console Site.

## Choose an access mode

The CLI has 2 access modes. [Choose access](/gscdump-cli/guides/start/choose-access) compares them.

- **Local mode** calls Google with your own credentials. A service account is the simplest path, and its key never expires.
- **Hosted mode** reads the record that [gscdump.com](http://gscdump.com) keeps for your Sites. The CLI never calls Google in Hosted mode.

## Install and connect

For Local mode with a service account, add the service account email as a user of the Site in Search Console first.

::pre{tabindex="0"}
```bash
npm install -g @gscdump/cli
gscdump auth login --mode local --service-account ./gsc-sa.json
gscdump auth status --json
gscdump sites --json
```
::

For Hosted mode, log in and [connect a Site](/app/onboarding?step=connect-sites) on [gscdump.com](http://gscdump.com):

::pre{tabindex="0"}
```bash
gscdump auth login --mode hosted
gscdump sites --json
gscdump query --site example.com --dimensions date --limit 7 --format json
```
::

Use a Site printed by `sites`. A domain Site may appear as `sc-domain:example.com`; pass `--site example.com` in the query. The CLI saves its credentials in its private configuration directory.

## Run one live query in Local mode

<docsexample title="First live query" input="gscdump query --live --site example.com --dimensions date --limit 7 --format json" result="Returned rows contain a date, clicks, and impressions. JSON metadata identifies the source as live." failure="If rows are empty, check the Site and final date window. If access fails, check sites and auth status." caption="Site: example.com; window: latest final 28 days; source: live Google Search Console; result fields from the CLI contract."></docsexample>

::pre{tabindex="0"}
```bash
gscdump query --live --site example.com --dimensions date --limit 7 --format json
```
::

Each returned row has a date and Search Analytics metrics such as clicks and impressions. Read `meta.source` to confirm `live`. `--live` needs Local mode. In Hosted mode, drop `--live`: `meta.source` is then `hosted`. The [query reference](/gscdump-cli/api/query) lists dimensions and filters. Live queries default to 28 days ending three days ago in Search Console's Pacific reporting calendar. The newest days may still change.

::table{tabindex="0"}
| Check                            | Meaning                                                                       |
| -------------------------------- | ----------------------------------------------------------------------------- |
| Rows with clicks and impressions | Google returned data for this Site and window.                                |
| Empty rows                       | The Site may have no matching data. Check its exact identity and date window. |
| Permission error                 | Check the Google connection and Site access in `gscdump sites --json`.        |
| Quota error                      | Use the retry time from the CLI. Do not loop immediately.                     |
::

<docsagentprompt prompt="Use the installed gscdump skill. List my Search Console Sites and ask which one to query. Show page clicks, dates, and meta.source."></docsagentprompt>

## Pick your next task

[Query and export rows](/gscdump-cli/guides/use-data/query-and-export), [save history in a Store](/gscdump-cli/guides/use-data/build-history), or [review traffic each week](/gscdump-cli/guides/investigate-traffic/weekly-triage). The [Start guides](/gscdump-cli/guides/start) cover access and agents.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.