ga4-cli 0.1.1__py3-none-any.whl

ga4_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: ga4-cli
+Version: 0.1.1
+Summary: Command-line interface for Google Analytics 4
+Home-page: https://github.com/sulimanbenhalim/ga-cli
+Author: Suliman Ben Halim
+Author-email: suliman.benhalim@binary.ly
+License: MIT
+Project-URL: Bug Reports, https://github.com/sulimanbenhalim/ga-cli/issues
+Project-URL: Source, https://github.com/sulimanbenhalim/ga-cli
+Project-URL: Documentation, https://github.com/sulimanbenhalim/ga-cli#readme
+Keywords: google-analytics ga4 cli command-line
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9.0.0,>=8.0.0
+Requires-Dist: google-analytics-admin<1.0.0,>=0.27.0
+Requires-Dist: google-auth<3.0.0,>=2.0.0
+Requires-Dist: rich<14.0.0,>=13.0.0
+Requires-Dist: pytz>=2023.3
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# GA CLI - Google Analytics Command Line Interface
+
+A command-line interface tool for managing Google Analytics 4 properties, accounts, and data streams.
+
+**Note**: The package is published as `ga4-cli` on PyPI, but the command is `ga-cli`.
+
+## Features
+
+- List and manage Google Analytics accounts
+- Create and manage GA4 properties
+- Manage data streams and retrieve measurement IDs
+- Beautiful table output with Rich
+- JSON output support
+- Authentication via service account credentials
+
+## Installation
+
+### Using pip
+
+```bash
+pip install ga4-cli
+```
+
+After installation, the command is available as `ga-cli`:
+
+```bash
+ga-cli --version
+ga-cli --help
+```
+
+### Using Homebrew (macOS/Linux)
+
+```bash
+# Add the tap
+brew tap sulimanbenhalim/ga-cli
+
+# Install
+brew install ga-cli
+
+# Use it
+ga-cli --version
+```
+
+### Using Docker
+
+```bash
+# Pull from Docker Hub
+docker pull sulimanbenhalim/ga-cli:latest
+
+# Or build locally
+docker build -t ga-cli .
+
+# Run with credentials mounted
+docker run -v /path/to/credentials.json:/credentials.json \
+  -v ~/.ga-cli:/root/.ga-cli \
+  ga-cli accounts list --credentials /credentials.json
+```
+
+### Download Binary (No Python Required)
+
+Download standalone binaries from [GitHub Releases](https://github.com/sulimanbenhalim/ga-cli/releases):
+
+**Linux/macOS:**
+```bash
+# Download and extract
+curl -L -o ga-cli.tar.gz https://github.com/sulimanbenhalim/ga-cli/releases/latest/download/ga-cli-linux-amd64.tar.gz
+tar -xzf ga-cli.tar.gz
+chmod +x ga-cli
+sudo mv ga-cli /usr/local/bin/
+```
+
+**Windows:**
+Download `ga-cli-windows-amd64.exe.zip` from the releases page, extract, and run.
+
+### From source
+
+```bash
+git clone https://github.com/sulimanbenhalim/ga-cli.git
+cd ga-cli
+pip install -e .
+```
+
+## Setup
+
+### 1. Get Google Service Account Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create or select a project
+3. Enable the Google Analytics Admin API
+4. Create a service account with Analytics Admin permissions
+5. Download the JSON credentials file
+
+### 2. Initialize GA CLI
+
+```bash
+ga-cli config init
+```
+
+This will prompt you for the path to your service account JSON file and test the credentials.
+
+Alternatively, set the environment variable:
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+```
+
+## Usage
+
+### Configuration
+
+```bash
+# Initialize with credentials
+ga-cli config init
+
+# Show current configuration
+ga-cli config show
+```
+
+### Accounts
+
+```bash
+# List all accounts
+ga-cli accounts list
+
+# Get account details
+ga-cli accounts get <account-id>
+
+# Output as JSON
+ga-cli accounts list --format json
+```
+
+### Properties
+
+```bash
+# List properties for an account
+ga-cli properties list <account-id>
+
+# Get property details
+ga-cli properties get <property-id>
+
+# Create a new property
+ga-cli properties create <account-id> --name "My Website" --timezone "America/New_York" --currency "USD"
+
+# Delete a property
+ga-cli properties delete <property-id>
+```
+
+### Data Streams
+
+```bash
+# List data streams for a property
+ga-cli datastreams list <property-id>
+
+# Get data stream details (including measurement ID)
+ga-cli datastreams get <property-id> <stream-id>
+
+# Create a new web data stream
+ga-cli datastreams create <property-id> --name "Main Website" --url "https://example.com"
+```
+
+## Examples
+
+### Quick workflow to create a new GA4 property
+
+```bash
+# 1. List your accounts to get the account ID
+ga-cli accounts list
+
+# 2. Create a new property
+ga-cli properties create 123456789 --name "BOTCHA" --timezone "Africa/Tripoli"
+
+# 3. Create a web data stream
+ga-cli datastreams create 987654321 --name "BOTCHA Website" --url "https://botcha.example.com"
+
+# 4. Get the measurement ID
+ga-cli datastreams get 987654321 111222333
+```
+
+### Get measurement ID quickly
+
+```bash
+# If you know your property and stream IDs
+ga-cli datastreams get <property-id> <stream-id> | grep "Measurement ID"
+```
+
+## Command Reference
+
+### Global Options
+
+- `--credentials PATH` - Path to service account credentials file
+- `--version` - Show version
+- `--help` - Show help message
+
+### Output Formats
+
+Most list and get commands support:
+- `--format table` (default) - Beautiful table output
+- `--format json` - JSON output
+
+## Development
+
+### Setup development environment
+
+```bash
+# Clone the repository
+git clone https://github.com/sulimanbenhalim/ga-cli.git
+cd ga-cli
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode
+pip install -e .
+```
+
+### Run tests
+
+```bash
+pytest tests/ -v
+```
+
+## Project Structure
+
+```
+ga-cli/
+├── ga_cli/
+│   ├── __init__.py
+│   ├── cli.py              # Main CLI entry point
+│   ├── auth.py             # Authentication manager
+│   ├── config.py           # Configuration manager
+│   ├── commands/
+│   │   ├── accounts.py     # Account commands
+│   │   ├── properties.py   # Property commands
+│   │   ├── datastreams.py  # Data stream commands
+│   │   └── config.py       # Config commands
+│   └── formatters/
+│       ├── table.py        # Table formatter
+│       └── json.py         # JSON formatter
+├── tests/
+├── setup.py
+├── requirements.txt
+└── README.md
+```
+
+## Requirements
+
+- Python 3.8+
+- Click 8.0+
+- google-analytics-admin 0.27.0+
+- google-auth 2.0+
+- rich 13.0+
+- pytz 2023.3+
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues and questions, please open an issue on GitHub.

ga4_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,32 @@
+ga4_cli-0.1.1.dist-info/licenses/LICENSE,sha256=9vweInHjCIGx8SsP1v0L3seMYTVersqfyZZtgD0P3ho,1076
+ga_cli/__init__.py,sha256=hAbFYu5MOiv15bo441luVaXVLlvr0bekRovXy4TzHM4,85
+ga_cli/auth.py,sha256=7D_QL4FOs1SeT3Xhjn6v6D4fBu34zk9Owel1ayLUnU8,1892
+ga_cli/cli.py,sha256=gqojzERWqVwZjdI5_H36Flfbpr6oUPvnp9y34GDPF_M,954
+ga_cli/config.py,sha256=PSRwRJPVhH5eCTM9Hy6KR65klpeeIrOb0HXEy4sTJu8,3040
+ga_cli/decorators.py,sha256=Qn4LfV0Xs9680KrV0lcIt73dRAiTLXEprXOVJOVBYA4,3269
+ga_cli/errors.py,sha256=7Qkw_vjJjVdApoG8IaPe5pStHCt4Ps8sELDRAtaDkGs,1612
+ga_cli/logging_config.py,sha256=DqW5x7-pR-LTjXH88N7TPRt4RrqG0kzTTZlEjJXE-T4,937
+ga_cli/output.py,sha256=JyOafS8DMqLvcjfqXf9xb1YAXb5nkw9LLhGclzcPISA,1581
+ga_cli/retry.py,sha256=WFfdGw7N5ohElUlKqOpdw2F1Y2w5uvx42pZRVkHzGy4,1432
+ga_cli/validators.py,sha256=eDmZ_lnPInn3DNDkH-W-QUiv2C7N8qK33eZVxwEkooU,1457
+ga_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ga_cli/commands/accounts.py,sha256=WIS4liWgnmfWWh_OHO-CboheZKbCQzRt-jqOgr9EUDk,2648
+ga_cli/commands/config.py,sha256=fjxRB8wpJ_0a01R9whThkWhO7lBN8XMiOCsa0NRgeBc,2034
+ga_cli/commands/datastreams.py,sha256=ps_HomGWPwlAgYXt9ZLNg5R90fbUmL0VJFVk6-7yv0M,5671
+ga_cli/commands/properties.py,sha256=tnGe4OZujpCNwWUfVseGXRThlL3mXMyUz9Zjpkka4Js,5545
+ga_cli/formatters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ga_cli/formatters/json.py,sha256=C1a-ghd-k7Sr7_Cmg9up96xcFueC4PgF2931pOhCcHM,145
+ga_cli/formatters/table.py,sha256=HSwcH92wQSzgFebzr9z82NWrh27SEeD4mqj6bknhhg8,569
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/conftest.py,sha256=jrTHupz_iYC6kdm2dpPKt7zzjwu6Udq-yqL_RUWeXRg,2618
+tests/test_accounts.py,sha256=-7xgnqYwzj24RhZldykUkj0MEGcOlfUnd5tpPkU_1qQ,1671
+tests/test_auth.py,sha256=UhtpUZOKWXRA6ty_3N9GHPouuZNJB1kt_2oD3BphdiM,2939
+tests/test_cli.py,sha256=2bbcFPON-vYfdylXawIULFh-Tgs6CzsfmpubD1-OBvQ,1539
+tests/test_config.py,sha256=Ide0_EMkVX58HIFxPuvkw3toHBKQ6n5yqjRsGVEpv9M,5406
+tests/test_errors.py,sha256=zANsghozyAoRf4MNoIEgqlbmO_HGjBwhg_AB9hJ-eE4,3197
+tests/test_validators.py,sha256=LO9wBHawTcn8eZ_zTIxBV7WCOSRU_Wq1UD7szwJIj0o,5176
+ga4_cli-0.1.1.dist-info/METADATA,sha256=f9K_qbYnn9zkz9HN6SbzNTPExMFzL3ZEN-UHGc6yEds,7138
+ga4_cli-0.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ga4_cli-0.1.1.dist-info/entry_points.txt,sha256=RgZTBWAkc21O2EnGi13mqHuy-ClVEffLAKW7MZ5cpdU,42
+ga4_cli-0.1.1.dist-info/top_level.txt,sha256=8h9UkbqhP9WgaX0PfFMR5XjE1v5CcsswRYUB6ErXLE8,13
+ga4_cli-0.1.1.dist-info/RECORD,,

ga4_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ga4_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ga-cli = ga_cli.cli:cli

ga4_cli-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GA CLI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ga4_cli-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+ga_cli
+tests

ga_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Google Analytics CLI - Manage GA4 from the command line"""
+
+__version__ = "0.1.1"

ga_cli/auth.py

@@ -0,0 +1,59 @@
+"""Authentication manager for Google Analytics Admin API"""
+
+from google.analytics.admin import AnalyticsAdminServiceClient
+from google.oauth2 import service_account
+import os
+
+
+class AuthManager:
+    """Manages authentication for Google Analytics Admin API
+
+    This class supports context manager protocol for proper resource cleanup.
+
+    Usage:
+        # Standard usage
+        auth = AuthManager(credentials_path)
+        client = auth.get_client()
+
+        # With context manager
+        with AuthManager(credentials_path) as client:
+            # Use client
+            pass
+    """
+
+    def __init__(self, credentials_path=None):
+        self.credentials_path = credentials_path or os.getenv('GOOGLE_APPLICATION_CREDENTIALS')
+        self._client = None
+
+    def __enter__(self):
+        """Context manager entry"""
+        return self.get_client()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - clean up client resources"""
+        if self._client:
+            # Close client connection
+            self._client = None
+        return False
+
+    def get_client(self, timeout=30):
+        """Get authenticated Analytics Admin API client
+
+        Args:
+            timeout: Request timeout in seconds (default: 30)
+
+        Returns:
+            AnalyticsAdminServiceClient: Authenticated client instance
+        """
+        if self._client is None:
+            if self.credentials_path:
+                credentials = service_account.Credentials.from_service_account_file(
+                    self.credentials_path
+                )
+                self._client = AnalyticsAdminServiceClient(
+                    credentials=credentials,
+                    client_options={'api_endpoint': 'analyticsadmin.googleapis.com'}
+                )
+            else:
+                self._client = AnalyticsAdminServiceClient()
+        return self._client

ga_cli/cli.py

@@ -0,0 +1,35 @@
+"""Main CLI entry point"""
+
+import click
+from ga_cli import __version__
+from ga_cli.commands.accounts import accounts
+from ga_cli.commands.properties import properties
+from ga_cli.commands.datastreams import datastreams
+from ga_cli.commands.config import config
+from ga_cli.config import ConfigManager
+
+
+@click.group()
+@click.version_option(version=__version__)
+@click.option('--credentials', envvar='GOOGLE_APPLICATION_CREDENTIALS',
+              help='Path to service account credentials file')
+@click.pass_context
+def cli(ctx, credentials):
+    """Google Analytics CLI - Manage GA4 from the command line"""
+    ctx.ensure_object(dict)
+
+    if not credentials:
+        config_manager = ConfigManager()
+        credentials = config_manager.get_credentials_path()
+
+    ctx.obj['credentials'] = credentials
+
+
+cli.add_command(accounts)
+cli.add_command(properties)
+cli.add_command(datastreams)
+cli.add_command(config)
+
+
+if __name__ == '__main__':
+    cli()

ga_cli/commands/accounts.py

@@ -0,0 +1,81 @@
+"""Account management commands"""
+
+import click
+from ga_cli.decorators import with_client
+from ga_cli.formatters.table import format_table
+from ga_cli.formatters.json import format_json
+from ga_cli.validators import validate_account_id
+from ga_cli.logging_config import logger
+from ga_cli.retry import retry_on_transient_error
+
+
+@click.group()
+def accounts():
+    """Manage Google Analytics accounts"""
+    pass
+
+
+@accounts.command()
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+@with_client
+def list(ctx, format):
+    """List all accounts"""
+    client = ctx.obj['client']
+    logger.info("Listing Google Analytics accounts")
+
+    accounts_data = []
+    for account in _list_accounts_with_retry(client):
+        accounts_data.append({
+            'id': account.name.split('/')[-1] if '/' in account.name else account.name,
+            'name': account.display_name or 'N/A',
+            'region': account.region_code or 'N/A',
+            'create_time': str(account.create_time).split('.')[0] if account.create_time else 'N/A',
+        })
+
+    logger.info(f"Found {len(accounts_data)} accounts")
+
+    if format == 'json':
+        format_json(accounts_data)
+    else:
+        format_table(accounts_data, title="Google Analytics Accounts")
+
+
+@accounts.command()
+@click.argument('account_id', callback=validate_account_id)
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+@with_client
+def get(ctx, account_id, format):
+    """Get account details"""
+    client = ctx.obj['client']
+    logger.info(f"Getting account details for: {account_id}")
+
+    account = _get_account_with_retry(client, account_id)
+
+    account_data = {
+        'id': account.name.split('/')[-1] if '/' in account.name else account.name,
+        'name': account.display_name or 'N/A',
+        'region': account.region_code or 'N/A',
+        'create_time': str(account.create_time).split('.')[0] if account.create_time else 'N/A',
+        'update_time': str(account.update_time).split('.')[0] if account.update_time else 'N/A',
+    }
+
+    logger.info(f"Retrieved account: {account.display_name}")
+
+    if format == 'json':
+        format_json(account_data)
+    else:
+        format_table([account_data], title=f"Account: {account.display_name}")
+
+
+@retry_on_transient_error()
+def _list_accounts_with_retry(client):
+    """List accounts with retry logic"""
+    return list(client.list_accounts())
+
+
+@retry_on_transient_error()
+def _get_account_with_retry(client, account_id):
+    """Get account with retry logic"""
+    return client.get_account(name=f"accounts/{account_id}")

ga_cli/commands/config.py

@@ -0,0 +1,65 @@
+"""Configuration commands"""
+
+import click
+import os
+from ga_cli.config import ConfigManager
+from ga_cli.auth import AuthManager
+
+
+@click.group()
+def config():
+    """Manage CLI configuration"""
+    pass
+
+
+@config.command()
+@click.option('--credentials', prompt='Path to service account JSON',
+              help='Path to Google service account credentials file')
+def init(credentials):
+    """Initialize GA CLI with credentials"""
+    try:
+        credentials_path = os.path.expanduser(credentials)
+
+        if not os.path.exists(credentials_path):
+            click.echo(f"Error: Credentials file not found at {credentials_path}", err=True)
+            raise click.Abort()
+
+        click.echo("Testing credentials...")
+        auth = AuthManager(credentials_path)
+        client = auth.get_client()
+
+        accounts = list(client.list_accounts())
+
+        if accounts:
+            click.echo(f"Credentials valid! Found {len(accounts)} account(s)")
+
+            config_manager = ConfigManager()
+            config_manager.set_credentials_path(credentials_path)
+
+            click.echo(f"Configuration saved to {config_manager.config_file}")
+            click.echo("\nYou can now use ga-cli commands without specifying credentials")
+        else:
+            click.echo("Warning: Credentials are valid but no accounts found", err=True)
+
+    except Exception as e:
+        click.echo(f"Error: {str(e)}", err=True)
+        raise click.Abort()
+
+
+@config.command()
+def show():
+    """Show current configuration"""
+    try:
+        config_manager = ConfigManager()
+        credentials_path = config_manager.get_credentials_path()
+
+        if credentials_path:
+            click.echo("Configuration:")
+            click.echo(f"  Credentials: {credentials_path}")
+            click.echo(f"  Config file: {config_manager.config_file}")
+        else:
+            click.echo("No configuration found. Run 'ga-cli config init' to set up.")
+
+    except Exception as e:
+        click.echo(f"Error: {str(e)}", err=True)
+        raise click.Abort()