google-analytics-cli 0.1.0rc1__tar.gz

google_analytics_cli-0.1.0rc1/.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.0rc1/.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.0rc1/.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.0rc1/.python-version

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

google_analytics_cli-0.1.0rc1/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: google-analytics-cli
+Version: 0.1.0rc1
+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: 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: typer[all]>=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) and service account support
+- **Account management** — List, inspect, and update GA4 accounts
+- **Property management** — List, create, inspect, update, and delete GA4 properties
+- **Data stream management** — List, create, inspect, update, and delete web, Android, and iOS data streams
+- **Custom dimensions & metrics** — List, create, update, and archive custom definitions
+- **Key events** — List, create, update, and delete key events (conversions)
+- **Reporting** — Run custom reports, pivot reports, real-time reports with live polling, check compatibility, and build reports interactively
+- **Flexible output** — Table (default), JSON, and compact output formats
+- **Self-update** — Check for and install updates via `ga upgrade`
+- **Schema introspection** — `ga --describe` outputs JSON Schema for all commands (agent/MCP-ready)
+- **Shell completions** — Generate completion scripts for bash, zsh, and fish
+- **Interactive setup** — Guided configuration wizard via `ga config setup`
+
+## 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` | `login`, `logout`, `status` | Manage authentication |
+| `ga config` | `setup`, `get`, `set`, `unset`, `path`, `reset` | Manage CLI configuration |
+| `ga accounts` | `list`, `get`, `update` | List, inspect, and update GA4 accounts |
+| `ga account-summaries` | `list` | Quick overview of all accounts and properties |
+| `ga properties` | `list`, `get`, `create`, `update`, `delete` | 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 data-streams` | `list`, `get`, `create`, `update`, `delete` | Manage data streams |
+| `ga key-events` | `list`, `get`, `create`, `update`, `delete` | Manage key events (conversions) |
+| `ga reports` | `run`, `pivot`, `check-compatibility`, `metadata`, `realtime`, `build` | Run and build reports |
+| `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_SERVICE_ACCOUNT` | Path to service account key file |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Standard GCP credential path (fallback) |
+| `GA_CLI_CONFIG_DIR` | Override config directory |
+| `GA_CLI_CLIENT_ID` | OAuth client ID (alternative to client_secret.json) |
+| `GA_CLI_CLIENT_SECRET` | OAuth client secret (alternative to client_secret.json) |
+| `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

google_analytics_cli-0.1.0rc1/README.md

@@ -0,0 +1,238 @@
+# 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) and service account support
+- **Account management** — List, inspect, and update GA4 accounts
+- **Property management** — List, create, inspect, update, and delete GA4 properties
+- **Data stream management** — List, create, inspect, update, and delete web, Android, and iOS data streams
+- **Custom dimensions & metrics** — List, create, update, and archive custom definitions
+- **Key events** — List, create, update, and delete key events (conversions)
+- **Reporting** — Run custom reports, pivot reports, real-time reports with live polling, check compatibility, and build reports interactively
+- **Flexible output** — Table (default), JSON, and compact output formats
+- **Self-update** — Check for and install updates via `ga upgrade`
+- **Schema introspection** — `ga --describe` outputs JSON Schema for all commands (agent/MCP-ready)
+- **Shell completions** — Generate completion scripts for bash, zsh, and fish
+- **Interactive setup** — Guided configuration wizard via `ga config setup`
+
+## 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` | `login`, `logout`, `status` | Manage authentication |
+| `ga config` | `setup`, `get`, `set`, `unset`, `path`, `reset` | Manage CLI configuration |
+| `ga accounts` | `list`, `get`, `update` | List, inspect, and update GA4 accounts |
+| `ga account-summaries` | `list` | Quick overview of all accounts and properties |
+| `ga properties` | `list`, `get`, `create`, `update`, `delete` | 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 data-streams` | `list`, `get`, `create`, `update`, `delete` | Manage data streams |
+| `ga key-events` | `list`, `get`, `create`, `update`, `delete` | Manage key events (conversions) |
+| `ga reports` | `run`, `pivot`, `check-compatibility`, `metadata`, `realtime`, `build` | Run and build reports |
+| `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_SERVICE_ACCOUNT` | Path to service account key file |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Standard GCP credential path (fallback) |
+| `GA_CLI_CONFIG_DIR` | Override config directory |
+| `GA_CLI_CLIENT_ID` | OAuth client ID (alternative to client_secret.json) |
+| `GA_CLI_CLIENT_SECRET` | OAuth client secret (alternative to client_secret.json) |
+| `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

google_analytics_cli-0.1.0rc1/install.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="ga-cli"
+
+echo "Installing ${PACKAGE}..."
+
+# 1. Detect platform
+OS="$(uname -s)"
+case "${OS}" in
+    Linux|Darwin) ;;
+    *)
+        echo "Error: Unsupported platform '${OS}'. Only Linux and macOS are supported." >&2
+        exit 1
+        ;;
+esac
+
+# 2. Find installer and install
+if command -v pipx &>/dev/null; then
+    echo "Using pipx..."
+    pipx install "${PACKAGE}"
+elif command -v uv &>/dev/null; then
+    echo "Using uv..."
+    uv tool install "${PACKAGE}"
+elif command -v pip &>/dev/null; then
+    echo "Using pip..."
+    pip install "${PACKAGE}"
+elif command -v pip3 &>/dev/null; then
+    echo "Using pip3..."
+    pip3 install "${PACKAGE}"
+else
+    echo "Error: No package installer found. Install pipx, uv, or pip first." >&2
+    echo "  pipx: https://pypa.github.io/pipx/" >&2
+    echo "  uv:   https://docs.astral.sh/uv/" >&2
+    echo "  pip:  https://pip.pypa.io/" >&2
+    exit 1
+fi
+
+# 3. Verify installation
+if command -v ga &>/dev/null; then
+    echo ""
+    echo "Successfully installed $(ga --version)"
+    echo ""
+    echo "Get started:"
+    echo "  ga auth login        # Authenticate with Google"
+    echo "  ga accounts list     # List your GA4 accounts"
+    echo "  ga --help            # See all commands"
+else
+    echo ""
+    echo "Warning: 'ga' command not found in PATH." >&2
+    echo "You may need to restart your shell or add the install location to PATH." >&2
+    exit 1
+fi