gmp-cli

What is gmp-cli?

gmp-cli is a command-line interface for working with Google Marketing Platform services, including GA4 (Google Analytics Data API), Google Search Console, Google Ads, and Google Tag Manager. Its core purpose is to let you fetch marketing data and configuration details from your terminal (or scripts) rather than manually through web UIs.

The project is built with “agent-friendly” workflows in mind: it supports piping JSON output to tools like jq, so you can pass results directly into an AI agent or process them in shell scripts.

Key Features

• Unified CLI for multiple GMP services: GA4, Search Console, Google Ads, and Tag Manager are accessed via dedicated subcommands.
• Authentication and token management: OAuth-based login is supported, with tokens stored at ~/.config/gmp-cli/tokens.json and auto-refresh.
• GA4 reporting and filtering: run reports for metrics/dimensions (e.g., sessions and bounce rate by page path) with date ranges and value filters.
• Search Console analytics + index inspection: list verified sites, generate search analytics reports, inspect URL indexation, and list sitemaps.
• Google Ads querying for performance: list accessible accounts (optionally via MCC), retrieve campaigns/ad groups/keywords/search terms, and run raw GAQL queries.
• Tag Manager workspace operations: list accounts/containers, list tags/triggers/variables, and retrieve published versions (including selecting a specific workspace).
• Structured output formats: commands support -f / --format (for example, table or CSV for GA4 reports) to make results usable in scripts.

How to Use gmp-cli

1. Install the CLI from the repository:

   • git clone https://github.com/lucianfialho/gmp-cli.git
   • cd gmp-cli
   • npm install
   • npm run build
   • npm link

2. Set up OAuth authentication (first time only):

   • Create a project in Google Cloud Console.
   • Enable the required APIs (Analytics Data API, Analytics Admin API, Search Console API for Search Console, and Google Ads API for Ads).
   • Configure the OAuth consent screen and create an OAuth Client ID for a Desktop app.
   • Use redirect URI http://localhost:3847/callback.
   • Authenticate via:
     • gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
     • gmp auth login
     • gmp auth status

3. Add service-specific credentials:

   • For Google Ads: set a developer token with gmp auth set-developer-token YOUR_DEVELOPER_TOKEN.
   • If using a Manager Account (MCC): set the login customer ID with gmp auth set-login-customer-id 1234567890.

4. Run reports and export results using the relevant command group (e.g., gmp ga, gmp gsc, gmp ads, gmp gtm). Use -f to control output format and redirect CSV output to files when needed.

Use Cases

• Weekly GA4 performance review in the terminal: generate sessions and bounce rate by pagePath for the last 30 days, then export as CSV for spreadsheet review.
• Targeted GA4 analysis with filters: run the same GA4 report but restrict results to a specific page path (e.g., pagePath==/product) and set a custom date range.
• Search Console query monitoring: list top queries for a verified site for the last 28 days, or filter results by a specific query keyword.
• Google Ads performance reporting for stakeholders: list campaigns for a date range and pull campaign/ad group/keyword performance tables; optionally use GAQL for a custom metric query.
• Tag Manager inventory and audit: list tags, triggers, and variables for a specific container/workspace and review published versions.

FAQ

Where are OAuth tokens stored?

Tokens are stored in ~/.config/gmp-cli/tokens.json and are auto-refreshed.

Do I need a Google Ads developer token?

Yes. The Google Ads API setup described in the project requires a developer token in addition to OAuth credentials.

How do I output results for scripting?

Many commands accept -f / --format to control output. For GA4 reports, the README shows output as table or csv and demonstrates redirecting CSV output to a file.

Can I query Google Ads across an MCC?

The README includes MCC-specific setup via gmp auth set-login-customer-id and provides Ads account listing commands with an MCC option.

How does the CLI support “agent-friendly” workflows?

The project explicitly supports piping JSON output to tools like jq, which can then be fed into an AI agent or used in shell scripts.

Alternatives

• Google’s official APIs (direct calls): Instead of a CLI wrapper, you can use the APIs directly from your code. This offers maximum flexibility but requires building authentication and request logic yourself.
• Other data extraction scripting approaches: You can write scripts that call Google services via REST/official client libraries and then format results as JSON/CSV. This is similar in automation goals but lacks the ready-made command structure.
• Tag Manager/GMP web interfaces: Using the built-in UI can be simpler for one-off checks. However, it’s less suited to repeatable, scriptable workflows compared to a CLI.
• Analytics/reporting BI tools: BI or dashboarding tools can centralize reporting and visualization. They typically emphasize dashboards over terminal-first piping/automation workflows described for gmp-cli.