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 thev1alphaAPI) - 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 --describeoutputs 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
From PyPI (recommended)
# 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:
- Go to APIs & Services > Credentials
- Click Create Credentials > OAuth client ID
- Choose Desktop app as the application type
- 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
Breaking change (post-0.3.0):
ga reports runandga reports buildwith-o jsonreturn a{"rows": [...], "metadata": {...}}envelope instead of a bare rows array.metadatais the API'sResponseMetaData— sampling, thresholding, and data-truncation information that was previously discarded. In table output the same information renders as a Data Notes section under the results whenever present; unaffected reports look exactly as before.
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
v1alphaData API. Google announced GA forproperties.chaton 2026-09-17; it now works end-to-end on live GA4 properties. The method still lives under thev1alphaAPI version, so its shape may still change. If you do hit a403, 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.readscope, added in 0.3.0. If you authenticated with an earlier version, runga auth loginagain — 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.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| google_analytics_cli-0.4.0.tar.gz | 317.9 kB | Without provenance | Details for google_analytics_cli-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| google_analytics_cli-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for google_analytics_cli-0.4.0-py3-none-any.whl |
Total release size: 419.8 kB
Release files / google_analytics_cli-0.4.0.tar.gz
| Download URL | google_analytics_cli-0.4.0.tar.gz |
|---|---|
| Size | 317.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
916f0895da939951c5bfa38831e68cb8a36268535e21bc2be2ac91aeb0e51bb0
|
|
BLAKE2b-256 checksum How to use checksums |
494965a85dc0225c2a18d3eed712025086b92f6d24a63550d4bb61d83544c057
|
| 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.4.0-py3-none-any.whl
| Download URL | google_analytics_cli-0.4.0-py3-none-any.whl |
|---|---|
| Size | 101.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
87278f52e2e291e8cb2502120bd6ec3247694fa3edb7f650abff4a2b7f2cf657
|
|
BLAKE2b-256 checksum How to use checksums |
259eb5cb1b5a4fc39208678a53b540d07f89b700fdec42ca991800abd4dea71d
|
| 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.4.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.