Ad-Preflight CLI

A zero-friction validator and packager for HTML5 ad creatives, built for Google Ads, DV360, and similar platforms - with smart auto-fixes for common rejection issues.

• Features
• Who is this for?
• Quick start
• Installation
• Usage
• Local Preview
• Pro plan availability
• License

Features

• Fewer rejections: Enforces ad specs (size limits, ad.size meta, HTTPS, ClickTag) before upload.
• Safer creatives: Validates file types via magic numbers to catch spoofed extensions.
• Less manual plumbing: Auto-injects clickTag and <meta name="ad.size"> when missing.
• Fits existing workflows: Works as a CLI and as an MCP tool inside Cursor.
• Local Preview: Run your ad in a realistic publisher page-mock to test layout, z-index, and click-through before deploying.
• Deep validation (Pro): Headless browser validation with CPU profiling, network analysis, and visual snapshots.

Pricing: Core validation and auto-fix features are free. Deep browser-based validation is part of the upcoming optional Pro plan.

Who is this for?

• Ad ops teams who need consistent, rejection-proof HTML5 creatives
• Creative developers who want a fast preflight before sending to trafficking
• Agencies managing many banners across Google Ads / DV360 / Campaign Manager

Quick start

npm install -g @ad-preflight/cli
ad-preflight package ./path/to/ad --fix

Installation

NPM Installation (Recommended)

Recommended (global CLI):

npm install -g @ad-preflight/cli
ad-preflight --help

This makes the ad-preflight command available globally (PowerShell, CMD, macOS, Linux) as long as your global npm bin is on PATH.

Alternative (local install + npx):

npm install @ad-preflight/cli

Or as a dev dependency:

npm install --save-dev @ad-preflight/cli

Then run the CLI via npx (if you did a local install):

npx @ad-preflight/cli --help

MCP Server Setup (for Cursor/Editor Integration)

After installing, configure the MCP server to use ad-preflight in Cursor:

Create or update .cursor/mcp.json (project-specific) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "ad-preflight": {
      "command": "node",
      "args": ["node_modules/@ad-preflight/cli/dist/mcp-server.js"]
    }
  }
}

Restart Cursor after configuration. You can then use the validate_ad_creative tool via Cursor's agent.

Enable Agent Suggestions (Optional)

To help Cursor agents automatically detect HTML5 ad projects and suggest @ad-preflight/cli, you can copy the .cursorrules file to your project root:

Recommended method (using CLI):

ad-preflight init-rules

This command automatically copies .cursorrules to your project root from the installed package.

Manual method:

# Copy from node_modules to your project root
cp node_modules/@ad-preflight/cli/.cursorrules .cursorrules

This teaches Cursor agents to:

• Recognize HTML5 ad project patterns
• Suggest installing @ad-preflight/cli when appropriate
• Guide users through installation and setup

Tip: If you're using Cursor, the AI agent may automatically suggest installing and configuring @ad-preflight/cli when it detects HTML5 ad projects in your workspace. The .cursorrules file enhances this capability.

Usage

Use --fix when you want ad-preflight to automatically repair common issues; omit it if you only want a report of problems.

CLI Usage

ad-preflight package <folder> [options]

Arguments:

• <folder>: Path to the ad creative folder.

Options:

• --type <type>: Ad type. Choices: standard (default), amp, app.
• --fix: Auto-fix issues (inject ClickTag, HTTPS, Ad Size). Default: false.
• --deep: Run deep validation with headless browser (requires Pro Plan). Default: false.
• -h, --help: Display help for command.

Examples

Standard validation (no fix):

ad-preflight package ./banners/my-ad

Validate and auto-fix:

ad-preflight package ./banners/my-ad --fix

Validate and fix a specific ad type:

ad-preflight package ./banners/app-ad --type app --fix

AMP ad validation:

ad-preflight package ./banners/amp-ad --type amp --fix

Deep validation (Pro Plan):

ad-preflight package ./banners/my-ad --deep

Initialize .cursorrules for AI agent suggestions:

ad-preflight init-rules

Typical workflow: validate + fix + zip

ad-preflight package ./banners/campaign-001 --fix
# => outputs a ready-to-upload ZIP and a validation report

MCP Tool Usage (Cursor/Editor Integration)

Once configured, you can use the validate_ad_creative tool via Cursor's agent:

• "Validate this ad creative" – Validates without fixing
• "Check and fix issues in this ad" – Validates and auto-fixes
• "Validate this AMP ad" – Validates with AMP type

The tool accepts:

• folderPath: Absolute path to the ad creative folder
• type: "standard" (default), "amp", or "app"
• fix: true to auto-fix, false to only validate

Local Preview

The preview command spins up a local development server and injects your ad creative into a realistic publisher environment (page-mock). This allows you to test layout, z-index, and click-through functionality without deploying code.

Usage

npx ad-preflight preview ./path-to-your-ad

Or with a globally installed CLI:

ad-preflight preview ./path-to-your-ad

Pro plan availability

Ad-Preflight Pro | Early Access ✨

Deep validation is almost here. We are currently onboarding our first batch of users. To get early access:

ad-preflight buy

or visit https://ad-preflight.com for more info. This will show you how to join the waitlist and be notified when Pro features go live.

Once Pro Plan is available, you'll be able to:

1. Purchase a subscription through the secure checkout
2. Receive your license key via email
3. Activate your license

License commands

# Check current license
ad-preflight license

# Activate a Pro license
ad-preflight activate <your-license-key>

License management

• Licenses are tied to your machine ID
• Each Pro license supports up to 2 machines
• License validation happens server-side
• All existing free features remain free forever

License

See LICENSE.md for details.