Marketing Toolbox

Desktop OAuth setup

Mon, 01 Jan 0001 00:00:00 +0000

Desktop OAuth setup

Use a Google Cloud Desktop app client for native OAuth. The CLI owns its loopback callback; do not create a Web application or enter redirect URIs.

Configure a Cloud project

Create or select a Cloud project.
In the API Library, enable only the APIs you need:
- Google Analytics Data API for ga4datactl.
- Google Analytics Admin API for ga4adminctl.
- Tag Manager API for gtmctl.
In Google Auth Platform, complete Branding with an app name, support email, and contact email.
Under Audience, choose External for a personal project or users outside a Google Workspace organization. Choose Internal only for eligible organization-only users. For an External app in Testing, add each signing-in account as a test user.
Under Data Access, add only the scope or scopes for the access tiers you will use. The authentication guide lists the exact tiers and scopes.

External Testing refresh tokens can expire after seven days. Personal testing does not require verification or publishing the app to Production.

GA4 Data

Mon, 01 Jan 0001 00:00:00 +0000

GA4 Data

ga4datactl queries the Google Analytics Data API. Its native OAuth tier is read; see authentication for credential selection and the separate resource-permission requirement.

Start with the installed request descriptor when composing a request. This route is local, credential-free, and network-free:

ga4datactl sdk schema --command "reports run"

The descriptor is a request shape, not a response schema or a complete statement of CLI requiredness and Google semantics. sdk schema is available for the six report leaves (reports run, batch-run, pivot-run, realtime-run, batch-pivot-run, and compatibility-check) and for audience-exports create.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation

Marketing Toolbox requires Python 3.11 or later and uv.

Run without installing

Use uvx for an ephemeral command. This resolves the named package for that invocation:

uvx ga4datactl --help
uvx ga4adminctl --help
uvx gtmctl --help

Pin a release when reproducibility matters:

uvx --from 'ga4datactl==0.3.0' ga4datactl --version

Install persistently

Install each tool separately when you need only one command:

uv tool install ga4datactl
uv tool install ga4adminctl
uv tool install gtmctl

Or install the combined package to provide all three commands:

GA4 Admin

Mon, 01 Jan 0001 00:00:00 +0000

GA4 Admin

ga4adminctl manages Google Analytics configuration through the Google Analytics Admin API. Most read-only commands use the read tier and configuration changes use edit; the read-only accounts change-history search command also requires edit. OAuth consent alone does not grant access to a property.

Read one property with an account that has permission for it:

ga4adminctl properties get --property properties/1234

For eligible request bodies, inspect the installed SDK descriptor before composing a request:

Tag Manager

Mon, 01 Jan 0001 00:00:00 +0000

Tag Manager

gtmctl works with Google Tag Manager API v2 resource paths. An account path is accounts/<account-id>; containers and workspaces extend it as accounts/<account-id>/containers/<container-id>/workspaces/<workspace-id>.

Read one account you are authorized to access:

gtmctl accounts get --path accounts/1

Native OAuth tiers

The native OAuth tier is specific to the operation, not merely whether it reads, writes, or deletes:

Tier	Reviewed operation family
`read`	Ordinary reads, including version reads
`users`	Account user-permission get, list, create, update, and delete
`accounts`	Account update
`containers`	Ordinary container, workspace, and entity mutations: creates and updates; variable and other entity deletion; environment deletion; container actions; and `versions set-latest`
`versions`	Version update, delete, and undelete; workspace `quick-preview` and `create-version`
`publish`	Version publish and environment reauthorize
`delete`	Only container deletion and workspace deletion

Thus a user-permission read requires users, while a variable or environment delete requires containers; only container/workspace deletion uses delete. Likewise, versions set-latest uses containers, while version deletion, workspace quick preview, and workspace version creation use versions. See authentication for tier-to-scope mappings and separate tool+tier credential records.