google-analytics-cli 0.1.0__tar.gz

google_analytics_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Run tests
+        run: uv run pytest

google_analytics_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync
+      - name: Lint
+        run: uv run ruff check src/ tests/
+      - name: Run tests
+        run: uv run pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Publish to TestPyPI
+        run: uv publish --publish-url https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Publish to PyPI
+        run: uv publish

google_analytics_cli-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# OAuth credentials
+client_secret.json
+test-service-account.json
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual environment
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+
+# Claude
+CLAUDE.md
+.claude/*
+
+# Archive
+archive/

google_analytics_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

google_analytics_cli-0.1.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: google-analytics-cli
+Version: 0.1.0
+Summary: Command-line interface for Google Analytics 4
+Project-URL: Homepage, https://github.com/daidalytics/google-analytics-cli
+Project-URL: Repository, https://github.com/daidalytics/google-analytics-cli
+Project-URL: Issues, https://github.com/daidalytics/google-analytics-cli/issues
+Author: Gunnar Griese
+License: MIT
+Keywords: analytics,cli,ga4,google-analytics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: google-api-python-client>=2.0
+Requires-Dist: google-auth-oauthlib>=1.0
+Requires-Dist: google-auth>=2.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: shellingham>=1.3.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# GA CLI
+
+Command-line interface for Google Analytics 4.
+
+Manage GA4 accounts, properties, data streams, and run reports — all from your terminal.
+
+## 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](https://developers.google.com/analytics/devguides/reporting/data/v1)
+
+- **Reporting** — Run standard, pivot, batch, funnel, and real-time reports
+- **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](https://developers.google.com/analytics/devguides/config/admin/v1)
+
+- **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, Google Signals, and enhanced measurement settings
+
+### 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
+
+### From PyPI (recommended)
+
+```bash
+# 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)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/daidalytics/google-analytics-cli/master/install.sh | bash
+```
+
+### From GitHub
+
+```bash
+# 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
+
+```bash
+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)
+
+```bash
+uvx --from git+https://github.com/daidalytics/google-analytics-cli.git ga --help
+```
+
+## Quick Start
+
+```bash
+# 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](https://console.cloud.google.com/apis/credentials):
+
+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:
+
+```bash
+mkdir -p ~/.config/ga-cli
+cp /path/to/client_secret.json ~/.config/ga-cli/client_secret.json
+```
+
+Alternatively, set environment variables:
+
+```bash
+export GA_CLI_CLIENT_ID="your-client-id"
+export GA_CLI_CLIENT_SECRET="your-client-secret"
+```
+
+### 3. Authenticate
+
+```bash
+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)
+
+```bash
+ga auth login --service-account /path/to/key.json
+```
+
+Or set an environment variable:
+
+```bash
+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 property-settings` | `attribution`, `google-signals`, `enhanced-measurement` | View and update property settings |
+| `ga reports` | `run`, `pivot`, `batch`, `funnel`, `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:
+
+```bash
+ga accounts list --output json      # JSON output
+ga accounts list --output table     # Table output (default)
+ga accounts list --output compact   # Minimal ID + name output
+```
+
+## 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
+
+```bash
+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
+
+```yaml
+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
+```
+
+## 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
+
+```bash
+# 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