Getting Started

Get up and running with YourTM CLI in under 5 minutes. This guide walks you through installation, project setup, and your first deployment.

Prerequisites

Before you begin, make sure you have the following installed:

Installation

Install the YourTM CLI with a single command:

curl -fsSL https://yourtm.dev/install | bash

This installs ytm to ~/.yourtm/bin and adds it to your PATH.

Or install via npm if you prefer:

npm install -g @yourtm/cli

Verify the installation:

ytm --version

Initialize a New Project

Create a new YourTM project in your current directory:

ytm init

The interactive wizard will ask you a few questions:

? Container name: My Website Tags
? Container ID: YTM-MYSITE
? Description: Tag management for mysite.com
? Default environment: development

✔ Created yourtm.config.ts
✔ Created yourtm/tags/
✔ Created yourtm/triggers/
✔ Created yourtm/zones/
✔ Installed dependencies

🎉 Project initialized! Run 'ytm create tag' to add your first tag.

Project Structure

After initialization, your project will have this structure:

my-project/ ├── yourtm.config.ts # Main configuration ├── yourtm/ │ ├── tags/ # Tag definitions │ │ └── custom/ # Custom tags │ ├── triggers/ # Trigger definitions │ └── zones/ # Zone definitions ├── dist/ # Build output (gitignored) │ └── ytm/ │ ├── core.js # Core runtime │ ├── zone-global.js # Global zone bundle │ └── zone-*.js # Other zone bundles └── package.json

Configuration

The yourtm.config.ts file is the heart of your project:

yourtm.config.ts
import { defineConfig } from '@yourtm/core'

export default defineConfig({
  // Container identification
  container: {
    id: 'YTM-MYSITE',
    name: 'My Website Tags',
    description: 'Tag management for mysite.com',
  },

  // Build settings
  build: {
    outDir: 'dist/ytm',
    minify: true,
    sourcemap: false,
  },

  // Performance budgets
  budgets: {
    maxBundleSize: 100_000,  // 100KB total
    maxTagSize: 10_000,       // 10KB per tag
    warnOnSlowTags: 100,      // Warn if tag takes >100ms
  },

  // Consent categories
  consent: {
    categories: ['necessary', 'analytics', 'marketing', 'preferences'],
    defaultState: {
      necessary: true,
      analytics: false,
      marketing: false,
      preferences: false,
    },
  },

  // Cloudflare deployment (added by ytm deploy init)
  cloudflare: {
    accountId: 'YOUR_ACCOUNT_ID',
    kvNamespaceId: 'YOUR_KV_NAMESPACE_ID',
    workerName: 'yourtm-cdn',
  },
})

Create Your First Tag

Use the interactive wizard to create a tag from a template:

ytm create tag

Select a platform and template:

? Select platform:
  ❯ Google (GA4, Google Ads, GTM)
    Meta (Pixel, CAPI)
    TikTok
    Social (LinkedIn, Twitter, Pinterest)
    E-commerce
    Utilities

? Select template:
  ❯ GA4 Configuration
    GA4 Event
    GA4 Pageview
    GA4 E-commerce Purchase
    Google Ads Conversion
    Google Ads Remarketing

Or create a custom tag manually:

yourtm/tags/custom/my-tracker.ts
import { defineTag } from '@yourtm/core'

export default defineTag({
  name: 'My Custom Tracker',
  description: 'Send events to our internal analytics',
  triggers: ['page-load'],
  zones: ['global'],
  consent: ['analytics'],

  execute(ctx) {
    // Send data to your endpoint
    fetch('/api/track', {
      method: 'POST',
      body: JSON.stringify({
        event: 'pageview',
        url: ctx.url.href,
        timestamp: Date.now(),
      }),
    })
  },
})

Create a Trigger

Triggers define when tags fire:

ytm create trigger

Or create manually:

yourtm/triggers/button-click.ts
import { defineTrigger } from '@yourtm/core'

export default defineTrigger({
  name: 'CTA Button Click',
  type: 'click',
  config: {
    selector: '.cta-button',
    waitForAllClicks: false,
  },
})

Create a Zone

Zones control which tags load on which pages:

yourtm/zones/checkout.ts
import { defineZone } from '@yourtm/core'

export default defineZone({
  name: 'checkout',
  description: 'Checkout and payment pages',
  match: {
    pathname: ['/checkout/*', '/payment/*', '/order/confirm'],
  },
})

Build Your Container

Compile your tags into optimized bundles:

ytm build

Output:

Building YourTM Container
-------------------------

- Loading configuration...
  Container ID  YTM-MYSITE
  Environment   development
  Minify        true
  Sourcemaps    false

✔ Build completed successfully!

  Tags      4
  Triggers  3
  Zones     3
  Bundles   4

  Bundle Sizes:

  core.js                 2.06 KB
  zone-global.js          1.92 KB
  zone-checkout.js          635 B
  zone-product.js           229 B
--------------------------------------------------
  Total                   4.83 KB

✔ Bundle size within budget: 4.83 KB / 100 KB

Local Testing

Start the development server with hot reload:

ytm dev

This starts a local server that:

Add the script tag to your site:

<script src="http://localhost:3456/ytm/core.js"></script>

Deploy to the Edge

First, set up your Cloudflare infrastructure:

ytm deploy init

This interactive command will:

  1. Prompt for your Cloudflare API credentials
  2. Create an R2 bucket for storing bundles
  3. Enable public CDN access
  4. Save configuration to yourtm.config.ts

Then deploy your bundles:

ytm build && ytm deploy -e production
You're live! Your tags are now served from Cloudflare's global edge network. Update your script tag to use your worker URL.

Next Steps