--- title: "Choose CLI access" description: "Compare the Local and Hosted access modes, then set up one of them." canonical_url: "https://gscdump.com/gscdump-cli/guides/start/choose-access" last_updated: "2026-10-03T07:15:31.584Z" --- # Choose CLI access The CLI has 2 access modes. Pick one before your first command. ::table{tabindex="0"} | Mode | Credentials | What the CLI reads | | ---------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **Local** | Your own Google credentials: a service account or an OAuth client | Google directly. Data stays in a local Store on your disk | | **Hosted** | Your [gscdump.com](http://gscdump.com) account | Your hosted record on [gscdump.com](http://gscdump.com). The CLI never calls Google | :: `auth login --mode local` or `auth login --mode hosted` saves the mode for later commands. `--mode local` or `--mode hosted` overrides it for one command. `GSCDUMP_AUTH_MODE` also overrides the saved mode. If no mode is saved and `GSCDUMP_API_KEY` is set, the CLI uses Hosted mode. Otherwise it uses Local mode. Run `gscdump auth status --json` to see the active mode. The [commands reference](/gscdump-cli/api/commands) lists profile options. The CLI reads credentials from its configuration directory and from exported environment variables. It never reads a `.env` file, so a project's credentials stay with that project. To use a `.env` file, export its variables before you run `gscdump`. ## Local mode Local mode calls Google with your own credentials. [gscdump.com](http://gscdump.com) is not involved. ### Service account (recommended) A service account key never expires, and it works on servers and in CI. 1. In Google Cloud, create a project and enable the Google Search Console API. 2. Create a service account, then create a JSON key for it. 3. In Search Console, open the Site, then Settings > Users and permissions. Add the service account email as a user. 4. Check the key and save its path: ::pre{tabindex="0"} ```bash gscdump auth login --mode local --service-account ./gsc-sa.json gscdump auth status --json gscdump sites --json ``` :: For scheduled runs, set `GOOGLE_APPLICATION_CREDENTIALS` or `GSC_SERVICE_ACCOUNT_JSON` to the key path instead. ### OAuth client Use an OAuth client when you want to sign in as yourself. 1. In Google Cloud, enable the Google Search Console API. 2. Create an OAuth client ID of type Desktop application. 3. On the OAuth consent screen, set the publishing status to **In production**. In **Testing** status, Google expires refresh tokens after 7 days, and you must log in again each week. 4. Set the client credentials, then log in: ::pre{tabindex="0"} ```bash export GSC_CLIENT_ID=your-client-id export GSC_CLIENT_SECRET=your-client-secret gscdump auth login --mode local gscdump auth status --json ``` :: For an existing access token, set `GSC_ACCESS_TOKEN`. For renewable credentials, set `GSC_CLIENT_ID`, `GSC_CLIENT_SECRET`, and `GSC_REFRESH_TOKEN` together. `gscdump auth status --json` identifies the active source. For a remote terminal, `gscdump auth login --mode local --no-browser` prints an authorization URL. The loopback flow may need port forwarding. Google login does not connect Bing. Run `gscdump bing login --mode local` and `gscdump bing sites --mode local --json` separately. Use the exact Bing Site URL printed by `bing sites` for local Bing commands. See the [Bing reference](/gscdump-cli/api/bing) for OAuth and API key options. ## Hosted mode Hosted mode reads the record that [gscdump.com](http://gscdump.com) keeps for your Sites. [gscdump.com](http://gscdump.com) runs the sync. The CLI never calls Google in Hosted mode. Hosted login opens [gscdump.com](http://gscdump.com). Sign in, approve the CLI, then [connect a Site](/app/onboarding?step=connect-sites). The CLI saves a session. You do not need to copy an API key. The session ends 90 days after you approve it. Then the CLI prints `Your gscdump.com session expired.` Run `gscdump auth login --mode hosted` to sign in again. SDK integrations and CI can use a user API key from [Agent setup](/app/developers#api-keys) with `--api-key` or `GSCDUMP_API_KEY`. ::pre{tabindex="0"} ```bash gscdump auth login --mode hosted gscdump sites --json gscdump query --site example.com -d page -f json ``` :: After login, the CLI prints one next step. If your hosted record has no Sites, the step is the connect link: `Next: connect a Site at https://gscdump.com/app/onboarding?step=connect-sites.` If Hosted access is not active, [gscdump.com](http://gscdump.com) asks you to activate it first. `gscdump auth status` prints the same step while the record has no Sites. If you select Cancel on the [gscdump.com](http://gscdump.com) login page, the CLI prints `Login cancelled in the browser.` and exits 1. Hosted mode runs these commands: - `sites` lists your hosted Sites and their sync state. - `query` reads rows from the hosted record. - `sitemaps current`, `history`, `membership`, `lastmod`, and `export` read saved sitemap evidence. - `indexing urls` lists saved URL Inspection results. - `indexing summary` shows the coverage ladder per day from saved URL Inspection results, with the time gscdump counted them. - `indexing watch list`, `add`, and `remove` manage Watched URLs. gscdump inspects each Watched URL every 7 days. - `bing login --site`, `sites`, `status`, `dump`, `inspect`, and `verify` use the Bing connection saved on [gscdump.com](http://gscdump.com). If `gscdump sites --json` prints `[]`, your hosted record has no Sites. Commands that need a Site stop with the code `NO_SITES`. If you logged in with the browser, connect a Site on [gscdump.com](http://gscdump.com). If an app gave you an API key, connect a Site in that app. The `NO_SITES` message names that app when [gscdump.com](http://gscdump.com) reports it, for example `Connect a Site in Request Indexing.` Every other command calls Google, so it needs Local mode. Examples: `sync`, `inspect`, `query --live`, `sites add`, `sitemaps submit`, `indexing submit`, and `mcp`. In Hosted mode these commands stop and print the Local mode setup command. For an MCP client in Hosted mode, connect it to `https://gscdump.com/mcp`. For Bing, connect the Site in [gscdump.com](http://gscdump.com), then run `gscdump bing sites --json` and `gscdump bing status --site s_SITE_ID --json`. Use the hosted Site ID printed by `bing sites` for Bing commands. ## Fix access errors If a command prints `Google credentials are missing`, set up Local mode or Hosted mode as shown above. If a command prints `This command calls Google, so it needs Local mode`, the command has no Hosted equivalent. Set up Local mode, or pass `--mode local` if Local credentials exist. If `sites` is empty in Local mode, check the Google identity and the Site's Users and permissions. If Hosted mode rejects the session, run `gscdump auth login --mode hosted` again. If an OAuth refresh token expires after 7 days, set the OAuth consent screen to **In production** and run `gscdump auth login --mode local --force`. `gscdump doctor` can check configuration. Do not paste credentials into an issue or agent prompt. ## Continue with a result Run the [first query](/gscdump-cli/guides/start/first-result), or [compare Google and Bing evidence](/gscdump-cli/guides/check-visibility/google-and-bing) after connecting both Search Engines. More setup: [Start](/gscdump-cli/guides/start). ## Sitemap See the full [sitemap](/sitemap.md) for all pages.