Skip to content
owntag
gtm-cli
Public

About

A command line interface for Google Tag Manager API

www.owntag.eu/resources/gtm-cli/

Resources

Readme
MIT license
Activity
Custom properties

Stars

58 stars

Watchers

0 watching

Forks

10 forks
Report repository
BranchesTags

Latest commit

 

History

51 Commits

Folders and files

Repository files navigation

GTM CLI

A powerful command-line interface for Google Tag Manager. Manage your GTM resources directly from the terminal - perfect for automation, CI/CD pipelines, and AI agents.

Features

  • Full GTM API Coverage - Manage all GTM resources: accounts, containers, workspaces, tags, triggers, variables, and more
  • Flexible Authentication - OAuth or Service Account
  • Self-Updating - Built-in upgrade command to stay up to date
  • AI-Friendly - Structured JSON output that AI agents can easily parse
  • Human-Friendly - Colored output, tables, and progress indicators
  • Offline Token Storage - Authenticate once, stay logged in
  • Default Configuration - Set default account/container to avoid repetitive flags
  • Server-Side GTM Support - Full support for sGTM clients, templates, and transformations
  • Shell Completions - Built-in completion scripts for bash, zsh, and fish

Installation

Quick Install (Recommended)

macOS, Linux, WSL:

curl -fsSL https://raw.githubusercontent.com/owntag/gtm-cli/main/install.sh | bash

Note: Windows is not currently supported. Please use WSL (Windows Subsystem for Linux) instead.

Install via npm

Best for CI/CD pipelines with version pinning:

npm install -g @owntag/gtm-cli

# Or pin to a specific version
npm install -g @owntag/gtm-cli@1.5.6

Manual Download

Download the binary for your platform from Releases:

Platform Binary
macOS (Apple Silicon) gtm-darwin-arm64
macOS (Intel) gtm-darwin-x64
Linux (x64) gtm-linux-x64 
# Example for macOS Apple Silicon
curl -fsSL https://github.com/owntag/gtm-cli/releases/latest/download/gtm-darwin-arm64 -o gtm
chmod +x gtm
sudo mv gtm /usr/local/bin/

Run with Deno

If you have Deno installed, run directly without installing:

deno run --allow-net --allow-read --allow-write --allow-env --allow-run \
  https://raw.githubusercontent.com/owntag/gtm-cli/main/src/main.ts

Note: Running directly from source does not include the OAuth credentials shipped with official releases. Either authenticate with a service account, or provide your own OAuth client before running gtm auth login.

Build from Source

git clone https://github.com/owntag/gtm-cli.git
cd gtm-cli
deno task compile
./gtm --help

Note: Source builds do not include the OAuth credentials shipped with official releases. Either authenticate with a service account, or provide your own OAuth client before running gtm auth login.

OAuth when building from source

If you want to use gtm auth login (browser-based OAuth) with a source build, you need to supply your own Google OAuth client:

  1. In the Google Cloud Console, create an OAuth 2.0 Client ID. Choose Desktop app, or Web application with http://localhost:8085/callback registered as an authorized redirect URI.

  2. Enable the Tag Manager API on the same project.

  3. Set the credentials before running the CLI — either as environment variables or in a .env file at the repo root:

    export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
gtm auth login

Alternatively, skip OAuth entirely and use a service account — no redirect URI required.

Quick Start

1. Authenticate

gtm auth login

This opens your browser for Google OAuth authentication. Your credentials are stored securely in ~/.config/gtm-cli/credentials.json.

2. Set Up Defaults (Optional)

Run the interactive setup to configure default account and container:

gtm config setup

This lets you run commands without specifying --account-id and --container-id every time.

3. Start Using

# List your accounts
gtm accounts list

# List containers in an account
gtm containers list --account-id 123456789

# List tags in a workspace
gtm tags list --account-id 123 --container-id 456 --workspace-id 1

# Or, if you've set up defaults:
gtm tags list

Updating

GTM CLI can update itself:

# Check for updates
gtm upgrade --check

# Upgrade to the latest version
gtm upgrade

The CLI will also notify you when a new version is available (checks once per day).

Authentication Options

GTM CLI supports three authentication methods to fit different use cases:

Option 1: OAuth (Default)

Best for: Individual users who want a quick, interactive setup.

gtm auth login

Opens your browser for Google sign-in. Uses the GTM CLI application's API quotas.

Option 2: Service Account

Best for: CI/CD pipelines, automation, and organizations who want to use their own GCP project.

# Login with a service account key file
gtm auth login --service-account /path/to/service-account-key.json

# Or use the standard Google environment variable
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
gtm accounts list

Benefits:

  • Uses your own GCP project's API quotas
  • No interactive browser login required
  • Perfect for CI/CD and automation
  • Your organization controls the credentials

Setup:

  1. Go to Google Cloud Console
  2. Create a Service Account with Tag Manager roles
  3. Download the JSON key file
  4. Grant the service account access to your GTM containers

Checking Auth Status

gtm auth status

Shows which authentication method is active and the associated account.

Logging Out

gtm auth logout

Clears stored credentials. For service accounts, only removes the CLI's reference to the key file (doesn't delete the key file itself).

Command Reference

Authentication

gtm auth login                                # OAuth (browser)
gtm auth login --service-account <file>       # Service account
gtm auth logout                               # Sign out
gtm auth status                               # Check authentication status

Configuration

gtm config setup              # Interactive setup for defaults
gtm config get                # Show all configuration
gtm config set <key> <value>  # Set a configuration value
gtm config unset <key>        # Remove a configuration value

Available configuration keys:

  • defaultAccountId - Default GTM account ID
  • defaultContainerId - Default GTM container ID
  • defaultWorkspaceId - Default GTM workspace ID
  • outputFormat - Default output format (json, table, compact)

Upgrade

gtm upgrade           # Upgrade to the latest version
gtm upgrade --check   # Check for updates without installing
gtm upgrade --force   # Force reinstall current version

Accounts

gtm accounts list                              # List all accounts
gtm accounts get --account-id 123456           # Get account details
gtm accounts update --account-id 123 --name "New Name"

Containers

gtm containers list --account-id 123456
gtm containers get --account-id 123 --container-id 456
gtm containers create --name "My Container" --type web
gtm containers update --container-id 456 --name "New Name"
gtm containers delete --container-id 456 --force
gtm containers snippet --container-id 456     # Get installation snippet

Workspaces

gtm workspaces list
gtm workspaces get --workspace-id 1
gtm workspaces create --name "Feature Branch"
gtm workspaces update --workspace-id 1 --name "Updated Name"
gtm workspaces delete --workspace-id 1 --force
gtm workspaces status --workspace-id 1        # Show pending changes
gtm workspaces sync --workspace-id 1          # Sync with live version
gtm workspaces preview --workspace-id 1       # Quick preview

Tags, Triggers, Variables

All three follow the same pattern:

# List
gtm tags list
gtm triggers list
gtm variables list

# Get
gtm tags get --tag-id 42
gtm triggers get --trigger-id 42
gtm variables get --variable-id 42

# Create
gtm tags create --name "GA4 Event" --type gaawe --config '{"parameter": [...]}'
gtm triggers create --name "Page View" --type pageview
gtm variables create --name "Page URL" --type u

# Update
gtm tags update --tag-id 42 --name "New Name" --config '{"paused": true}'

# Delete
gtm tags delete --tag-id 42 --force

# Revert (undo workspace changes)
gtm tags revert --tag-id 42

Versions

gtm versions create --name "v1.0" --notes "Initial release"
gtm versions get --version-id 42
gtm versions live                              # Get live version
gtm versions publish --version-id 42           # Publish a version
gtm versions set-latest --version-id 42
gtm version-headers list                       # List all versions (lightweight)

Other Resources

# Folders
gtm folders list
gtm folders create --name "Marketing Tags"
gtm folders entities --folder-id 1            # List folder contents

# Environments
gtm environments list
gtm environments create --name "Staging" --url "https://staging.example.com"
gtm environments reauthorize --environment-id 1

# Built-in Variables
gtm built-in-variables list
gtm built-in-variables enable --types "pageUrl,pageHostname,pagePath"
gtm built-in-variables disable --types "pageUrl"

# User Permissions
gtm user-permissions list
gtm user-permissions create --email "user@example.com" --account-access admin

Server-Side GTM (sGTM)

# Clients
gtm clients list
gtm clients create --name "GA4 Client" --type gaaw_client

# Templates
gtm templates list
gtm templates create --name "Custom Template" --template-data "..."

# Transformations
gtm transformations list
gtm transformations create --name "Data Cleanup" --type modify

# Zones
gtm zones list
gtm zones create --name "EU Zone"

# Destinations
gtm destinations list
gtm destinations link --destination-id "AW-123456789"

# Gtag Configs
gtm gtag-configs list
gtm gtag-configs create --type "googleAnalytics"

Output Formats

Control output format with the --output flag:

# Table output (default for terminals)
gtm tags list --output table

# JSON output (default when piping)
gtm tags list --output json

# Compact output (just IDs and names)
gtm tags list --output compact

When piping to other commands or files, JSON is used automatically:

# Piped output is automatically JSON
gtm tags list | jq '.[].name'

# Save to file
gtm tags list --output json > tags.json

Global Options

--help, -h      Show help
--version, -V   Show version
--quiet, -q     Suppress non-essential output
--no-color      Disable colored output

Shell Completions

Generate shell completion scripts:

# Bash
gtm completions bash > ~/.bash_completion.d/gtm

# Zsh
gtm completions zsh > ~/.zsh/completions/_gtm

# Fish
gtm completions fish > ~/.config/fish/completions/gtm.fish

Environment Variables

  • GOOGLE_APPLICATION_CREDENTIALS - Path to service account key file (takes precedence over saved auth)
  • GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET - Override the OAuth client used by gtm auth login (only needed for source builds; see OAuth when building from source)
  • GTM_CLI_CONFIG_DIR - Override configuration directory (default: ~/.config/gtm-cli)
  • NO_COLOR - Disable colored output

For AI Agents

GTM CLI works great with AI assistants and LLMs. A comprehensive guide with examples, best practices, and troubleshooting is embedded in the CLI itself—agents can access it by running gtm agent guide.

CI/CD Integration

GTM CLI works great in CI/CD pipelines with service account authentication:

# GitHub Actions example
jobs:
  export-gtm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install GTM CLI
        run: npm install -g @owntag/gtm-cli@1.5.0

      - name: Export live container
        run: |
          echo '${{ secrets.GTM_SERVICE_ACCOUNT_KEY }}' > /tmp/sa-key.json
          gtm auth login --service-account /tmp/sa-key.json
          gtm versions live -a ${{ vars.GTM_ACCOUNT_ID }} -c ${{ vars.GTM_CONTAINER_ID }} -o json > container.json
          rm /tmp/sa-key.json

Development

Prerequisites

Commands

deno task dev        # Run in development mode with watch
deno task start      # Run the CLI
deno task compile    # Build standalone binary for current platform
deno task lint       # Run linter
deno task fmt        # Format code
deno task check      # Type check

Project Structure

src/
├── main.ts           # CLI entry point
├── auth/             # Authentication (OAuth, Service Account)
├── api/              # GTM API client wrapper
├── commands/         # CLI command definitions
├── config/           # Configuration management
└── utils/            # Utilities (output, errors, update checker)

GitHub Actions will automatically build binaries for macOS and Linux and create a release.

License

MIT License - see LICENSE for details.

Privacy

GTM CLI stores authentication credentials locally on your machine. No data is sent to owntag or any third party — all communication is directly between your machine and Google's APIs. See PRIVACY.md for details.

Credits

Built by owntag - 100% European hosting for Server Side Google Tag Manager.

About

A command line interface for Google Tag Manager API

www.owntag.eu/resources/gtm-cli/

Resources

Readme
MIT license
Activity
Custom properties

Stars

58 stars

Watchers

0 watching

Forks

10 forks
Report repository

Releases

Packages

Contributors

Languages