marketing-toolbox 0.1.0__tar.gz

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

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - name: Check out source
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: "0.12.17"
+          enable-cache: false
+      - name: Install locked development and build environment
+        run: uv sync --locked --all-groups --all-packages
+      - name: Verify lockfile
+        run: uv lock --check
+      - name: Run tests
+        run: uv run --locked --no-sync pytest
+      - name: Lint
+        run: uv run --locked --no-sync ruff check .
+      - name: Check formatting
+        run: uv run --locked --no-sync ruff format --check .
+      - name: Type check
+        run: uv run --locked --no-sync mypy
+      - name: Build distributions offline
+        run: uv build --all-packages --offline --no-build-isolation --no-python-downloads --out-dir dist

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

@@ -0,0 +1,185 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      publish_target:
+        description: "Bootstrap target (the only supported manual target)"
+        required: true
+        type: choice
+        options:
+          - marketing-toolbox
+        default: marketing-toolbox
+      confirmation:
+        description: "Type BOOTSTRAP-MARKETING-TOOLBOX to confirm the core-only publish"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out release source
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && 'refs/heads/main' || github.ref }}
+
+      - name: Verify release mode
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          WORKFLOW_REF: ${{ github.ref }}
+          PUBLISH_TARGET: ${{ inputs.publish_target }}
+          CONFIRMATION: ${{ inputs.confirmation }}
+        run: |
+          set -euo pipefail
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            [[ "$WORKFLOW_REF" == "refs/heads/main" ]] || {
+              echo "manual bootstrap releases are allowed only from main" >&2
+              exit 1
+            }
+            [[ "$PUBLISH_TARGET" == "marketing-toolbox" ]] || {
+              echo "manual releases may publish only marketing-toolbox" >&2
+              exit 1
+            }
+            [[ "$CONFIRMATION" == "BOOTSTRAP-MARKETING-TOOLBOX" ]] || {
+              echo "manual core-only publish confirmation did not match" >&2
+              exit 1
+            }
+          else
+            [[ "$EVENT_NAME" == "push" ]] || {
+              echo "unsupported release event: $EVENT_NAME" >&2
+              exit 1
+            }
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: "0.12.17"
+          enable-cache: false
+
+      - name: Install locked development and build environment
+        run: uv sync --locked --all-groups --all-packages
+
+      - name: Verify tag and package versions
+        if: github.event_name == 'push'
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          uv run --locked --no-sync python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ["RELEASE_TAG"]
+          if not tag.startswith("v") or tag == "v":
+              raise SystemExit(f"release tag must be v<version>: {tag}")
+          tag_version = tag[1:]
+
+          manifests = [
+              Path("pyproject.toml"),
+              Path("packaging/ga4adminctl/pyproject.toml"),
+              Path("packaging/ga4datactl/pyproject.toml"),
+              Path("packaging/gtmctl/pyproject.toml"),
+          ]
+          versions = []
+          for manifest in manifests:
+              with manifest.open("rb") as file:
+                  project = tomllib.load(file)["project"]
+              versions.append((project["name"], project["version"]))
+
+          if any(version != tag_version for _, version in versions):
+              raise SystemExit(
+                  f"tag {tag_version} does not match package versions: {versions}"
+              )
+          if any(tag != f"v{version}" for _, version in versions):
+              raise SystemExit(f"tag must be v<version>: {tag}, packages: {versions}")
+          if len({version for _, version in versions}) != 1:
+              raise SystemExit(f"package versions are not synchronized: {versions}")
+          print(f"validated release {tag}: {versions}")
+          PY
+
+      - name: Verify lockfile
+        run: uv lock --check
+      - name: Run tests and metadata checks
+        run: uv run --locked --no-sync pytest
+      - name: Lint
+        run: uv run --locked --no-sync ruff check .
+      - name: Check formatting
+        run: uv run --locked --no-sync ruff format --check .
+      - name: Type check
+        run: uv run --locked --no-sync mypy
+
+      - name: Build all distributions
+        run: uv build --all-packages --offline --no-build-isolation --no-python-downloads --clear --out-dir dist
+      - name: Inspect distributions
+        run: uvx twine check dist/*
+      - name: Upload release distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download release distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-distributions
+          path: dist
+          merge-multiple: true
+      - name: Stage distributions for publication
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          rm -rf publish-dist
+          mkdir publish-dist
+          shopt -s nullglob
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            core_artifacts=(dist/marketing_toolbox-*.whl dist/marketing_toolbox-*.tar.gz)
+            [[ ${#core_artifacts[@]} -eq 2 ]] || {
+              echo "expected exactly one marketing-toolbox wheel and sdist" >&2
+              exit 1
+            }
+            cp "${core_artifacts[@]}" publish-dist/
+          else
+            all_artifacts=(dist/*.whl dist/*.tar.gz)
+            [[ ${#all_artifacts[@]} -eq 8 ]] || {
+              echo "expected wheel and sdist for all four distributions" >&2
+              exit 1
+            }
+            cp "${all_artifacts[@]}" publish-dist/
+          fi
+          published_artifacts=(publish-dist/*)
+          [[ ${#published_artifacts[@]} -eq 2 && "$EVENT_NAME" == "workflow_dispatch" || \
+             ${#published_artifacts[@]} -eq 8 && "$EVENT_NAME" == "push" ]] || {
+            echo "publication staging did not match the release mode" >&2
+            exit 1
+          }
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: publish-dist/
+          # The bootstrap has already uploaded marketing-toolbox 0.1.0.
+          skip-existing: true

marketing_toolbox-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+
+# uv virtual environment
+.venv/
+
+# Local credentials and environment
+.env
+.env.*
+*.json
+!pyproject.toml
+!uv.lock
+# Versioned GA4 request/response fixtures are part of the CLI contract.
+!docs/specification/v1/ga4datactl/fixtures/**/*.json
+
+/.worktrees/

marketing_toolbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enver
+
+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.

marketing_toolbox-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: marketing-toolbox
+Version: 0.1.0
+Summary: Command-line tools for Google Analytics 4 and Google Tag Manager.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: google-analytics-admin==0.30.1
+Requires-Dist: google-analytics-data==0.23.0
+Requires-Dist: google-api-python-client==2.198.0
+Requires-Dist: google-auth==2.56.2
+Requires-Dist: jsonschema==4.25.1
+Requires-Dist: typer==0.27.0
+Description-Content-Type: text/markdown
+
+# marketing-toolbox
+
+`marketing-toolbox` provides three command-line interfaces for the official Google
+APIs:
+
+- `ga4datactl` — Google Analytics Data API v1beta
+- `ga4adminctl` — Google Analytics Admin API v1beta
+- `gtmctl` — Google Tag Manager API v2
+
+The tools provide explicit commands, structured JSON output, normalized errors,
+and safety controls for non-interactive automation. They use the official
+Google Python clients for authentication, transport, retries, and API models.
+
+## Quick start
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --all-groups
+uv run ga4datactl --help
+uv run ga4adminctl --help
+uv run gtmctl --help
+uv run pytest
+uv run ruff check .
+```
+
+The installed entry points are `ga4datactl`, `ga4adminctl`, and `gtmctl`.
+
+## Published installation (after the first release)
+
+After the first release has been configured and published to all four PyPI
+projects, the three command-specific distributions can be run without a
+persistent installation with [`uvx`](https://docs.astral.sh/uv/guides/tools/):
+
+```bash
+uvx ga4datactl --help
+uvx ga4adminctl --help
+uvx gtmctl --help
+```
+
+After publication, pin a release when reproducibility matters. The package
+named with `--from` is the distribution to resolve, and the following argument
+is its executable:
+
+```bash
+uvx --from ga4datactl==0.1.0 ga4datactl --help
+uvx --from ga4adminctl==0.1.0 ga4adminctl --help
+uvx --from gtmctl==0.1.0 gtmctl --help
+```
+
+For a published distribution, `uvx` caches its isolated tool environment. An
+unpinned invocation can be refreshed to pick up a newer published release; use
+`--refresh` when you need to re-resolve and reinstall the tool:
+
+```bash
+uvx --refresh ga4datactl --help
+```
+
+A version-pinned invocation remains on that version, even when refreshed:
+
+```bash
+uvx --refresh --from ga4datactl==0.1.0 ga4datactl --help
+```
+
+Each command-specific distribution is a thin launcher distribution. It exposes
+one command and pins the corresponding `marketing-toolbox` release; the
+`marketing-toolbox` distribution contains the shared implementation and all three
+entry points. This gives each CLI a discoverable PyPI name while keeping the
+implementation in one distribution.
+
+## Command map
+
+```text
+ga4datactl
+  reports (run, batch-run, pivot-run, batch-pivot-run, realtime-run, compatibility-check)
+  metadata get
+  audience-exports (get, list, create, query)
+  sdk schema --command "<eligible leaf path>"
+
+ga4adminctl
+  account-summaries list
+  accounts (...)
+  properties (...)
+  sdk schema --command "<eligible leaf path>"
+
+gtmctl
+  accounts (...)
+  sdk schema --command "<eligible body leaf path>"
+```
+
+Use `--help` for the executable command set. The complete current target maps
+are the [GA4 Admin catalog](docs/specification/v1/ga4adminctl/catalog.md) and
+[GTM catalog](docs/specification/v1/gtmctl/catalog.md). The
+[GA4 Data command contracts](docs/specification/v1/ga4datactl/commands/) cover
+its public request and safety boundaries.
+
+`sdk schema` reads the pinned local SDK or Discovery descriptor. It does not
+load credentials or call Google.
+
+## Authentication
+
+Commands that call Google use a service account supplied at process runtime by
+one of these environment variables, in precedence order:
+
+```text
+GOOGLE_SERVICE_ACCOUNT_JSON
+GOOGLE_APPLICATION_CREDENTIALS
+```
+
+The first contains the complete service-account JSON document and is parsed in
+memory. The second names a service-account JSON file. Credentials are never
+accepted as command-line arguments or written to output. Interactive OAuth,
+user credentials, and application-default user credentials are not supported.
+See [docs/authentication.md](docs/authentication.md).
+
+## Output and safety
+
+Successful commands write one versioned JSON document to stdout. Diagnostics
+and warnings go to stderr. Read operations run normally; Google-side writes
+require `--apply`, and `--dry-run` validates and plans without making the
+mutation request. Command-specific acknowledgements remain required for
+high-impact operations and sensitive reads.
+
+`--apply` expresses caller intent; Google IAM, the invoking caller's execution
+policy, and any required human approval remain the authorization boundary. See
+the [CLI contract](docs/cli-contract.md) for output, errors, exit codes, and
+mutation behavior.
+
+## Installation
+
+From a checkout, install the package with:
+
+```bash
+uv tool install .
+```
+
+This installs all three entry points into uv's managed executable directory.
+Ensure that directory is on `PATH`. For repository development, use `uv sync`
+and invoke commands with `uv run`.
+
+After the first release has been configured and published, the root
+distribution will also be available as a compatibility path. For example, this
+runs the root distribution's `ga4datactl` entry point:
+
+```bash
+uvx --from marketing-toolbox ga4datactl --help
+uvx --from marketing-toolbox ga4adminctl --help
+uvx --from marketing-toolbox gtmctl --help
+```
+
+The pinned form is `uvx --from marketing-toolbox==0.1.0 ga4datactl --help`, for
+example. For new installs from PyPI after publication, prefer the
+command-specific paths above.
+
+## Specification
+
+The current public contracts, catalogs, schemas, and deterministic fixtures are
+indexed from [docs/specification/README.md](docs/specification/README.md).
+[SDK-backed introspection](docs/specification/v1/sdk-backed-introspection.md)
+describes the local descriptor command and its current behavior.

marketing_toolbox-0.1.0/README.md

@@ -0,0 +1,160 @@
+# marketing-toolbox
+
+`marketing-toolbox` provides three command-line interfaces for the official Google
+APIs:
+
+- `ga4datactl` — Google Analytics Data API v1beta
+- `ga4adminctl` — Google Analytics Admin API v1beta
+- `gtmctl` — Google Tag Manager API v2
+
+The tools provide explicit commands, structured JSON output, normalized errors,
+and safety controls for non-interactive automation. They use the official
+Google Python clients for authentication, transport, retries, and API models.
+
+## Quick start
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --all-groups
+uv run ga4datactl --help
+uv run ga4adminctl --help
+uv run gtmctl --help
+uv run pytest
+uv run ruff check .
+```
+
+The installed entry points are `ga4datactl`, `ga4adminctl`, and `gtmctl`.
+
+## Published installation (after the first release)
+
+After the first release has been configured and published to all four PyPI
+projects, the three command-specific distributions can be run without a
+persistent installation with [`uvx`](https://docs.astral.sh/uv/guides/tools/):
+
+```bash
+uvx ga4datactl --help
+uvx ga4adminctl --help
+uvx gtmctl --help
+```
+
+After publication, pin a release when reproducibility matters. The package
+named with `--from` is the distribution to resolve, and the following argument
+is its executable:
+
+```bash
+uvx --from ga4datactl==0.1.0 ga4datactl --help
+uvx --from ga4adminctl==0.1.0 ga4adminctl --help
+uvx --from gtmctl==0.1.0 gtmctl --help
+```
+
+For a published distribution, `uvx` caches its isolated tool environment. An
+unpinned invocation can be refreshed to pick up a newer published release; use
+`--refresh` when you need to re-resolve and reinstall the tool:
+
+```bash
+uvx --refresh ga4datactl --help
+```
+
+A version-pinned invocation remains on that version, even when refreshed:
+
+```bash
+uvx --refresh --from ga4datactl==0.1.0 ga4datactl --help
+```
+
+Each command-specific distribution is a thin launcher distribution. It exposes
+one command and pins the corresponding `marketing-toolbox` release; the
+`marketing-toolbox` distribution contains the shared implementation and all three
+entry points. This gives each CLI a discoverable PyPI name while keeping the
+implementation in one distribution.
+
+## Command map
+
+```text
+ga4datactl
+  reports (run, batch-run, pivot-run, batch-pivot-run, realtime-run, compatibility-check)
+  metadata get
+  audience-exports (get, list, create, query)
+  sdk schema --command "<eligible leaf path>"
+
+ga4adminctl
+  account-summaries list
+  accounts (...)
+  properties (...)
+  sdk schema --command "<eligible leaf path>"
+
+gtmctl
+  accounts (...)
+  sdk schema --command "<eligible body leaf path>"
+```
+
+Use `--help` for the executable command set. The complete current target maps
+are the [GA4 Admin catalog](docs/specification/v1/ga4adminctl/catalog.md) and
+[GTM catalog](docs/specification/v1/gtmctl/catalog.md). The
+[GA4 Data command contracts](docs/specification/v1/ga4datactl/commands/) cover
+its public request and safety boundaries.
+
+`sdk schema` reads the pinned local SDK or Discovery descriptor. It does not
+load credentials or call Google.
+
+## Authentication
+
+Commands that call Google use a service account supplied at process runtime by
+one of these environment variables, in precedence order:
+
+```text
+GOOGLE_SERVICE_ACCOUNT_JSON
+GOOGLE_APPLICATION_CREDENTIALS
+```
+
+The first contains the complete service-account JSON document and is parsed in
+memory. The second names a service-account JSON file. Credentials are never
+accepted as command-line arguments or written to output. Interactive OAuth,
+user credentials, and application-default user credentials are not supported.
+See [docs/authentication.md](docs/authentication.md).
+
+## Output and safety
+
+Successful commands write one versioned JSON document to stdout. Diagnostics
+and warnings go to stderr. Read operations run normally; Google-side writes
+require `--apply`, and `--dry-run` validates and plans without making the
+mutation request. Command-specific acknowledgements remain required for
+high-impact operations and sensitive reads.
+
+`--apply` expresses caller intent; Google IAM, the invoking caller's execution
+policy, and any required human approval remain the authorization boundary. See
+the [CLI contract](docs/cli-contract.md) for output, errors, exit codes, and
+mutation behavior.
+
+## Installation
+
+From a checkout, install the package with:
+
+```bash
+uv tool install .
+```
+
+This installs all three entry points into uv's managed executable directory.
+Ensure that directory is on `PATH`. For repository development, use `uv sync`
+and invoke commands with `uv run`.
+
+After the first release has been configured and published, the root
+distribution will also be available as a compatibility path. For example, this
+runs the root distribution's `ga4datactl` entry point:
+
+```bash
+uvx --from marketing-toolbox ga4datactl --help
+uvx --from marketing-toolbox ga4adminctl --help
+uvx --from marketing-toolbox gtmctl --help
+```
+
+The pinned form is `uvx --from marketing-toolbox==0.1.0 ga4datactl --help`, for
+example. For new installs from PyPI after publication, prefer the
+command-specific paths above.
+
+## Specification
+
+The current public contracts, catalogs, schemas, and deterministic fixtures are
+indexed from [docs/specification/README.md](docs/specification/README.md).
+[SDK-backed introspection](docs/specification/v1/sdk-backed-introspection.md)
+describes the local descriptor command and its current behavior.

marketing_toolbox-0.1.0/docs/authentication.md

@@ -0,0 +1,71 @@
+# Service-account authentication
+
+All three CLIs authenticate as a Google service account. This behavior is the
+same for a checkout, a `uv tool install .` installation, and a `uvx`
+installation after the first release has been configured and published to all
+four PyPI projects. `uvx` passes the invoking process's environment to the CLI,
+so set the credential before running the command:
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/secure/path/service-account.json
+
+# Checkout/marketing-toolbox installation:
+uv run ga4datactl --help
+
+# After the first release has been configured and published:
+uvx ga4datactl --help
+```
+
+For an in-memory credential instead:
+
+```bash
+# Set GOOGLE_SERVICE_ACCOUNT_JSON to the complete service-account JSON document.
+
+# Checkout/marketing-toolbox installation:
+uv run gtmctl accounts list
+
+# After the first release has been configured and published:
+uvx gtmctl accounts list
+```
+
+Supply the credential only at process runtime using one of these mechanisms, in precedence order:
+
+```text
+GOOGLE_SERVICE_ACCOUNT_JSON
+GOOGLE_APPLICATION_CREDENTIALS
+```
+
+`GOOGLE_SERVICE_ACCOUNT_JSON` contains the complete service-account JSON document and is parsed in memory. `GOOGLE_APPLICATION_CREDENTIALS` names a readable service-account JSON file managed by the runtime. Neither representation may be committed, printed, passed as a command-line flag, or copied into request/output files.
+
+## Credential loading
+
+The shared `marketing_common.auth.service_account_credentials()` loader prefers the in-memory JSON secret and otherwise loads the declared service-account file, then creates scoped `google-auth` credentials. It does not discover user credentials, start a browser OAuth flow, or fall back to a developer's local Google login.
+
+Missing or invalid credentials return a sanitized configuration error that names only the credential environment-variable key, never any secret content or file contents.
+
+## Per-command-family scopes
+
+Each live command scopes its credentials for its own operation. Help, `--version`, dry-run planning, and `sdk schema` do not load credentials. The following is the runtime selection, not a recommendation to grant every scope to every service account.
+
+| CLI | Command family | Requested OAuth scope |
+|---|---|---|
+| `ga4datactl` | Reports, metadata, and audience-export `get`, `list`, and sensitive `query` | `https://www.googleapis.com/auth/analytics.readonly` |
+| `ga4datactl` | `audience-exports create` | `https://www.googleapis.com/auth/analytics` |
+| `ga4adminctl` | Ordinary reads | `https://www.googleapis.com/auth/analytics.readonly` |
+| `ga4adminctl` | Mutations, sensitive actions, and account change-history search | `https://www.googleapis.com/auth/analytics.edit` |
+| `gtmctl` | Ordinary GTM reads | `https://www.googleapis.com/auth/tagmanager.readonly` |
+| `gtmctl` | Account user-permission reads and mutations | `https://www.googleapis.com/auth/tagmanager.manage.users` |
+| `gtmctl` | `accounts update` | `https://www.googleapis.com/auth/tagmanager.manage.accounts` |
+| `gtmctl` | Ordinary container/workspace/entity mutations | `https://www.googleapis.com/auth/tagmanager.edit.containers` |
+| `gtmctl` | Container-version `update`, `delete`, and `undelete`; workspace `create-version` and `quick-preview` | `https://www.googleapis.com/auth/tagmanager.edit.containerversions` |
+| `gtmctl` | Container-version `publish` and environment `reauthorize` | `https://www.googleapis.com/auth/tagmanager.publish` |
+| `gtmctl` | Container and workspace deletion | `https://www.googleapis.com/auth/tagmanager.delete.containers` |
+
+The [GTM catalog](specification/v1/gtmctl/catalog.md) records the exact scope allowed for each official target; the runtime families above identify the scope this CLI currently requests. Scopes constrain the token request, but Google Analytics and GTM IAM roles remain the ultimate authorization boundary. Configure each service account with only the Google-side permissions required for its intended commands.
+
+## Runtime requirements
+
+- The process launcher must inject `GOOGLE_SERVICE_ACCOUNT_JSON` or securely provide the service-account file named by `GOOGLE_APPLICATION_CREDENTIALS`.
+- Local tests and help/version commands do not require credentials.
+- SDK-backed API commands fail before making a Google request if neither credential source is available or the supplied credential is invalid.
+- Do not use interactive OAuth, application-default user credentials, or `.env` files for these tools.