Ad-Preflight CLI

A "Zero-Friction" validator and packager for HTML5 ad creatives. Validates and packages ads according to platform specifications (Google Ads, DoubleClick, etc.) with auto-fix capabilities.

Installation

$3

Recommended (global CLI):

``bash
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):

`bash
npm install @ad-preflight/cli
`

Or as a dev dependency:

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

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

`bash
npx @ad-preflight/cli --help
`

$3

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):

`json
{
"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.

$3

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):
`bash
ad-preflight init-rules
`

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

Manual method:
`bash

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

$3

`bash
ad-preflight package [options]
`

Arguments:
- : Path to the ad creative folder.

Options:
- --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.

$3

Standard validation (no fix):
`bash
ad-preflight package ./banners/my-ad
`

Validate and auto-fix:
`bash
ad-preflight package ./banners/my-ad --fix
`

Validate and fix a specific ad type:
`bash
ad-preflight package ./banners/app-ad --type app --fix
`

AMP ad validation:
`bash
ad-preflight package ./banners/amp-ad --type amp --fix
`

Deep validation (Pro Plan):
`bash
ad-preflight package ./banners/my-ad --deep
`

Initialize .cursorrules for AI agent suggestions:
`bash
ad-preflight init-rules
`

$3

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

Features

- Smart Sanitation: Automatically detects project root (index.html) and flattens nested folder structures
- Security: Validates file types via magic number inspection to prevent extension spoofing
- Dynamic Size Enforcement: Checks and enforces file size limits:
- Standard HTML5 Display: 150 KB max
- AMPHTML Ads: 600 KB max
- App Campaigns: 5 MB max
- Auto-Injection: Automatically fixes common issues:
- Injects var clickTag if missing
- Injects derived from CSS analysis
- Enforces HTTPS by replacing http:// links
- Validation Mode: Without --fix, scans for issues and provides detailed reports
- MCP Server: Exposes validate_ad_creative tool for agentic use in Cursor and other MCP-compatible editors
- Deep Validation (Pro): Headless browser validation with CPU profiling, network analysis, and visual snapshots

Pricing & Licensing

$3

All core features are completely free and always will be:
- ✅ Static validation (file structure, ClickTag, ad size, HTTPS)
- ✅ Auto-fix capabilities (--fix flag)
- ✅ All ad types (standard, AMP, app)
- ✅ MCP server integration
- ✅ File size enforcement
- ✅ Magic number validation
- ✅ All validation and packaging features

$3

The Pro Plan will unlock advanced deep validation :
- 🔍 Deep Validation (--deep flag):
- CPU profiling (Google Heavy Ad Intervention check)
- Network waterfall analysis (illegal external calls)
- Visual snapshot generation (screenshot proof)
- Prevents Google ad rejections before submission

Note: Pro Plan is currently in development. All existing features remain free forever.

$3

Ad-Preflight Pro | Early Access ✨

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

`bash
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 and success page
3. Activate your license:

`bash
ad-preflight activate
`

Check License Status:
`bash
ad-preflight license
`

Activate License Key:
`bash
ad-preflight activate
``

$3

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

What Gets Validated

Static Validation (Free):
- ✅ File structure (index.html at root)
- ✅ ClickTag script presence
- ✅ Ad size meta tag
- ✅ HTTPS enforcement (no mixed content)
- ✅ File size limits (by ad type)
- ✅ Valid file types (magic number validation)
- ✅ Security (forbidden file types)

Deep Validation (Pro Plan):
- 🔍 CPU usage profiling
- 🔍 Network request analysis
- 🔍 Visual rendering verification
- 🔍 Heavy Ad Intervention detection

Platform Support

Validates and packages ads for:
- Google Ads (Standard HTML5 Display)
- Google AMPHTML Ads
- Google App Campaigns
- DoubleClick (and other platforms following similar specs)

License

See LICENSE.md for details.