Skip to main content

GA CLI

Command-line interface for Google Analytics 4.

Manage GA4 accounts, properties, data streams, and run reports — all from your terminal.

Read an introductory blog post on the GA CLI on gunnargriese.com.

Features

Authentication

  • OAuth 2.0 — Browser-based login flow with automatic token refresh
  • Service accounts — Key-file authentication for CI/CD and server environments

GA4 Data API

  • Reporting — Run standard, pivot, batch, funnel, and real-time reports
  • Chat — Ask questions in plain language via ga reports chat (built on the v1alpha API)
  • Report builder — Interactive metric/dimension selection via ga reports build
  • Compatibility checks — Validate metric/dimension combinations before running reports
  • Metadata — Browse and search available metrics and dimensions

GA4 Admin API

  • Accounts — List, inspect, update, delete accounts; view data sharing settings and change history
  • Account summaries — Quick overview of all accounts and their properties
  • Properties — List, create, inspect, update, delete properties; acknowledge user data collection; view API quotas
  • Data streams — List, create, inspect, update, and delete web, Android, and iOS data streams
  • Custom dimensions & metrics — List, create, inspect, update, and archive custom definitions
  • Calculated metrics — List, create, inspect, update, and delete calculated metrics
  • Key events — List, create, inspect, update, and delete key events (conversions)
  • Audiences — List, create, inspect, update, and archive audiences
  • Access bindings — Manage user-role assignments at account and property level
  • Access reports — Run data-access reports (who accessed what) at account or property level
  • Data retention — View and update event and user data retention settings
  • Annotations — Create, update, and delete reporting data annotations
  • Measurement Protocol secrets — Manage MP API secrets per data stream
  • BigQuery links — List, create, update, and delete BigQuery export links
  • Channel groups — Manage custom channel groupings
  • Event create & edit rules — Manage server-side event creation and modification rules
  • Firebase links — List, create, and delete Firebase project links
  • Google Ads links — List, create, update, and delete Google Ads account links
  • Property settings — View and update attribution and Google Signals settings
  • Enhanced measurement — View and update enhanced measurement settings per data stream

Interactive usage

  • Flexible output — Table (default), JSON, and compact output formats
  • Shell completions — Generate completion scripts for bash, zsh, and fish
  • Interactive setup — Guided configuration wizard via ga config setup
  • Self-update — Check for and install updates via ga upgrade

Automation & agent integration

  • Schema introspection — ga --describe outputs JSON Schema for all commands (MCP/agent-ready)
  • Dry run — Preview mutative requests (create, update, delete) without executing them
  • Structured errors — Categorized exit codes and JSON error output for programmatic handling
  • Agent guide — Built-in AI agent quick reference via ga agent guide

Installation

# pipx (recommended for CLI tools — isolated env)
pipx install google-analytics-cli

# uv
uv tool install google-analytics-cli

# pip
pip install google-analytics-cli

Quick install (script)

curl -fsSL https://raw.githubusercontent.com/daidalytics/google-analytics-cli/master/install.sh | bash

From GitHub

# With uv
uv pip install git+https://github.com/daidalytics/google-analytics-cli.git

# With pip
pip install git+https://github.com/daidalytics/google-analytics-cli.git

From source

git clone https://github.com/daidalytics/google-analytics-cli.git
cd google-analytics-cli
uv sync
uv run ga --help

One-off execution (no install)

uvx --from git+https://github.com/daidalytics/google-analytics-cli.git ga --help

Quick Start

# 1. Authenticate
ga auth login

# 2. List your accounts
ga accounts list

# 3. List properties for an account
ga properties list --account-id 123456789

# 4. Run a report
ga reports run --property-id 987654321 \
  --metrics sessions,totalUsers \
  --dimensions date \
  --start-date 7daysAgo

Setup

1. Create OAuth credentials

Create an OAuth 2.0 Client ID in the Google Cloud Console:

  1. Go to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Choose Desktop app as the application type
  4. Download the JSON file

Make sure the following APIs are enabled in your GCP project:

  • Google Analytics Admin API
  • Google Analytics Data API

2. Configure client credentials

Copy the downloaded client_secret.json to the GA CLI config directory:

mkdir -p ~/.config/ga-cli
cp /path/to/client_secret.json ~/.config/ga-cli/client_secret.json

Alternatively, set environment variables:

export GA_CLI_CLIENT_ID="your-client-id"
export GA_CLI_CLIENT_SECRET="your-client-secret"

3. Authenticate

ga auth login

This opens your browser for Google OAuth consent and stores the token locally at ~/.config/ga-cli/credentials.json.

Service account (alternative)

ga auth login --service-account /path/to/key.json

Or set an environment variable:

export GA_CLI_SERVICE_ACCOUNT="/path/to/key.json"

Command Reference

Command Subcommands Description
ga auth setup, login, logout, status Manage authentication
ga config setup, get, set, unset, path, reset Manage CLI configuration
ga accounts list, get, update, delete, get-data-sharing, change-history Manage GA4 accounts
ga account-summaries list Quick overview of all accounts and properties
ga properties list, get, create, update, delete, acknowledge-udc, quotas Manage GA4 properties
ga custom-dimensions list, get, create, update, archive Manage custom dimensions
ga custom-metrics list, get, create, update, archive Manage custom metrics
ga calculated-metrics list, get, create, update, delete Manage calculated metrics
ga data-streams list, get, create, update, delete Manage data streams
ga key-events list, get, create, update, delete Manage key events (conversions)
ga audiences list, get, create, update, archive Manage audiences
ga access-bindings list, get, create, update, delete Manage user-role assignments
ga access-reports run-account, run-property Run data-access reports
ga data-retention get, update View and update data retention settings
ga annotations list, get, create, update, delete Manage reporting annotations
ga mp-secrets list, get, create, update, delete Manage Measurement Protocol secrets
ga bigquery-links list, get, create, update, delete Manage BigQuery export links
ga channel-groups list, get, create, update, delete Manage custom channel groups
ga event-create-rules list, get, create, update, delete Manage event creation rules
ga event-edit-rules list, get, create, update, delete, reorder Manage event editing rules
ga firebase-links list, create, delete Manage Firebase links
ga google-ads-links list, create, update, delete Manage Google Ads links
ga enhanced-measurement get, update Manage enhanced measurement settings
ga property-settings attribution, google-signals View and update property settings
ga reports run, pivot, batch, funnel, chat, check-compatibility, metadata, realtime, build Run and build reports
ga agent guide AI agent quick reference
ga upgrade --check, --force Check for and install updates
ga completions bash, zsh, fish Generate shell completion scripts

Use ga <command> --help for detailed usage of any command, or ga --describe for the full CLI schema as JSON.

Output formats

All read commands support --output (-o) to control output format:

ga accounts list --output json      # JSON output
ga accounts list --output table     # Table output (default)
ga accounts list --output compact   # Minimal ID + name output

Chat

Ask questions about a property in plain language:

ga reports chat "how many users did I have last week?"
ga reports chat "now break that down by country" --continue
ga reports chat --interactive          # multi-turn conversation
ga reports chat "top pages" -o json    # raw ChatResponse for scripts
Flag Effect
--session-id ID Continue a specific conversation
--continue Continue this property's most recent conversation
--interactive / -i Multi-turn REPL; quota shown per turn
--return-property-quota Show token quota (on by default in --interactive)

Built on the v1alpha Data API. Google announced GA for properties.chat on 2026-09-17; it now works end-to-end on live GA4 properties. The method still lives under the v1alpha API version, so its shape may still change. If you do hit a 403, it means either you lack access to the property or chat isn't enabled for your account — the API returns the same generic message for both, so the CLI names both possibilities.

Chat requires the analytics.chatbot.read scope, added in 0.3.0. If you authenticated with an earlier version, run ga auth login again — a refresh token cannot gain a scope it was never granted. Other commands are unaffected.

Uses AI and may return inaccurate information.

Global Options

--help, -h      Show help
--version, -v   Show version
--quiet, -q     Suppress non-essential output
--no-color      Disable colored output
--describe      Show full CLI schema as JSON (for agents and tooling)

Shell Completions

ga completions bash > ~/.bash_completion.d/ga
ga completions zsh > ~/.zsh/completions/_ga
ga completions fish > ~/.config/fish/completions/ga.fish

Environment Variables

Variable Description
GA_CLI_CLIENT_ID OAuth client ID (alternative to client_secret.json)
GA_CLI_CLIENT_SECRET OAuth client secret (alternative to client_secret.json)
GA_CLI_SERVICE_ACCOUNT Path to service account key file
GOOGLE_APPLICATION_CREDENTIALS Standard GCP credential path (fallback)
GA_CLI_CONFIG_DIR Override config directory
NO_COLOR Disable colored output

CI/CD Integration

jobs:
  ga-report:
    runs-on: ubuntu-latest
    steps:
      - name: Install GA CLI
        run: pip install google-analytics-cli

      - name: Export daily report
        run: |
          echo '${{ secrets.GA_SERVICE_ACCOUNT_KEY }}' > /tmp/sa-key.json
          ga auth login --service-account /tmp/sa-key.json
          ga reports run -p ${{ vars.GA_PROPERTY_ID }} \
            --metrics sessions,users --dimensions date \
            --start-date 7daysAgo -o json > report.json
          rm /tmp/sa-key.json

Troubleshooting

ga runs git add instead of GA CLI. You have a shell alias shadowing the command — commonly alias ga='git add' in ~/.gitconfig-style setups or ~/.zshrc/~/.bashrc. Run type ga to confirm, then unalias ga (or remove the alias from your shell config) and restart your shell.

ga: command not found after install. Your Python user bin directory isn't on PATH. For pip install --user, pipx, or uv tool install, the binary lives in ~/.local/bin on Linux/macOS. Add it to your shell config:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc

Then restart your shell. pipx ensurepath and uv tool update-shell can do this automatically.

Upgrading from 0.2.1 or earlier on macOS. Older versions stored config at ~/Library/Application Support/ga-cli/. GA CLI now uses ~/.config/ga-cli/ on all platforms and will migrate the directory automatically the first time you run any command. No action required.

Privacy

GA CLI stores authentication credentials locally on your machine. No data is sent to any third party — all communication is directly between your machine and Google's APIs.

Development

# Install with dev dependencies
uv sync

# Run the CLI
uv run ga --help

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/

License

MIT

Metadata

Release files for google-analytics-cli 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for google-analytics-cli 0.3.0
File Size Uploaded Provenance Actions
google_analytics_cli-0.3.0.tar.gz 315.3 kB Without provenance Details for google_analytics_cli-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for google-analytics-cli 0.3.0
File Interpreter ABI Platform Actions
google_analytics_cli-0.3.0-py3-none-any.whl Python 3 none any Details for google_analytics_cli-0.3.0-py3-none-any.whl

Total release size: 415.4 kB

Release files / google_analytics_cli-0.3.0.tar.gz

Download URL google_analytics_cli-0.3.0.tar.gz
Size 315.3 kB
Tags Source
SHA-256 checksum
How to use checksums
708f770b8edfcd51ccf173da572a9606f598d24cb2fbc008f335c208b6008243
BLAKE2b-256 checksum
How to use checksums
a8bcc6fd8a7b88d2ec317ef7d754976ba2d58b5339e6b012b277bec3d4c28270
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / google_analytics_cli-0.3.0-py3-none-any.whl

Download URL google_analytics_cli-0.3.0-py3-none-any.whl
Size 100.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a43a155921e8e4cc43d821fbfe805ed89342774f157d6467e9d95e9f743f5d5
BLAKE2b-256 checksum
How to use checksums
954f2999bea9e6c285e26d347f639f49317de78b06d29411f9a4c3f3ea57d567
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for google-analytics-cli 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page