@myvillage/cli 1.64.7 → 1.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.64.7",
+  "version": "1.66.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/agent-runtime/loop.js

@@ -21,44 +21,53 @@ export async function agentLoop(agentName, { signal }) {
   const configPath = join(agentDir, 'agent.config.yaml');
   const config = parseYaml(readFileSync(configPath, 'utf-8'));
 
-  // Determine provider and resolve API key
-  const provider = config.brain?.provider || 'anthropic';
+  // Determine provider + model, honoring the app-wide default model in
+  // ~/.myvillage/config.json (written by MyVillage Studio's Settings). Precedence:
+  // per-agent brain.* > app-wide defaultModel > built-in default.
   const globalConfigPath = join(homedir(), '.myvillage', 'config.json');
-  let apiKey;
+  let globalConfig = {};
+  if (existsSync(globalConfigPath)) {
+    try {
+      globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf-8'));
+    } catch { /* ignore */ }
+  }
+  const defaultModel = globalConfig.defaultModel || {};
+
+  const provider = config.brain?.provider || defaultModel.provider || 'anthropic';
+  const DEFAULT_MODEL_ID = {
+    anthropic: 'claude-sonnet-4-5-20250929',
+    openai: 'gpt-4o',
+    'self-hosted': '',
+  };
+  const modelId =
+    config.brain?.model || defaultModel.model || DEFAULT_MODEL_ID[provider] || DEFAULT_MODEL_ID.anthropic;
 
+  // Create provider and model
+  let model;
   if (provider === 'openai') {
-    apiKey = process.env.OPENAI_API_KEY;
-    if (!apiKey && existsSync(globalConfigPath)) {
-      try {
-        const globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf-8'));
-        apiKey = globalConfig.openaiApiKey;
-      } catch { /* ignore */ }
-    }
+    const apiKey = process.env.OPENAI_API_KEY || globalConfig.openaiApiKey;
     if (!apiKey) {
       logActivity(agentDir, { type: 'error', error: 'No OpenAI API key configured' });
-      throw new Error('No OpenAI API key configured. Set OPENAI_API_KEY or run: myvillage agent start ' + agentName);
+      throw new Error('No OpenAI API key configured. Set OPENAI_API_KEY or configure a model in MyVillage Studio settings.');
     }
-  } else {
-    apiKey = process.env.ANTHROPIC_API_KEY;
-    if (!apiKey && existsSync(globalConfigPath)) {
-      try {
-        const globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf-8'));
-        apiKey = globalConfig.anthropicApiKey;
-      } catch { /* ignore */ }
+    const openai = createOpenAI({ apiKey });
+    model = openai(modelId);
+  } else if (provider === 'self-hosted') {
+    // Self-hosted = any OpenAI-compatible endpoint.
+    const baseURL = config.brain?.baseURL || defaultModel.baseURL;
+    if (!baseURL) {
+      logActivity(agentDir, { type: 'error', error: 'No base URL configured for self-hosted model' });
+      throw new Error('No base URL configured for the self-hosted model. Set it in MyVillage Studio settings.');
     }
+    const apiKey = process.env.SELF_HOSTED_API_KEY || globalConfig.selfHostedApiKey || 'not-needed';
+    const openai = createOpenAI({ apiKey, baseURL });
+    model = openai(modelId);
+  } else {
+    const apiKey = process.env.ANTHROPIC_API_KEY || globalConfig.anthropicApiKey;
     if (!apiKey) {
       logActivity(agentDir, { type: 'error', error: 'No Anthropic API key configured' });
-      throw new Error('No Anthropic API key configured. Set ANTHROPIC_API_KEY or run: myvillage agent start ' + agentName);
+      throw new Error('No Anthropic API key configured. Set ANTHROPIC_API_KEY or configure a model in MyVillage Studio settings.');
     }
-  }
-
-  // Create provider and model
-  const modelId = config.brain?.model || (provider === 'openai' ? 'gpt-4o' : 'claude-sonnet-4-5-20250929');
-  let model;
-  if (provider === 'openai') {
-    const openai = createOpenAI({ apiKey });
-    model = openai(modelId);
-  } else {
     const anthropic = createAnthropic({ apiKey });
     model = anthropic(modelId);
   }

package/src/agent-runtime/mcp-client.js

@@ -156,7 +156,12 @@ export async function getMCPTools(agentDir, agentConfig) {
       }
 
       activeClients.push(client);
-      const tools = await client.tools();
+      // Per-server tool allowlist (least privilege). When `allowed_tools` is a
+      // non-empty array in tools.yaml, expose ONLY those tools to the agent and
+      // withhold everything else this server offers (e.g. grant `network_feed`
+      // but not `wallet_send`). Absent/empty → all tools, the backward-compatible
+      // default.
+      const tools = applyToolAllowlist(await client.tools(), server.allowed_tools, name);
       const toolNames = Object.keys(tools);
       Object.assign(allTools, tools);
       servers.push({
@@ -182,6 +187,29 @@ export async function getMCPTools(agentDir, agentConfig) {
   return { tools: allTools, servers };
 }
 
+/**
+ * Restrict a server's tools to an allowlist. `allowed` is the `allowed_tools`
+ * array from a tools.yaml server entry; when it's missing or empty, all tools
+ * pass through unchanged (backward-compatible). Allowlisted names that the
+ * server doesn't actually expose are logged so a typo or a removed/renamed tool
+ * is visible rather than silently dropping the scope to nothing.
+ */
+export function applyToolAllowlist(tools, allowed, serverName) {
+  if (!Array.isArray(allowed) || allowed.length === 0) return tools;
+  const allow = new Set(allowed);
+  const filtered = {};
+  for (const [name, tool] of Object.entries(tools)) {
+    if (allow.has(name)) filtered[name] = tool;
+  }
+  const unknown = allowed.filter((n) => !(n in tools));
+  if (unknown.length > 0) {
+    console.error(
+      `[mcp-client] ${serverName}: allowed_tools lists ${unknown.length} tool(s) this server doesn't expose: ${unknown.join(', ')}`,
+    );
+  }
+  return filtered;
+}
+
 export async function cleanupMCPClients() {
   for (const client of activeClients) {
     try { await client.close(); } catch { /* ignore */ }

package/src/commands/create-game.js

@@ -8,54 +8,117 @@ import inquirer from 'inquirer';
 import { isAuthenticated } from '../utils/auth.js';
 import { createGameProject, createUnityGameProject } from '../utils/templates.js';
 
+// ── Option normalizers (for non-interactive / Studio-driven creation) ────────
+function normOrientation(v) {
+  if (!v) return null;
+  v = String(v).toLowerCase();
+  return v === 'portrait' || v === 'landscape' ? v : null;
+}
+function normEngine(v) {
+  if (!v) return null;
+  v = String(v).toLowerCase();
+  if (v === 'threejs' || v === 'three' || v === 'js') return 'threejs';
+  if (v === 'unity') return 'unity';
+  return null;
+}
+function normType(v) {
+  if (!v) return null;
+  v = String(v).toLowerCase();
+  return ['quiz', 'exploration', 'narrative', 'custom'].includes(v) ? v : null;
+}
+function normAge(v) {
+  if (!v) return null;
+  v = String(v).toLowerCase();
+  return ['under-5', '6-12', '13-and-over'].includes(v) ? v : null;
+}
+function normCategory(v) {
+  if (!v) return null;
+  v = String(v).toLowerCase();
+  return ['education', 'action', 'adventure', 'puzzle', 'other'].includes(v) ? v : null;
+}
+function fail(json, msg) {
+  if (json) console.log(JSON.stringify({ ok: false, error: msg }));
+  else console.log(chalk.red(`\n  ✗ ${msg}`));
+}
+
 export async function createGameCommand(options = {}) {
-  // Check authentication
+  const json = !!options.json;
+  // In JSON/non-interactive mode we never prompt — missing required flags error out.
+  const nonInteractive = json || !!options.yes || !!options.nonInteractive;
+
   if (!isAuthenticated()) {
-    console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
-    return;
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
   }
 
   // Orientation first — it decides where the game can play.
-  //   Portrait  → muni mobile app + web (mvp-video-games)
-  //   Landscape → web only (mvp-video-games)
-  const { orientation } = await inquirer.prompt([
-    {
-      type: 'list',
-      name: 'orientation',
-      message: 'Where will this game play?',
-      choices: [
-        { name: 'Portrait — muni mobile app + web (plays everywhere)', value: 'portrait' },
-        { name: 'Landscape — web only (mvp-video-games)', value: 'landscape' },
-      ],
-    },
-  ]);
+  let orientation = normOrientation(options.orientation);
+  if (!orientation) {
+    if (nonInteractive) return fail(json, 'Missing --orientation (portrait|landscape)');
+    orientation = (
+      await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'orientation',
+          message: 'Where will this game play?',
+          choices: [
+            { name: 'Portrait — muni mobile app + web (plays everywhere)', value: 'portrait' },
+            { name: 'Landscape — web only (mvp-video-games)', value: 'landscape' },
+          ],
+        },
+      ])
+    ).orientation;
+  }
 
   // Engine choice
-  const { engine } = await inquirer.prompt([
-    {
-      type: 'list',
-      name: 'engine',
-      message: 'Which engine are you using?',
-      choices: [
-        { name: 'JS / Three.js — web build (runs in a browser / WebView)', value: 'threejs' },
+  let engine = normEngine(options.engine);
+  if (!engine) {
+    if (nonInteractive) return fail(json, 'Missing --engine (threejs|unity)');
+    engine = (
+      await inquirer.prompt([
         {
-          name: orientation === 'landscape'
-            ? 'Unity — WebGL build (runs in browser)'
-            : 'Unity — native build for muni (can also build WebGL for web)',
-          value: 'unity',
+          type: 'list',
+          name: 'engine',
+          message: 'Which engine are you using?',
+          choices: [
+            { name: 'JS / Three.js — web build (runs in a browser / WebView)', value: 'threejs' },
+            {
+              name:
+                orientation === 'landscape'
+                  ? 'Unity — WebGL build (runs in browser)'
+                  : 'Unity — native build for muni (can also build WebGL for web)',
+              value: 'unity',
+            },
+          ],
         },
-      ],
-    },
-  ]);
+      ])
+    ).engine;
+  }
 
   if (engine === 'unity') {
     return createUnityGame({ ...options, orientation });
   }
 
-  // ── Three.js path (existing flow) ──
+  // ── Three.js path ──
+  const provided = {
+    type: normType(options.type),
+    name: options.name && String(options.name).trim() ? String(options.name).trim() : null,
+    description: options.description,
+    ageGroup: normAge(options.targetAge || options.ageGroup),
+  };
+
+  const needType = !provided.type;
+  const needName = !provided.name;
+  const needAge = !provided.ageGroup;
+  if (nonInteractive && (needType || needName || needAge)) {
+    const miss = [needType && '--type', needName && '--name', needAge && '--target-age']
+      .filter(Boolean)
+      .join(', ');
+    return fail(json, `Missing required option(s): ${miss}`);
+  }
 
-  const answers = await inquirer.prompt([
-    {
+  const prompts = [];
+  if (needType)
+    prompts.push({
       type: 'list',
       name: 'type',
       message: 'What type of game would you like to create?',
@@ -65,24 +128,24 @@ export async function createGameCommand(options = {}) {
         { name: 'Narrative Game - Story-driven experience', value: 'narrative' },
         { name: 'Custom - Start with base Three.js template', value: 'custom' },
       ],
-    },
-    {
+    });
+  if (needName)
+    prompts.push({
       type: 'input',
       name: 'name',
       message: 'Game name:',
       default: 'My Game',
-      validate: (input) => {
-        if (!input.trim()) return 'Game name is required.';
-        return true;
-      },
-    },
-    {
+      validate: (input) => (input.trim() ? true : 'Game name is required.'),
+    });
+  if (provided.description === undefined && !nonInteractive)
+    prompts.push({
       type: 'input',
       name: 'description',
       message: 'Game description:',
       default: 'An educational game built with Three.js',
-    },
-    {
+    });
+  if (needAge)
+    prompts.push({
       type: 'list',
       name: 'ageGroup',
       message: 'Target age group:',
@@ -91,81 +154,113 @@ export async function createGameCommand(options = {}) {
         { name: '6-12', value: '6-12' },
         { name: '13 and Over', value: '13-and-over' },
       ],
-    },
-  ]);
+    });
+
+  const answers = prompts.length ? await inquirer.prompt(prompts) : {};
+  const game = {
+    type: provided.type || answers.type,
+    name: provided.name || answers.name,
+    description: provided.description ?? answers.description ?? 'An educational game built with Three.js',
+    ageGroup: provided.ageGroup || answers.ageGroup,
+  };
 
-  const slug = answers.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
-  const targetDir = resolve(process.cwd(), slug);
+  const slug = game.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+  const targetDir = resolve(options.dir ? resolve(options.dir) : process.cwd(), slug);
 
   if (existsSync(targetDir)) {
-    console.log(chalk.red(`\n  \u2717 Directory "${slug}" already exists. Choose a different name or remove the existing directory.`));
-    return;
+    return fail(json, `Directory "${slug}" already exists. Choose a different name or remove it.`);
   }
 
-  const spinner = villageSpinner('Creating game project...').start();
+  const spinner = json ? null : villageSpinner('Creating game project...').start();
 
   try {
     createGameProject(targetDir, {
-      name: answers.name,
-      description: answers.description,
-      type: answers.type,
-      ageGroup: answers.ageGroup,
+      name: game.name,
+      description: game.description,
+      type: game.type,
+      ageGroup: game.ageGroup,
       orientation,
     });
 
-    spinner.text = 'Installing dependencies...';
+    if (spinner) spinner.text = 'Installing dependencies...';
+    execSync('npm install', { cwd: targetDir, stdio: 'pipe' });
+    if (spinner) spinner.succeed(`Game "${game.name}" created successfully!`);
 
-    execSync('npm install', {
-      cwd: targetDir,
-      stdio: 'pipe',
-    });
-
-    spinner.succeed(`Game "${answers.name}" created successfully!`);
+    if (json) {
+      console.log(
+        JSON.stringify({
+          ok: true,
+          slug,
+          dir: targetDir,
+          name: game.name,
+          type: game.type,
+          orientation,
+          ageGroup: game.ageGroup,
+          engine: 'threejs',
+        }),
+      );
+      return;
+    }
 
     console.log();
-    console.log(brand.green(`  \u2713 Game "${answers.name}" created successfully!`));
+    console.log(brand.green(`  ✓ Game "${game.name}" created successfully!`));
     console.log();
     console.log(brand.teal('  Next steps:'));
     console.log();
     console.log(`    ${brand.gold('cd')} ${slug}`);
-    console.log(`    ${brand.gold('npm install')}      ${brand.teal('- Install dependencies (already run for you; re-run after cloning)')}`);
     console.log(`    ${brand.gold('npm run dev')}      ${brand.teal('- Start development server')}`);
     console.log(`    ${brand.gold('npm run build')}    ${brand.teal('- Build for production')}`);
     console.log(`    ${brand.gold('myvillage deploy')} ${brand.teal('- Deploy to MyVillageOS')}`);
     console.log();
-    console.log(brand.teal(`  Game type: ${answers.type} | Orientation: ${orientation} | Age group: ${answers.ageGroup}`));
+    console.log(brand.teal(`  Game type: ${game.type} | Orientation: ${orientation} | Age group: ${game.ageGroup}`));
     console.log(brand.teal(`  Cover art: drop thumbnail.png / banner.png in ${slug}/assets/ before deploy.`));
     console.log();
   } catch (err) {
-    spinner.fail('Failed to create game project.');
-    console.error(chalk.red(`  ${err.message}`));
+    if (spinner) spinner.fail('Failed to create game project.');
+    fail(json, err.message);
   }
 }
 
 // ── Unity path ──
-
 async function createUnityGame(options = {}) {
-  // orientation is decided in the top-level wizard; default portrait for Unity.
-  const orientation = options.orientation || 'portrait';
+  const json = !!options.json;
+  const nonInteractive = json || !!options.yes || !!options.nonInteractive;
+  const orientation = normOrientation(options.orientation) || 'portrait';
+
+  const provided = {
+    name: options.name && String(options.name).trim() ? String(options.name).trim() : null,
+    description: options.description,
+    category: normCategory(options.category),
+    ageGroup: normAge(options.targetAge || options.ageGroup),
+  };
+  const needName = !provided.name;
+  const needCategory = !provided.category;
+  const needAge = !provided.ageGroup;
+  if (nonInteractive && (needName || needCategory || needAge)) {
+    const miss = [needName && '--name', needCategory && '--category', needAge && '--target-age']
+      .filter(Boolean)
+      .join(', ');
+    return fail(json, `Missing required option(s): ${miss}`);
+  }
 
-  const answers = await inquirer.prompt([
-    {
+  const prompts = [];
+  if (needName)
+    prompts.push({
       type: 'input',
       name: 'name',
       message: 'Game name:',
       default: 'My Unity Game',
-      validate: (input) => {
-        if (!input.trim()) return 'Game name is required.';
-        return true;
-      },
-    },
-    {
+      validate: (input) => (input.trim() ? true : 'Game name is required.'),
+    });
+  if (provided.description === undefined && !nonInteractive)
+    prompts.push({
       type: 'input',
       name: 'description',
       message: 'Game description:',
       default: 'A Unity game for MyVillageOS',
-    },
-    {
+    });
+  if (needCategory)
+    prompts.push({
       type: 'list',
       name: 'category',
       message: 'Game category:',
@@ -176,8 +271,9 @@ async function createUnityGame(options = {}) {
         { name: 'Puzzle', value: 'puzzle' },
         { name: 'Other', value: 'other' },
       ],
-    },
-    {
+    });
+  if (needAge)
+    prompts.push({
       type: 'list',
       name: 'ageGroup',
       message: 'Target age group:',
@@ -186,33 +282,58 @@ async function createUnityGame(options = {}) {
         { name: '6-12', value: '6-12' },
         { name: '13 and Over', value: '13-and-over' },
       ],
-    },
-  ]);
+    });
 
-  const slug = answers.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
-  const targetDir = resolve(process.cwd(), slug);
+  const answers = prompts.length ? await inquirer.prompt(prompts) : {};
+  const game = {
+    name: provided.name || answers.name,
+    description: provided.description ?? answers.description ?? 'A Unity game for MyVillageOS',
+    category: provided.category || answers.category,
+    ageGroup: provided.ageGroup || answers.ageGroup,
+  };
+
+  const slug = game.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+  const targetDir = resolve(options.dir ? resolve(options.dir) : process.cwd(), slug);
 
   if (existsSync(targetDir)) {
-    console.log(chalk.red(`\n  \u2717 Directory "${slug}" already exists.`));
-    return;
+    return fail(json, `Directory "${slug}" already exists.`);
   }
 
-  const spinner = villageSpinner('Creating Unity game project...').start();
+  const spinner = json ? null : villageSpinner('Creating Unity game project...').start();
 
   try {
     const scaffold = await createUnityGameProject(targetDir, {
-      name: answers.name,
-      description: answers.description,
-      type: answers.category,
-      ageGroup: answers.ageGroup,
+      name: game.name,
+      description: game.description,
+      type: game.category,
+      ageGroup: game.ageGroup,
       orientation,
       unityVersion: options.unityVersion,
     });
 
-    spinner.succeed(`Unity game "${answers.name}" created!`);
+    if (spinner) spinner.succeed(`Unity game "${game.name}" created!`);
+
+    if (json) {
+      console.log(
+        JSON.stringify({
+          ok: true,
+          slug,
+          dir: targetDir,
+          name: game.name,
+          category: game.category,
+          orientation,
+          ageGroup: game.ageGroup,
+          engine: 'unity',
+          unityVersion: scaffold.unityVersion,
+          sdkVersion: scaffold.sdkVersion,
+          sdkEmbedded: scaffold.sdkEmbedded,
+        }),
+      );
+      return;
+    }
 
     console.log();
-    console.log(brand.green(`  \u2713 Unity game "${answers.name}" created!`));
+    console.log(brand.green(`  ✓ Unity game "${game.name}" created!`));
     console.log(brand.teal(`     Unity: ${scaffold.unityVersion}`));
     console.log(brand.teal(`     GameKit SDK: ${scaffold.sdkVersion}${scaffold.sdkEmbedded ? ' (bundled — no git needed)' : ''}`));
     console.log(brand.teal(`     Orientation: ${orientation} (${orientation === 'landscape' ? 'web only' : 'muni mobile + web'})`));
@@ -220,31 +341,19 @@ async function createUnityGame(options = {}) {
     if (!scaffold.sdkEmbedded) {
       console.log(chalk.yellow('  ⚠ Could not download the GameKit SDK (offline?). The project falls back to a'));
       console.log(chalk.yellow('    git-URL dependency, so opening it in Unity will require git to be installed.'));
-      console.log(chalk.yellow('    Re-run this command with a network connection to bundle the SDK locally instead.'));
       console.log();
     }
     console.log(brand.teal('  Next steps:'));
     console.log();
-    console.log(`    1. ${brand.gold('Open this project in Unity Hub')} (Add \u2192 Add project from disk)`);
-    console.log(`    2. ${brand.teal('Click menu')} ${brand.gold('MyVillage \u2192 Create Starter Mission Scene')}`);
-    console.log(`    3. ${brand.teal('Press')} ${brand.gold('Play')} ${brand.teal('\u2014 your mission runs end-to-end in the editor')}`);
-    console.log(`    4. ${brand.teal('Edit')} ${brand.gold(`Assets/Scripts/${answers.name.replace(/[^a-zA-Z0-9]/g, '')}.cs`)} ${brand.teal('and iterate (hit Play again)')}`);
-    console.log();
-    console.log(brand.teal('  Ready to ship:'));
-    if (orientation === 'landscape') {
-      console.log(`    5. ${brand.teal('Build WebGL via')} ${brand.gold('File \u2192 Build Settings \u2192 WebGL \u2192 Build')} ${brand.teal('to')} ${brand.gold('builds/webgl/')}`);
-      console.log(`    6. ${brand.gold('cd ' + slug + ' && myvillage deploy --platform webgl')}`);
-    } else {
-      console.log(`    5. ${brand.teal('Build AssetBundle:')} ${brand.gold('MyVillage \u2192 Build Mission Bundle')} ${brand.teal('(into builds/ios or builds/android)')}`);
-      console.log(`    6. ${brand.gold('cd ' + slug + ' && myvillage deploy')} ${brand.teal('\u2014 ships every platform found in builds/')}`);
-      console.log(`       ${brand.teal('Optional: also build WebGL into builds/webgl/ to offer it on the web too.')}`);
-    }
+    console.log(`    1. ${brand.gold('Open this project in Unity Hub')} (Add → Add project from disk)`);
+    console.log(`    2. ${brand.teal('Click menu')} ${brand.gold('MyVillage → Create Starter Mission Scene')}`);
+    console.log(`    3. ${brand.teal('Press')} ${brand.gold('Play')} ${brand.teal('— your mission runs end-to-end in the editor')}`);
     console.log();
     console.log(brand.teal(`  Cover art: drop thumbnail.png / banner.png in ${slug}/assets/ before deploy.`));
     console.log(brand.teal(`  See ${slug}/README.md for the full developer guide.`));
     console.log();
   } catch (err) {
-    spinner.fail('Failed to create Unity game project.');
-    console.error(chalk.red(`  ${err.message}`));
+    if (spinner) spinner.fail('Failed to create Unity game project.');
+    fail(json, err.message);
   }
 }

package/src/commands/deploy.js

@@ -67,10 +67,23 @@ function saveVillages(dir, isUnity, villageIds) {
   }
 }
 
+// Non-interactive when driven by Studio / scripts (--json, --yes).
+function isNonInteractive(options = {}) {
+  return !!(options.json || options.yes || options.nonInteractive);
+}
+
 // Gather the submission's village visibility once per deploy. Returns an array
 // of village ids (possibly empty), or null if the developer aborted/failed —
-// the caller should stop the deploy in that case.
-async function gatherVillages(existingIds = []) {
+// the caller should stop the deploy in that case. A `--villages a,b,c` flag (or
+// non-interactive mode) skips the prompt.
+async function gatherVillages(existingIds = [], options = {}) {
+  if (options.villages !== undefined) {
+    return String(options.villages)
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+  if (isNonInteractive(options)) return existingIds; // keep prior selection, no prompt
   console.log();
   console.log(brand.teal('  Village visibility — who can see & play this game:'));
   const villageIds = await selectGameVillages(existingIds);
@@ -80,7 +93,7 @@ async function gatherVillages(existingIds = []) {
 // If the target game is currently PUBLISHED, a redeploy takes it offline and
 // sends the new build back through admin review. Confirm with the developer and
 // move it to DRAFT first. Returns true to proceed with the deploy, false to abort.
-async function confirmRedeployIfPublished(gameId) {
+async function confirmRedeployIfPublished(gameId, options = {}) {
   if (!gameId) return true; // brand-new game — nothing live to disturb
 
   let game;
@@ -93,23 +106,26 @@ async function confirmRedeployIfPublished(gameId) {
 
   if (!game || game.status !== 'PUBLISHED') return true;
 
-  console.log();
-  console.log(chalk.yellow(`  ! "${game.title}" is currently PUBLISHED (live).`));
-  console.log(brand.teal('    Redeploying takes it offline and sends the new build back through'));
-  console.log(brand.teal('    admin review before it can go live again.'));
-  console.log();
+  if (!isNonInteractive(options)) {
+    console.log();
+    console.log(chalk.yellow(`  ! "${game.title}" is currently PUBLISHED (live).`));
+    console.log(brand.teal('    Redeploying takes it offline and sends the new build back through'));
+    console.log(brand.teal('    admin review before it can go live again.'));
+    console.log();
 
-  const { confirm } = await inquirer.prompt([{
-    type: 'confirm',
-    name: 'confirm',
-    message: 'Take the live game offline and redeploy?',
-    default: false,
-  }]);
+    const { confirm } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Take the live game offline and redeploy?',
+      default: false,
+    }]);
 
-  if (!confirm) {
-    console.log(brand.teal('\n  Deploy cancelled — game is still live.\n'));
-    return false;
+    if (!confirm) {
+      console.log(brand.teal('\n  Deploy cancelled — game is still live.\n'));
+      return false;
+    }
   }
+  // Non-interactive (--yes/--json): proceed to unpublish without prompting.
 
   const spinner = villageSpinner('Taking game offline (returning to draft)...').start();
   try {
@@ -196,16 +212,22 @@ async function autoSubmitForReview(gameId, deployResult) {
 
 // ── Three.js deploy (existing flow) ──
 
-async function deployThreeJsGame(projectDir, pkg) {
+async function deployThreeJsGame(projectDir, pkg, options = {}) {
+  const json = !!options.json;
   // If this game is already live, confirm + unpublish before we rebuild/upload.
-  if (!(await confirmRedeployIfPublished(pkg.myvillage.gameId))) return;
+  if (!(await confirmRedeployIfPublished(pkg.myvillage.gameId, options))) return;
 
   // Village visibility is part of the submission — gather it up front (before
   // the build) so it travels in the deploy metadata.
-  const villageIds = await gatherVillages(pkg.myvillage.villages || []);
+  const villageIds = await gatherVillages(pkg.myvillage.villages || [], options);
   if (villageIds === null) return; // could not resolve villages — abort
 
-  const spinner = villageSpinner('Building game...').start();
+  const spinner = json ? null : villageSpinner('Building game...').start();
+
+  const failOut = (msg) => {
+    if (spinner) spinner.fail(msg);
+    else if (json) console.log(JSON.stringify({ ok: false, error: msg }));
+  };
 
   try {
     // Run production build
@@ -217,16 +239,16 @@ async function deployThreeJsGame(projectDir, pkg) {
     // Check that build output exists
     const distDir = join(projectDir, 'dist');
     if (!existsSync(distDir)) {
-      spinner.fail('Build completed but no dist/ directory found.');
+      failOut('Build completed but no dist/ directory found.');
       return;
     }
 
-    spinner.text = 'Packaging build artifacts...';
+    if (spinner) spinner.text = 'Packaging build artifacts...';
 
     const filePaths = collectFilePaths(distDir);
 
     if (filePaths.length === 0) {
-      spinner.fail('No files found in dist/ directory.');
+      failOut('No files found in dist/ directory.');
       return;
     }
 
@@ -254,7 +276,7 @@ async function deployThreeJsGame(projectDir, pkg) {
       formData.append('files', blob, relPath);
     }
 
-    spinner.text = 'Deploying to MyVillageOS...';
+    if (spinner) spinner.text = 'Deploying to MyVillageOS...';
 
     const gameIdOrNew = pkg.myvillage.gameId || 'new';
     const result = await deployGame(gameIdOrNew, formData);
@@ -265,7 +287,7 @@ async function deployThreeJsGame(projectDir, pkg) {
 
     const finalGameId = result.gameId || pkg.myvillage.gameId;
 
-    spinner.succeed('Upload complete!');
+    if (spinner) spinner.succeed('Upload complete!');
 
     saveVillages(projectDir, false, villageIds);
 
@@ -274,13 +296,27 @@ async function deployThreeJsGame(projectDir, pkg) {
     // DRAFT/REJECTED/SUBMITTED (only APPROVED/PUBLISHED lock it), so this works
     // for non-admin developers too — not just admins.
     if (finalGameId) {
-      await submitCoverArt(finalGameId, projectDir, pkg.myvillage);
+      await submitCoverArt(finalGameId, projectDir, pkg.myvillage, options);
     }
 
     // Safety net: promote to SUBMITTED if the deploy left the game in DRAFT.
     // (A normal deploy already submits, so this is usually a no-op.)
     const finalStatus = await autoSubmitForReview(finalGameId, result);
 
+    if (json) {
+      console.log(
+        JSON.stringify({
+          ok: true,
+          gameId: finalGameId || null,
+          slug: result.slug || null,
+          status: finalStatus,
+          title: metadata.title,
+          villageIds,
+        }),
+      );
+      return;
+    }
+
     console.log();
     if (finalStatus === 'SUBMITTED') {
       console.log(brand.green(`  \u2713 Game "${metadata.title}" submitted for review`));
@@ -295,18 +331,15 @@ async function deployThreeJsGame(projectDir, pkg) {
     console.log(brand.teal('  Run "myvillage status" to check the review status.'));
     console.log();
   } catch (err) {
-    if (err.response) {
-      const message = err.response.data?.error_description
-        || err.response.data?.error
-        || err.response.data?.message
-        || 'Unknown server error';
-      spinner.fail(`Deployment failed: ${message}`);
-    } else if (err.stderr) {
-      spinner.fail('Build failed.');
-      console.error(chalk.red(`  ${err.stderr.toString().trim()}`));
-    } else {
-      spinner.fail(`Deployment failed: ${err.message}`);
-    }
+    const message = err.response
+      ? err.response.data?.error_description ||
+        err.response.data?.error ||
+        err.response.data?.message ||
+        'Unknown server error'
+      : err.stderr
+        ? `Build failed: ${err.stderr.toString().trim()}`
+        : err.message;
+    failOut(`Deployment failed: ${message}`);
   }
 }
 
@@ -357,11 +390,11 @@ async function deployUnityGame(projectDir, mvConfig, options) {
   console.log(brand.teal(`  Deploying ${platformsToDeploy.length} platform(s): ${platformsToDeploy.join(', ')}`));
 
   // If this game is already live, confirm + unpublish before we upload new builds.
-  if (!(await confirmRedeployIfPublished(mvConfig.gameId))) return;
+  if (!(await confirmRedeployIfPublished(mvConfig.gameId, options))) return;
 
   // Village visibility is part of the submission — gather once for the whole
   // multi-platform deploy and thread it into every platform's metadata.
-  const villageIds = await gatherVillages(mvConfig.villages || []);
+  const villageIds = await gatherVillages(mvConfig.villages || [], options);
   if (villageIds === null) return; // could not resolve villages — abort
   console.log();
 
@@ -391,7 +424,7 @@ async function deployUnityGame(projectDir, mvConfig, options) {
   // DRAFT/REJECTED/SUBMITTED (only APPROVED/PUBLISHED lock it). Submit is kept
   // out of the per-platform loop so it runs once, after every platform is up.
   if (finalGameId) {
-    await submitCoverArt(finalGameId, projectDir, mvConfig);
+    await submitCoverArt(finalGameId, projectDir, mvConfig, options);
   }
 
   // Safety net: promote to SUBMITTED if a platform deploy left it in DRAFT.
@@ -618,39 +651,53 @@ function warnOnAspectMismatch(filePath, assetType, orientation) {
 // Cover art shipped with the submission. Uploads whatever's declared in
 // myvillage.assets first; only prompts for what's missing. A thumbnail is
 // required — without one the game card renders blank in muni and on the web.
-async function submitCoverArt(gameId, projectDir, config) {
+async function submitCoverArt(gameId, projectDir, config, options = {}) {
+  if (options.skipCoverArt) return;
   const orientation = config?.orientation || 'landscape';
   const declared = config?.assets || {};
+  const nonInteractive = isNonInteractive(options);
   console.log();
 
-  // 1. Thumbnail — declared, else prompt (required).
+  // An explicit --thumbnail/--banner path overrides whatever's declared.
+  const thumbSource = options.thumbnail
+    ? resolve(String(options.thumbnail))
+    : declared.thumbnail
+      ? resolve(projectDir, declared.thumbnail)
+      : null;
+  const bannerSource = options.banner
+    ? resolve(String(options.banner))
+    : declared.banner
+      ? resolve(projectDir, declared.banner)
+      : null;
+
+  // 1. Thumbnail — explicit/declared, else prompt (required) when interactive.
   let thumbUploaded = false;
-  if (declared.thumbnail) {
-    const p = resolve(projectDir, declared.thumbnail);
-    if (existsSync(p)) {
-      warnOnAspectMismatch(p, 'THUMBNAIL', orientation);
-      thumbUploaded = await uploadImageAsset(gameId, p, 'THUMBNAIL');
+  if (thumbSource) {
+    if (existsSync(thumbSource)) {
+      warnOnAspectMismatch(thumbSource, 'THUMBNAIL', orientation);
+      thumbUploaded = await uploadImageAsset(gameId, thumbSource, 'THUMBNAIL');
     } else {
-      console.log(chalk.yellow(`  ! Declared thumbnail not found: ${declared.thumbnail}`));
+      console.log(chalk.yellow(`  ! Thumbnail not found: ${thumbSource}`));
     }
   }
-  if (!thumbUploaded) {
+  if (!thumbUploaded && !nonInteractive) {
     thumbUploaded = await promptForImage(gameId, 'THUMBNAIL', orientation, { required: true });
+  } else if (!thumbUploaded && nonInteractive) {
+    console.log(chalk.yellow('  ! No thumbnail — add one with "myvillage game upload-thumbnail <file>".'));
   }
 
-  // 2. Banner — declared, else optional prompt.
+  // 2. Banner — explicit/declared, else optional prompt when interactive.
   let bannerHandled = false;
-  if (declared.banner) {
-    const p = resolve(projectDir, declared.banner);
-    if (existsSync(p)) {
-      warnOnAspectMismatch(p, 'BANNER', orientation);
-      await uploadImageAsset(gameId, p, 'BANNER');
+  if (bannerSource) {
+    if (existsSync(bannerSource)) {
+      warnOnAspectMismatch(bannerSource, 'BANNER', orientation);
+      await uploadImageAsset(gameId, bannerSource, 'BANNER');
       bannerHandled = true;
     } else {
-      console.log(chalk.yellow(`  ! Declared banner not found: ${declared.banner}`));
+      console.log(chalk.yellow(`  ! Banner not found: ${bannerSource}`));
     }
   }
-  if (!bannerHandled) {
+  if (!bannerHandled && !nonInteractive) {
     await promptForImage(gameId, 'BANNER', orientation, { required: false });
   }
 }

package/src/index.js

@@ -179,6 +179,16 @@ export function run() {
     .command('create-game')
     .description('Create a new game project with interactive wizard')
     .option('--unity-version <version>', 'Override the Unity Editor version for Unity scaffolds (e.g. 6000.0.76f1)')
+    .option('--name <name>', 'Game name (skips the prompt)')
+    .option('--description <text>', 'Game description')
+    .option('--engine <engine>', 'Engine: threejs | unity')
+    .option('--orientation <orientation>', 'portrait | landscape')
+    .option('--type <type>', 'Three.js type: quiz | exploration | narrative | custom')
+    .option('--category <category>', 'Unity category: education | action | adventure | puzzle | other')
+    .option('--target-age <age>', 'Target age: under-5 | 6-12 | 13-and-over')
+    .option('--dir <path>', 'Parent directory to scaffold into (defaults to cwd)')
+    .option('-y, --yes', 'Non-interactive: fail instead of prompting for missing options')
+    .option('--json', 'Output the result as JSON (implies non-interactive)')
     .action(createGameCommand);
 
   program
@@ -190,6 +200,12 @@ export function run() {
     .command('deploy')
     .description('Build and deploy your game to MyVillageOS')
     .option('-p, --platform <platform>', 'Target Unity platform (ios, android, webgl). Optional — defaults to deploying every platform found in builds/.')
+    .option('--villages <ids>', 'Comma-separated village ids for visibility (skips the prompt)')
+    .option('--thumbnail <path>', 'Path to a thumbnail image (skips the prompt)')
+    .option('--banner <path>', 'Path to a banner image (skips the prompt)')
+    .option('--skip-cover-art', 'Skip cover-art upload entirely')
+    .option('-y, --yes', 'Non-interactive: assume yes (e.g. unpublish-to-redeploy) and skip prompts')
+    .option('--json', 'Output the result as JSON (implies non-interactive)')
     .action((options) => deployCommand(options));
 
   program