@mihilista/gtm-cli

A small, focused CLI for Google Tag Manager, built on the Tag Manager API v2 and your own Google login (OAuth). Every command prints JSON to stdout and exits non-zero on error, so they compose cleanly with jq and in CI.

Read-only

• accounts: list the GTM accounts you can access.
• containers: list the containers under an account.
• dump: full audit dump of an account. For every container it pulls the live published version (tags, triggers, variables, built-in variables), falling back to the Default Workspace when a container has never been published.
• export: reconstruct a container as GTM export JSON (the API has no export endpoint), for backups or to round-trip into push.
• diff: compare a container between two refs (live, workspace, a version id, or a file). Tag trigger references are compared by name, so reassigned ids don't show up as spurious changes.
• audit: run best-practice checks across an account (consent gating, consent-setting consistency, GA4↔Meta conversion parity, Meta standard-event semantics, naming-convention drift). Exits non-zero on findings, so it drops into a pre-publish gate.

Mutating

• push: create a new container under an existing account from a GTM export JSON, populate it, and cut a named, unpublished version.
• publish: publish an existing version live. Refuses to run without --confirm.

Auth

• login / logout / whoami: run a fresh consent flow, clear the cached token, or show which token is in use and what it can reach.

It never creates accounts (the API can't, see Constraints) and never publishes without an explicit --confirm.

Install

# one-off
npx @mihilista/gtm-cli accounts

# or globally
pnpm add -g @mihilista/gtm-cli
gtm-cli --help

Requires Node.js >= 18.

One-time OAuth setup

1. In the Google Cloud Console, enable the "Tag Manager API" for a project.
2. Create an OAuth client ID of type Desktop app. Download the JSON.
3. Save it to ~/.config/gtm-cli/oauth-client.json.
4. If your OAuth consent screen is in "Testing" mode, add your Google account as a test user.

The first authenticated command prints a consent URL (it does not auto-open a browser, so you can paste it into whichever browser you like) and waits on a local loopback server for the redirect. The refresh token is then cached at ~/.config/gtm-cli/token.json, so later runs are non-interactive.

The authorizing browser must be on the same machine (the OAuth redirect points at http://localhost:<port>). Your Google account needs Edit access to the chosen GTM account for push, and Publish access for publish; read access is enough for accounts, containers, dump, export, diff, and audit.

Config location. Files live under $XDG_CONFIG_HOME/gtm-cli/ (i.e. ~/.config/gtm-cli/). For backwards compatibility the CLI also reads the legacy ~/.config/gtm-skill/ directory if the new one is empty, so a token cached by the original skill keeps working. New tokens are always written to the new location. To force a fresh consent (e.g. to switch Google accounts), delete ~/.config/gtm-cli/token.json.

Usage

--account and --container accept an id, an exact name, or a name substring (--container also matches the GTM-XXXX public id).

# List accounts / containers.
gtm-cli accounts
gtm-cli containers --account "example.com"

# Audit an account's live config (great as a pre-publish gate).
gtm-cli audit --account 1234567            # exit 1 if any errors
gtm-cli audit --account 1234567 --strict   # exit 1 on warnings too

# Dump everything, pipe into jq.
gtm-cli dump --account "example.com" | jq '.containers[].tags | length'

# Back up a container as GTM export JSON.
gtm-cli export --account 1234567 --container GTM-XXXX > backup.json

# What would publishing the Default Workspace change?
gtm-cli diff --account 1234567 --container GTM-XXXX
# Compare a generated file against what's live:
gtm-cli diff --account 1234567 --container GTM-XXXX --from live --to file:new.json

# Create + populate a container, then cut a version (does NOT publish).
gtm-cli push \
  --file gtm-container-www-example-com.json \
  --account 1234567 \
  --container-name "www.example.com" \
  --version-name "Initial setup: www.example.com"

# Publish a reviewed version live (production-affecting, needs --confirm).
gtm-cli publish --account 1234567 --container GTM-XXXX --version-id 7 --confirm

# Auth management.
gtm-cli whoami
gtm-cli login    # force a fresh consent (e.g. switch Google accounts)
gtm-cli logout   # clear cached token(s)

For push, --container-name defaults to container.name in the JSON and --version-name defaults to Initial setup: <name>.

Refs (for diff and export)

A ref selects which version of a container to read:

• live: the live published version (default).
• workspace (or ws): the Default Workspace (your unpublished edits).
• a version id, e.g. 7 or v7.
• file:<path>: a local GTM export JSON (also any path ending in .json).

What push does, in order

1. accounts.containers.create under the chosen account, getting the real GTM-XXXXXX public id.
2. Finds the auto-created Default Workspace.
3. built_in_variables.create for each built-in (ignores 409 for ones enabled by default).
4. variables.create for each custom variable.
5. triggers.create for each trigger, building a placeholder id -> real id map.
6. tags.create for each tag, with firing/blocking trigger ids remapped.
7. create_version with a name, producing a reviewable, unpublished container version.

It prints a JSON summary: account, container public id, tagManagerUrl, the new version id, and counts of entities created.

After a push

The container is populated and versioned but not live. Open the tagManagerUrl, run Preview to confirm tags fire, then Publish the version manually. If consent mode was enabled, your CMP must push the consent update (e.g. consent_marketing: true) on grant.

API constraints worth knowing

These shape why the tool works the way it does:

• No account creation. Tag Manager API v2 has no accounts.create (accounts are get/list/update only). New accounts are made in the GTM UI. This CLI creates containers, never accounts.
• No JSON import endpoint. Container export/import is a UI-only feature. To populate a container via the API you must create each entity individually, which is exactly what push does.
• Trigger ids are server-assigned. The triggerIds in an export JSON are placeholders. Triggers are created first, a placeholder -> real map is built, then each tag's firingTriggerId/blockingTriggerId is remapped. Built-in trigger ids (2147479553 Initialization, 2147479573 All Pages) are not in trigger[] and pass through unchanged. Variables are referenced by name, so they need no remap.

Error notes

• 403 on create usually means the OAuth identity lacks Edit access on that account, or the wrong account id was passed.
• A compilerError on version creation means an entity references something missing; review the workspace in the GTM UI.

Development

pnpm install
pnpm typecheck   # tsc --noEmit (strict)
pnpm test        # vitest, covers the pure translate/diff/audit logic
pnpm build       # tsup -> dist/index.js (ESM, with shebang)

The CLI is plain ESM TypeScript with no runtime config file. Dependencies (googleapis, google-auth-library, commander) are kept external and resolved from node_modules rather than bundled.

License

MIT