@getdial/cli 0.12.1 → 0.13.0

package/README.md

@@ -1,19 +1,93 @@
 # @getdial/cli
 
-The Dial CLI.
+The official command-line interface for [Dial](https://getdial.ai) — a communication stack for AI agents. Provision phone numbers, send SMS, place AI voice calls, and react to inbound events, all from your terminal. The CLI wraps the [Dial REST API](https://docs.getdial.ai) so you never have to write HTTP code.
 
-Install via the bootstrap script:
+## Installation
+
+Install globally from npm:
 
 ```bash
-curl -fsSL https://dial.up.railway.app/install | bash
+npm install -g @getdial/cli
 ```
 
-Or directly from npm:
+Or use the bootstrap script, which installs the CLI and walks you through sign-up:
 
 ```bash
-npm install -g @getdial/cli
+curl -fsSL https://getdial.ai/install | bash
+```
+
+Requires **Node.js 22+**.
+
+## Quick start
+
+```bash
+dial signup you@example.com      # email a 6-digit sign-up code
+dial onboard --code 123456 \     # verify the code and provision your account
+  --inbound-instruction "You are my receptionist. Greet the caller and find out what they need."
+dial doctor                      # check account state and what to do next
+```
+
+Once onboarded, your API key is saved locally and the CLI uses it automatically.
+
+```bash
+# Send an SMS
+dial message --to +14155550123 --body "Hello from Dial"
+
+# Place an AI voice call
+dial call --to +14155550123 --outbound-instruction "You are a helpful scheduling assistant."
+
+# Wait for an inbound event (e.g. a verification code)
+dial wait-for message.received --field to=+14155550123
 ```
 
-Requires Node 22+.
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `dial doctor` | Report account state and what to do next. |
+| `dial signup <email>` | Email a 6-digit sign-up code. |
+| `dial onboard --code <code>` | Verify the code and finish onboarding. |
+| `dial number list` | List the phone numbers on your account. |
+| `dial number purchase` | Purchase an additional phone number. |
+| `dial number set <number>` | Update a number's inbound instruction. |
+| `dial message` | Send an SMS. |
+| `dial message list` | List recent messages. |
+| `dial call` | Place an outbound AI voice call. |
+| `dial call list` | List recent calls. |
+| `dial call get <id>` | Fetch a single call — status, duration, transcript. |
+| `dial wait-for <event>` | Block until a matching account event arrives. |
+| `dial listen install` | Install the background event daemon. |
+| `dial listen status` | Report the daemon's state and recent events. |
+| `dial listen uninstall` | Stop and remove the daemon. |
+| `dial local-target add url <url>` | Fan out events to a local HTTP endpoint. |
+| `dial local-target add cmd <path>` | Run an executable once per event. |
+| `dial local-target list` | List registered fan-out targets. |
+| `dial local-target remove <id>` | Unregister a fan-out target. |
+
+Run `dial --help` for the full command tree, or `dial <command> --help` for a specific command's flags. Every command accepts `--json` for machine-readable output.
+
+## Configuration
+
+| Variable | Description |
+| --- | --- |
+| `DIAL_API_URL` | Target a non-default Dial deployment. |
+
+Your API key is stored at `~/.local/share/dial/auth.json` (honoring `XDG_DATA_HOME`).
+
+## Use from an AI agent
+
+The CLI ships with a [skill](https://docs.getdial.ai/integrations/tools/cli-skill) that teaches AI coding agents how to drive `dial`. Install it into your agent's config during onboarding:
+
+```bash
+dial onboard --code 123456 --agent claude-code
+```
+
+Supported agents: `claude-code`, `cursor`, `codex`, `opencode`, `pi`, `openclaw`, `nanoclaw`, `hermes`.
+
+## Documentation
+
+Full documentation lives at **[docs.getdial.ai](https://docs.getdial.ai)** — including the [CLI reference](https://docs.getdial.ai/documentation/cli/commands) and the [listen service](https://docs.getdial.ai/documentation/cli/listen-service) guide.
+
+## License
 
-See `docs/superpowers/specs/2026-05-25-dial-cli-and-listen-service-design.md` for design.
+MIT

package/dist/cli.js

@@ -11,6 +11,7 @@ import { runListenStatus } from "./commands/listen/status.js";
 import { runWaitFor } from "./commands/wait-for.js";
 import { runNumberList } from "./commands/number/list.js";
 import { runNumberPurchase } from "./commands/number/purchase.js";
+import { runNumberSet } from "./commands/number/set.js";
 import { runMessageSend } from "./commands/message/send.js";
 import { runMessageList } from "./commands/message/list.js";
 import { runCallSend } from "./commands/call/send.js";
@@ -42,11 +43,13 @@ program
     .description("Verify the OTP and finish onboarding.")
     .option("--verification-id <id>", "explicit verification id (falls back to local pending signup)")
     .requiredOption("--code <code>", "6-digit OTP from your email")
+    .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], [])
     .option("--json", "machine-readable output")
     .action(async (opts) => process.exit(await runOnboard({
     verificationId: opts.verificationId,
     code: opts.code,
+    inboundInstruction: opts.inboundInstruction,
     agents: opts.agent,
     json: !!opts.json,
 })));
@@ -80,14 +83,26 @@ number
 number
     .command("purchase")
     .description("Purchase an additional phone number. POST /api/v1/numbers.")
+    .requiredOption("--inbound-instruction <text>", "system prompt for inbound calls to this number")
     .option("--country <iso2>", "ISO-3166-1 alpha-2 country code (defaults to US server-side)")
     .option("--area-code <code>", "preferred area code (US/CA)")
     .option("--json", "machine-readable output")
     .action(async (opts) => process.exit(await runNumberPurchase({
+    inboundInstruction: opts.inboundInstruction,
     country: opts.country,
     areaCode: opts.areaCode,
     json: !!opts.json,
 })));
+number
+    .command("set <number>")
+    .description("Update a number's inbound instruction. PATCH /api/v1/numbers/<id>.")
+    .requiredOption("--inbound-instruction <text>", "new system prompt for inbound calls to this number")
+    .option("--json", "machine-readable output")
+    .action(async (numberArg, opts) => process.exit(await runNumberSet({
+    number: numberArg,
+    inboundInstruction: opts.inboundInstruction,
+    json: !!opts.json,
+})));
 const message = program
     .command("message")
     .description("Send an SMS. POST /api/v1/messages.")
@@ -124,18 +139,18 @@ const call = program
     .command("call")
     .description("Place an outbound voice call. POST /api/v1/calls.")
     .option("--to <e164>", "destination phone number, E.164 (e.g. +14155551234)")
-    .option("--system-prompt <text>", "system prompt for the agent that will speak")
+    .option("--outbound-instruction <text>", "system prompt for the agent that will speak")
     .option("--language <bcp47>", "BCP-47 language tag for the call", "en-US")
     .option("--from-number-id <id>", "phoneNumberId to call from (defaults to onboard's number)")
     .option("--json", "machine-readable output")
     .action(async (opts) => {
-    if (!opts.to || !opts.systemPrompt) {
-        console.error("error: --to and --system-prompt are required to place a call. Use `dial call list` to list, `dial call get <id>` to fetch one, or `dial call --help` for usage.");
+    if (!opts.to || !opts.outboundInstruction) {
+        console.error("error: --to and --outbound-instruction are required to place a call. Use `dial call list` to list, `dial call get <id>` to fetch one, or `dial call --help` for usage.");
         process.exit(2);
     }
     process.exit(await runCallSend({
         to: opts.to,
-        systemPrompt: opts.systemPrompt,
+        outboundInstruction: opts.outboundInstruction,
         language: opts.language,
         fromNumberId: opts.fromNumberId,
         json: !!opts.json,

package/dist/commands/call/get.js

@@ -23,9 +23,9 @@ export async function runCallGet(opts) {
     console.log(`status:     ${c.status}`);
     console.log(`duration:   ${c.duration}s`);
     console.log(`created:    ${c.createdAt}`);
-    if (c.systemPrompt) {
-        console.log(`systemPrompt:`);
-        console.log(c.systemPrompt);
+    if (c.instruction) {
+        console.log(`instruction:`);
+        console.log(c.instruction);
     }
     if (c.transcript) {
         console.log(`transcript:`);

package/dist/commands/call/send.js

@@ -14,7 +14,7 @@ export async function runCallSend(opts) {
     const res = await apiPost("/api/v1/calls", {
         to: opts.to,
         fromNumberId,
-        systemPrompt: opts.systemPrompt,
+        outboundInstruction: opts.outboundInstruction,
         language: opts.language,
     }, auth.apiKey);
     if (!res.ok) {

package/dist/commands/number/purchase.js

@@ -6,7 +6,7 @@ export async function runNumberPurchase(opts) {
         fail(opts.json, "not_signed_in", "Not signed in. Run `dial signup` and `dial onboard` first.");
         return 1;
     }
-    const body = {};
+    const body = { inboundInstruction: opts.inboundInstruction };
     if (opts.country)
         body.country = opts.country;
     if (opts.areaCode)

package/dist/commands/number/set.js

@@ -0,0 +1,44 @@
+import { readAuth } from "../../lib/state.js";
+import { apiGet, apiPatch } from "../../lib/api.js";
+export async function runNumberSet(opts) {
+    const auth = readAuth();
+    if (!auth) {
+        fail(opts.json, "not_signed_in", "Not signed in. Run `dial signup` and `dial onboard` first.");
+        return 1;
+    }
+    // The REST API keys numbers by id; the CLI takes the E.164 number for ergonomics,
+    // so resolve it to its id first.
+    const list = await apiGet("/api/v1/numbers", auth.apiKey);
+    if (!list.ok) {
+        fail(opts.json, "list_failed", list.error, { status: list.status });
+        return 2;
+    }
+    const match = list.data.numbers.find((n) => n.number === opts.number);
+    if (!match) {
+        const known = list.data.numbers.map((n) => n.number).join(", ") || "(none)";
+        fail(opts.json, "number_not_found", `No phone number ${opts.number} on your account. Yours: ${known}.`);
+        return 1;
+    }
+    const res = await apiPatch(`/api/v1/numbers/${match.id}`, { inboundInstruction: opts.inboundInstruction }, auth.apiKey);
+    if (!res.ok) {
+        fail(opts.json, "update_failed", res.error, { status: res.status });
+        return 2;
+    }
+    const n = res.data.number;
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, number: n }));
+    }
+    else {
+        console.log(`updated.`);
+        console.log(`  number:               ${n.number}`);
+        console.log(`  id:                   ${n.id}`);
+        console.log(`  inbound instruction:  ${n.inboundInstruction ?? ""}`);
+    }
+    return 0;
+}
+function fail(json, code, message, extra) {
+    if (json)
+        console.log(JSON.stringify({ ok: false, code, message, ...extra }));
+    else
+        console.error(message);
+}

package/dist/commands/onboard.js

@@ -27,7 +27,13 @@ export async function runOnboard(opts) {
         verificationId = pending.verificationId;
         email = pending.email;
     }
-    const res = await apiPost("/api/v1/auth/verify", { verificationId, code: opts.code });
+    const res = await apiPost("/api/v1/auth/verify", {
+        verificationId,
+        code: opts.code,
+        // Sent only when provided; the server requires it when provisioning a first
+        // number (new account) and ignores it when signing in.
+        ...(opts.inboundInstruction ? { inboundInstruction: opts.inboundInstruction } : {}),
+    });
     if (!res.ok) {
         if (opts.json)
             console.log(JSON.stringify({ ok: false, code: "verify_failed", status: res.status, error: res.error }));

package/dist/lib/api.js

@@ -10,6 +10,9 @@ export async function apiPost(path, body, apiKey) {
 export async function apiGet(path, apiKey) {
     return apiRequest("GET", path, undefined, apiKey);
 }
+export async function apiPatch(path, body, apiKey) {
+    return apiRequest("PATCH", path, body, apiKey);
+}
 async function apiRequest(method, path, body, apiKey) {
     const url = `${baseUrl()}${path}`;
     const headers = { "content-type": "application/json" };

package/package.json

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