google-analytics-cli 0.1.0rc1__tar.gz → 0.1.1__tar.gz

{google_analytics_cli-0.1.0rc1 → google_analytics_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-analytics-cli
-Version: 0.1.0rc1
+Version: 0.1.1
 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
@@ -19,6 +19,7 @@ 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
@@ -26,7 +27,8 @@ 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
+Requires-Dist: shellingham>=1.3.0
+Requires-Dist: typer>=0.9.0
 Description-Content-Type: text/markdown
 
 # GA CLI
@@ -37,18 +39,53 @@ Manage GA4 accounts, properties, data streams, and run reports — all from your
 
 ## 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
+### 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
-- **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`
+- **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
 
@@ -170,16 +207,31 @@ export GA_CLI_SERVICE_ACCOUNT="/path/to/key.json"
 
 | Command | Subcommands | Description |
 |---------|-------------|-------------|
-| `ga auth` | `login`, `logout`, `status` | Manage authentication |
+| `ga auth` | `setup`, `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 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` | Manage GA4 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 reports` | `run`, `pivot`, `check-compatibility`, `metadata`, `realtime`, `build` | Run and build reports |
+| `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 |
 
@@ -217,11 +269,11 @@ ga completions fish > ~/.config/fish/completions/ga.fish
 
 | 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 |
-| `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

{google_analytics_cli-0.1.0rc1 → google_analytics_cli-0.1.1}/README.md

@@ -6,18 +6,53 @@ Manage GA4 accounts, properties, data streams, and run reports — all from your
 
 ## 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
+### 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
-- **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`
+- **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
 
@@ -139,16 +174,31 @@ export GA_CLI_SERVICE_ACCOUNT="/path/to/key.json"
 
 | Command | Subcommands | Description |
 |---------|-------------|-------------|
-| `ga auth` | `login`, `logout`, `status` | Manage authentication |
+| `ga auth` | `setup`, `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 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` | Manage GA4 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 reports` | `run`, `pivot`, `check-compatibility`, `metadata`, `realtime`, `build` | Run and build reports |
+| `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 |
 
@@ -186,11 +236,11 @@ ga completions fish > ~/.config/fish/completions/ga.fish
 
 | 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 |
-| `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

{google_analytics_cli-0.1.0rc1 → google_analytics_cli-0.1.1}/install.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-PACKAGE="ga-cli"
+PACKAGE="google-analytics-cli"
 
 echo "Installing ${PACKAGE}..."
 

{google_analytics_cli-0.1.0rc1 → google_analytics_cli-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-analytics-cli"
-version = "0.1.0rc1"
+version = "0.1.1"
 description = "Command-line interface for Google Analytics 4"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,7 +20,9 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
 ]
 dependencies = [
-    "typer[all]>=0.9.0",
+    "typer>=0.9.0",
+    "click>=8.0",
+    "shellingham>=1.3.0",
     "google-api-python-client>=2.0",
     "google-auth-oauthlib>=1.0",
     "google-auth>=2.0",

{google_analytics_cli-0.1.0rc1 → google_analytics_cli-0.1.1}/src/ga_cli/commands/agent_cmd.py

@@ -74,7 +74,7 @@ ga account-summaries list [-o json]
 
 ### Properties
 ```bash
-ga properties list [-a ACCOUNT_ID] [-o json]
+ga properties list [-a ACCOUNT_ID] [-o json]       # pipe: | jq '.[] | select(.displayName | test("prod"; "i"))'
 ga properties get [-p PROPERTY_ID] [-o json]
 ga properties create -a ACCOUNT_ID --name "Name" [--timezone TZ] [--currency CODE]
 ga properties update -p PROPERTY_ID [--name NAME] [--timezone TZ] [--currency CODE] [--industry CAT]
@@ -237,7 +237,7 @@ Get/set hybrid: no update flags = GET, any update flag = PATCH. Enhanced measure
 
 ### Reports
 ```bash
-ga reports run [-p PROPERTY_ID] -m metrics -d dimensions --start-date DATE --end-date DATE [--limit N] [-o json]
+ga reports run [-p PROPERTY_ID] -m metrics -d dimensions --start-date DATE --end-date DATE [--limit N] [-o json]  # pipe: | jq '[.[] | {date, sessions, users}]'
 ga reports pivot [-p PROPERTY_ID] -m metrics -d dimensions --pivot-field FIELD [--start-date DATE] [-o json]
 ga reports check-compatibility [-p PROPERTY_ID] [-m metrics] [-d dimensions] [-o json]
 ga reports metadata [-p PROPERTY_ID] [--type metrics|dimensions] [--search TEXT] [-o json]
@@ -263,6 +263,28 @@ ga completions bash|zsh|fish
 | `GA_CLI_CONFIG_DIR` | Override config directory |
 | `NO_COLOR` | Disable colored output |
 
+## Parsing Output
+
+`-o json` produces machine-parseable output **meant for jq**. Always pipe through jq — never parse raw JSON manually.
+
+### Reusable jq recipes
+```bash
+# Extract numeric IDs from resource names ("accounts/123" → "123")
+ga accounts list -o json | jq -r '.[].name' | grep -o '[0-9]*$'
+
+# Filter resources by display name (case-insensitive regex)
+ga properties list -o json | jq '.[] | select(.displayName | test("prod"; "i"))'
+
+# Pick specific fields
+ga data-streams list -o json | jq '[.[] | {id: (.name | split("/") | last), displayName, type}]'
+
+# Count results
+ga custom-dimensions list -o json | jq 'length'
+
+# Get first result's ID (useful for chaining)
+ga properties list -o json | jq -r '.[0].name' | grep -o '[0-9]*$'
+```
+
 ## Agent Workflow
 Typical discover → act pattern:
 ```bash
@@ -299,7 +321,7 @@ ga data-streams list -o json | jq -r '.[].name' | grep -o '[0-9]*$'
 - **Start with `ga --describe`** — discover every command, parameter, type, and flag in one JSON call; cache the result
 - **Use `--dry-run` before mutations** — preview the exact API request before executing creates, updates, and deletes
 - **Set defaults first** — eliminates repetitive `--account-id` / `--property-id` flags from every command
-- **Always use `-o json`** — structured output is easier to parse than tables
+- **Always use `-o json` and pipe through `jq`** — JSON output is machine-parseable; always pipe through `jq` to filter, extract IDs, or reshape — never parse raw output manually (see "Parsing Output" above)
 - **Use `check-compatibility` before complex reports** — avoids API errors from incompatible metric/dimension combos
 - **Use `metadata` to discover available metrics/dimensions** — `ga reports metadata -p ID --search revenue -o json`
 - **Parallelize independent operations** — run creates/deletes concurrently with `&` and `wait`

{google_analytics_cli-0.1.0rc1 → google_analytics_cli-0.1.1}/uv.lock

@@ -306,9 +306,10 @@ wheels = [
 
 [[package]]
 name = "google-analytics-cli"
-version = "0.1.0"
+version = "0.1.1"
 source = { editable = "." }
 dependencies = [
+    { name = "click" },
     { name = "google-api-python-client" },
     { name = "google-auth" },
     { name = "google-auth-oauthlib" },
@@ -316,6 +317,7 @@ dependencies = [
     { name = "platformdirs" },
     { name = "questionary" },
     { name = "rich" },
+    { name = "shellingham" },
     { name = "typer" },
 ]
 
@@ -327,6 +329,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
+    { name = "click", specifier = ">=8.0" },
     { name = "google-api-python-client", specifier = ">=2.0" },
     { name = "google-auth", specifier = ">=2.0" },
     { name = "google-auth-oauthlib", specifier = ">=1.0" },
@@ -334,7 +337,8 @@ requires-dist = [
     { name = "platformdirs", specifier = ">=4.0" },
     { name = "questionary", specifier = ">=2.0" },
     { name = "rich", specifier = ">=13.0" },
-    { name = "typer", extras = ["all"], specifier = ">=0.9.0" },
+    { name = "shellingham", specifier = ">=1.3.0" },
+    { name = "typer", specifier = ">=0.9.0" },
 ]
 
 [package.metadata.requires-dev]