@aiwg/cli 2026.8.20 → 2026.8.25

package/dist/src/cli/handlers/artifact-verify.js

@@ -102,6 +102,9 @@ export const artifactVerifyHandler = {
     description: 'Verify cross-asset DSSE provenance and manage trust roots',
     category: 'utility',
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage() };
+    },
     async execute(ctx) {
         if (ctx.args.includes('--help') || ctx.args.includes('-h') || ctx.args.length === 0)
             return { exitCode: 0, message: usage() };

package/dist/src/cli/handlers/refresh.js

@@ -10,7 +10,7 @@
  *
  * @implements @agentic/code/frameworks/sdlc-complete/rules/self-maintenance.md
  * @source @src/cli/router.ts
- * @issue #482, #557, #694
+ * @issue #173, #174, #482, #557, #694
  */
 import { promises as fs } from 'fs';
 import path from 'path';
@@ -151,6 +151,30 @@ export function collectModelDeployArgs(args) {
     }
     return forwarded;
 }
+const REFRESH_HELP = `Usage: aiwg refresh [options]
+
+Update AIWG, re-deploy installed frameworks, and run health verification.
+
+Options:
+  --dry-run                 Preview changes without updating or deploying
+  --quiet                   Suppress progress output
+  --skip-update             Skip the installation update
+  --packages-only           Refresh remote packages only
+  --provider <name>         Override provider auto-detection
+  --channel <name>          Select the update channel (stable or main)
+  --frameworks <list>       Re-deploy a comma-separated installed subset
+  --model <name>            Override all deployed agent model tiers
+  --reasoning-model <name>  Override the reasoning model tier
+  --coding-model <name>     Override the coding model tier
+  --efficiency-model <name> Override the efficiency model tier
+  --filter <pattern>        Limit model deployment by agent name
+  --filter-role <role>      Limit model deployment by role
+  --model-tier <tier>       Limit model deployment by tier
+  --save                    Save model overrides to the project
+  --save-user               Save model overrides to user configuration
+  -h, --help                Show this help without running refresh
+
+Alias: aiwg sync (deprecated)`;
 /**
  * Refresh command handler (formerly sync)
  */
@@ -160,6 +184,9 @@ export const refreshHandler = {
     description: 'Refresh AIWG to latest version and re-deploy installed frameworks',
     category: 'maintenance',
     aliases: ['--refresh', 'sync', '--sync'],
+    async help() {
+        return { exitCode: 0, message: REFRESH_HELP, rawOutput: true };
+    },
     async execute(ctx) {
         const dryRun = hasFlag(ctx.args, '--dry-run');
         const quiet = hasFlag(ctx.args, '--quiet');
@@ -451,6 +478,10 @@ export const refreshHandler = {
             if (dryRun) {
                 ui.info('Dry run complete — no changes made');
             }
+            else if (updateFailure) {
+                ui.warn(`Refresh completed with installation update failure (exit ${updateFailure.exitCode}); ` +
+                    're-deployment continued, but AIWG may still be on the previous version.');
+            }
             else {
                 ui.success('Refresh complete');
             }
@@ -459,7 +490,11 @@ export const refreshHandler = {
         // Quiet mode: JSON output
         if (quiet) {
             const output = JSON.stringify({
-                status: dryRun ? 'dry-run' : 'refreshed',
+                status: dryRun
+                    ? 'dry-run'
+                    : updateFailure
+                        ? 'refreshed-with-update-failure'
+                        : 'refreshed',
                 provider: detectedProvider,
                 frameworks,
                 skipUpdate,

package/dist/src/cli/handlers/subcommands.js

@@ -1139,34 +1139,40 @@ export const pluginStatusHandler = {
  *
  * Delegates to tools/plugin/package-plugins.mjs
  */
+function packagePluginHelp() {
+    return {
+        exitCode: 0,
+        message: [
+            "aiwg package-plugin — package a project-local or built-in marketplace wrapper",
+            "",
+            "Usage:",
+            "  aiwg package-plugin <name> [--source <path>] [--output <path>] [--provider <name>] [--clean] [--dry-run]",
+            "  aiwg package-plugin --plugin <name> [options]  # compatibility form",
+            "",
+            "Options:",
+            "  --source <path>    explicit project-local wrapper source (must stay inside the project)",
+            "  --output <path>    standalone archive output (default: dist/plugins)",
+            "  --provider <name>  claude, codex, or all for standalone wrappers; built-ins retain all formats",
+            "  --clean            clean generated plugin output before packaging",
+            "  --dry-run, -n      preview without writing",
+            "  --help, -h         show this help",
+            "",
+            "Project-local wrappers are discovered under .aiwg/plugins and packaged as deterministic archives.",
+        ].join("\n"),
+    };
+}
 export const packagePluginHandler = {
     id: "package-plugin",
     name: "Package Plugin",
     description: "Package a plugin for distribution",
     category: "plugin",
     aliases: ["-package-plugin", "--package-plugin"],
+    async help() {
+        return packagePluginHelp();
+    },
     async execute(ctx) {
         if (ctx.args.includes("--help") || ctx.args.includes("-h")) {
-            return {
-                exitCode: 0,
-                message: [
-                    "aiwg package-plugin — package a project-local or built-in marketplace wrapper",
-                    "",
-                    "Usage:",
-                    "  aiwg package-plugin <name> [--source <path>] [--output <path>] [--provider <name>] [--clean] [--dry-run]",
-                    "  aiwg package-plugin --plugin <name> [options]  # compatibility form",
-                    "",
-                    "Options:",
-                    "  --source <path>    explicit project-local wrapper source (must stay inside the project)",
-                    "  --output <path>    standalone archive output (default: dist/plugins)",
-                    "  --provider <name>  claude, codex, or all for standalone wrappers; built-ins retain all formats",
-                    "  --clean            clean generated plugin output before packaging",
-                    "  --dry-run, -n      preview without writing",
-                    "  --help, -h         show this help",
-                    "",
-                    "Project-local wrappers are discovered under .aiwg/plugins and packaged as deterministic archives.",
-                ].join("\n"),
-            };
+            return packagePluginHelp();
         }
         const hasExplicitPlugin = ctx.args.includes("--plugin") || ctx.args.includes("-p");
         const positional = ctx.args[0] && !ctx.args[0].startsWith("-")

package/dist/src/cli/handlers/utilities.js

@@ -466,6 +466,9 @@ export const doctorHandler = {
     description: 'Run health diagnostics',
     category: 'maintenance',
     aliases: ['-doctor', '--doctor'],
+    async help() {
+        return { exitCode: 0, message: DOCTOR_HELP, rawOutput: true };
+    },
     async execute(ctx) {
         if (ctx.args.includes('--help') || ctx.args.includes('-h')) {
             return { exitCode: 0, message: DOCTOR_HELP, rawOutput: true };

package/dist/src/cli/router.js

@@ -10,6 +10,7 @@
  * @tests @test/unit/cli/router.test.ts
  * @issue #33
  * @issue #58
+ * @issue #174
  */
 import { loadRegistry } from '../extensions/loader.js';
 import { getFrameworkRoot } from '../channel/manager.mjs';
@@ -134,6 +135,32 @@ export async function run(args, options = {}) {
         ui.error(`No handler found for command: ${commandId}`);
         process.exit(1);
     }
+    // Help must be intercepted before hooks and the normal handler path. Some
+    // commands mutate project or installation state, so passing an unrecognised
+    // help flag through to execute() is unsafe (#174).
+    if (commandArgs.includes('--help') || commandArgs.includes('-h')) {
+        const ctx = await buildContext(commandArgs, args, options);
+        if (handler.help) {
+            const result = await handler.help(ctx);
+            if (result.message) {
+                if (result.rawOutput) {
+                    process.stdout.write(result.message.endsWith('\n') ? result.message : `${result.message}\n`);
+                }
+                else if (result.exitCode !== 0) {
+                    ui.error(result.message);
+                }
+                else {
+                    ui.info(result.message);
+                }
+            }
+            if (result.exitCode !== 0)
+                process.exit(result.exitCode);
+        }
+        else {
+            ui.info(`No detailed help for \`aiwg ${commandId}\`. Run \`aiwg help\` for the command overview.`);
+        }
+        return;
+    }
     // Build context for handler and hooks
     const ctx = await buildContext(commandArgs, args, options);
     // Build hook context

package/dist/src/installation/manager-command.mjs

@@ -21,11 +21,20 @@ export function resolveManagerCommand(file, args, options = {}) {
   return {
     file: commandInterpreter,
     args: ['/d', '/s', '/c', command],
+    // The payload above already contains cmd.exe-native quoting. Instruct
+    // Node not to apply MSVCRT escaping to those embedded quotes (#173).
+    windowsVerbatimArguments: true,
   };
 }
 
 export function executeManagerCommand(file, args, options = {}) {
   const invocation = resolveManagerCommand(file, args, options);
   const execute = options.execute ?? execFileSync;
-  return execute(invocation.file, invocation.args, options.execOptions ?? { stdio: 'inherit' });
+  const execOptions = options.execOptions
+    ? { ...options.execOptions }
+    : { stdio: 'inherit' };
+  if (invocation.windowsVerbatimArguments === true) {
+    execOptions.windowsVerbatimArguments = true;
+  }
+  return execute(invocation.file, invocation.args, execOptions);
 }

package/dist/src/update/service.mjs

@@ -6,7 +6,6 @@
  * the calling handlers.
  */
 
-import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { getPackageRoot, loadConfig } from '../channel/manager.mjs';
@@ -16,7 +15,7 @@ import {
   loadInstallationIdentity,
   saveInstallationIdentity,
 } from '../installation/manager.mjs';
-import { resolveManagerCommand } from '../installation/manager-command.mjs';
+import { executeManagerCommand } from '../installation/manager-command.mjs';
 
 const VALID_MODES = new Set(['npm', 'web', 'source']);
 
@@ -149,9 +148,7 @@ export async function updateInstallation(options = {}) {
     throw new Error('Canonical npm installation has no package-manager executable. Run `aiwg installation adopt --manager <absolute-path-to-npm>`.');
   }
   if (!dryRun) {
-    const invocation = resolveManagerCommand(managerExecutable, command, options);
-    const execute = options.execute ?? ((file, args) => execFileSync(file, args, { stdio: 'inherit' }));
-    execute(invocation.file, invocation.args);
+    executeManagerCommand(managerExecutable, command, options);
     if (detected.identity && detected.identityPersistent && options.persistIdentity !== false) {
       saveInstallationIdentity({ ...detected.identity, channel }, options);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.20",
+  "version": "2026.8.25",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",