@agentled/cli 0.1.6 → 0.5.0

package/dist/commands/schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agentled schema` — fetch the canonical PipelineStep field schema from the
+ * live API (`GET /api/external/workflows/step-schema`).
+ *
+ * Wraps the existing `get_step_schema` MCP tool so the CLI-driven agent has
+ * a no-MCP way to look up "what fields are valid on an appAction step?" or
+ * "what's the minimal JSON for an aiAction?" before writing a pipeline.
+ */
+import { Command } from 'commander';
+export declare function registerSchemaCommand(program: Command): void;

package/dist/commands/schema.js

@@ -0,0 +1,107 @@
+/* eslint-disable no-console */
+import { AgentledClient } from '../client.js';
+import { printOutput, printError } from '../utils/output.js';
+import { BASE_FIELD_KEYS, CONTEXT_FIELD_TYPES, CONTEXT_FIELD_TYPE_ALIASES, } from '../context-schema.js';
+function filterByStepType(schema, stepType) {
+    const groups = schema.groups
+        .map(g => ({
+        ...g,
+        fields: g.fields.filter(f => !f.stepTypes || f.stepTypes.includes(stepType)),
+    }))
+        .filter(g => g.fields.length > 0);
+    const fieldCount = groups.reduce((n, g) => n + g.fields.length, 0);
+    return { ...schema, groups, fieldCount };
+}
+function renderTable(schema) {
+    const lines = [];
+    lines.push(schema.description);
+    lines.push(`(${schema.fieldCount} fields in ${schema.groups.length} categories)`);
+    lines.push('');
+    for (const g of schema.groups) {
+        lines.push(`## ${g.category}`);
+        lines.push(`  ${g.description}`);
+        for (const f of g.fields) {
+            const req = f.required ? ' *' : '';
+            const types = f.stepTypes ? ` [${f.stepTypes.join(', ')}]` : '';
+            lines.push(`    - ${f.name}${req}: ${f.type}${types}`);
+            lines.push(`      ${f.description}`);
+            if (f.example)
+                lines.push(`      example: ${f.example}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function buildContextSchema() {
+    return {
+        description: 'Valid field types for pipeline.context input pages (`executionInputConfig.fields[]`, ' +
+            '`inputPages[].configuration.fields[]`). Unknown `type` values fall back to a plain text ' +
+            'input at render time but lose type-aware validation and pickers.',
+        scope: 'context',
+        baseKeys: [...BASE_FIELD_KEYS],
+        fieldTypes: CONTEXT_FIELD_TYPES,
+        aliases: { ...CONTEXT_FIELD_TYPE_ALIASES },
+    };
+}
+function renderContextTable(schema) {
+    const lines = [];
+    lines.push(schema.description);
+    lines.push(`(${schema.fieldTypes.length} valid field types)`);
+    lines.push('');
+    lines.push(`Base keys (every field): ${schema.baseKeys.join(', ')}`);
+    lines.push('');
+    lines.push('Field types:');
+    for (const t of schema.fieldTypes) {
+        const extras = t.extraKeys?.length ? ` [+ ${t.extraKeys.join(', ')}]` : '';
+        lines.push(`  - ${t.value}${extras}`);
+        lines.push(`      ${t.description}`);
+        if (t.example) {
+            lines.push(`      example: ${JSON.stringify(t.example)}`);
+        }
+    }
+    const aliasEntries = Object.entries(schema.aliases);
+    if (aliasEntries.length > 0) {
+        lines.push('');
+        lines.push('Legacy aliases (accepted but prefer the canonical name):');
+        for (const [alias, canonical] of aliasEntries) {
+            lines.push(`  - ${alias} → ${canonical}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function registerSchemaCommand(program) {
+    program
+        .command('schema')
+        .description('Show the canonical PipelineStep field schema, or the context/input-page field schema with --context.')
+        .option('--step-type <type>', 'Filter fields applicable to this step type (trigger, appAction, aiAction, code, …)')
+        .option('--context', 'Show the context / input-page field schema (pipeline.context.*.fields[].type) instead of the step schema')
+        .option('--format <format>', 'Output format: json (default), table, minimal', 'json')
+        .action(async (opts) => {
+        try {
+            const format = opts.format;
+            if (opts.context) {
+                const ctx = buildContextSchema();
+                if (format === 'table' || format === 'minimal') {
+                    console.log(renderContextTable(ctx));
+                }
+                else {
+                    printOutput(ctx, format);
+                }
+                return;
+            }
+            const client = new AgentledClient();
+            const schema = await client.getStepSchema();
+            const filtered = opts.stepType ? filterByStepType(schema, opts.stepType) : schema;
+            if (format === 'table' || format === 'minimal') {
+                console.log(renderTable(filtered));
+            }
+            else {
+                printOutput(filtered, format);
+            }
+        }
+        catch (e) {
+            printError(e.message);
+        }
+    });
+}
+//# sourceMappingURL=schema.js.map

package/dist/commands/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/commands/schema.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAY/B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAgB,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,mBAAmB,EACnB,0BAA0B,GAE7B,MAAM,sBAAsB,CAAC;AAqB9B,SAAS,gBAAgB,CAAC,MAAsB,EAAE,QAAgB;IAC9D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM;SACvB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACP,GAAG,CAAC;QACJ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;KAC/E,CAAC,CAAC;SACF,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACnE,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAC7C,CAAC;AAED,SAAS,WAAW,CAAC,MAAsB;IACvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC/B,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,cAAc,MAAM,CAAC,MAAM,CAAC,MAAM,cAAc,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;YACvB,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC;YACvD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YACrC,IAAI,CAAC,CAAC,OAAO;gBAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAUD,SAAS,kBAAkB;IACvB,OAAO;QACH,WAAW,EACP,uFAAuF;YACvF,0FAA0F;YAC1F,kEAAkE;QACtE,KAAK,EAAE,SAAS;QAChB,QAAQ,EAAE,CAAC,GAAG,eAAe,CAAC;QAC9B,UAAU,EAAE,mBAAmB;QAC/B,OAAO,EAAE,EAAE,GAAG,0BAA0B,EAAE;KAC7C,CAAC;AACN,CAAC;AAED,SAAS,kBAAkB,CAAC,MAA6B;IACrD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC/B,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,qBAAqB,CAAC,CAAC;IAC9D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,4BAA4B,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACZ,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9D,CAAC;IACL,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;QACvE,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,YAAY,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,MAAM,SAAS,EAAE,CAAC,CAAC;QAC9C,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IAClD,OAAO;SACF,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,sGAAsG,CAAC;SACnH,MAAM,CAAC,oBAAoB,EAAE,oFAAoF,CAAC;SAClH,MAAM,CAAC,WAAW,EAAE,0GAA0G,CAAC;SAC/H,MAAM,CAAC,mBAAmB,EAAE,+CAA+C,EAAE,MAAM,CAAC;SACpF,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACnB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAsB,CAAC;YAE3C,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAC;gBACjC,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBAC7C,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;gBACzC,CAAC;qBAAM,CAAC;oBACJ,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAC7B,CAAC;gBACD,OAAO;YACX,CAAC;YAED,MAAM,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,EAAoB,CAAC;YAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAElF,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC7C,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;YACvC,CAAC;iBAAM,CAAC;gBACJ,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAClC,CAAC;QACL,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YACd,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;IACL,CAAC,CAAC,CAAC;AACX,CAAC"}

package/dist/commands/skills.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agentled skills` — manage the Claude Code skill bundled with the CLI.
+ *
+ * Matches the old `npx @agentled/mcp-server --setup-skills` flow but surfaces
+ * it as a first-class CLI verb so users can refresh skills after the CLI
+ * itself is updated.
+ */
+import { Command } from 'commander';
+export declare function registerSkillsCommands(program: Command): void;

package/dist/commands/skills.js

@@ -0,0 +1,94 @@
+/* eslint-disable no-console */
+import { describeSkillsInstall, getSkillsTargetDir, installSkills, resolveBundledSkillsDir, } from '../utils/skills.js';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function parseSkillVersion(skillMdPath) {
+    try {
+        const content = readFileSync(skillMdPath, 'utf-8');
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            return null;
+        const versionMatch = fmMatch[1].match(/^version:\s*(.+)$/m);
+        return versionMatch ? versionMatch[1].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function registerSkillsCommands(program) {
+    const skills = program
+        .command('skills')
+        .description('Manage Claude Code skills bundled with the CLI');
+    skills
+        .command('install')
+        .description('Install the bundled Agentled skill into ~/.claude/skills (global by default)')
+        .option('--project', 'Install into the current project\'s .claude/skills/ instead of the user-global location')
+        .option('--force', 'Overwrite existing skill files even if they contain local edits')
+        .action((opts) => {
+        try {
+            const isGlobal = !opts.project;
+            const targetDir = getSkillsTargetDir(isGlobal);
+            const results = installSkills({ global: isGlobal, force: opts.force });
+            console.log(describeSkillsInstall(results, targetDir));
+        }
+        catch (e) {
+            console.error(`Error: ${e.message}`);
+            process.exit(1);
+        }
+    });
+    skills
+        .command('update')
+        .description('Refresh the installed skill to the version bundled with this CLI')
+        .option('--project', 'Update the project-level skill (default: user-global)')
+        .option('--force', 'Overwrite even if the installed skill has local edits')
+        .action((opts) => {
+        try {
+            const isGlobal = !opts.project;
+            const targetDir = getSkillsTargetDir(isGlobal);
+            const results = installSkills({ global: isGlobal, force: opts.force });
+            console.log(describeSkillsInstall(results, targetDir));
+        }
+        catch (e) {
+            console.error(`Error: ${e.message}`);
+            process.exit(1);
+        }
+    });
+    skills
+        .command('status')
+        .description('Show bundled vs installed skill versions')
+        .option('--project', 'Check the project-level skills (default: user-global)')
+        .action((opts) => {
+        const isGlobal = !opts.project;
+        const targetDir = getSkillsTargetDir(isGlobal);
+        const sourceDir = resolveBundledSkillsDir();
+        if (!existsSync(sourceDir)) {
+            console.log(`No bundled skills found (${sourceDir}). Reinstall @agentled/cli.`);
+            return;
+        }
+        const bundled = readdirSync(sourceDir, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name);
+        if (bundled.length === 0) {
+            console.log('No skills bundled with this CLI version.');
+            return;
+        }
+        for (const name of bundled) {
+            const bundledVersion = parseSkillVersion(join(sourceDir, name, 'SKILL.md')) ?? '?';
+            const installedSkillMd = join(targetDir, name, 'SKILL.md');
+            const installedVersion = existsSync(installedSkillMd)
+                ? (parseSkillVersion(installedSkillMd) ?? 'unknown')
+                : null;
+            if (installedVersion === null) {
+                console.log(`  ${name}: bundled v${bundledVersion}, not installed`);
+            }
+            else if (installedVersion === bundledVersion) {
+                console.log(`  ${name}: bundled v${bundledVersion}, installed v${installedVersion} (up to date)`);
+            }
+            else {
+                console.log(`  ${name}: bundled v${bundledVersion}, installed v${installedVersion}`);
+            }
+        }
+        console.log(`\nSkills directory: ${targetDir}`);
+    });
+}
+//# sourceMappingURL=skills.js.map

package/dist/commands/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"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"}

package/dist/commands/tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agentled tools builtins` — list the builtin tools accepted by
+ * `aiActionWithTools` steps (`tools[].builtinType` values).
+ *
+ * The canonical source is the `Tool.builtinType` union in
+ * `shared/types/pipeline/PipelineTypes.ts`; the CLI ships a mirror at
+ * `src/builtin-tools-catalog.ts` (drift-tested).
+ */
+import { Command } from 'commander';
+export declare function registerToolsCommands(program: Command): void;

package/dist/commands/tools.js

@@ -0,0 +1,53 @@
+/* eslint-disable no-console */
+import { BUILTIN_TOOLS_CATALOG } from '../builtin-tools-catalog.js';
+import { printOutput } from '../utils/output.js';
+function renderTable() {
+    const lines = [];
+    lines.push(`Builtin tools for \`aiActionWithTools\` steps (${BUILTIN_TOOLS_CATALOG.length} total):`);
+    lines.push('');
+    for (const t of BUILTIN_TOOLS_CATALOG) {
+        const providers = t.providers.join(', ');
+        const credits = t.typicalCreditsPerCall ? ` (~${t.typicalCreditsPerCall} credits/call)` : '';
+        lines.push(`  - ${t.value} [providers: ${providers}]${credits}`);
+        lines.push(`      ${t.description}`);
+        if (t.extraKeys?.length) {
+            lines.push(`      extra keys: ${t.extraKeys.join(', ')}`);
+        }
+        lines.push(`      example: ${JSON.stringify(t.example)}`);
+    }
+    lines.push('');
+    lines.push('Usage on a step:');
+    lines.push('  {');
+    lines.push('    "id": "analyze",');
+    lines.push('    "type": "aiActionWithTools",');
+    lines.push('    "name": "Analyze with tools",');
+    lines.push('    "tools": [');
+    lines.push('      { "type": "builtin", "name": "web_search", "builtinType": "web_search" },');
+    lines.push('      { "type": "builtin", "name": "workspace_memory", "builtinType": "workspace_memory" }');
+    lines.push('    ],');
+    lines.push('    "pipelineStepPrompt": { "template": "…", "responseStructure": { … } },');
+    lines.push('    "creditCost": 10,');
+    lines.push('    "next": { "stepId": "…" }');
+    lines.push('  }');
+    lines.push('');
+    lines.push('Scaffold: `agentled workflows scaffold ai-with-tools`');
+    return lines.join('\n');
+}
+export function registerToolsCommands(program) {
+    const tools = program
+        .command('tools')
+        .description('Discover runtime tools (e.g. builtin tools for aiActionWithTools).');
+    tools
+        .command('builtins')
+        .description('List builtin tools (`tools[].builtinType`) accepted by aiActionWithTools steps.')
+        .option('--format <format>', 'Output format: table (default), json', 'table')
+        .action((opts) => {
+        const format = opts.format;
+        if (format === 'json' || format === 'minimal') {
+            printOutput({ builtinTools: BUILTIN_TOOLS_CATALOG }, format);
+            return;
+        }
+        console.log(renderTable());
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/commands/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/commands/tools.ts"],"names":[],"mappings":"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"}

package/dist/commands/workflows.js

@@ -1,11 +1,97 @@
+/* eslint-disable no-console */
 import { AgentledClient } from '../client.js';
 import { printOutput, printError } from '../utils/output.js';
+import { preflightPipeline, formatPreflightIssue } from '../utils/preflight.js';
+import { registerScaffoldCommand } from './scaffold.js';
 import * as fs from 'node:fs';
+/**
+ * Exit code used when a workflow is created/updated but server-side validation
+ * reports errors. Distinct from `1` (user/network error) so CI pipelines can
+ * detect "the pipeline JSON is broken" vs "the CLI itself failed".
+ */
+const VALIDATION_EXIT_CODE = 2;
+function formatIssueLine(issue) {
+    const scope = issue.stepId ? `[${issue.stepId}] ` : '';
+    const code = issue.code ? ` (${issue.code})` : '';
+    const msg = typeof issue.message === 'string' ? issue.message : JSON.stringify(issue);
+    const fix = issue.suggestedFix ? `\n      fix: ${issue.suggestedFix}` : '';
+    return `    - ${scope}${msg}${code}${fix}`;
+}
+/**
+ * Calls validate_workflow on a freshly created/updated workflow. Returns a
+ * tagged outcome instead of a boolean so callers can distinguish "broken
+ * pipeline" (exit 2) from "CLI/network failure" (exit 1).
+ *
+ * In pretty formats this function prints the human-readable report directly.
+ * In JSON format it is silent — the caller is responsible for emitting the
+ * combined envelope so fields from the create/update mutation response
+ * (name, pathname, status, workspaceId, …) are preserved for script consumers.
+ *
+ * When called from `workflows create`, the caller sets `createdId` so the
+ * fix-flow hint can tell the user how to clean up.
+ */
+async function runAutoValidate(client, workflowId, opts) {
+    let result;
+    try {
+        result = await client.validateWorkflow(workflowId);
+    }
+    catch (e) {
+        // The workflow was saved; only the post-hoc validate call failed.
+        // Surface as a structured warning but do not treat it as a pipeline
+        // defect — callers map this outcome to exit code 1, not 2.
+        console.error(`\nValidation request failed: ${e.message}`);
+        console.error(`  The workflow was saved as ${workflowId}, but we could not validate it automatically.`);
+        console.error(`  Run: agentled workflows validate ${workflowId}`);
+        return { status: 'request-failed' };
+    }
+    if (opts.format !== 'json') {
+        const errorCount = result.errors?.length ?? 0;
+        const warnCount = result.warnings?.length ?? 0;
+        if (errorCount === 0 && warnCount === 0) {
+            console.log(`  ✓ Validated (0 errors, 0 warnings) — ${workflowId}`);
+        }
+        else {
+            if (errorCount > 0) {
+                console.error(`\n  ✗ Validation failed: ${errorCount} error${errorCount === 1 ? '' : 's'}`);
+                for (const e of result.errors)
+                    console.error(formatIssueLine(e));
+            }
+            if (warnCount > 0) {
+                console.log(`\n  ⚠ ${warnCount} warning${warnCount === 1 ? '' : 's'}`);
+                for (const w of result.warnings)
+                    console.log(formatIssueLine(w));
+            }
+        }
+    }
+    if (!result.valid) {
+        const id = opts.createdId ?? workflowId;
+        console.error(`\n  Workflow ${id} was saved but is broken. Fix flow:`);
+        console.error(`    1. agentled workflows export ${id} --output pipeline.json`);
+        console.error(`    2. edit pipeline.json (use \`agentled workflows scaffold <pattern>\` or \`agentled examples <pattern>\` for reference)`);
+        console.error(`    3. agentled workflows validate --file pipeline.json   # local preflight, no API call`);
+        console.error(`    4. agentled workflows update ${id} --file pipeline.json`);
+        console.error(`    (or) agentled workflows delete ${id}`);
+    }
+    return { status: result.valid ? 'valid' : 'invalid', result };
+}
+/**
+ * Map a ValidateOutcome to its CLI exit code. `valid` returns 0 (caller does
+ * not exit), `invalid` returns 2 (pipeline broken), `request-failed` returns
+ * 1 (CLI/network problem).
+ */
+function exitCodeForOutcome(outcome) {
+    if (outcome.status === 'valid')
+        return 0;
+    if (outcome.status === 'invalid')
+        return VALIDATION_EXIT_CODE;
+    return 1;
+}
 export function registerWorkflowCommands(program) {
     const workflows = program
         .command('workflows')
         .alias('wf')
         .description('Manage workflows');
+    registerScaffoldCommand(workflows);
     workflows
         .command('list')
         .description('List all workflows in the workspace')
@@ -41,11 +127,12 @@ export function registerWorkflowCommands(program) {
     });
     workflows
         .command('create')
-        .description('Create a new workflow from pipeline JSON')
+        .description('Create a new workflow from pipeline JSON (auto-validates unless --skip-validate)')
         .option('--file <path>', 'Path to pipeline JSON file')
         .option('--pipeline <json>', 'Inline pipeline JSON')
         .option('--locale <locale>', 'Locale (default: en)')
         .option('--format <fmt>', 'Output format', 'json')
+        .option('--skip-validate', 'Skip the post-create validate call (advanced — legacy raw create behavior)')
         .action(async (opts) => {
         try {
             let pipeline;
@@ -61,8 +148,40 @@ export function registerWorkflowCommands(program) {
                 return;
             }
             const client = new AgentledClient();
+            const format = (opts.format ?? 'json');
             const result = await client.createWorkflow(pipeline, opts.locale);
-            printOutput(result, opts.format);
+            const workflowId = (result?.id ?? result?.workflow?.id);
+            if (opts.skipValidate || !workflowId) {
+                printOutput(result, format);
+                return;
+            }
+            if (format === 'json') {
+                // Compound envelope: preserve every field from the create
+                // mutation response (name, pathname, status, workspaceId, …)
+                // AND include the validation report. Scripts that parse
+                // top-level fields continue to work.
+                const outcome = await runAutoValidate(client, workflowId, {
+                    format,
+                    createdId: workflowId,
+                });
+                const validation = outcome.status === 'request-failed'
+                    ? { requestFailed: true }
+                    : outcome.result;
+                printOutput({ ...result, validation }, 'json');
+                const code = exitCodeForOutcome(outcome);
+                if (code !== 0)
+                    process.exit(code);
+                return;
+            }
+            // Pretty-print formats: emit the create response first, then validation.
+            printOutput(result, format);
+            const outcome = await runAutoValidate(client, workflowId, {
+                format,
+                createdId: workflowId,
+            });
+            const code = exitCodeForOutcome(outcome);
+            if (code !== 0)
+                process.exit(code);
         }
         catch (e) {
             printError(e.message);
@@ -70,11 +189,12 @@ export function registerWorkflowCommands(program) {
     });
     workflows
         .command('update <id>')
-        .description('Update an existing workflow (partial update)')
+        .description('Update an existing workflow (auto-validates unless --skip-validate)')
         .option('--file <path>', 'Path to updates JSON file')
         .option('--updates <json>', 'Inline updates JSON')
         .option('--locale <locale>', 'Locale')
         .option('--format <fmt>', 'Output format', 'json')
+        .option('--skip-validate', 'Skip the post-update validate call (advanced)')
         .action(async (id, opts) => {
         try {
             let updates;
@@ -90,8 +210,34 @@ export function registerWorkflowCommands(program) {
                 return;
             }
             const client = new AgentledClient();
+            const format = (opts.format ?? 'json');
             const result = await client.updateWorkflow(id, updates, opts.locale);
-            printOutput(result, opts.format);
+            if (opts.skipValidate) {
+                printOutput(result, format);
+                return;
+            }
+            if (format === 'json') {
+                // Preserve the update mutation response fields in the JSON
+                // envelope — `result` may contain the refreshed workflow
+                // record, which script consumers parse.
+                const outcome = await runAutoValidate(client, id, { format });
+                const validation = outcome.status === 'request-failed'
+                    ? { requestFailed: true }
+                    : outcome.result;
+                const envelope = result && typeof result === 'object'
+                    ? { ...result, validation }
+                    : { workflowId: id, validation };
+                printOutput(envelope, 'json');
+                const code = exitCodeForOutcome(outcome);
+                if (code !== 0)
+                    process.exit(code);
+                return;
+            }
+            printOutput(result, format);
+            const outcome = await runAutoValidate(client, id, { format });
+            const code = exitCodeForOutcome(outcome);
+            if (code !== 0)
+                process.exit(code);
         }
         catch (e) {
             printError(e.message);
@@ -112,16 +258,88 @@ export function registerWorkflowCommands(program) {
         }
     });
     workflows
-        .command('validate <id>')
-        .description('Validate workflow pipeline structure')
-        .option('--pipeline <json>', 'Optional draft pipeline to validate before saving')
+        .command('validate [id]')
+        .description('Validate a workflow. With <id>: server-side validation. With --file/--pipeline and no id: fast client-side preflight (no API call).')
+        .option('--file <path>', 'Path to pipeline JSON file (client-side preflight if no <id> is given)')
+        .option('--pipeline <json>', 'Inline pipeline JSON (overrides the saved pipeline when <id> is given; otherwise runs preflight)')
         .option('--format <fmt>', 'Output format', 'json')
         .action(async (id, opts) => {
         try {
-            const pipeline = opts.pipeline ? JSON.parse(opts.pipeline) : undefined;
+            let pipeline = undefined;
+            if (opts.file) {
+                pipeline = JSON.parse(fs.readFileSync(opts.file, 'utf-8'));
+            }
+            else if (opts.pipeline) {
+                pipeline = JSON.parse(opts.pipeline);
+            }
+            // No workflow id → run a local preflight. This is the "pre-create"
+            // path: catches invalid step types, duplicate ids, dangling next
+            // references, stripped root fields, missing prompt templates —
+            // without spending a create+validate+delete round trip.
+            if (!id) {
+                if (!pipeline) {
+                    printError('Provide either <id> (server validate) or --file/--pipeline (client preflight).');
+                    return;
+                }
+                const result = preflightPipeline(pipeline);
+                const format = opts.format;
+                if (format === 'json') {
+                    printOutput({ preflight: true, ...result }, 'json');
+                }
+                else {
+                    if (result.valid) {
+                        console.log(`  ✓ Preflight OK (${result.stepCount} steps, ${result.warnings.length} warnings)`);
+                    }
+                    else {
+                        console.error(`\n  ✗ Preflight failed: ${result.errors.length} error${result.errors.length === 1 ? '' : 's'}`);
+                        for (const e of result.errors)
+                            console.error(formatPreflightIssue(e));
+                    }
+                    if (result.warnings.length > 0) {
+                        console.log(`\n  ⚠ ${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'}`);
+                        for (const w of result.warnings)
+                            console.log(formatPreflightIssue(w));
+                    }
+                    console.log('\n  Note: preflight is a fast structural check. Run `agentled workflows create` for full server-side validation.');
+                }
+                if (!result.valid)
+                    process.exit(VALIDATION_EXIT_CODE);
+                return;
+            }
             const client = new AgentledClient();
             const result = await client.validateWorkflow(id, pipeline);
-            printOutput(result, opts.format);
+            const format = opts.format;
+            if (format === 'json') {
+                printOutput(result, 'json');
+            }
+            else {
+                const errorCount = result.errors?.length ?? 0;
+                const warnCount = result.warnings?.length ?? 0;
+                if (errorCount === 0 && warnCount === 0) {
+                    console.log(`  ✓ Validated (0 errors, 0 warnings) — ${id}`);
+                }
+                else {
+                    if (errorCount > 0) {
+                        console.error(`\n  ✗ Validation failed: ${errorCount} error${errorCount === 1 ? '' : 's'}`);
+                        for (const e of result.errors)
+                            console.error(formatIssueLine(e));
+                    }
+                    if (warnCount > 0) {
+                        console.log(`\n  ⚠ ${warnCount} warning${warnCount === 1 ? '' : 's'}`);
+                        for (const w of result.warnings)
+                            console.log(formatIssueLine(w));
+                    }
+                }
+            }
+            if (!result.valid) {
+                console.error(`\n  Fix flow:`);
+                console.error(`    1. agentled workflows export ${id} --output pipeline.json`);
+                console.error(`    2. edit pipeline.json`);
+                console.error(`    3. agentled workflows validate --file pipeline.json   # local preflight`);
+                console.error(`    4. agentled workflows update ${id} --file pipeline.json`);
+                console.error(`    (or) agentled workflows delete ${id}`);
+                process.exit(VALIDATION_EXIT_CODE);
+            }
         }
         catch (e) {
             printError(e.message);