@wabery/cli 0.2.0 → 0.4.0

package/dist/cli.js

@@ -8,11 +8,15 @@ import { createInterface } from "node:readline";
 import { WaberyApiClient, WaberyApiError } from "./api-client.js";
 import { createExampleConfig } from "./config-example.js";
 import { checkWaberyConnection } from "./diagnostics.js";
-import { getConfigPath, writeLocalConfig } from "./local-config.js";
+import { clearCredentials, findCredentialByProject, getConfigPath, readCredentials, removeCredential, repoConfigWritePath, resolveProjectId, upsertCredential, writeRepoProjectId, } from "./local-config.js";
 import { runMcpServer } from "./mcp-server.js";
 async function main() {
     const parsed = parseArgs(process.argv.slice(2));
     const [command, subcommand, ...rest] = parsed.positionals;
+    // Global output shaping for scripting: `--id-only` or `--field <dot.path>`
+    // print a single raw value instead of JSON (no jq needed).
+    outputIdOnly = booleanFlag(parsed.flags, "id-only") === true;
+    outputField = stringFlag(parsed.flags, "field");
     if (!command ||
         command === "help" ||
         command === "--help" ||
@@ -29,6 +33,14 @@ async function main() {
         await handleLogin(parsed.flags);
         return;
     }
+    if (command === "logout") {
+        await handleLogout(parsed.flags);
+        return;
+    }
+    if (command === "use") {
+        await handleUse(subcommand ?? rest[0]);
+        return;
+    }
     if (command === "mcp-config") {
         await handleMcpConfig(subcommand, parsed.flags);
         return;
@@ -42,25 +54,42 @@ async function main() {
         await testDataExchange(parsed.flags);
         return;
     }
+    if (command === "flows" && subcommand === "simulate") {
+        await simulateFlow(parsed.flags);
+        return;
+    }
     const client = new WaberyApiClient({
         apiKey: stringFlag(parsed.flags, "api-key"),
         baseUrl: stringFlag(parsed.flags, "base-url"),
         apiVersion: stringFlag(parsed.flags, "api-version"),
+        projectId: stringFlag(parsed.flags, "project-id"),
     });
     if (command === "mcp") {
         await runMcpServer(client);
         return;
     }
+    if (command === "whoami") {
+        await handleWhoami(client);
+        return;
+    }
+    if (command === "init") {
+        await handleInit(client, parsed.flags);
+        return;
+    }
     if (command === "doctor" || command === "check") {
         await printJson(await checkWaberyConnection(client));
         return;
     }
+    if (command === "env") {
+        await handleEnv(client, parsed.flags);
+        return;
+    }
     if (command === "config") {
         await handleConfig(client, subcommand, rest, parsed.flags);
         return;
     }
     if (command === "projects") {
-        await handleProjects(client, subcommand, parsed.flags);
+        await handleProjects(client, subcommand, rest, parsed.flags);
         return;
     }
     if (command === "channels" && subcommand === "list") {
@@ -131,12 +160,13 @@ async function handleConfig(client, subcommand, rest, flags) {
     throw new Error("Usage: wabery config schema|export|example|init|validate|diff|apply [wabery.config.json]");
 }
 async function handleLocalConfig(subcommand, rest, flags) {
+    const resolvedProjectId = stringFlag(flags, "project-id") ?? resolveProjectId({}).projectId;
     if (subcommand === "example") {
-        await printJson(createExampleConfig(stringFlag(flags, "project-id")));
+        await printJson(createExampleConfig(resolvedProjectId));
         return;
     }
     const outputPath = rest[0] ?? stringFlag(flags, "file") ?? "wabery.config.json";
-    const config = createExampleConfig(stringFlag(flags, "project-id"));
+    const config = createExampleConfig(resolvedProjectId);
     await writeFile(outputPath, `${JSON.stringify(config, null, 2)}\n`, {
         flag: booleanFlag(flags, "force") ? "w" : "wx",
     });
@@ -237,8 +267,98 @@ async function handleLogin(flags) {
     if (!apiKey.startsWith("wab_live_")) {
         throw new Error("That does not look like a Wabery CLI key (it should start with wab_live_). Run `wabery login` again.");
     }
-    const configPath = writeLocalConfig({ apiKey, baseUrl });
-    await printText(`\nLogged in to Wabery. Credentials saved to ${configPath}\n`);
+    // Identify which project this key is scoped to via /v1/me, then store the
+    // credential keyed by project so multiple projects can coexist locally.
+    const client = new WaberyApiClient({ apiKey, baseUrl });
+    const identity = (await client.get("/me"));
+    const projectId = identity.project?.id;
+    if (!projectId) {
+        throw new Error("This key is not scoped to a project. Create a key from a project's settings in the Wabery dashboard.");
+    }
+    const configPath = upsertCredential({
+        projectId,
+        projectName: identity.project?.name,
+        organizationId: identity.organization?.id,
+        apiKey,
+        baseUrl,
+    });
+    let boundLine = "";
+    if (!resolveProjectId({}).projectId) {
+        // No repo binding yet — bind this directory to the project we logged into.
+        const repoPath = writeRepoProjectId(repoConfigWritePath(), projectId);
+        boundLine = `Bound this directory to project ${projectId} (${repoPath}).\n`;
+    }
+    await printText(`\nLogged in to project ${identity.project?.name ?? projectId} (${projectId}).\nCredentials saved to ${configPath}\n${boundLine}`);
+}
+/** Clear stored credentials: one project, or all of them with --all. */
+async function handleLogout(flags) {
+    if (booleanFlag(flags, "all")) {
+        clearCredentials();
+        await printText("Logged out. Removed all stored Wabery credentials.\n");
+        return;
+    }
+    const target = stringFlag(flags, "project") ?? stringFlag(flags, "project-id");
+    const credentials = readCredentials();
+    let projectId = target;
+    if (!projectId) {
+        // Default to the project resolved for the current directory.
+        projectId = resolveProjectId({}).projectId;
+    }
+    if (!projectId && credentials.length === 1) {
+        projectId = credentials[0].projectId;
+    }
+    if (!projectId) {
+        throw new Error("Specify which project to log out of: `wabery logout --project <id|name>`, or `wabery logout --all`.");
+    }
+    // Allow matching by name too.
+    const match = credentials.find((c) => c.projectId === projectId) ??
+        credentials.find((c) => c.projectName?.toLowerCase() === projectId?.toLowerCase());
+    if (!match) {
+        throw new Error(`No stored credential for "${projectId}".`);
+    }
+    removeCredential(match.projectId);
+    await printText(`Logged out of project ${match.projectName ?? match.projectId} (${match.projectId}).\n`);
+}
+/**
+ * Bind the current repo to one of the projects you've logged into, by writing
+ * a secret-free `.wabery.json`. Resolves a project id or (case-insensitive)
+ * name against the locally stored credentials.
+ */
+async function handleUse(query) {
+    if (!query) {
+        throw new Error("Usage: wabery use <project-id-or-name>");
+    }
+    const credentials = readCredentials();
+    if (credentials.length === 0) {
+        throw new Error("No projects are logged in yet. Run `wabery login` first.");
+    }
+    const match = credentials.find((c) => c.projectId === query) ??
+        credentials.find((c) => c.projectName?.toLowerCase() === query.toLowerCase());
+    if (!match) {
+        const available = credentials
+            .map((c) => `  - ${c.projectName ?? "(unnamed)"} (${c.projectId})`)
+            .join("\n");
+        throw new Error(`No logged-in project matches "${query}". Available:\n${available}\n\nRun \`wabery login\` to add another project.`);
+    }
+    const path = writeRepoProjectId(repoConfigWritePath(), match.projectId);
+    await printJson({
+        object: "repo_default",
+        path,
+        project_id: match.projectId,
+        project_name: match.projectName ?? null,
+    });
+}
+/** Show the active key (masked), org, and bound project + how it resolved. */
+async function handleWhoami(client) {
+    const identity = (await client.get("/me"));
+    const resolved = resolveProjectId({});
+    await printJson({
+        ...identity,
+        resolution: {
+            project_id: client.projectId ?? null,
+            source: resolved.source,
+        },
+    });
 }
 /** Read a single line from the terminal, echoing what the user types. */
 function promptLine(question) {
@@ -273,22 +393,163 @@ function openUrl(url) {
 function normalizeAppBaseUrl(value) {
     return value.replace(/\/api\/v1\/?$/, "").replace(/\/+$/, "");
 }
-async function handleProjects(client, subcommand, flags) {
+async function handleProjects(client, subcommand, rest, flags) {
     if (subcommand === "list") {
         await printJson(await client.get("/projects"));
         return;
     }
     if (subcommand === "create") {
-        await printJson(await client.post("/projects", {
-            name: requiredStringFlag(flags, "name"),
-            description: stringFlag(flags, "description"),
-            webhook_url: stringFlag(flags, "webhook-url"),
-            webhook_signing_enabled: booleanFlag(flags, "webhook-signing-enabled") ?? true,
-        }));
+        throw new Error("API keys are scoped to one project and cannot create projects. Create a project in the Wabery dashboard, then run `wabery login` for that project.");
+    }
+    if (subcommand === "ensure") {
+        // API keys are scoped to one project. Ensure configures that scoped
+        // project idempotently; it does not create sibling projects.
+        const name = requiredStringFlag(flags, "name");
+        await printJson(await ensureProject(client, name, flags));
+        return;
+    }
+    const projectId = rest[0] ?? stringFlag(flags, "project-id");
+    if (subcommand === "get") {
+        await printJson(await client.get(`/projects/${requiredValue(projectId, "project-id")}`));
+        return;
+    }
+    if (subcommand === "update") {
+        const body = {};
+        const name = stringFlag(flags, "name");
+        if (name !== undefined)
+            body.name = name;
+        const description = stringFlag(flags, "description");
+        if (description !== undefined)
+            body.description = description;
+        const webhookUrl = stringFlag(flags, "webhook-url");
+        if (webhookUrl !== undefined)
+            body.webhook_url = webhookUrl;
+        const signing = booleanFlag(flags, "webhook-signing-enabled");
+        if (signing !== undefined)
+            body.webhook_signing_enabled = signing;
+        const secret = stringFlag(flags, "webhook-secret");
+        if (secret !== undefined)
+            body.webhook_secret = secret;
+        await printJson(await client.patch(`/projects/${requiredValue(projectId, "project-id")}`, body));
+        return;
+    }
+    if (subcommand === "rotate-secret") {
+        const secret = stringFlag(flags, "webhook-secret");
+        await printJson(await client.post(`/projects/${requiredValue(projectId, "project-id")}/rotate-webhook-secret`, secret ? { webhook_secret: secret } : undefined));
         return;
     }
-    throw new Error("Usage: wabery projects list|create --name <name>");
+    throw new Error("Usage: wabery projects list|get|ensure|update|rotate-secret [<project_id>] [--name --description --webhook-url --webhook-signing-enabled --webhook-secret]");
+}
+/** Configure the project visible to this API key, then return it. Idempotent. */
+async function ensureProject(client, name, flags) {
+    const list = (await client.get("/projects"));
+    const existing = list.data?.[0];
+    const id = existing?.project_id ?? existing?.id;
+    if (!existing || !id) {
+        throw new Error("No project is visible to this API key. Create a project in the Wabery dashboard, then run `wabery login` again.");
+    }
+    const webhookBody = {};
+    if (name !== undefined && existing.name !== name)
+        webhookBody.name = name;
+    const description = stringFlag(flags, "description");
+    if (description !== undefined)
+        webhookBody.description = description;
+    const webhookUrl = stringFlag(flags, "webhook-url");
+    if (webhookUrl !== undefined)
+        webhookBody.webhook_url = webhookUrl;
+    const signing = booleanFlag(flags, "webhook-signing-enabled");
+    if (signing !== undefined)
+        webhookBody.webhook_signing_enabled = signing;
+    const secret = stringFlag(flags, "webhook-secret");
+    if (secret !== undefined)
+        webhookBody.webhook_secret = secret;
+    if (Object.keys(webhookBody).length > 0) {
+        return client.patch(`/projects/${id}`, webhookBody);
+    }
+    return client.get(`/projects/${id}`);
+}
+/**
+ * Scaffold a runnable Wabery setup in the current directory:
+ * ensure a project, then write wabery.config.json, a .env block, and a webhook
+ * handler stub. Non-destructive — existing files are left untouched unless --force.
+ */
+async function handleInit(client, flags) {
+    const name = stringFlag(flags, "name");
+    const force = booleanFlag(flags, "force") === true;
+    const ensured = (await ensureProject(client, name, flags));
+    const projectId = ensured.project_id ?? ensured.id;
+    if (!projectId)
+        throw new Error("Could not resolve a project id.");
+    // Single GET reveals the webhook secret + url for the env block.
+    const project = (await client.get(`/projects/${projectId}`));
+    const channelId = project.channel_id ?? project.enrollment_channel?.id ?? undefined;
+    const cred = findCredentialByProject(projectId);
+    const baseUrl = stringFlag(flags, "base-url") ??
+        process.env.WABERY_BASE_URL ??
+        cred?.baseUrl ??
+        "https://api.wabery.com/v1";
+    const apiKey = stringFlag(flags, "api-key") ??
+        process.env.WABERY_API_KEY ??
+        cred?.apiKey ??
+        "wab_live_...";
+    const written = [];
+    const skipped = [];
+    const writeFlag = force ? "w" : "wx";
+    const tryWrite = async (path, content) => {
+        try {
+            await writeFile(path, content, { flag: writeFlag });
+            written.push(path);
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                skipped.push(path);
+                return;
+            }
+            throw error;
+        }
+    };
+    const envLines = [
+        `WABERY_API_KEY=${apiKey}`,
+        `WABERY_BASE_URL=${baseUrl}`,
+        `WABERY_PROJECT_ID=${projectId}`,
+        `WABERY_CHANNEL_ID=${channelId ?? ""}`,
+    ];
+    if (project.webhook_url)
+        envLines.push(`WABERY_WEBHOOK_URL=${project.webhook_url}`);
+    envLines.push(`WABERY_WEBHOOK_SECRET=${project.webhook_secret ?? ""}`);
+    await tryWrite(".env.wabery", `${envLines.join("\n")}\n`);
+    await tryWrite("wabery.config.json", `${JSON.stringify(createExampleConfig(projectId), null, 2)}\n`);
+    await tryWrite("wabery-webhook-handler.ts", WEBHOOK_HANDLER_STUB);
+    await printText(`Initialized Wabery for project ${projectId}.\n` +
+        (written.length ? `Wrote: ${written.join(", ")}\n` : "") +
+        (skipped.length
+            ? `Skipped (already exist, use --force to overwrite): ${skipped.join(", ")}\n`
+            : "") +
+        "\nNext: load .env.wabery, edit the webhook URL, then `wabery config apply wabery.config.json`.\n");
 }
+const WEBHOOK_HANDLER_STUB = `// Verify and handle Wabery webhook deliveries.
+// npm i @wabery/sdk
+import { Wabery } from "@wabery/sdk";
+
+const wabery = new Wabery(); // reads WABERY_API_KEY
+const secret = process.env.WABERY_WEBHOOK_SECRET ?? "";
+
+// Express-style handler; adapt to your framework. Pass the RAW request body.
+export async function handleWaberyWebhook(rawBody: string, signature: string) {
+\tconst event = wabery.webhooks.constructEvent(rawBody, signature, secret);
+\tswitch (event.event) {
+\t\tcase "message.received":
+\t\t\t// event.payload.text, .from, .conversation_id ...
+\t\t\tbreak;
+\t\tcase "flow.completed":
+\t\t\t// event.payload.submission ...
+\t\t\tbreak;
+\t\tdefault:
+\t\t\tbreak;
+\t}
+\treturn event;
+}
+`;
 async function handleContacts(client, subcommand, rest, flags) {
     if (subcommand === "list") {
         await printJson(await client.get("/contacts", {
@@ -305,7 +566,8 @@ async function handleContacts(client, subcommand, rest, flags) {
     if (subcommand === "enroll") {
         await printJson(await client.post("/contacts", {
             phone: requiredStringFlag(flags, "phone"),
-            project_id: requiredStringFlag(flags, "project-id"),
+            // Keys are project-scoped; default to the key's project.
+            project_id: stringFlag(flags, "project-id") ?? client.projectId,
             name: stringFlag(flags, "name"),
             reference_id: stringFlag(flags, "reference-id"),
             metadata: optionalJsonFlag(flags, "metadata"),
@@ -402,7 +664,13 @@ async function handleFlows(client, subcommand, rest, flags) {
         return;
     }
     if (subcommand === "publish") {
-        await printJson(await client.post(`/flows/${requiredValue(flowId, "flow-id")}/publish`));
+        const id = requiredValue(flowId, "flow-id");
+        const published = await client.post(`/flows/${id}/publish`);
+        if (booleanFlag(flags, "wait")) {
+            await printJson(await waitUntilPublished(client, id));
+            return;
+        }
+        await printJson(published);
         return;
     }
     if (subcommand === "send") {
@@ -423,6 +691,73 @@ async function handleFlows(client, subcommand, rest, flags) {
     // `flows test` is handled before client creation (no API key needed).
     throw new Error("Usage: wabery flows list|get|publish|send|test");
 }
+/**
+ * Poll a flow until Meta reports PUBLISHED (sendable), or throw with the rejection
+ * reason on a terminal BLOCKED/DEPRECATED state or timeout. Publishing surfaces most
+ * validation errors synchronously; this covers Meta's short review window.
+ */
+async function waitUntilPublished(client, flowId, { timeoutMs = 120_000, intervalMs = 3_000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const flow = (await client.get(`/flows/${flowId}`));
+        const status = flow.meta_status ?? flow.status ?? null;
+        if (status === "PUBLISHED")
+            return flow;
+        if (status === "BLOCKED" || status === "DEPRECATED") {
+            throw new Error(`Flow ${flowId} is ${status} and cannot be published`);
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for flow ${flowId} to become publishable (last status: ${status ?? "unknown"})`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+/**
+ * Print a ready-to-paste env block for a project. Pulls project id, the authorized
+ * channel id, API key (from your CLI config / shell), and base URL. The webhook
+ * signing secret is never returned by the API for security — paste it from the
+ * dashboard (Project → Webhooks).
+ */
+async function handleEnv(client, flags) {
+    let projectId = stringFlag(flags, "project-id");
+    let channelId = stringFlag(flags, "channel-id");
+    if (!projectId) {
+        const projects = (await client.get("/projects"));
+        projectId = projects.data?.[0]?.project_id ?? projects.data?.[0]?.id;
+    }
+    // Single GET reveals webhook_url + webhook_secret (the list never does).
+    let project;
+    if (projectId) {
+        project = (await client.get(`/projects/${projectId}`));
+    }
+    if (!channelId) {
+        channelId =
+            project?.channel_id ?? project?.enrollment_channel?.id ?? undefined;
+    }
+    if (!channelId) {
+        const channels = (await client.get("/channels"));
+        channelId = channels.data?.[0]?.channel_id ?? channels.data?.[0]?.id;
+    }
+    const cred = findCredentialByProject(client.projectId ?? projectId ?? "");
+    const apiKey = stringFlag(flags, "api-key") ??
+        process.env.WABERY_API_KEY ??
+        cred?.apiKey ??
+        "wab_live_...";
+    const baseUrl = stringFlag(flags, "base-url") ??
+        process.env.WABERY_BASE_URL ??
+        cred?.baseUrl ??
+        "https://api.wabery.com/v1";
+    const lines = [
+        `WABERY_API_KEY=${apiKey}`,
+        `WABERY_BASE_URL=${baseUrl}`,
+        `WABERY_PROJECT_ID=${projectId ?? "<no project found>"}`,
+        `WABERY_CHANNEL_ID=${channelId ?? "<no channel found>"}`,
+    ];
+    if (project?.webhook_url)
+        lines.push(`WABERY_WEBHOOK_URL=${project.webhook_url}`);
+    lines.push(`WABERY_WEBHOOK_SECRET=${project?.webhook_secret ?? ""}`);
+    await printText(`${lines.join("\n")}\n`);
+}
 /** Sign a body the same way Wabery does: `sha256=<hex>` HMAC-SHA256. */
 function signBody(secret, body) {
     return `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
@@ -475,6 +810,11 @@ async function testDataExchange(flags) {
     await postSigned(url, secret, body);
 }
 async function postSigned(url, secret, body) {
+    const { status, statusText, text } = await postSignedRaw(url, secret, body);
+    await printText(`→ POST ${url}\n${body}\n`);
+    await printText(`← ${status} ${statusText}\n${text}`);
+}
+async function postSignedRaw(url, secret, body) {
     const response = await fetch(url, {
         method: "POST",
         headers: {
@@ -483,9 +823,75 @@ async function postSigned(url, secret, body) {
         },
         body,
     });
-    const text = await response.text();
-    await printText(`→ POST ${url}\n${body}\n`);
-    await printText(`← ${response.status} ${response.statusText}\n${text}`);
+    return {
+        status: response.status,
+        statusText: response.statusText,
+        text: await response.text(),
+    };
+}
+/**
+ * Walk a whole data-exchange flow locally, then fire the completion webhook — the full
+ * journey (open → field changes → branch → submit) without a deploy or Meta publish.
+ *
+ * wabery flows simulate --url <data_exchange_url> --secret <s> \
+ *   [--webhook-url <flow.completed target>] \
+ *   [--steps '[{"action":"INIT"},{"action":"data_exchange","screen":"SELECT","data":{"workspace":"ws_1"}}]'] \
+ *   [--submission '{"workspace":"ws_1","project":"proj_a"}']
+ */
+async function simulateFlow(flags) {
+    const url = requiredStringFlag(flags, "url");
+    const secret = requiredStringFlag(flags, "secret");
+    const webhookUrl = stringFlag(flags, "webhook-url");
+    const identity = {
+        flow_token: stringFlag(flags, "flow-token") ?? "sim_flow_token",
+        flow_id: stringFlag(flags, "flow-id") ?? "sim_flow_id",
+        agent_id: stringFlag(flags, "agent-id") ?? "sim_agent_id",
+        organization_id: stringFlag(flags, "organization-id") ?? "sim_org_id",
+        contact_id: stringFlag(flags, "contact-id") ?? "sim_contact_id",
+        contact_reference: stringFlag(flags, "contact-reference") ?? null,
+        from: stringFlag(flags, "from") ?? null,
+    };
+    const steps = (optionalJsonFlag(flags, "steps") ?? [
+        { action: "INIT" },
+    ]);
+    if (!Array.isArray(steps)) {
+        throw new Error("--steps must be a JSON array of { action, screen, data }");
+    }
+    for (const [index, step] of steps.entries()) {
+        const body = JSON.stringify({
+            action: step.action ?? "data_exchange",
+            screen: step.screen ?? null,
+            data: step.data ?? {},
+            ...identity,
+        });
+        const res = await postSignedRaw(url, secret, body);
+        await printText(`step ${index + 1}/${steps.length} · ${step.action ?? "data_exchange"}${step.screen ? ` → ${step.screen}` : ""}\n  ← ${res.status} ${res.statusText}: ${res.text}\n`);
+        if (res.status >= 400) {
+            throw new Error(`data-exchange step ${index + 1} failed (${res.status})`);
+        }
+    }
+    if (webhookUrl) {
+        const event = JSON.stringify({
+            event: "flow.completed",
+            api_version: stringFlag(flags, "api-version") ?? "2026-06-18",
+            payload: {
+                object: "flow_submission",
+                flow_token: identity.flow_token,
+                flow_id: identity.flow_id,
+                agent_id: identity.agent_id,
+                organization_id: identity.organization_id,
+                contact_id: identity.contact_id,
+                contact_reference: identity.contact_reference,
+                from: identity.from,
+                valid: true,
+                submission: optionalJsonFlag(flags, "submission") ?? {},
+                submitted_at: new Date().toISOString(),
+            },
+            sentAt: new Date().toISOString(),
+        });
+        const res = await postSignedRaw(webhookUrl, secret, event);
+        await printText(`completion · flow.completed → ${webhookUrl}\n  ← ${res.status} ${res.statusText}: ${res.text}\n`);
+    }
 }
 function samplePayload(event) {
     if (event === "flow.completed") {
@@ -595,7 +1001,48 @@ function requiredValue(value, name) {
         throw new Error(`Missing required --${name}`);
     return value;
 }
+// Global output shaping, set from --id-only / --field at startup.
+let outputIdOnly = false;
+let outputField;
+const ID_FIELDS = [
+    "id",
+    "project_id",
+    "contact_id",
+    "flow_id",
+    "channel_id",
+    "flow_token",
+    "dispatch_id",
+];
+function extractPath(data, path) {
+    return path.split(".").reduce((node, key) => {
+        if (node && typeof node === "object") {
+            return node[key];
+        }
+        return undefined;
+    }, data);
+}
+function formatScalar(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
 async function printJson(data) {
+    if (outputIdOnly) {
+        const record = data && typeof data === "object"
+            ? data
+            : undefined;
+        const id = record
+            ? ID_FIELDS.map((key) => record[key]).find((v) => typeof v === "string")
+            : undefined;
+        process.stdout.write(`${formatScalar(id)}\n`);
+        return;
+    }
+    if (outputField) {
+        process.stdout.write(`${formatScalar(extractPath(data, outputField))}\n`);
+        return;
+    }
     process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
 }
 async function printText(text) {
@@ -618,19 +1065,38 @@ function redactSensitive(value) {
 function printHelp() {
     process.stdout.write(`Wabery CLI and MCP server
 
+Projects & keys:
+  API keys are scoped to a single project. Log into each project once; the CLI
+  stores one key per project and auto-selects the right one based on the repo.
+  A repo declares its project in a committed, secret-free .wabery.json
+  ({"project_id": "..."}); the CLI walks up from the current directory to find
+  it (falling back to wabery.config.json's project_id).
+
 Environment:
-  WABERY_API_KEY       API key override. Defaults to wabery login config.
+  WABERY_API_KEY       API key override (used directly, bypasses the store).
+  WABERY_PROJECT_ID    Select which stored project's key to use.
   WABERY_BASE_URL      Defaults to https://api.wabery.com/v1.
   WABERY_API_VERSION   Optional dated API version.
 
 Global flags:
   --api-key <key>      Override WABERY_API_KEY.
+  --project-id <id>    Select which stored project's key to use.
   --base-url <url>     Override WABERY_BASE_URL.
   --api-version <ver>  Override WABERY_API_VERSION.
+  --id-only            Print just the result id (for shell: ID=$(wabery ... --id-only)).
+  --field <dot.path>   Print just one field, e.g. --field webhook_secret.
+
+Getting started:
+  wabery login                           # log into a project (stores its key)
+  wabery whoami                          # active key (masked), org, project
+  wabery init [--name "My project"]      # scaffold .env.wabery + wabery.config.json + handler
 
 Authentication:
-  wabery login
+  wabery login                           # add/refresh the current project's key
   wabery login --no-open
+  wabery use <project-id-or-name>        # bind this repo to a logged-in project
+  wabery logout [--project <id|name>]    # remove one stored key
+  wabery logout --all                    # remove every stored key
   Config file: ${getConfigPath()}
 
 MCP:
@@ -642,6 +1108,7 @@ MCP:
 
 Diagnostics:
   wabery doctor
+  wabery env --project-id <project_id>   # ready-to-paste env block
 
 Config:
   wabery config schema
@@ -654,7 +1121,10 @@ Config:
 
 Projects and contacts:
   wabery projects list
-  wabery projects create --name "Demo"
+  wabery projects get <project_id>                 # reveals webhook_secret
+  wabery projects ensure --name "Demo"             # idempotently configure the key's scoped project
+  wabery projects update <project_id> [--name <n>] [--webhook-url <url>] [--webhook-signing-enabled true|false] [--webhook-secret <secret>]
+  wabery projects rotate-secret <project_id> [--webhook-secret <secret>]
   wabery contacts enroll --project-id <id> --phone +15555550123 --name "Jane" --opt-in '{"source":"checkout"}'
   wabery contacts get <contact_id>
   wabery contacts unenroll <contact_id>
@@ -672,12 +1142,13 @@ Templates, messages, and conversations:
 Flows:
   wabery flows list
   wabery flows get <flow_id>
-  wabery flows publish <flow_id>
+  wabery flows publish <flow_id> [--wait]
   wabery flows send <flow_id> --channel-id <id> --contact-id <contact_id>
 
 Local testing (sign + POST to your own endpoint, no deploy needed):
   wabery webhooks send-test --url http://localhost:3000/webhooks --secret <secret> [--event message.received] [--payload '<json>']
   wabery flows test --url http://localhost:3000/flow --secret <secret> [--action INIT] [--screen SELECT] [--data '<json>']
+  wabery flows simulate --url http://localhost:3000/flow --secret <secret> [--webhook-url <url>] [--steps '<json array>'] [--submission '<json>']
 `);
 }
 main().catch((error) => {