@getdial/cli 0.35.0 → 0.37.0

package/dist/cli.js

@@ -5,6 +5,9 @@ import { runDoctor } from "./commands/doctor.js";
 import { runBilling } from "./commands/billing.js";
 import { runSignup } from "./commands/signup.js";
 import { runOnboard } from "./commands/onboard.js";
+import { runAuthLogin } from "./commands/auth/login.js";
+import { runAuthVerifyOtp } from "./commands/auth/verify-otp.js";
+import { runAuthRegisterNumber } from "./commands/auth/register-number.js";
 import { runListen } from "./commands/listen/index.js";
 import { runListenInstall } from "./commands/listen/install.js";
 import { runListenUninstall } from "./commands/listen/uninstall.js";
@@ -62,21 +65,60 @@ program
     .description("Show account billing: balance, plan, per-number mode, recent activity. GET /api/v1/billing.")
     .option("--json", "machine-readable output")
     .action(async (opts) => process.exit(await runBilling({ json: !!opts.json })));
+if (!sandbox) {
+    const auth = program
+        .command("auth")
+        .description("Create an account or sign in: email OTP, then phone verification.");
+    auth
+        .command("login <email>")
+        .description("Request an email OTP for the given address.")
+        .option("--force", "overwrite any pending signup")
+        .option("--json", "machine-readable output")
+        .action(async (email, opts) => process.exit(await runAuthLogin(email, { force: !!opts.force, json: !!opts.json })));
+    auth
+        .command("register-number <phone>")
+        .description("Text a verification code to the phone number that will own the account.")
+        .option("--registration-id <id>", "explicit registration id (falls back to local pending signup)")
+        .option("--json", "machine-readable output")
+        .action(async (phone, opts) => process.exit(await runAuthRegisterNumber(phone, {
+        registrationId: opts.registrationId,
+        json: !!opts.json,
+    })));
+    auth
+        .command("verify-otp")
+        .description("Verify a one-time code — the emailed one, or with --number the texted one.")
+        .option("--code <code>", "the 6-digit OTP (omit if already signed in — the command just installs the --agent skill and skips verification)")
+        .option("--number", "verify the SMS code for a registered phone number instead of the email code")
+        .option("--verification-id <id>", "explicit verification id for the email step (falls back to local pending signup)")
+        .option("--registration-id <id>", "explicit registration id for --number (falls back to local pending signup)")
+        .option("--agent <name>", "install the Dial skill into the named agent's config dir. One of: claude-code, cursor, codex, opencode, pi, openclaw, nanoclaw, hermes. Repeatable.", (v, prev = []) => [...prev, v], [])
+        .option("--json", "machine-readable output")
+        .action(async (opts) => process.exit(await runAuthVerifyOtp({
+        verificationId: opts.verificationId,
+        registrationId: opts.registrationId,
+        code: opts.code,
+        number: !!opts.number,
+        agents: opts.agent,
+        json: !!opts.json,
+    })));
+}
+// DEPRECATED, kept registered so a stale skill gets a pointer rather than
+// commander's "unknown command". Both exit non-zero without doing anything.
 if (!sandbox)
     program
         .command("signup <email>")
-        .description("Request an email OTP for the given address.")
+        .description("DEPRECATED — use `dial auth login <email>`.")
         .option("--force", "overwrite any pending signup")
         .option("--json", "machine-readable output")
         .action(async (email, opts) => process.exit(await runSignup(email, { force: !!opts.force, json: !!opts.json })));
 if (!sandbox)
     program
         .command("onboard")
-        .description("Verify the OTP and finish onboarding.")
-        .option("--verification-id <id>", "explicit verification id (falls back to local pending signup)")
-        .option("--code <code>", "6-digit OTP from your email (omit if already signed in — the command just installs the --agent skill and skips verification)")
-        .option("--inbound-instruction <text>", "system prompt for inbound calls to your auto-provisioned number (required for a new account; ignored when signing in)")
-        .option("--agent <name>", "install the Dial skill into the named agent's config dir. One of: claude-code, cursor, codex, opencode, pi, openclaw, nanoclaw, hermes. Repeatable.", (v, prev = []) => [...prev, v], [])
+        .description("DEPRECATED — use `dial auth verify-otp --code <code>`.")
+        .option("--verification-id <id>", "no longer used")
+        .option("--code <code>", "no longer used")
+        .option("--inbound-instruction <text>", "no longer used")
+        .option("--agent <name>", "no longer used", (v, prev = []) => [...prev, v], [])
         .option("--json", "machine-readable output")
         .action(async (opts) => process.exit(await runOnboard({
         verificationId: opts.verificationId,

package/dist/commands/auth/login.js

@@ -0,0 +1,46 @@
+import { signup } from "../../lib/ops/account.js";
+import { isDialError } from "../../lib/ops/errors.js";
+export async function runAuthLogin(email, opts) {
+    try {
+        const { verificationId } = await signup({ email, force: opts.force });
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                verificationId,
+                email,
+                // Every step names the next one, so an agent never has to guess the flow.
+                nextCommand: "dial auth verify-otp --code <code>",
+            }));
+        }
+        else {
+            console.log(`OTP sent to ${email}.`);
+            console.log(`Run \`dial auth verify-otp --code <code>\` once you have it (verificationId is stored locally).`);
+        }
+        return 0;
+    }
+    catch (e) {
+        if (!isDialError(e))
+            throw e;
+        if (e.code === "pending_exists") {
+            const d = e.data ?? {};
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    ok: false,
+                    code: "pending_exists",
+                    verificationId: d.verificationId,
+                    email: d.email,
+                    ageSeconds: d.ageSeconds,
+                }));
+            }
+            else {
+                console.error(e.message);
+            }
+            return 3;
+        }
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: e.code, status: e.status, error: e.message }));
+        else
+            console.error(`login failed: ${e.message}`);
+        return 2;
+    }
+}

package/dist/commands/auth/register-number.js

@@ -0,0 +1,30 @@
+import { registerNumber } from "../../lib/ops/account.js";
+import { isDialError } from "../../lib/ops/errors.js";
+const NEXT_COMMAND = "dial auth verify-otp --number --code <code>";
+export async function runAuthRegisterNumber(phone, opts) {
+    try {
+        const { registrationId, phoneNumber } = await registerNumber({
+            registrationId: opts.registrationId,
+            phoneNumber: phone,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, registrationId, phoneNumber, nextCommand: NEXT_COMMAND }));
+        }
+        else {
+            console.log(`code sent to ${phoneNumber}.`);
+            console.log(`Ask the user to read it back, then run \`${NEXT_COMMAND}\`.`);
+        }
+        return 0;
+    }
+    catch (e) {
+        if (!isDialError(e))
+            throw e;
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: e.code, status: e.status, error: e.message }));
+        else
+            console.error(`register-number failed: ${e.message}`);
+        // A missing registration is the caller's sequencing mistake (1); anything else
+        // is a request failure (2).
+        return e.code === "no_pending_registration" ? 1 : 2;
+    }
+}

package/dist/commands/auth/verify-otp.js

@@ -0,0 +1,264 @@
+import { onboard, verifyNumber, installAgentSkills, } from "../../lib/ops/account.js";
+import { isDialError } from "../../lib/ops/errors.js";
+import { readAuth, readPendingSignup, authFilePath } from "../../lib/state.js";
+import { supervisorAvailability } from "../../lib/supervisor/index.js";
+import { baseUrl } from "../../lib/api.js";
+import { dashboardHint, dashboardUrl } from "../../lib/dashboard.js";
+function maskApiKey(key) {
+    return key.length >= 4 ? `sk_live_***${key.slice(-4)}` : "sk_live_***";
+}
+const LISTEN_QUESTION = "Install the background notification listening service?";
+const LISTEN_RATIONALE = "The background notification listening service runs on this machine and listens for notifications from Dial — SMS arrivals (2FA codes, replies) and call-ended notifications — so the agent on this machine learns about them in real time. " +
+    "Without it the agent is send-only: it can place outbound calls and send messages, but it has no way to know when something arrives at your Dial number. " +
+    "It can always be installed later with `dial listen install`.";
+const PRESENTATION_HINT = "When you ask the user, describe it as \"the background notification listening service.\" Don't expose technical details (launchd, plists, daemons, systemd units) — that's not how to talk about it to a non-technical user.";
+const FINALIZATION_HINT = 'To finalize onboarding, ask the user this question before continuing with any other task. If the user\'s original request was something else (e.g. "call X", "send Y"), briefly pause that task, ask the question, get an answer, then resume.';
+const REGISTER_NUMBER_COMMAND = "dial auth register-number <phone>";
+function printSkills(skills) {
+    for (const r of skills) {
+        if ("error" in r)
+            console.log(`  skill (${r.agent}):  failed — ${r.error}`);
+        else if (r.written)
+            console.log(`  skill (${r.agent}):  installed → ${r.path}`);
+        else if (r.unchanged)
+            console.log(`  skill (${r.agent}):  already up to date → ${r.path}`);
+    }
+}
+/** The account exists: report the key, the skills, and the listen-service offer. */
+function reportOnboarded(result, json) {
+    const { apiKey, accountId, phoneNumber, phoneNumberId, apiKeyPath, skills, supervisor } = result;
+    const masked = maskApiKey(apiKey);
+    if (json) {
+        console.log(JSON.stringify({
+            ok: true,
+            apiKeyFingerprint: apiKey.slice(-4),
+            apiKeyMasked: masked,
+            apiKeyPath,
+            accountId,
+            email: result.email,
+            phoneNumber,
+            phoneNumberId,
+            dashboardUrl: result.dashboardUrl,
+            listen: {
+                installed: false,
+                autoInstalled: false,
+                canInstall: supervisor.available,
+                unavailableReason: supervisor.available ? null : supervisor.reason,
+            },
+            skills,
+            agentHint: supervisor.available
+                ? {
+                    action: "ask_user",
+                    kind: "onboarding_finalization",
+                    question: LISTEN_QUESTION,
+                    rationale: LISTEN_RATIONALE,
+                    presentation: PRESENTATION_HINT,
+                    finalizationNote: FINALIZATION_HINT,
+                    useStructuredToolIfAvailable: true,
+                    onYes: "dial listen install",
+                    onNo: null,
+                }
+                : {
+                    action: "skip",
+                    kind: "listen_install_unavailable",
+                    reason: supervisor.reason,
+                    note: "No user-level service supervisor on this machine (sandbox/container/CI). Skip the install offer and continue with the original task. Inbound events are still reachable via `dial wait-for` (long-poll); only the always-on background listener and `dial local-target` fan-out are unavailable here.",
+                },
+        }));
+        return 0;
+    }
+    console.log("onboarded.");
+    console.log(`  api key:      ${masked}   (saved to ${apiKeyPath})`);
+    if (phoneNumber)
+        console.log(`  phone number: ${phoneNumber}`);
+    printSkills(skills);
+    // Part of the summary, deliberately above the finalization block so that block
+    // stays the last thing an agent reads.
+    console.log(dashboardHint(result.dashboardUrl, result.email));
+    console.log(``);
+    if (!supervisor.available) {
+        console.log(`listen service: not available on this machine (${supervisor.reason}).`);
+        console.log(`Skipping the install offer. Inbound events still work via \`dial wait-for\` (long-poll);`);
+        console.log(`only the always-on background listener and \`dial local-target\` fan-out are unavailable here.`);
+        return 0;
+    }
+    console.log(`Onboarding finalization (required):`);
+    console.log(``);
+    console.log(FINALIZATION_HINT);
+    console.log(``);
+    console.log(`Ask the user:`);
+    console.log(``);
+    console.log(`    "${LISTEN_QUESTION}"`);
+    console.log(``);
+    console.log(`Background: ${LISTEN_RATIONALE}`);
+    console.log(``);
+    console.log(`Phrasing rules: ${PRESENTATION_HINT}`);
+    console.log(``);
+    console.log(`Use your structured ask-user / clarification tool if you have one;`);
+    console.log(`otherwise ask in your regular reply and wait for the answer.`);
+    console.log(``);
+    console.log(`After the user answers:`);
+    console.log(`  yes → run \`dial listen install\`, then resume the original task.`);
+    console.log(`  no  → resume the original task. They can install later with \`dial listen install\`.`);
+    return 0;
+}
+/** The email is verified but the account still needs a phone number. */
+function reportPendingPhone(result, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            ok: true,
+            pendingPhone: true,
+            registrationId: result.registrationId,
+            email: result.email,
+            skills: result.skills,
+            nextCommand: REGISTER_NUMBER_COMMAND,
+            agentHint: {
+                action: "ask_user",
+                kind: "phone_number_required",
+                question: "What phone number should this Dial account be registered to?",
+                rationale: "Creating a Dial account requires a verified phone number as well as a verified email. Dial texts a 6-digit code to the number, and the user reads it back. The number is linked to the account permanently — a number can register only one Dial account — so it should be one the user keeps. It must be able to receive SMS, and a Dial number cannot be used.",
+                presentation: "Ask for the number in international form including the country code. Don't invent one, and don't reuse a Dial number.",
+                useStructuredToolIfAvailable: true,
+                onAnswer: REGISTER_NUMBER_COMMAND,
+            },
+        }));
+        return 0;
+    }
+    console.log("email verified — a phone number is still required.");
+    printSkills(result.skills);
+    console.log(``);
+    console.log(`Creating an account needs a verified phone number as well as a verified email.`);
+    console.log(`No API key has been issued yet.`);
+    console.log(``);
+    console.log(`Ask the user for a phone number that can receive SMS, then run:`);
+    console.log(``);
+    console.log(`    ${REGISTER_NUMBER_COMMAND}`);
+    console.log(``);
+    console.log(`That number is linked to the account permanently — a number can register only one`);
+    console.log(`Dial account — so use one the user keeps. A Dial number can't be used here.`);
+    console.log(``);
+    console.log(`Dial texts a 6-digit code to it; then run:`);
+    console.log(``);
+    console.log(`    dial auth verify-otp --number --code <code>`);
+    return 0;
+}
+/** No --code on a machine that's already signed in: just install the skills. */
+function reportAlreadySignedIn(opts) {
+    const auth = readAuth();
+    if (!auth) {
+        const message = "Not signed in. Run `dial auth login <email>` first, then re-run with --code from your inbox.";
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: "not_signed_in", error: message }));
+        else
+            console.error(message);
+        return 1;
+    }
+    const skills = installAgentSkills(opts.agents);
+    const supervisor = supervisorAvailability();
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            alreadySignedIn: true,
+            apiKeyFingerprint: auth.apiKey.slice(-4),
+            apiKeyMasked: maskApiKey(auth.apiKey),
+            apiKeyPath: authFilePath(),
+            accountId: auth.accountId,
+            email: auth.email || null,
+            phoneNumber: auth.phoneNumber ?? null,
+            phoneNumberId: auth.phoneNumberId ?? null,
+            dashboardUrl: dashboardUrl(baseUrl()),
+            listen: {
+                installed: false,
+                autoInstalled: false,
+                canInstall: supervisor.available,
+                unavailableReason: supervisor.available ? null : supervisor.reason,
+            },
+            skills,
+            agentHint: {
+                action: "skip",
+                kind: "already_signed_in",
+                note: "Account is already signed in; verification was skipped and only the requested --agent skills were installed.",
+            },
+        }));
+    }
+    else {
+        console.log(`already signed in as ${auth.email || "(unknown email)"} — skipped verification.`);
+        console.log(`  api key: ${maskApiKey(auth.apiKey)}   (saved at ${authFilePath()})`);
+        printSkills(skills);
+        console.log(dashboardHint(dashboardUrl(baseUrl()), auth.email || null));
+    }
+    return 0;
+}
+function reportFailure(e, opts, label) {
+    if (!isDialError(e))
+        throw e;
+    if (e.code === "no_pending_signup" || e.code === "no_pending_registration") {
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: e.code, error: e.message }));
+        else
+            console.error(e.message);
+        return 1;
+    }
+    if (e.code === "verify_failed") {
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: "verify_failed", status: e.status, error: e.message }));
+        else
+            console.error(`${label} failed: ${e.message}`);
+        // 401 is a wrong/expired code (the user's problem); anything else is ours.
+        return e.status === 401 ? 1 : 2;
+    }
+    // missing_api_key
+    if (opts.json)
+        console.log(JSON.stringify({ ok: false, code: e.code, error: e.message }));
+    else
+        console.error(`${label} failed: ${e.message}`);
+    return 2;
+}
+export async function runAuthVerifyOtp(opts) {
+    // ── SMS code: the step that creates the account ──
+    if (opts.number) {
+        if (!opts.code) {
+            const message = "A --code is required with --number. Check the text message.";
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, code: "code_required", error: message }));
+            else
+                console.error(message);
+            return 1;
+        }
+        if (!opts.registrationId && !readPendingSignup()?.registrationId) {
+            const message = `No phone number awaiting verification. Run \`${REGISTER_NUMBER_COMMAND}\` first.`;
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, code: "no_pending_registration", error: message }));
+            else
+                console.error(message);
+            return 1;
+        }
+        try {
+            const result = await verifyNumber({
+                registrationId: opts.registrationId,
+                code: opts.code,
+                agents: opts.agents,
+            });
+            return reportOnboarded(result, !!opts.json);
+        }
+        catch (e) {
+            return reportFailure(e, opts, "verify-otp --number");
+        }
+    }
+    // ── Email code ──
+    if (!opts.code)
+        return reportAlreadySignedIn(opts);
+    try {
+        const result = await onboard({
+            verificationId: opts.verificationId,
+            code: opts.code,
+            agents: opts.agents,
+        });
+        return result.pendingPhone
+            ? reportPendingPhone(result, !!opts.json)
+            : reportOnboarded(result, !!opts.json);
+    }
+    catch (e) {
+        return reportFailure(e, opts, "verify-otp");
+    }
+}

package/dist/commands/onboard.js

@@ -1,217 +1,38 @@
-import { onboard } from "../lib/ops/account.js";
-import { isDialError } from "../lib/ops/errors.js";
-import { readAuth, authFilePath } from "../lib/state.js";
-import { installSkill, isSupportedAgent, SUPPORTED_AGENTS, } from "../lib/skill-install.js";
-import { supervisorAvailability } from "../lib/supervisor/index.js";
-import { baseUrl } from "../lib/api.js";
-import { dashboardHint, dashboardUrl } from "../lib/dashboard.js";
-function maskApiKey(key) {
-    return key.length >= 4 ? `sk_live_***${key.slice(-4)}` : "sk_live_***";
-}
-// Install skills for each requested agent — mirrors the loop inside
-// `onboard()` in ops/account.ts. Used by the signed-in-only branch below,
-// which skips OTP verification entirely.
-function installAgentSkills(agents) {
-    const skills = [];
-    for (const requested of agents) {
-        if (!isSupportedAgent(requested)) {
-            skills.push({
-                agent: requested,
-                error: `unknown agent "${requested}". Supported: ${SUPPORTED_AGENTS.join(", ")}.`,
-            });
-            continue;
-        }
-        try {
-            skills.push(installSkill(requested));
-        }
-        catch (err) {
-            skills.push({ agent: requested, error: err instanceof Error ? err.message : String(err) });
-        }
-    }
-    return skills;
-}
-const LISTEN_QUESTION = "Install the background notification listening service?";
-const LISTEN_RATIONALE = "The background notification listening service runs on this machine and listens for notifications from Dial — SMS arrivals (2FA codes, replies) and call-ended notifications — so the agent on this machine learns about them in real time. " +
-    "Without it the agent is send-only: it can place outbound calls and send messages, but it has no way to know when something arrives at your Dial number. " +
-    "It can always be installed later with `dial listen install`.";
-const PRESENTATION_HINT = "When you ask the user, describe it as \"the background notification listening service.\" Don't expose technical details (launchd, plists, daemons, systemd units) — that's not how to talk about it to a non-technical user.";
-const FINALIZATION_HINT = 'To finalize onboarding, ask the user this question before continuing with any other task. If the user\'s original request was something else (e.g. "call X", "send Y"), briefly pause that task, ask the question, get an answer, then resume.';
+/**
+ * DEPRECATED. `dial onboard` was replaced by `dial auth verify-otp`, and creating an
+ * account now also requires verifying a phone number.
+ *
+ * The command stays registered rather than being deleted so a stale skill or cached
+ * doc gets an instruction it can act on, instead of commander's bare "unknown
+ * command". Exits non-zero: nothing was done.
+ */
+const REPLACEMENT = "dial auth verify-otp --code <code>";
+const PHONE_NOTE = "Creating an account now also requires a verified phone number: after the email code, run `dial auth register-number <phone>`, then `dial auth verify-otp --number --code <code>`.";
+const INSTRUCTION_NOTE = "`--inbound-instruction` no longer exists — a new number starts with the default prompt; change it with `dial number set`.";
 export async function runOnboard(opts) {
-    // Skill-install-only branch: when --code isn't supplied, we can't (and shouldn't)
-    // re-verify — but if the machine is already signed in, the useful thing to do
-    // is just install any --agent skills the caller asked for. This is what agents
-    // following the docs on an already-onboarded account hit when they read the
-    // integration page: signup is a no-op, all that's left is the skill drop-in.
-    if (!opts.code) {
-        const auth = readAuth();
-        if (!auth) {
-            const message = "Not signed in. Run `dial signup <email>` first, then re-run with --code from your inbox.";
-            if (opts.json)
-                console.log(JSON.stringify({ ok: false, code: "not_signed_in", error: message }));
-            else
-                console.error(message);
-            return 1;
-        }
-        const skills = installAgentSkills(opts.agents ?? []);
-        const supervisor = supervisorAvailability();
-        if (opts.json) {
-            console.log(JSON.stringify({
-                ok: true,
-                alreadySignedIn: true,
-                apiKeyFingerprint: auth.apiKey.slice(-4),
-                apiKeyMasked: maskApiKey(auth.apiKey),
-                apiKeyPath: authFilePath(),
-                accountId: auth.accountId,
-                email: auth.email || null,
-                phoneNumber: auth.phoneNumber ?? null,
-                phoneNumberId: auth.phoneNumberId ?? null,
-                dashboardUrl: dashboardUrl(baseUrl()),
-                listen: {
-                    installed: false,
-                    autoInstalled: false,
-                    canInstall: supervisor.available,
-                    unavailableReason: supervisor.available ? null : supervisor.reason,
-                },
-                skills,
-                agentHint: {
-                    action: "skip",
-                    kind: "already_signed_in",
-                    note: "Account is already signed in; verification was skipped and only the requested --agent skills were installed.",
-                },
-            }));
-        }
-        else {
-            console.log(`already signed in as ${auth.email || "(unknown email)"} — skipped verification.`);
-            console.log(`  api key: ${maskApiKey(auth.apiKey)}   (saved at ${authFilePath()})`);
-            for (const r of skills) {
-                if ("error" in r)
-                    console.log(`  skill (${r.agent}):  failed — ${r.error}`);
-                else if (r.written)
-                    console.log(`  skill (${r.agent}):  installed → ${r.path}`);
-                else if (r.unchanged)
-                    console.log(`  skill (${r.agent}):  already up to date → ${r.path}`);
-            }
-            console.log(dashboardHint(dashboardUrl(baseUrl()), auth.email || null));
-        }
-        return 0;
-    }
-    let result;
-    try {
-        result = await onboard({
-            verificationId: opts.verificationId,
-            code: opts.code,
-            inboundInstruction: opts.inboundInstruction,
-            agents: opts.agents,
-        });
-    }
-    catch (e) {
-        if (!isDialError(e))
-            throw e;
-        if (e.code === "no_pending_signup") {
-            if (opts.json)
-                console.log(JSON.stringify({ ok: false, code: "no_pending_signup" }));
-            else
-                console.error(e.message);
-            return 1;
-        }
-        if (e.code === "verify_failed") {
-            if (opts.json)
-                console.log(JSON.stringify({ ok: false, code: "verify_failed", status: e.status, error: e.message }));
-            else
-                console.error(`onboard failed: ${e.message}`);
-            return e.status === 401 ? 1 : 2;
-        }
-        // missing_api_key
-        if (opts.json)
-            console.log(JSON.stringify({ ok: false, code: "missing_api_key", error: e.message }));
-        else
-            console.error(`onboard failed: ${e.message}`);
-        return 2;
-    }
-    const { apiKey, accountId, email, phoneNumber, phoneNumberId, apiKeyPath, skills, supervisor } = result;
-    const masked = maskApiKey(apiKey);
+    const message = `\`dial onboard\` has been replaced by \`${REPLACEMENT}\`. Nothing was done.`;
+    const instructionNote = opts.inboundInstruction ? INSTRUCTION_NOTE : undefined;
     if (opts.json) {
         console.log(JSON.stringify({
-            ok: true,
-            apiKeyFingerprint: apiKey.slice(-4),
-            apiKeyMasked: masked,
-            apiKeyPath,
-            accountId,
-            email,
-            phoneNumber,
-            phoneNumberId,
-            dashboardUrl: result.dashboardUrl,
-            listen: {
-                installed: false,
-                autoInstalled: false,
-                canInstall: supervisor.available,
-                unavailableReason: supervisor.available ? null : supervisor.reason,
-            },
-            skills,
-            agentHint: supervisor.available
-                ? {
-                    action: "ask_user",
-                    kind: "onboarding_finalization",
-                    question: LISTEN_QUESTION,
-                    rationale: LISTEN_RATIONALE,
-                    presentation: PRESENTATION_HINT,
-                    finalizationNote: FINALIZATION_HINT,
-                    useStructuredToolIfAvailable: true,
-                    onYes: "dial listen install",
-                    onNo: null,
-                }
-                : {
-                    action: "skip",
-                    kind: "listen_install_unavailable",
-                    reason: supervisor.reason,
-                    note: "No user-level service supervisor on this machine (sandbox/container/CI). Skip the install offer and continue with the original task. Inbound events are still reachable via `dial wait-for` (long-poll); only the always-on background listener and `dial local-target` fan-out are unavailable here.",
-                },
+            ok: false,
+            code: "deprecated_command",
+            error: message,
+            replacement: REPLACEMENT,
+            note: PHONE_NOTE,
+            ...(instructionNote ? { instructionNote } : {}),
         }));
     }
     else {
-        console.log("onboarded.");
-        console.log(`  api key:      ${masked}   (saved to ${apiKeyPath})`);
-        if (phoneNumber)
-            console.log(`  phone number: ${phoneNumber}`);
-        for (const r of skills) {
-            if ("error" in r) {
-                console.log(`  skill (${r.agent}):  failed — ${r.error}`);
-            }
-            else if (r.written) {
-                console.log(`  skill (${r.agent}):  installed → ${r.path}`);
-            }
-            else if (r.unchanged) {
-                console.log(`  skill (${r.agent}):  already up to date → ${r.path}`);
-            }
-        }
-        // Part of the summary, deliberately above the finalization block so that
-        // block stays the last thing an agent reads.
-        console.log(dashboardHint(result.dashboardUrl, email));
-        console.log(``);
-        if (!supervisor.available) {
-            console.log(`listen service: not available on this machine (${supervisor.reason}).`);
-            console.log(`Skipping the install offer. Inbound events still work via \`dial wait-for\` (long-poll);`);
-            console.log(`only the always-on background listener and \`dial local-target\` fan-out are unavailable here.`);
-            return 0;
+        console.error(message);
+        console.error(``);
+        console.error(`Run instead:`);
+        console.error(`    dial auth verify-otp${opts.code ? ` --code ${opts.code}` : ""}`);
+        console.error(``);
+        console.error(PHONE_NOTE);
+        if (instructionNote) {
+            console.error(``);
+            console.error(instructionNote);
         }
-        console.log(`Onboarding finalization (required):`);
-        console.log(``);
-        console.log(FINALIZATION_HINT);
-        console.log(``);
-        console.log(`Ask the user:`);
-        console.log(``);
-        console.log(`    "${LISTEN_QUESTION}"`);
-        console.log(``);
-        console.log(`Background: ${LISTEN_RATIONALE}`);
-        console.log(``);
-        console.log(`Phrasing rules: ${PRESENTATION_HINT}`);
-        console.log(``);
-        console.log(`Use your structured ask-user / clarification tool if you have one;`);
-        console.log(`otherwise ask in your regular reply and wait for the answer.`);
-        console.log(``);
-        console.log(`After the user answers:`);
-        console.log(`  yes → run \`dial listen install\`, then resume the original task.`);
-        console.log(`  no  → resume the original task. They can install later with \`dial listen install\`.`);
     }
-    return 0;
+    return 2;
 }

package/dist/commands/signup.js

@@ -1,41 +1,27 @@
-import { signup } from "../lib/ops/account.js";
-import { isDialError } from "../lib/ops/errors.js";
+/**
+ * DEPRECATED. `dial signup` was replaced by `dial auth login`.
+ *
+ * The command stays registered rather than being deleted so that a stale skill or
+ * cached doc gets an instruction it can act on, instead of commander's bare
+ * "unknown command". Exits non-zero: nothing was done.
+ */
+const REPLACEMENT = "dial auth login <email>";
 export async function runSignup(email, opts) {
-    try {
-        const { verificationId } = await signup({ email, force: opts.force });
-        if (opts.json) {
-            console.log(JSON.stringify({ ok: true, verificationId, email }));
-        }
-        else {
-            console.log(`OTP sent to ${email}.`);
-            console.log(`Run \`dial onboard --code <code>\` once you have it (verificationId is stored locally).`);
-        }
-        return 0;
+    const message = `\`dial signup\` has been replaced by \`${REPLACEMENT}\`. Nothing was sent.`;
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            code: "deprecated_command",
+            error: message,
+            replacement: REPLACEMENT,
+            email,
+        }));
     }
-    catch (e) {
-        if (!isDialError(e))
-            throw e;
-        if (e.code === "pending_exists") {
-            const d = e.data ?? {};
-            if (opts.json) {
-                console.log(JSON.stringify({
-                    ok: false,
-                    code: "pending_exists",
-                    verificationId: d.verificationId,
-                    email: d.email,
-                    ageSeconds: d.ageSeconds,
-                }));
-            }
-            else {
-                console.error(e.message);
-            }
-            return 3;
-        }
-        // signup_failed
-        if (opts.json)
-            console.log(JSON.stringify({ ok: false, code: e.code, status: e.status, error: e.message }));
-        else
-            console.error(`signup failed: ${e.message}`);
-        return 2;
+    else {
+        console.error(message);
+        console.error(``);
+        console.error(`Run instead:`);
+        console.error(`    dial auth login ${email}`);
     }
+    return 2;
 }

package/dist/lib/api.js

@@ -1,7 +1,7 @@
 import { request, fetch as undiciFetch, FormData as UndiciFormData, setGlobalDispatcher, EnvHttpProxyAgent, } from "undici";
 import { logger } from "./log.js";
-import { VERSION } from "./version.js";
 import { refParamsHeader } from "./ref-params.js";
+import { userAgent } from "./user-agent.js";
 // Route this package's undici requests through HTTP(S)_PROXY when one is set.
 // The `undici` npm package keeps its OWN global dispatcher, which — unlike
 // Node's built-in fetch (wired by NODE_USE_ENV_PROXY) — ignores the proxy env
@@ -19,9 +19,6 @@ if (process.env.HTTPS_PROXY ||
 // check) — Node's global FormData would be coerced to a text/plain string.
 export { UndiciFormData as ApiFormData };
 const DEFAULT_BASE = "https://api.getdial.ai";
-// Identifies the CLI on every request, so server-side request logs attribute
-// provisioning (and everything else) to the client + version that made the call.
-const USER_AGENT = `@getdial/cli/${VERSION}`;
 export function baseUrl() {
     return process.env.DIAL_API_URL ?? DEFAULT_BASE;
 }
@@ -69,7 +66,7 @@ async function apiRequest(method, path, body, apiKey, extraHeaders) {
     const url = `${baseUrl()}${path}`;
     const headers = applyRefParamsHeader({
         "content-type": "application/json",
-        "user-agent": USER_AGENT,
+        "user-agent": userAgent(),
         ...(extraHeaders ?? {}),
     });
     if (apiKey)
@@ -99,7 +96,7 @@ async function sendMultipart(method, path, form, apiKey) {
     // No content-type here on purpose: undici's fetch sets the multipart boundary.
     // The user-agent must still be set (server request logs key off it — the
     // POST path once regressed by dropping it, see the git history).
-    const headers = applyRefParamsHeader({ "user-agent": USER_AGENT });
+    const headers = applyRefParamsHeader({ "user-agent": userAgent() });
     if (apiKey)
         headers.authorization = `Bearer ${apiKey}`;
     try {

package/dist/lib/ops/account.js

@@ -117,6 +117,28 @@ export async function signup(opts) {
     });
     return { verificationId: res.data.verificationId, email: opts.email };
 }
+/** Install the Dial skill into each requested agent's config directory. A local
+ *  side effect: it writes files and needs no API key, so it runs whether or not
+ *  the signup has produced an account yet. */
+export function installAgentSkills(agents) {
+    const skills = [];
+    for (const requested of agents ?? []) {
+        if (!isSupportedAgent(requested)) {
+            skills.push({
+                agent: requested,
+                error: `unknown agent "${requested}". Supported: ${SUPPORTED_AGENTS.join(", ")}.`,
+            });
+            continue;
+        }
+        try {
+            skills.push(installSkill(requested));
+        }
+        catch (err) {
+            skills.push({ agent: requested, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return skills;
+}
 export async function onboard(opts) {
     let verificationId = opts.verificationId;
     let email = null;
@@ -131,10 +153,27 @@ export async function onboard(opts) {
     const res = await apiPost("/api/v1/auth/verify", {
         verificationId,
         code: opts.code,
-        ...(opts.inboundInstruction ? { inboundInstruction: opts.inboundInstruction } : {}),
     });
     if (!res.ok)
         throw new DialError("verify_failed", res.error, res.status);
+    // Two outcomes. A registrationId means the email is verified but the account
+    // needs a verified phone number first — no key is issued yet, so the authed side
+    // effects (saving it, offering the listen service) have nothing to do.
+    if (res.data.registrationId) {
+        const pending = readPendingSignup();
+        writePendingSignup({
+            verificationId,
+            email: email ?? pending?.email ?? "",
+            createdAt: pending?.createdAt ?? new Date().toISOString(),
+            registrationId: res.data.registrationId,
+        });
+        return {
+            pendingPhone: true,
+            registrationId: res.data.registrationId,
+            email: email ?? pending?.email ?? null,
+            skills: installAgentSkills(opts.agents),
+        };
+    }
     const apiKey = res.data.apiKey ?? null;
     if (!apiKey || !res.data.accountId) {
         throw new DialError("missing_api_key", "backend returned no apiKey");
@@ -147,22 +186,7 @@ export async function onboard(opts) {
         phoneNumberId: res.data.phoneNumberId ?? null,
     });
     clearPendingSignup();
-    const skills = [];
-    for (const requested of opts.agents ?? []) {
-        if (!isSupportedAgent(requested)) {
-            skills.push({
-                agent: requested,
-                error: `unknown agent "${requested}". Supported: ${SUPPORTED_AGENTS.join(", ")}.`,
-            });
-            continue;
-        }
-        try {
-            skills.push(installSkill(requested));
-        }
-        catch (err) {
-            skills.push({ agent: requested, error: err instanceof Error ? err.message : String(err) });
-        }
-    }
+    const skills = installAgentSkills(opts.agents);
     return {
         apiKey,
         apiKeyFingerprint: apiKey.slice(-4),
@@ -176,3 +200,68 @@ export async function onboard(opts) {
         supervisor: supervisorAvailability(),
     };
 }
+// ── Phone verification ───────────────────────────────────────────────────────
+/**
+ * Send a verification code to the phone number that will own the account.
+ *
+ * The number is passed through as typed: the server canonicalizes it and returns
+ * the E.164 form, which is what we store and display. Deliberately no local
+ * validation — libphonenumber throws under the CLI's test loader, and duplicating
+ * the rule would only let the two disagree.
+ */
+export async function registerNumber(opts) {
+    const registrationId = opts.registrationId ?? readPendingSignup()?.registrationId;
+    if (!registrationId) {
+        throw new DialError("no_pending_registration", "No signup awaiting a phone number. Run `dial auth login <email>` and `dial auth verify-otp --code <code>` first.");
+    }
+    const res = await apiPost("/api/v1/auth/register-number", { registrationId, phoneNumber: opts.phoneNumber });
+    if (!res.ok)
+        throw new DialError("register_number_failed", res.error, res.status);
+    const pending = readPendingSignup();
+    if (pending) {
+        writePendingSignup({ ...pending, registrationId, ownerPhoneNumber: res.data.phoneNumber });
+    }
+    return { registrationId, phoneNumber: res.data.phoneNumber };
+}
+/**
+ * Submit the SMS code, which creates the account. Same result shape as onboard's
+ * account outcome, so both paths finish identically — key saved, skills installed,
+ * listen service offered.
+ */
+export async function verifyNumber(opts) {
+    const pending = readPendingSignup();
+    const registrationId = opts.registrationId ?? pending?.registrationId;
+    if (!registrationId) {
+        throw new DialError("no_pending_registration", "No phone number awaiting verification. Run `dial auth register-number <phone>` first.");
+    }
+    const res = await apiPost("/api/v1/auth/verify-number", {
+        registrationId,
+        code: opts.code,
+    });
+    if (!res.ok)
+        throw new DialError("verify_failed", res.error, res.status);
+    const apiKey = res.data.apiKey ?? null;
+    if (!apiKey || !res.data.accountId) {
+        throw new DialError("missing_api_key", "backend returned no apiKey");
+    }
+    writeAuth({
+        apiKey,
+        accountId: res.data.accountId,
+        email: pending?.email ?? "",
+        phoneNumber: res.data.phoneNumber ?? null,
+        phoneNumberId: res.data.phoneNumberId ?? null,
+    });
+    clearPendingSignup();
+    return {
+        apiKey,
+        apiKeyFingerprint: apiKey.slice(-4),
+        apiKeyPath: authFilePath(),
+        accountId: res.data.accountId,
+        email: pending?.email ?? null,
+        phoneNumber: res.data.phoneNumber ?? null,
+        phoneNumberId: res.data.phoneNumberId ?? null,
+        dashboardUrl: dashboardUrl(baseUrl()),
+        skills: installAgentSkills(opts.agents),
+        supervisor: supervisorAvailability(),
+    };
+}

package/dist/lib/state.js

@@ -12,6 +12,12 @@ export const PendingSignupSchema = z.object({
     verificationId: z.string(),
     email: z.string(),
     createdAt: z.string(),
+    // Set once the email OTP is verified but the account still needs a verified
+    // phone number. Optional so a file written by an older CLI still parses.
+    registrationId: z.string().optional(),
+    // The number a code was last sent to, so `auth verify-otp --number` can report
+    // which one it is verifying.
+    ownerPhoneNumber: z.string().optional(),
 });
 const authFile = defineVersionedFile({
     dir: () => paths().dataDir,

package/dist/lib/user-agent.js

@@ -0,0 +1,46 @@
+import { VERSION } from "./version.js";
+// Identifies the CLI on every request, so server-side request logs attribute
+// provisioning (and everything else) to the client + version that made the call.
+const STOCK_USER_AGENT = `@getdial/cli/${VERSION}`;
+// A caller-supplied token longer than this is almost certainly a bug, and an
+// unbounded one would bloat every server-side request log line it appears in.
+const MAX_PREFIX_LENGTH = 128;
+/**
+ * Reduce a caller-supplied identifier to something safe to put in a header.
+ *
+ * This never throws and never rejects: the prefix is telemetry, so a malformed
+ * value degrades to no prefix at all rather than failing the request. That
+ * matters concretely — undici refuses a header value containing CR/LF, so
+ * passing one through unsanitized would turn a cosmetic misconfiguration into a
+ * hard failure of every Dial call the host makes.
+ *
+ * Returns "" when there is nothing usable left.
+ */
+export function sanitizeUserAgent(raw) {
+    if (!raw)
+        return "";
+    return (raw
+        // Anything outside printable ASCII — CR, LF, tabs, other control chars, and
+        // non-ASCII bytes — becomes a space, in one pass.
+        .replace(/[^\x20-\x7E]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, MAX_PREFIX_LENGTH)
+        // Truncation can land mid-gap and leave a trailing space behind.
+        .trim());
+}
+/**
+ * The full User-Agent for an outgoing API request.
+ *
+ * `DIAL_USER_AGENT` lets an embedding host runtime (an agent platform, a
+ * product wrapping the CLI) identify itself: its token is *prepended*, and the
+ * CLI's own identifier is always still sent. Unset or unusable, the header goes
+ * out exactly as it always has.
+ *
+ * Read at call time, not at module load — like `baseUrl()` reading
+ * DIAL_API_URL, so the environment is still honored if it changes after import.
+ */
+export function userAgent() {
+    const prefix = sanitizeUserAgent(process.env.DIAL_USER_AGENT);
+    return prefix ? `${prefix} ${STOCK_USER_AGENT}` : STOCK_USER_AGENT;
+}

package/dist/mcp/tools/{sign-up.js → auth-login.js}

@@ -5,12 +5,13 @@ const inputSchema = {
     email: z.string().email().describe("Email address to send the sign-up OTP to"),
     force: z.boolean().optional().describe("Overwrite an existing fresh pending signup"),
 };
-export const signUpTool = {
-    name: "sign_up",
+/** Mirrors `dial auth login`. */
+export const authLoginTool = {
+    name: "auth_login",
     config: {
-        title: "Sign Up",
-        description: "Request an email OTP for a Dial account. The code is emailed; finish with the onboard tool. " +
-            "Stores the pending verification locally.",
+        title: "Auth Login",
+        description: "Request an email OTP to create a Dial account or sign in. The code is emailed; submit it " +
+            "with the auth_verify_otp tool. Stores the pending verification locally.",
         inputSchema,
         outputSchema: {
             verificationId: z.string().describe("Pending verification id (also stored locally)"),

package/dist/mcp/tools/auth-register-number.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { jsonResult } from "../result.js";
+import { registerNumber } from "../../lib/ops/account.js";
+const inputSchema = {
+    phoneNumber: z
+        .string()
+        .describe("The user's own phone number, in international form with the country code. Must be able to receive SMS. ASK THE USER for it — never invent one, and never use a Dial number (they are refused)."),
+    registrationId: z
+        .string()
+        .optional()
+        .describe("Explicit registration id; falls back to the locally stored pending signup"),
+};
+/** Mirrors `dial auth register-number`. */
+export const authRegisterNumberTool = {
+    name: "auth_register_number",
+    config: {
+        title: "Auth Register Number",
+        description: "Text a 6-digit verification code to the phone number that will own the account. Required to " +
+            "CREATE an account (never needed to sign in), and only valid after auth_verify_otp reported " +
+            "that a phone number is still required. The number becomes permanently bound to this " +
+            "account — a number can register only one Dial account. Submit the texted code with " +
+            "auth_verify_otp using number: true.",
+        inputSchema,
+        outputSchema: {
+            registrationId: z.string(),
+            phoneNumber: z.string().describe("The number in canonical E.164 form"),
+        },
+        annotations: { openWorldHint: true },
+    },
+    run: async (args) => jsonResult(await registerNumber({
+        phoneNumber: args.phoneNumber,
+        registrationId: args.registrationId,
+    })),
+};

package/dist/mcp/tools/{onboard.js → auth-verify-otp.js}

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { jsonResult } from "../result.js";
-import { onboard } from "../../lib/ops/account.js";
+import { onboard, verifyNumber } from "../../lib/ops/account.js";
 import { readAuth, authFilePath } from "../../lib/state.js";
 import { installSkill, isSupportedAgent, SUPPORTED_AGENTS, } from "../../lib/skill-install.js";
 import { supervisorAvailability } from "../../lib/supervisor/index.js";
@@ -11,22 +11,27 @@ const inputSchema = {
         .string()
         .min(1)
         .optional()
-        .describe("6-digit OTP from the sign-up email. Omit if the account is already signed in — the tool will just install the requested --agent skills and skip verification."),
+        .describe("The 6-digit OTP. Omit if the account is already signed in — the tool will just install the requested agent skills and skip verification."),
+    number: z
+        .boolean()
+        .optional()
+        .describe("Set true to verify the SMS code sent by auth_register_number instead of the emailed code. This is the step that creates the account."),
     verificationId: z
         .string()
         .optional()
-        .describe("Explicit verification id (defaults to the local pending signup)"),
-    inboundInstruction: z
+        .describe("Explicit verification id for the email step (defaults to the local pending signup)"),
+    registrationId: z
         .string()
         .optional()
-        .describe("System prompt for inbound calls to a newly provisioned number (new accounts)"),
+        .describe("Explicit registration id for number: true (defaults to the local pending signup)"),
     agents: z
         .array(z.string())
         .optional()
         .describe("Agent names to install the Dial skill into (e.g. claude-code, cursor)"),
 };
-export const onboardTool = {
-    name: "onboard",
+/** Mirrors `dial auth verify-otp`. */
+export const authVerifyOtpTool = {
+    name: "auth_verify_otp",
     config: {
         title: "Onboard",
         description: "Verify the sign-up OTP and finish onboarding: saves the API key locally and optionally installs " +
@@ -95,12 +100,30 @@ export const onboardTool = {
                 listenAvailable: supervisor.available,
             });
         }
-        const r = await onboard({
-            code: args.code,
-            verificationId: args.verificationId,
-            inboundInstruction: args.inboundInstruction,
-            agents: args.agents,
-        });
+        // number: true is the SMS step, which creates the account.
+        const r = args.number
+            ? await verifyNumber({
+                code: args.code,
+                registrationId: args.registrationId,
+                agents: args.agents,
+            })
+            : await onboard({
+                code: args.code,
+                verificationId: args.verificationId,
+                agents: args.agents,
+            });
+        // The email step has two outcomes. A pending phone number means no account and
+        // no API key yet: report what remains rather than pretending onboarding is done.
+        if ("pendingPhone" in r && r.pendingPhone) {
+            return jsonResult({
+                pendingPhone: true,
+                registrationId: r.registrationId,
+                email: r.email,
+                skills: r.skills,
+                nextTool: "auth_register_number",
+                note: "The email is verified, but creating an account also requires a verified phone number. ASK THE USER for a phone number that can receive SMS, then call auth_register_number with it. No API key has been issued yet. The number is bound to the account permanently, and a Dial number cannot be used.",
+            });
+        }
         // Never surface the raw API key to the model; it's saved to disk for the CLI to read.
         const { apiKey: _omit, ...safe } = r;
         void _omit;

package/dist/mcp/tools/index.js

@@ -10,8 +10,9 @@ import { placeCallTool } from "./place-call.js";
 import { listCallsTool } from "./list-calls.js";
 import { getCallTool } from "./get-call.js";
 import { getAccountStatusTool } from "./get-account-status.js";
-import { signUpTool } from "./sign-up.js";
-import { onboardTool } from "./onboard.js";
+import { authLoginTool } from "./auth-login.js";
+import { authVerifyOtpTool } from "./auth-verify-otp.js";
+import { authRegisterNumberTool } from "./auth-register-number.js";
 import { waitForEventTool } from "./wait-for-event.js";
 import { addUrlTargetTool } from "./add-url-target.js";
 import { addCommandTargetTool } from "./add-command-target.js";
@@ -34,8 +35,9 @@ export const tools = [
     listCallsTool,
     getCallTool,
     getAccountStatusTool,
-    signUpTool,
-    onboardTool,
+    authLoginTool,
+    authRegisterNumberTool,
+    authVerifyOtpTool,
     waitForEventTool,
     addUrlTargetTool,
     addCommandTargetTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getdial/cli",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Dial CLI — install, sign up, and run the local listen service.",
   "license": "MIT",
   "repository": {