@myapihq/cli 1.1.0-wip.0 → 1.1.0-wip.2

package/dist/commands/org.js

@@ -1,9 +1,9 @@
-import * as readline from 'readline';
 import { hq, funnel as sdkFunnel } from '@myapihq/sdk';
 import { requireConfig, saveConfig } from '../config.js';
 import { success, error, printTable, printJson, info } from '../output.js';
-import { sleep, formatDate } from '../utils.js';
-import { requireOrg } from '../helpers.js';
+import { confirm } from '../prompt.js';
+import { formatDate, pollJob } from '../utils.js';
+import { requireOrg, requireArg } from '../helpers.js';
 export const SCHEMA = {
     name: 'string',
     tagline: 'string',
@@ -34,13 +34,7 @@ export async function create(restArgs, flags) {
             info(`Preview domain: https://${org.preview_subdomain}.makeautonomous.com`);
         }
     }
-    const setDefault = flags.yes || await new Promise(resolve => {
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        rl.question('› Set as default org and funnel? (Y/n) ', ans => {
-            rl.close();
-            resolve(ans.trim().toLowerCase() !== 'n');
-        });
-    });
+    const setDefault = !!flags.yes || await confirm('› Set as default org and funnel? (Y/n) ', true);
     let funnelId;
     if (setDefault) {
         config.default_org = org.id;
@@ -108,8 +102,7 @@ export async function get(id, flags) {
         info(`Preview: https://${org.preview_subdomain}.makeautonomous.com`);
 }
 export async function del(id, _flags) {
-    if (!id)
-        error('Missing org id. Usage: myapi org delete <id>');
+    requireArg(id, 'id', 'myapi org delete <id>');
     const config = requireConfig();
     await hq.deleteOrg(config.api_key, id);
     success(`Org ${id} deleted`);
@@ -122,28 +115,18 @@ export async function importOrg(args, flags) {
         error('Missing required arguments.\nUsage: myapi org sync-brand <domain> [--org <id>]\n(Or set default: myapi config set-domain <domain>)');
     const result = await hq.importOrg(config.api_key, orgId, domain);
     const importId = result.job_id;
-    process.stdout.write('Importing ');
-    const chars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-    let i = 0;
-    let elapsed = 0;
-    while (elapsed < SYNC_BRAND_TIMEOUT_MS) {
-        const status = await hq.getOrgImportStatus(config.api_key, importId);
-        if (status.status === 'awaiting_confirm') {
-            process.stdout.write('\r\x1b[K');
-            const org = await hq.confirmOrgImport(config.api_key, importId);
-            success(`Import complete! Org ID: ${org.id}`);
-            return;
-        }
-        if (status.status === 'failed') {
-            process.stdout.write('\r\x1b[K');
-            error('Import failed');
-        }
-        process.stdout.write(`\rImporting ${chars[i++ % chars.length]}`);
-        await sleep(3000);
-        elapsed += 3000;
-    }
-    process.stdout.write('\r\x1b[K');
-    error(`Import timed out after ${SYNC_BRAND_TIMEOUT_MS / 1000}s. The job may still complete in the background — re-run "myapi org sync-brand" to retry.`);
+    await pollJob({
+        label: 'Importing',
+        timeoutMs: SYNC_BRAND_TIMEOUT_MS,
+        intervalMs: 3000,
+        check: () => hq.getOrgImportStatus(config.api_key, importId),
+        isDone: s => s.status === 'awaiting_confirm',
+        isFailed: s => s.status === 'failed',
+        failedMessage: 'Import failed',
+        timeoutMessage: `Import timed out after ${SYNC_BRAND_TIMEOUT_MS / 1000}s. The job may still complete in the background — re-run "myapi org sync-brand" to retry.`,
+    });
+    const org = await hq.confirmOrgImport(config.api_key, importId);
+    success(`Import complete! Org ID: ${org.id}`);
 }
 // ── Dispatcher ───────────────────────────────────────────────────────────────
 const SUBCOMMAND_USAGE = {

package/dist/commands/setup.js

@@ -1,19 +1,10 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as readline from 'readline';
 import { loadConfig, saveConfig, addAccount, loadFullConfig } from '../config.js';
 import { info, success } from '../output.js';
+import { ask, confirm } from '../prompt.js';
 import { hq, funnel as sdkFunnel } from '@myapihq/sdk';
-function ask(rl, q) {
-    return new Promise(resolve => rl.question(q, resolve));
-}
-function yn(answer, defaultYes = true) {
-    const t = answer.trim().toLowerCase();
-    if (t === '')
-        return defaultYes;
-    return t === 'y' || t === 'yes';
-}
 // ---------------------------------------------------------------------------
 // Skills installation
 // ---------------------------------------------------------------------------
@@ -53,10 +44,15 @@ export async function installSkills() {
             for (const skill of skills) {
                 const link = path.join(dir, skill);
                 const target = path.join(SKILLS_CANONICAL, skill);
+                // Only remove if it's already a symlink we own. Avoids clobbering a
+                // user-authored skill that happens to share the same `my-X-api/`
+                // name. ENOENT here just means "nothing to clean up".
                 try {
-                    fs.rmSync(link, { recursive: true, force: true });
+                    const stat = fs.lstatSync(link);
+                    if (stat.isSymbolicLink())
+                        fs.rmSync(link, { force: true });
                 }
-                catch { /* ignore */ }
+                catch { /* ENOENT: nothing there */ }
                 fs.symlinkSync(target, link);
             }
             info(`  ✓ ${agent}`);
@@ -74,13 +70,48 @@ export async function installSkills() {
     }
 }
 // ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+// Resolve the user's "install skills?" preference: explicit flag wins, else
+// prompt (defaulting to yes). `--yes` short-circuits to true.
+async function resolveSkillsPreference(flags) {
+    if (flags['install-skills'])
+        return true;
+    if (flags['no-skills'])
+        return false;
+    if (flags.yes)
+        return true;
+    return confirm('› Install the MyAPI skills pack? (Y/n) ', true);
+}
+// Resolve default org and funnel for a key by inspecting the account's orgs.
+// Used by both `setup` and `import-key`. Picks the most recently-created
+// org/funnel as the default; preserves the caller's hint if it still exists.
+async function resolveDefaults(apiKey, hint = {}) {
+    let org = hint.org ?? '';
+    let funnel = hint.funnel ?? '';
+    try {
+        const orgs = await hq.listOrgs(apiKey);
+        if (orgs.length > 0) {
+            if (!org || !orgs.find(o => o.id === org)) {
+                org = orgs[orgs.length - 1].id;
+            }
+            const funnels = await sdkFunnel.listFunnels(apiKey, org);
+            if (funnels.length > 0 && (!funnel || !funnels.find((f) => f.id === funnel))) {
+                funnel = funnels[funnels.length - 1].id;
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    return { org, funnel };
+}
+// ---------------------------------------------------------------------------
 // Registered flow
 // ---------------------------------------------------------------------------
-async function registeredFlow(rl) {
-    const email = (await ask(rl, '› Email? ')).trim();
+async function registeredFlow() {
+    const email = await ask('› Email? ');
     await hq.sendCode(email);
     info(`› Sent a code to ${email} · paste it below`);
-    const code = (await ask(rl, '› Code? ')).trim();
+    const code = await ask('› Code? ');
     const data = await hq.verifyCode(email, code);
     return { ...data, email };
 }
@@ -90,16 +121,39 @@ async function anonymousFlow() {
 // ---------------------------------------------------------------------------
 // Main setup command
 // ---------------------------------------------------------------------------
+const IMPORT_KEY_HELP = `Usage: myapi auth import-key <api_key> [--install-skills] [--no-skills]
+
+Imports an existing API key non-interactively. Use this in CI, Docker, or any
+environment where the interactive "myapi auth setup" flow is not practical.
+
+The key is validated against the API before being saved. Your default org and
+funnel are auto-detected from the account and written to the local config.
+
+Flags:
+  --install-skills   Also install the MyAPI skills pack for AI agents after importing
+  --no-skills        Skip skills installation even if previously installed
+
+Examples:
+  myapi auth import-key hq_live_xxxxxxxxxxxxxxxxxxxx
+  myapi auth import-key hq_live_xxxxxxxxxxxxxxxxxxxx --install-skills`;
+const SETUP_HELP = `Usage: myapi auth setup [--anonymous] [--yes] [--install-skills|--no-skills]
+
+Configures your account and stores your default org and funnel so you don't
+need to pass --org or --funnel on every command.
+
+Flags:
+  --anonymous       Skip registration, create anonymous account
+  --yes             Skip confirmation prompts
+  --install-skills  Auto-install skills pack
+  --no-skills       Skip skills installation`;
 // myapi auth import-key <key> — non-interactively import a raw API key.
 export async function importKey(apiKey, flags) {
     if (flags.help || !apiKey) {
-        info('Usage: myapi auth import-key <api_key> [--install-skills] [--no-skills]\n\nImports an existing API key non-interactively. Use this in CI, Docker, or any\nenvironment where the interactive "myapi auth setup" flow is not practical.\n\nThe key is validated against the API before being saved. Your default org and\nfunnel are auto-detected from the account and written to the local config.\n\nFlags:\n  --install-skills   Also install the MyAPI skills pack for AI agents after importing\n  --no-skills        Skip skills installation even if previously installed\n\nExamples:\n  myapi auth import-key hq_live_xxxxxxxxxxxxxxxxxxxx\n  myapi auth import-key hq_live_xxxxxxxxxxxxxxxxxxxx --install-skills');
+        info(IMPORT_KEY_HELP);
         return;
     }
     let accountId = '';
     let email;
-    let defaultOrg = '';
-    let defaultFunnel = '';
     try {
         const me = await hq.getAccount(apiKey);
         accountId = me.account_id ?? '';
@@ -108,25 +162,26 @@ export async function importKey(apiKey, flags) {
     catch (e) {
         throw new Error(`Could not verify API key: ${e.message}`);
     }
-    try {
-        const orgs = await hq.listOrgs(apiKey);
-        if (orgs.length > 0) {
-            defaultOrg = orgs[orgs.length - 1].id;
-            const funnels = await sdkFunnel.listFunnels(apiKey, defaultOrg);
-            if (funnels.length > 0)
-                defaultFunnel = funnels[funnels.length - 1].id;
-        }
-    }
-    catch { /* non-fatal */ }
-    const wantsSkills = flags['install-skills'] ? true : flags['no-skills'] ? false : true;
-    addAccount({ api_key: apiKey, account_id: accountId, email, default_org: defaultOrg, default_funnel: defaultFunnel, skills_installed: wantsSkills });
+    const { org: defaultOrg, funnel: defaultFunnel } = await resolveDefaults(apiKey);
+    const wantsSkills = flags['no-skills'] ? false : true;
+    addAccount({
+        api_key: apiKey, account_id: accountId, email,
+        default_org: defaultOrg, default_funnel: defaultFunnel,
+        skills_installed: wantsSkills,
+    });
     success(`› ✓ Key imported${email ? ` · ${email}` : ''}`);
     if (wantsSkills)
         await installSkills();
 }
+// Persist a new account + (optionally) install skills.
+async function installAndPersistSkills(account, wantsSkills) {
+    addAccount({ ...account, skills_installed: wantsSkills });
+    if (wantsSkills)
+        await installSkills();
+}
 export async function setup(flags = {}) {
     if (flags.help) {
-        info('Usage: myapi auth setup [--anonymous] [--yes] [--install-skills|--no-skills]\n\nConfigures your account and stores your default org and funnel so you don\'t need to pass --org or --funnel on every command.\n\nFlags:\n  --anonymous       Skip registration, create anonymous account\n  --yes             Skip confirmation prompts\n  --install-skills  Auto-install skills pack\n  --no-skills       Skip skills installation');
+        info(SETUP_HELP);
         return;
     }
     info('› Configuring MyAPI…');
@@ -139,27 +194,20 @@ export async function setup(flags = {}) {
         const activeType = existing.is_anonymous ? 'anonymous' : 'registered';
         const othersNote = total > 1 ? ` · ${total - 1} more saved` : '';
         info(`› Connected: ${activeLabel} (${activeType})${othersNote}`);
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        const add = await ask(rl, '› Connect a new account? (y/N) ');
-        if (!yn(add, false)) {
+        const add = await confirm('› Connect a new account? (y/N) ', false);
+        if (!add) {
             if (!existing.skills_installed) {
-                const ans = await ask(rl, '› Install the MyAPI skills pack? (Y/n) ');
-                rl.close();
-                if (yn(ans)) {
+                const wants = await resolveSkillsPreference(flags);
+                if (wants) {
                     await installSkills();
                     success('› Skills installed.');
                     saveConfig({ ...existing, skills_installed: true });
                 }
             }
-            else {
-                rl.close();
-            }
             return;
         }
-        rl.close();
         // Fall through to setup flow — new account will be added to the list.
     }
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     let apiKey = '';
     let accountId = '';
     let defaultOrg = '';
@@ -167,82 +215,62 @@ export async function setup(flags = {}) {
     let subdomainUrl = '';
     let isAnonymous = false;
     let email = '';
-    // Determine skills preference from flags before any prompts.
-    const skillsFromFlag = flags['install-skills'] ? true : flags['no-skills'] ? false : null;
+    const useAnon = flags.anonymous || flags.anon;
+    const wantsRegister = useAnon ? false : await confirm('› Register with email? (Y/n, or N to continue anonymously) ', true);
+    if (wantsRegister) {
+        const data = await registeredFlow();
+        apiKey = data.api_key;
+        accountId = data.account_id;
+        defaultOrg = data.default_org;
+        defaultFunnel = data.default_funnel;
+        email = data.email;
+    }
+    else {
+        info('› Continuing as anonymous — sites ship to *.makeautonomous.com');
+        const data = await anonymousFlow();
+        apiKey = data.api_key;
+        accountId = data.account_id;
+        defaultOrg = data.default_org;
+        defaultFunnel = data.default_funnel;
+        subdomainUrl = data.subdomain_url;
+        isAnonymous = true;
+    }
+    const wantsSkills = await resolveSkillsPreference(flags);
+    await installAndPersistSkills({
+        api_key: apiKey,
+        account_id: accountId,
+        email: email || undefined,
+        default_org: defaultOrg,
+        default_funnel: defaultFunnel,
+        is_anonymous: isAnonymous,
+    }, wantsSkills);
+    success(`› ✓ saved to ~/.myapi/config.json`);
+    // Validate key and ensure org/funnel defaults are still correct.
+    // (resolveDefaults is non-fatal if the API call fails.)
     try {
-        const useAnon = flags.anonymous || flags.anon;
-        const createAns = useAnon ? 'n' : await ask(rl, '› Register with email? (Y/n, or N to continue anonymously) ');
-        if (yn(createAns)) {
-            const data = await registeredFlow(rl);
-            apiKey = data.api_key;
-            accountId = data.account_id;
-            defaultOrg = data.default_org;
-            defaultFunnel = data.default_funnel;
-            email = data.email;
-        }
-        else {
-            info('› Continuing as anonymous — sites ship to *.makeautonomous.com');
-            const data = await anonymousFlow();
-            apiKey = data.api_key;
-            accountId = data.account_id;
-            defaultOrg = data.default_org;
-            defaultFunnel = data.default_funnel;
-            subdomainUrl = data.subdomain_url;
-            isAnonymous = true;
-        }
-        const wantsSkills = skillsFromFlag !== null ? skillsFromFlag : flags.yes ? true : yn(await ask(rl, '› Install the MyAPI skills pack? (Y/n) '));
-        addAccount({
-            api_key: apiKey,
-            account_id: accountId,
-            email: email || undefined,
-            default_org: defaultOrg,
-            default_funnel: defaultFunnel,
-            is_anonymous: isAnonymous,
-            skills_installed: wantsSkills,
-        });
-        success(`› ✓ saved to ~/.myapi/config.json`);
-        if (wantsSkills) {
-            await installSkills();
-        }
-        // Validate key and ensure org/funnel defaults are correct.
-        try {
-            await hq.getAccount(apiKey);
-            let resolvedOrg = defaultOrg;
-            let resolvedFunnel = defaultFunnel;
-            const orgs = await hq.listOrgs(apiKey);
-            if (orgs.length > 0) {
-                const latest = orgs[orgs.length - 1];
-                if (!resolvedOrg || !orgs.find(o => o.id === resolvedOrg)) {
-                    resolvedOrg = latest.id;
-                    info(`› Auto-selected org: ${latest.name} (${resolvedOrg})`);
-                }
-                const funnels = await sdkFunnel.listFunnels(apiKey, resolvedOrg);
-                if (funnels.length > 0 && (!resolvedFunnel || !funnels.find((f) => f.id === resolvedFunnel))) {
-                    resolvedFunnel = funnels[funnels.length - 1].id;
-                    info(`› Auto-selected funnel: ${resolvedFunnel}`);
-                }
-                if (resolvedOrg !== defaultOrg || resolvedFunnel !== defaultFunnel) {
-                    const current = loadConfig();
-                    if (current) {
-                        saveConfig({ ...current, default_org: resolvedOrg, default_funnel: resolvedFunnel });
-                        defaultOrg = resolvedOrg;
-                        defaultFunnel = resolvedFunnel;
-                    }
-                }
+        await hq.getAccount(apiKey);
+        const resolved = await resolveDefaults(apiKey, { org: defaultOrg, funnel: defaultFunnel });
+        if (resolved.org !== defaultOrg || resolved.funnel !== defaultFunnel) {
+            const current = loadConfig();
+            if (current) {
+                saveConfig({ ...current, default_org: resolved.org, default_funnel: resolved.funnel });
+                if (resolved.org !== defaultOrg)
+                    info(`› Auto-selected org: ${resolved.org}`);
+                if (resolved.funnel !== defaultFunnel)
+                    info(`› Auto-selected funnel: ${resolved.funnel}`);
+                defaultOrg = resolved.org;
+                defaultFunnel = resolved.funnel;
             }
         }
-        catch { /* non-fatal */ }
-        if (isAnonymous) {
-            success('› Setup complete. No card, no email, ready to ship.');
-            if (subdomainUrl)
-                info(`› Your funnel: ${subdomainUrl}`);
-            info('› Upgrade anytime — myapi auth link');
-        }
-        else {
-            success(`› Setup complete. Org ${defaultOrg} ready · $5.00 free credits added.`);
-        }
     }
-    finally {
-        rl.close();
+    catch { /* non-fatal */ }
+    if (isAnonymous) {
+        success('› Setup complete. No card, no email, ready to ship.');
+        if (subdomainUrl)
+            info(`› Your funnel: ${subdomainUrl}`);
+        info('› Upgrade anytime — myapi auth link');
+    }
+    else {
+        success(`› Setup complete. Org ${defaultOrg} ready · $5.00 free credits added.`);
     }
 }

package/dist/commands/update.js

@@ -126,6 +126,11 @@ export async function latestVersion() {
         return null;
     }
 }
+// Stable-only semver comparison (1.2.3). Prerelease versions (1.2.3-wip.0)
+// produce NaN in the patch slot, and `n > NaN` is always false — which is
+// what we want: a prerelease user should not be auto-rolled back to stable.
+// Auto-update is opt-in via the `latest` dist-tag (always stable); see
+// checkForUpdate() above.
 export function isNewer(latest, current) {
     const toNum = (v) => v.split('.').map(Number);
     const [lMaj, lMin, lPat] = toNum(latest);

package/dist/commands/webhook.d.ts

@@ -2,7 +2,7 @@ import type { FlagSchema } from '../flags.js';
 import { type Flags } from '../helpers.js';
 export declare const SCHEMA: FlagSchema;
 export declare function list(flags: Flags): Promise<void>;
-export declare function create(flags: Flags): Promise<void>;
+export declare function create(nameArg: string | undefined, flags: Flags): Promise<void>;
 export declare function del(id: string, flags: Flags): Promise<void>;
 export declare function delivery(id: string, flags: Flags): Promise<void>;
 export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/webhook.js

@@ -20,12 +20,12 @@ export async function list(flags) {
         empty: 'No webhook endpoints yet. Create one with: myapi webhook create --name <name>',
     });
 }
-export async function create(flags) {
+export async function create(nameArg, flags) {
     const config = requireConfig();
-    const orgId = requireOrg(flags, config, 'myapi webhook create --name <name> [--description <desc>] [--org <id>]');
-    const name = flags.name;
+    const orgId = requireOrg(flags, config, 'myapi webhook create <name> [--description <desc>] [--org <id>]');
+    const name = nameArg || flags.name;
     if (!name)
-        error('Missing required arguments.\nUsage: myapi webhook create --name <name> [--description <desc>] [--org <id>]');
+        error('Missing required arguments.\nUsage: myapi webhook create <name> [--description <desc>] [--org <id>]\n   or: myapi webhook create --name <name> [--description <desc>] [--org <id>]');
     const description = flags.description;
     const res = await sdkWebhook.createEndpoint(config.api_key, orgId, name, description);
     success(`Webhook created! ID: ${res.id}\nInbound URL: ${res.url}`);
@@ -49,7 +49,10 @@ export async function delivery(id, flags) {
 // ── Dispatcher ───────────────────────────────────────────────────────────────
 const SUBCOMMAND_USAGE = {
     'list': 'myapi webhook list [--org <id>] [--json]',
-    'create': 'myapi webhook create --name <name> [--description <desc>] [--org <id>]',
+    'create': `myapi webhook create <name> [--description <desc>] [--org <id>]
+       myapi webhook create --name <name> [--description <desc>] [--org <id>]
+
+Either form works; the positional name is the recommended shape.`,
     'delete': 'myapi webhook delete <id> [--org <id>]',
     'delivery': 'myapi webhook delivery <delivery_id> [--org <id>]',
 };
@@ -63,7 +66,20 @@ Subcommands:
   delete     Delete a webhook endpoint
   delivery   Inspect a specific webhook delivery (payload, received_at)
 
-All commands accept --org <id> (or set default: myapi config set-org <id>).`);
+All commands accept --org <id> (or set default: myapi config set-org <id>).
+
+Payload contract:
+  The inbound URL accepts ANY JSON body — there's no enforced schema.
+  Whatever you POST is stored verbatim alongside headers + timestamp.
+  Workflows reference fields with {{ payload.field }} templating.
+
+Example — wire a contact form to email + Slack:
+  WID=$(myapi webhook create "contact-form" --json | jq -r .id)
+  myapi workflow create "Contact handler" --endpoint-id $WID --steps '[
+    {"type":"send_email","to":"{{ payload.email }}","subject":"Thanks!","body":"..."},
+    {"type":"slack","webhook_url":"https://hooks.slack.com/...","text":"New: {{ payload.message }}"}
+  ]'
+See the my-webhook-api skill for the full HTML + JS recipe.`);
         return;
     }
     if (flags.help) {
@@ -76,7 +92,7 @@ All commands accept --org <id> (or set default: myapi config set-org <id>).`);
     }
     switch (subcommand) {
         case 'list': return list(flags);
-        case 'create': return create(flags);
+        case 'create': return create(args[0], flags);
         case 'delete': return del(args[0], flags);
         case 'delivery': return delivery(args[0], flags);
         default: error(`Unknown subcommand: ${subcommand}. Run "myapi webhook --help" for a list of valid subcommands.`);

package/dist/commands/workflow.d.ts

@@ -3,7 +3,7 @@ import { type Flags } from '../helpers.js';
 export declare const SCHEMA: FlagSchema;
 export declare function list(flags: Flags): Promise<void>;
 export declare function get(id: string, flags: Flags): Promise<void>;
-export declare function create(flags: Flags): Promise<void>;
+export declare function create(nameArg: string | undefined, flags: Flags): Promise<void>;
 export declare function update(id: string, flags: Flags): Promise<void>;
 export declare function enable(id: string, flags: Flags): Promise<void>;
 export declare function disable(id: string, flags: Flags): Promise<void>;

package/dist/commands/workflow.js

@@ -9,6 +9,23 @@ export const SCHEMA = {
     steps: 'string',
     'no-enable': 'boolean',
 };
+// Mirrors the backend's SupportedStepTypes list. Both alias and underscore
+// forms are accepted by the workflow runner. Keep this in sync if the
+// backend grows new step types.
+const SUPPORTED_STEP_TYPES = ['send_email', 'email', 'slack_message', 'slack'];
+function validateSteps(steps) {
+    if (!Array.isArray(steps))
+        error('--steps must be a JSON array of step objects.');
+    steps.forEach((s, i) => {
+        if (!s || typeof s !== 'object')
+            error(`step ${i}: must be a JSON object.`);
+        if (!s.type)
+            error(`step ${i}: missing required field "type". Supported: ${SUPPORTED_STEP_TYPES.join(', ')}`);
+        if (!SUPPORTED_STEP_TYPES.includes(s.type)) {
+            error(`step ${i}: unknown type "${s.type}". Supported: ${SUPPORTED_STEP_TYPES.join(', ')}`);
+        }
+    });
+}
 function summarizeWorkflow(w) {
     return {
         id: w.id,
@@ -52,13 +69,13 @@ export async function get(id, flags) {
     const wf = await sdkWorkflow.getWorkflow(config.api_key, orgId, id);
     printJson(wf);
 }
-export async function create(flags) {
+export async function create(nameArg, flags) {
     const config = requireConfig();
-    const orgId = requireOrg(flags, config, 'myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]');
-    const name = flags.name;
+    const orgId = requireOrg(flags, config, 'myapi workflow create <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]');
+    const name = nameArg || flags.name;
     const endpointId = flags['endpoint-id'];
     if (!name || !endpointId || !flags.steps) {
-        error('Missing required arguments.\nUsage: myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]');
+        error('Missing required arguments.\nUsage: myapi workflow create <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]\n   or: myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]');
     }
     let steps;
     try {
@@ -67,6 +84,7 @@ export async function create(flags) {
     catch {
         error('Invalid JSON for --steps');
     }
+    validateSteps(steps);
     const wf = await sdkWorkflow.createWorkflow(config.api_key, orgId, {
         name,
         trigger_config: { endpoint_id: endpointId },
@@ -98,6 +116,7 @@ export async function update(id, flags) {
         catch {
             error('Invalid JSON for --steps');
         }
+        validateSteps(payload.steps);
     }
     if (!payload.name && !payload.trigger_config && !payload.steps) {
         error('Nothing to update. Provide at least one of --name, --endpoint-id, --steps.');
@@ -156,7 +175,27 @@ export async function getRun(runId, flags) {
 const SUBCOMMAND_USAGE = {
     'list': 'myapi workflow list [--org <id>] [--json]',
     'get': 'myapi workflow get <id> [--org <id>]',
-    'create': 'myapi workflow create --name <str> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]',
+    'create': `myapi workflow create <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]
+       myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]
+
+Either form works; the positional name is the recommended shape.
+
+--steps is a JSON array of step objects. Supported step types:
+  send_email | email   — fields: from, to, subject, body | template_id, template_vars
+  slack_message | slack — fields: webhook_url, text
+
+Either alias works (e.g. type: "email" and type: "send_email" both run
+the same step). Field values support {{ payload.field }} templating to
+reference the incoming webhook payload, e.g. "to": "{{ payload.email }}".
+Unknown step types are rejected at create time, not at execute time.
+
+Example — fire on every webhook POST, send a thank-you email:
+  myapi workflow create "Contact handler" --endpoint-id <wid> --steps '[
+    {"type":"send_email","from":"hello@x.com","to":"{{ payload.email }}",
+     "subject":"Thanks!","body":"We got your message."}
+  ]'
+
+See the my-workflow-api skill for the full form-to-email recipe.`,
     'update': 'myapi workflow update <id> [--name <str>] [--endpoint-id <id>] [--steps <json>] [--org <id>]',
     'enable': 'myapi workflow enable <id> [--org <id>]',
     'disable': 'myapi workflow disable <id> [--org <id>]',
@@ -197,7 +236,7 @@ All commands accept --org <id> (or set default: myapi config set-org <id>).`);
     switch (subcommand) {
         case 'list': return list(flags);
         case 'get': return get(args[0], flags);
-        case 'create': return create(flags);
+        case 'create': return create(args[0], flags);
         case 'update': return update(args[0], flags);
         case 'enable': return enable(args[0], flags);
         case 'disable': return disable(args[0], flags);

package/dist/config.js

@@ -48,8 +48,14 @@ export function loadConfig() {
         config.api_key = envKey;
     return config;
 }
-export function saveConfig(config) {
+// Single point of truth for writes. Ensures CONFIG_DIR exists and that the
+// file is created with mode 0o600 (owner read/write only) — no caller has
+// to remember either.
+function writeFullConfig(full) {
     ensureDir();
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(full, null, 2), { mode: 0o600 });
+}
+export function saveConfig(config) {
     const full = loadFullConfig() ?? { active: 0, accounts: [] };
     const { autocomplete_setup, ...account } = config;
     if (full.accounts.length === 0)
@@ -58,10 +64,9 @@ export function saveConfig(config) {
         full.accounts[full.active] = account;
     if (autocomplete_setup !== undefined)
         full.autocomplete_setup = autocomplete_setup;
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(full, null, 2), { mode: 0o600 });
+    writeFullConfig(full);
 }
 export function addAccount(account) {
-    ensureDir();
     const full = loadFullConfig() ?? { active: 0, accounts: [] };
     // Replace if same account_id already exists.
     const existing = full.accounts.findIndex(a => a.account_id === account.account_id);
@@ -73,7 +78,7 @@ export function addAccount(account) {
         full.accounts.push(account);
         full.active = full.accounts.length - 1;
     }
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(full, null, 2), { mode: 0o600 });
+    writeFullConfig(full);
     return full.active;
 }
 export function switchAccount(index) {
@@ -81,7 +86,7 @@ export function switchAccount(index) {
     if (!full || index < 0 || index >= full.accounts.length)
         return false;
     full.active = index;
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(full, null, 2), { mode: 0o600 });
+    writeFullConfig(full);
     return true;
 }
 export function listAccounts() {