seomd-cli 1.1.2 → 1.2.0

package/README.md

@@ -36,6 +36,12 @@ SEO.md is a structured, version-controlled specification for describing your sit
 npm install -g seomd-cli
 ```
 
+Or run without installing (zero-install):
+
+```bash
+npx seomd-cli init
+```
+
 Verify:
 
 ```bash
@@ -52,6 +58,14 @@ Run in the root of your project:
 seomd init
 ```
 
+Or non-interactively with flags:
+
+```bash
+seomd init -y --type local
+# or
+seomd init --brand "Acme" --domain acme.com --primary-keyword "local seo"
+```
+
 ### 2) Validate
 
 ```bash
@@ -74,18 +88,21 @@ seomd status --json
 
 ## Configuration
 
-Copy the example env file:
+Copy `.env.example` from your platform provider docs, or create one with the vars you need:
 
+Required for live audits:
 ```bash
-cp .env.example .env
+SEOMD_API_URL=
+SEOMD_API_KEY=your_key_here
 ```
 
-Environment variables:
+Optional:
+```bash
+SEOMD_PAYMENT_TOKEN= # x402 pay-per-scan token
+SEOMD_DOMAIN= # override domain header
+```
 
-- `SEOMD_API_URL` (optional) API base URL (defaults to `https://api.foxcite.com`)
-- `SEOMD_API_KEY` (optional) platform API key (human dashboard auth)
-- `SEOMD_PAYMENT_TOKEN` (optional) agent-native payment token (x402 pay-per-scan)
-- `SEOMD_DOMAIN` (optional) override domain header
+> If you don't have a platform key yet, `seomd init` still works without `.env`.
 
 ## Commands
 
@@ -93,6 +110,31 @@ Environment variables:
 
 Scaffolds `SEO.md`, `SEO.REVERSE.md`, and the `.seomd/` intelligence directory.
 
+**Usage:**
+```bash
+seomd init                              # interactive 5-question flow
+seomd init -y --type local              # skip prompts, use defaults
+seomd init --brand "Acme" --domain acme.com  # non-interactive with partial flags
+seomd init --type saas --brand "MyApp" --domain myapp.com --primary-keyword "billing automation" --output ./new-project
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | skip prompts, use defaults |
+| `--type <type>` | site type: saas, ecommerce, local, blog, marketplace |
+| `--brand <name>` | brand name |
+| `--domain <domain>` | primary domain |
+| `--primary-keyword <keyword>` | primary keyword |
+| `--competitors <list>` | comma-separated competitor list |
+| `--output <dir>` | scaffold into a new (empty) directory instead of cwd |
+
+**Behavior:**
+- Interactive flow by default (5 questions)
+- Non-interactive when `-y` is set **OR** any config flag (`--brand`, `--domain`, `--primary-keyword`, `--competitors`) is provided
+- `--type` alone pre-selects site type in the interactive flow
+- `--output` writes all files to the target directory (must be empty or non-existent)
+
 ### `seomd validate`
 
 Validates your `SEO.md` against the spec requirements.
@@ -117,6 +159,25 @@ Pulls cached/latest platform intelligence and writes it back to the same files a
 
 - `--dry-run` prints a preview and does not modify files
 
+## Built-in Templates
+
+`seomd-cli` ships with type-specific templates under `src/templates/`. `seomd init --type <type>` uses the matching template automatically.
+
+| Type | Template dir | Best for |
+|------|-------------|----------|
+| `saas` | `src/templates/saas/` | Software products, B2B tools, web apps |
+| `blog` | `src/templates/blog/` | Content sites, newsletters, personal brands |
+| `ecommerce` | `src/templates/ecommerce/` | Online stores, DTC brands, product catalogs |
+| `local` | `src/templates/local/` | Service-area businesses, locations pages |
+| `marketplace` | `src/templates/marketplace/` | Two-sided platforms, directories |
+
+Each template contains:
+
+- `SEO.md` — pre-filled with type-specific intent queries, page structures, and negative keywords
+- `SEO.REVERSE.md` — reverse-engineer output scaffold with placeholders for competitor analysis
+
+Want to customize a template? Copy the relevant folder, edit the placeholders (`{{brand}}`, `{{domain}}`, etc.), and use `--type` with your custom scaffold.
+
 ## Local Development
 
 Prefer the local entrypoint while developing:

package/bin/seomd.js

@@ -25,6 +25,19 @@ program
     .description('Scaffold SEO.md for your project')
     .option('-y, --yes', 'skip prompts and use defaults')
     .option('--type <type>', 'site type: saas, ecommerce, local, blog, marketplace')
+    .option('--brand <brand>', 'brand name')
+    .option('--domain <domain>', 'primary domain')
+    .option('--primary-keyword <keyword>', 'primary keyword')
+    .option('--competitors <list>', 'comma-separated competitor list')
+    .option('--output <dir>', 'scaffold into a new directory instead of cwd')
+    .addHelpText('after', `
+
+Examples:
+  seomd init                              # interactive 5-question flow
+  seomd init -y --type local              # skip prompts, use defaults
+  seomd init --brand "Acme" --domain acme.com --primary-keyword "local seo"
+  seomd init --type saas --brand "MyApp" --domain myapp.com --output ./new-project
+`)
     .action(initCommand);
 
 program
@@ -33,23 +46,47 @@ program
     .option('--page <url>', 'analyze a specific page only')
     .option('--intent <category>', 'analyze a specific intent category only')
     .option('--engines <list>', 'comma-separated list of engines to scan (e.g. chatgpt,claude)')
+    .addHelpText('after', `
+
+Examples:
+  seomd analyze                           # full audit
+  seomd analyze --page /pricing           # single page audit
+  seomd analyze --intent transactional --engines chatgpt,claude
+`)
     .action(analyzeCommand);
 
 program
     .command('sync')
     .description('Sync latest platform intelligence to your SEO.md files')
     .option('--dry-run', 'preview changes without writing')
+    .addHelpText('after', `
+
+Examples:
+  seomd sync                              # sync latest data
+  seomd sync --dry-run                    # preview changes only
+`)
     .action(syncCommand);
 
 program
     .command('status')
     .description('Show current citation rates and gap scores')
     .option('--json', 'output as JSON')
+    .addHelpText('after', `
+
+Examples:
+  seomd status                            # human-readable summary
+  seomd status --json                     # machine-readable JSON
+`)
     .action(statusCommand);
 
 program
     .command('validate')
     .description('Validate your SEO.md against the spec')
+    .addHelpText('after', `
+
+Example:
+  seomd validate
+`)
     .action(validateCommand);
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "seomd-cli",
-    "version": "1.1.2",
+    "version": "1.2.0",
     "description": "The official CLI for the SEO.md open standard — AEO infrastructure for technical founders",
     "homepage": "https://seomd.dev",
     "repository": {
@@ -25,18 +25,20 @@
         "release:notes": "node scripts/release-notes.js"
     },
     "dependencies": {
+        "axios": "^1.6.0",
         "chalk": "^5.3.0",
         "commander": "^11.0.0",
+        "dotenv": "^16.3.1",
         "enquirer": "^2.4.1",
-        "ora": "^7.0.1",
-        "yaml": "^2.3.4",
         "fs-extra": "^11.1.1",
-        "axios": "^1.6.0",
-        "dotenv": "^16.3.1"
+        "ora": "^7.0.1",
+        "yaml": "^2.3.4"
     },
     "devDependencies": {
-        "jest": "^29.7.0",
-        "eslint": "^8.50.0"
+        "@eslint/js": "^10.0.1",
+        "eslint": "^8.50.0",
+        "eslint-plugin-n": "^18.1.0",
+        "jest": "^29.7.0"
     },
     "engines": {
         "node": ">=18.0.0"

package/src/commands/analyze.js

@@ -1,7 +1,6 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import fs from 'fs-extra';
-import path from 'path';
 import dotenv from 'dotenv';
 import { parseSeoMd } from '../utils/parser.js';
 import { client } from '../utils/api-client.js';

package/src/commands/init.js

@@ -16,8 +16,19 @@ export async function initCommand(options) {
     console.log(chalk.dim('The open standard for AI-era SEO configuration.'));
     console.log('');
 
-    // Check if SEO.md already exists
-    const seomdPath = path.join(process.cwd(), 'SEO.md');
+    // Determine target directory
+    let workingDir = process.cwd();
+    if (options.output) {
+        const resolved = path.resolve(options.output);
+        if (await fs.pathExists(resolved) && (await fs.readdir(resolved)).length > 0) {
+            console.log(chalk.red(`Output directory must be empty or non-existent: ${resolved}`));
+            process.exit(1);
+        }
+        await fs.ensureDir(resolved);
+        workingDir = resolved;
+    }
+
+    const seomdPath = path.join(workingDir, 'SEO.md');
     if (await fs.pathExists(seomdPath)) {
         console.log(chalk.yellow('⚠ SEO.md already exists in this directory.'));
         const { overwrite } = await prompt({
@@ -34,14 +45,26 @@ export async function initCommand(options) {
 
     let answers;
 
-    if (options.yes) {
-        // Default values for --yes flag
+    // Mode 5: non-interactive if -y OR any config field provided
+    const hasConfigFlags =
+        options.brand !== undefined ||
+        options.domain !== undefined ||
+        options.primaryKeyword !== undefined ||
+        options.competitors !== undefined;
+
+    if (options.yes || hasConfigFlags) {
         answers = {
             site_type: options.type || 'saas',
-            domain: 'example.com',
-            brand: 'My Brand',
-            primary_keyword: '',
-            competitors: '',
+            domain: options.domain || 'example.com',
+            brand: options.brand || 'My Brand',
+            primary_keyword: options.primaryKeyword || '',
+            competitors: options.competitors
+                ? options.competitors
+                      .split(',')
+                      .map((c) => c.trim())
+                      .filter(Boolean)
+                      .slice(0, 3)
+                : [],
         };
     } else {
         // The 5-question init flow
@@ -109,21 +132,20 @@ export async function initCommand(options) {
     try {
         // 1. Generate SEO.md
         const seomdContent = generateSeoMd(answers);
-        await fs.writeFile(seomdPath, seomdContent, 'utf8');
+        await fs.writeFile(path.join(workingDir, 'SEO.md'), seomdContent, 'utf8');
         spinner.succeed(chalk.green('SEO.md created'));
 
         // 2. Generate SEO.REVERSE.md
-        const reversePath = path.join(process.cwd(), 'SEO.REVERSE.md');
         const reverseContent = generateReverseMd(answers);
-        await fs.writeFile(reversePath, reverseContent, 'utf8');
+        await fs.writeFile(path.join(workingDir, 'SEO.REVERSE.md'), reverseContent, 'utf8');
         spinner.succeed(chalk.green('SEO.REVERSE.md initialized'));
 
         // 3. Create .seomd/ directory structure
-        await createSeomdDir(process.cwd(), answers);
+        await createSeomdDir(workingDir, answers);
         spinner.succeed(chalk.green('.seomd/ directory created'));
 
         // 4. Add .seomd/ to .gitignore if it exists
-        await updateGitignore(process.cwd());
+        await updateGitignore(workingDir);
 
         console.log('');
         console.log(chalk.bold.green('✓ SEO.md initialized successfully'));

package/src/commands/sync.js

@@ -1,7 +1,6 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import fs from 'fs-extra';
-import path from 'path';
 import dotenv from 'dotenv';
 import { parseSeoMd } from '../utils/parser.js';
 import { client } from '../utils/api-client.js';

package/src/generators/directory.js

@@ -40,38 +40,89 @@ export async function createSeomdDir(cwd, answers) {
 function generateSeomdReadme(brand, domain) {
     return `# .seomd/
 
-Intelligence directory for ${brand} (${domain})
+AI search optimization workspace for **${brand}** (${domain})
 Generated by SEO.md CLI — https://seomd.dev
 
+## What is this?
+
+\`.seomd/\` stores platform-generated intelligence from citation audits, competitor analysis, and reverse-engineered playbooks. It lives alongside your source code so SEO strategy is version-controlled and reviewable in PRs.
+
 ## Directory Structure
 
 \`\`\`
 .seomd/
-├── pages/          # per-page reverse engineer analysis
+├── pages/          # per-page reverse-engineer analysis
+│   ├── homepage.md
+│   ├── services.md
+│   └── ...
 ├── reports/        # dated snapshot reports (gitignored by default)
+│   └── 2026-06-10.md
 └── competitors/    # competitor citation profiles
+    └── comp-1.md
 \`\`\`
 
-## Usage
+## Git behavior
+
+| Path | Git | Why |
+|------|-----|-----|
+| \`.seomd/pages/\` | tracked | actionable playbooks belong in code review |
+| \`.seomd/competitors/\` | tracked | competitor intel is project state |
+| \`.seomd/reports/\` | ignored | dated snapshots are noise in git history |
+
+\`.seomd/reports/\` is added to \`.gitignore\` automatically by \`seomd init\`.
+
+## When to run what
 
 \`\`\`bash
-# Run citation analysis and update all files
+# First full audit — scans all pages + intents
 npx seomd analyze
 
-# Sync latest platform intelligence
+# Refresh from cached platform data (no new scan)
 npx seomd sync
 
-# View current status
+# Check current gap scores without modifying files
 npx seomd status
+npx seomd status --json
 \`\`\`
 
-## File Ownership
+| Command | Use when |
+|---------|----------|
+| \`analyze\` | You want a fresh audit, new competitor data, or updated playbooks |
+| \`sync\` | You just want the latest cached data from your platform |
+| \`status\` | You want a quick health check without writebacks |
+
+## Reading a page playbook
+
+Each \`pages/<id>.md\` contains:
+
+- **why_page_won** — what top-cited competitors do right
+- **citation_hooks** — patterns to replicate
+- **gaps_for_brand** — where your page falls short
+- **remediation_playbook** — step-by-step fixes with effort/impact
+- **fastest_win** — highest ROI action to take now
+- **suggested_content_outline** — ready-to-use outline for your writer or AI
+
+## File ownership
+
+| File/dir | Owner | Editable? |
+|-----------|-------|----------|
+| \`SEO.md\` | you | yes |
+| \`SEO.REVERSE.md\` | platform | no |
+| \`.seomd/pages/*.md\` | platform | no |
+| \`.seomd/competitors/*.md\` | platform | no |
+| \`.seomd/reports/*.md\` | platform | no |
+
+Platform-generated files are overwritten on each \`analyze\` or \`sync\`.
+
+## Platform connection
+
+To enable live writebacks:
 
-- \`pages/\` — platform generated, do not edit manually
-- \`reports/\` — platform generated, gitignored by default
-- \`competitors/\` — platform generated, do not edit manually
+1. Connect at https://seomd.dev/connect
+2. Add \`SEOMD_API_KEY\` to your \`.env\`
+3. Run \`npx seomd analyze\`
 
-Connect your platform at https://seomd.dev/connect
+_Note: Never commit API keys or \`.env\` files to version control._
 `;
 }