ZT CLI Wizard - Experiment Setup Tool

A modular CLI wizard for creating experiment setups with templates, analytics integration, and git workflow support. Originally extracted from the vite-exp template repository.

Features

• 🧙 Interactive wizard for guided experiment setup
• 📝 Automated mode via JSON payload for CI/CD integration
• 🎨 Template generation for HTML, SCSS, and JavaScript variations
• 📊 Analytics integration (Adobe Legacy AppMeasurement, Adobe Web SDK (Alloy), Tealium, GTM)
• 🌿 Git branch automation for experiment workflows
• 📚 README updates with experiment documentation
• ✅ Payload validation with detailed error messages

Installation

As a global CLI tool

pnpm add -g @zilker-trail/cli-wizard

or

npm install -g @zilker-trail/cli-wizard

As a library in your project

pnpm add @zilker-trail/cli-wizard

or

npm install @zilker-trail/cli-wizard

Usage

Interactive Mode

Run the wizard to be guided through the setup process:

cli-wizard

Or if installed locally:

node src/wizard.js

Automated Mode (JSON Payload)

For CI/CD pipelines or scripted setups:

cli-wizard --json='{"testName":"My Test","prefix":"exp","expNumber":1,"analytics":"adobe","author":"Jane Doe"}'
# or
cli-wizard --json=./config.json

See src/example-payload.json for a complete payload example.

Analytics supports Adobe Legacy AppMeasurement (legacy), Adobe Web SDK/Alloy (adobe target), Tealium (tealium), and Google Tag Manager (gtm).

When README updates are enabled, preview links are generated automatically from the BrowserSync proxy URL:

{browserSync.proxyUrl}?version=v0
{browserSync.proxyUrl}?version=v1

In interactive mode, browserSync.proxyUrl comes from the target page URL prompt. The value can be skipped during setup, but it is required before pushing because it generates the README preview links.

When branch push is requested, README update is required and the wizard validates these URLs before pushing:

• Test Plan URL
• Productive Dev Task URL
• Experiment URL
• Target Page URL

As a Library

Import and use specific modules programmatically:

import { 
  createConfig, 
  createExperimentFiles, 
  collectBasicInfo,
  validatePayload 
} from '@zilker-trail/cli-wizard';

// Use individual functions as needed
const answers = {};
await collectBasicInfo(answers);
const config = createConfig(answers);
await createExperimentFiles(config);

Project Structure

cli-wizard/
├── src/
│   ├── wizard.js              # Main CLI entry point
│   ├── index.js               # Library exports
│   ├── example-payload.json   # Example JSON payload
│   ├── config/                # Configuration generators
│   ├── generators/            # File generation logic
│   ├── prompts/               # Interactive prompts
│   ├── services/              # External integrations
│   ├── templates/             # Code templates
│   ├── ui/                    # Display utilities
│   └── utils/                 # Helper functions
├── package.json
├── LICENSE
└── README.md

See src/README.md for detailed architecture documentation.

Development

# Install dependencies
npm install

# Run the wizard locally
npm start

# Or run directly
node src/wizard.js

Testing Locally

Link the package for local testing:

# In this repo
npm link

# In your test project
cd /path/to/your/project
npm link @zilker-trail/cli-wizard

# Test the CLI
cli-wizard

Publishing

Before publishing to npm:

1. Update package.json:

   • Update version following semantic versioning
   • Verify author and repository information

2. Login to npm:

   npm login

3. Publish:

   npm publish

Dependencies

At runtime, this package uses only Node.js built-in modules:

• fs / fs/promises - File system operations
• path - Path utilities
• child_process - Git and npm command execution
• readline - Interactive prompts

No external dependencies required! 🎉

Requirements

• Node.js >= 18.0.0
• Git (for branch creation features)
• npm/pnpm (for dependency installation features)

License

MIT