@indigoai-us/hq-cli 5.58.1 → 5.59.0

package/dist/commands/channels.d.ts

@@ -0,0 +1,16 @@
+import { Command } from "commander";
+import { type ChannelSummary } from "./dm.js";
+/**
+ * Human label for a channel row. Named channels (personal/company) show their
+ * name + a `hq dm <slug>` hint; unnamed group DMs are identified by their
+ * members (caller excluded), matching how HQ Sync renders them. Pure →
+ * unit-testable.
+ */
+export declare function describeChannel(c: ChannelSummary): string;
+/**
+ * Render the caller's channels for `hq channels`. Pure (takes the already
+ * fetched list) so the formatting is unit-testable without network/auth.
+ */
+export declare function formatChannelsList(channels: ChannelSummary[]): string;
+export declare function registerChannelsCommand(program: Command): void;
+//# sourceMappingURL=channels.d.ts.map

package/dist/commands/channels.js

@@ -0,0 +1,78 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="891a3265-c9ff-53d8-8a3c-2a964f5a74b6")}catch(e){}}();
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { channelSlug } from "./dm.js";
+/**
+ * Human label for a channel row. Named channels (personal/company) show their
+ * name + a `hq dm <slug>` hint; unnamed group DMs are identified by their
+ * members (caller excluded), matching how HQ Sync renders them. Pure →
+ * unit-testable.
+ */
+export function describeChannel(c) {
+    if (c.scope === "group") {
+        const names = (c.members ?? [])
+            .map((m) => m.displayName)
+            .filter((n) => !!n);
+        const who = names.length > 0
+            ? names.join(", ")
+            : `${c.memberCount ?? "?"}-person group`;
+        return `${who}  ${chalk.dim("(group DM)")}`;
+    }
+    const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
+    const scopeTag = c.scope ? chalk.dim(`(${c.scope})`) : "";
+    const hint = slug ? chalk.dim(`— hq dm ${slug} "…"`) : "";
+    return `${chalk.bold(c.name ?? slug ?? c.channelId)} ${scopeTag} ${hint}`.trim();
+}
+/**
+ * Render the caller's channels for `hq channels`. Pure (takes the already
+ * fetched list) so the formatting is unit-testable without network/auth.
+ */
+export function formatChannelsList(channels) {
+    if (channels.length === 0) {
+        return chalk.dim("No channels yet. Group DMs and named channels you're in will appear here.");
+    }
+    const lines = [
+        chalk.green(`${channels.length} channel${channels.length === 1 ? "" : "s"}:`),
+    ];
+    for (const c of channels) {
+        lines.push(`  ${describeChannel(c)}`);
+    }
+    return lines.join("\n");
+}
+async function runChannelsList() {
+    try {
+        const token = await ensureCognitoToken();
+        const res = await vaultApiFetch({ token, path: "/v1/notify/channels" });
+        if (!res.ok) {
+            if (res.status === 401) {
+                console.error(chalk.red("Not authenticated — run `hq login` and try again."));
+            }
+            else {
+                const err = (await res.json().catch(() => ({})));
+                console.error(chalk.red(`Could not list channels: ${err.error ?? err.message ?? res.statusText}`));
+            }
+            process.exit(1);
+        }
+        const data = (await res.json());
+        console.log(formatChannelsList(data.channels ?? []));
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+export function registerChannelsCommand(program) {
+    const channels = program
+        .command("channels")
+        .description("List the DM channels you're in (name them with `hq dm <name> \"…\"`).");
+    channels
+        .command("list", { isDefault: true })
+        .description("List your DM channels — named channels and group DMs.")
+        .action(async () => {
+        await runChannelsList();
+    });
+}
+//# sourceMappingURL=channels.js.map
+//# debugId=891a3265-c9ff-53d8-8a3c-2a964f5a74b6

package/dist/commands/dm.d.ts

@@ -16,6 +16,47 @@ export declare function detectRecipient(recipient: string): DmRecipient | null;
  * (the normal 1:1 path). Pure → unit-testable.
  */
 export declare function parseGroupRecipients(recipient: string): string[] | null;
+/**
+ * Normalize a channel name into a stable slug for name matching. MIRRORS the
+ * server's `channelSlug` (hq-pro src/vault-service/lib/channels.ts): lowercase,
+ * collapse runs of non-alphanumerics to single hyphens, trim leading/trailing
+ * hyphens. Keep in lockstep with the server so `hq dm vyg-dev` matches the
+ * channel the server stored as slug `vyg-dev`. Pure → unit-testable.
+ */
+export declare function channelSlug(name: string): string;
+/**
+ * Decide whether a positional recipient token addresses a DM CHANNEL by name
+ * (rather than a person/agent or a group). Returns the bare channel name to
+ * resolve, or null when the token is a person path (email / prs_ / agt_ uid) or
+ * a comma group. Pure → unit-testable.
+ *
+ *   "#vyg-dev" → "vyg-dev"   (explicit hash form)
+ *   "vyg-dev"  → "vyg-dev"   (bare name — not an email/uid/group)
+ *   "a@b.com"  → null        (person)
+ *   "prs_…"    → null        (person)   "agt_…" → null (agent)
+ *   "a@x,b@y"  → null        (group DM)
+ */
+export declare function parseChannelName(recipient: string): string | null;
+/** Minimal channel shape the CLI reads back from GET /v1/notify/channels. */
+export interface ChannelSummary {
+    channelId: string;
+    name?: string;
+    slug?: string;
+    scope?: string;
+    memberCount?: number;
+    members?: {
+        personUid: string;
+        displayName?: string;
+    }[];
+}
+/**
+ * Find the caller's channel(s) whose name matches `name`, by slug or
+ * case-insensitive display name. Group DMs are unnamed (participant-keyed), so
+ * they never match a name. Returns ALL matches so the caller can detect an
+ * ambiguous name (same slug across personal + company scope). Pure →
+ * unit-testable.
+ */
+export declare function matchChannelsByName(channels: ChannelSummary[], name: string): ChannelSummary[];
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.

package/dist/commands/dm.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f4bc9146-4033-5a73-a246-6f80a5e0f7ef")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e95f345b-0e15-52b3-a851-fc97da935a99")}catch(e){}}();
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -37,6 +37,72 @@ export function parseGroupRecipients(recipient) {
         .filter(Boolean);
     return [...new Set(parts)];
 }
+/**
+ * Normalize a channel name into a stable slug for name matching. MIRRORS the
+ * server's `channelSlug` (hq-pro src/vault-service/lib/channels.ts): lowercase,
+ * collapse runs of non-alphanumerics to single hyphens, trim leading/trailing
+ * hyphens. Keep in lockstep with the server so `hq dm vyg-dev` matches the
+ * channel the server stored as slug `vyg-dev`. Pure → unit-testable.
+ */
+export function channelSlug(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Decide whether a positional recipient token addresses a DM CHANNEL by name
+ * (rather than a person/agent or a group). Returns the bare channel name to
+ * resolve, or null when the token is a person path (email / prs_ / agt_ uid) or
+ * a comma group. Pure → unit-testable.
+ *
+ *   "#vyg-dev" → "vyg-dev"   (explicit hash form)
+ *   "vyg-dev"  → "vyg-dev"   (bare name — not an email/uid/group)
+ *   "a@b.com"  → null        (person)
+ *   "prs_…"    → null        (person)   "agt_…" → null (agent)
+ *   "a@x,b@y"  → null        (group DM)
+ */
+export function parseChannelName(recipient) {
+    const r = recipient.trim();
+    if (!r)
+        return null;
+    if (r.startsWith("#")) {
+        const name = r.slice(1).trim();
+        return name || null;
+    }
+    // A comma is the group-DM signal; emails and prs_/agt_ uids are person paths.
+    if (r.includes(","))
+        return null;
+    if (EMAIL_PATTERN.test(r))
+        return null;
+    if (RECIPIENT_UID_PATTERN.test(r))
+        return null;
+    return r;
+}
+/**
+ * Find the caller's channel(s) whose name matches `name`, by slug or
+ * case-insensitive display name. Group DMs are unnamed (participant-keyed), so
+ * they never match a name. Returns ALL matches so the caller can detect an
+ * ambiguous name (same slug across personal + company scope). Pure →
+ * unit-testable.
+ */
+export function matchChannelsByName(channels, name) {
+    const targetSlug = channelSlug(name);
+    const targetName = name.trim().toLowerCase();
+    if (!targetSlug && !targetName)
+        return [];
+    return channels.filter((c) => {
+        if (c.scope === "group")
+            return false;
+        const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
+        if (slug && slug === targetSlug)
+            return true;
+        if (c.name && c.name.trim().toLowerCase() === targetName)
+            return true;
+        return false;
+    });
+}
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.
@@ -266,13 +332,95 @@ async function runGroupSend(recipients, message) {
         process.exit(1);
     }
 }
+/** Fetch the caller's channels (GET /v1/notify/channels). */
+async function fetchChannels(token) {
+    const res = await vaultApiFetch({ token, path: "/v1/notify/channels" });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
+    }
+    const data = (await res.json());
+    return data.channels ?? [];
+}
+/**
+ * Channel DM path: `hq dm vyg-dev "msg"`, `hq dm '#vyg-dev' "msg"`, or
+ * `hq dm --channel vyg-dev "msg"`. Resolves the caller's channel by name via
+ * GET /v1/notify/channels, then posts the message into it. Scheduling /
+ * prompt / details are 1:1-DM features and are rejected here rather than
+ * silently dropped.
+ */
+async function runChannelSend(channelName, message, opts) {
+    try {
+        const body = (message ?? "").trim();
+        if (!body) {
+            console.error(chalk.red(`A message body is required: hq dm ${channelName} "<message>" (or hq dm --channel ${channelName} "<message>").`));
+            process.exit(1);
+        }
+        const unsupported = [
+            opts.prompt || opts.promptFile ? "--prompt/--prompt-file" : null,
+            opts.details || opts.detailsFile ? "--details/--details-file" : null,
+            opts.at ? "--at" : null,
+            opts.in ? "--in" : null,
+        ].filter(Boolean);
+        if (unsupported.length > 0) {
+            console.error(chalk.red(`${unsupported.join(", ")} ${unsupported.length === 1 ? "is" : "are"} only supported for 1:1 DMs, not channel messages.`));
+            process.exit(1);
+        }
+        const token = await ensureCognitoToken();
+        const channels = await fetchChannels(token);
+        const matches = matchChannelsByName(channels, channelName);
+        if (matches.length === 0) {
+            console.error(chalk.red(`No channel named '${channelName}' — run \`hq channels\` to see your channels.`));
+            process.exit(1);
+        }
+        if (matches.length > 1) {
+            const scopes = matches.map((m) => m.scope ?? "?").join(", ");
+            console.error(chalk.red(`'${channelName}' matches ${matches.length} channels (${scopes}) — this is ambiguous. Open the channel in HQ Sync to post, or rename one.`));
+            process.exit(1);
+        }
+        const channel = matches[0];
+        const sendRes = await vaultApiFetch({
+            token,
+            path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/messages`,
+            method: "POST",
+            body: { body },
+        });
+        if (!sendRes.ok) {
+            const err = (await sendRes.json().catch(() => ({})));
+            console.error(chalk.red(friendlyDmError(sendRes.status, err.code, err.error ?? err.message ?? sendRes.statusText)));
+            process.exit(1);
+        }
+        console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.`));
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 async function runDmSend(recipient, message, opts) {
+    // --channel <name> is an explicit channel target; the positional carries the
+    // message (recipient slot), e.g. `hq dm --channel vyg-dev "hello"`.
+    if (opts.channel !== undefined) {
+        await runChannelSend(opts.channel, message ?? recipient, opts);
+        return;
+    }
+    if (recipient === undefined) {
+        console.error(chalk.red('A recipient is required: hq dm <email|personUid|#channel> "<message>" (or --channel <name>).'));
+        process.exit(1);
+        return;
+    }
     // A comma in the recipient means a group DM — fan into the channel path.
     const group = parseGroupRecipients(recipient);
     if (group) {
         await runGroupSend(group, message);
         return;
     }
+    // A bare name or #hash addresses a named DM channel.
+    const channelName = parseChannelName(recipient);
+    if (channelName !== null) {
+        await runChannelSend(channelName, message, opts);
+        return;
+    }
     try {
         // Resolve prompt/details from inline text or a file.
         let prompt = opts.prompt;
@@ -354,14 +502,15 @@ export function registerDmCommand(program) {
         .command("dm")
         .description("Send a direct message and manage connection requests.");
     dm
-        .command("send <recipient> [message]", { isDefault: true, hidden: true })
-        .description('Send a direct message to someone (email, personUid, or agentUid). A person receives it as an HQ Sync notification; an agent receives it in its durable box inbox and replies by DM. If you aren\'t connected yet, it sends a connection request that holds your message. For a GROUP DM, pass a comma-separated recipient: hq dm send "a@x.com,b@y.com" "hi".')
-        .option("--prompt <text>", "Agent-context prompt the recipient can one-click copy into their agent")
-        .option("--prompt-file <path>", "Read the agent prompt from a file")
-        .option("--details <text>", "Longer detail shown in the recipient's DM detail window")
-        .option("--details-file <path>", "Read the details from a file")
-        .option("--at <iso>", "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time)")
-        .option("--in <duration>", "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d")
+        .command("send [recipient] [message]", { isDefault: true, hidden: true })
+        .description('Send a direct message. RECIPIENT can be a person (email, personUid, or agentUid), a GROUP DM (comma-separated: "a@x.com,b@y.com"), or one of your DM CHANNELS by name — bare (hq dm vyg-dev "hi"), hash form (hq dm "#vyg-dev" "hi"), or via --channel (hq dm --channel vyg-dev "hi"). A person receives a DM as an HQ Sync notification; an agent receives it in its durable box inbox. If you aren\'t connected yet, it sends a connection request that holds your message. See your channels with `hq channels`.')
+        .option("--channel <name>", "Post the message to one of your DM channels by name (e.g. --channel vyg-dev)")
+        .option("--prompt <text>", "Agent-context prompt the recipient can one-click copy into their agent (1:1 DMs only)")
+        .option("--prompt-file <path>", "Read the agent prompt from a file (1:1 DMs only)")
+        .option("--details <text>", "Longer detail shown in the recipient's DM detail window (1:1 DMs only)")
+        .option("--details-file <path>", "Read the details from a file (1:1 DMs only)")
+        .option("--at <iso>", "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time; 1:1 DMs only)")
+        .option("--in <duration>", "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d (1:1 DMs only)")
         .action(async (recipient, message, opts) => {
         await runDmSend(recipient, message, opts);
     });
@@ -391,4 +540,4 @@ export function registerDmCommand(program) {
     });
 }
 //# sourceMappingURL=dm.js.map
-//# debugId=f4bc9146-4033-5a73-a246-6f80a5e0f7ef
+//# debugId=e95f345b-0e15-52b3-a851-fc97da935a99

package/dist/index.js

@@ -5,7 +5,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6ad01242-c165-5be2-bb31-e929c0b38f5e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8839ee7d-9f6d-54fe-8f90-99ad858e349e")}catch(e){}}();
 import "./node-preflight.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
@@ -41,6 +41,7 @@ import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
 import { registerPeopleCommand } from "./commands/people.js";
 import { registerDmCommand } from "./commands/dm.js";
+import { registerChannelsCommand } from "./commands/channels.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
 import { registerSourcesCommand } from "./commands/sources.js";
@@ -152,6 +153,7 @@ registerMembersCommand(program);
 // the local companies/<co>/people store scoped to one company.
 registerPeopleCommand(program);
 registerDmCommand(program);
+registerChannelsCommand(program);
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);
 // Feedback (subcommand group — hq feedback bug|feature)
@@ -242,4 +244,4 @@ registerCompanyCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=6ad01242-c165-5be2-bb31-e929c0b38f5e
+//# debugId=8839ee7d-9f6d-54fe-8f90-99ad858e349e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.58.1",
+  "version": "5.59.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/channels.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, beforeAll } from "vitest";
+import chalk from "chalk";
+import { describeChannel, formatChannelsList } from "./channels.js";
+import type { ChannelSummary } from "./dm.js";
+
+// Disable chalk's ANSI colouring so assertions read the plain rendered text
+// (chalk is a singleton, so this also affects the module under test).
+beforeAll(() => {
+  chalk.level = 0;
+});
+
+describe("describeChannel", () => {
+  it("shows a named channel with a `hq dm <slug>` hint", () => {
+    const c: ChannelSummary = {
+      channelId: "chn_v",
+      name: "VYG Dev",
+      slug: "vyg-dev",
+      scope: "company",
+    };
+    const out = describeChannel(c);
+    expect(out).toContain("VYG Dev");
+    expect(out).toContain("(company)");
+    expect(out).toContain('hq dm vyg-dev "…"');
+  });
+
+  it("identifies an unnamed group DM by its members", () => {
+    const c: ChannelSummary = {
+      channelId: "chn_grp",
+      scope: "group",
+      memberCount: 3,
+      members: [
+        { personUid: "prs_a", displayName: "Stefan" },
+        { personUid: "prs_b", displayName: "Hassaan" },
+      ],
+    };
+    const out = describeChannel(c);
+    expect(out).toContain("Stefan, Hassaan");
+    expect(out).toContain("(group DM)");
+  });
+
+  it("falls back to a member count when a group has no resolved names", () => {
+    const c: ChannelSummary = { channelId: "g", scope: "group", memberCount: 4 };
+    expect(describeChannel(c)).toContain("4-person group");
+  });
+});
+
+describe("formatChannelsList", () => {
+  it("renders an empty-state line when there are no channels", () => {
+    expect(formatChannelsList([])).toMatch(/No channels yet/);
+  });
+
+  it("headers with the count and lists each channel", () => {
+    const channels: ChannelSummary[] = [
+      { channelId: "chn_v", name: "VYG Dev", slug: "vyg-dev", scope: "company" },
+      {
+        channelId: "chn_grp",
+        scope: "group",
+        memberCount: 2,
+        members: [{ personUid: "prs_a", displayName: "Stefan" }],
+      },
+    ];
+    const out = formatChannelsList(channels);
+    expect(out).toMatch(/2 channels:/);
+    expect(out).toContain("VYG Dev");
+    expect(out).toContain("Stefan");
+  });
+
+  it("uses the singular 'channel' for one", () => {
+    const out = formatChannelsList([
+      { channelId: "chn_v", name: "VYG Dev", slug: "vyg-dev", scope: "company" },
+    ]);
+    expect(out).toMatch(/1 channel:/);
+  });
+});

package/src/commands/channels.ts

@@ -0,0 +1,88 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { channelSlug, type ChannelSummary } from "./dm.js";
+
+/**
+ * Human label for a channel row. Named channels (personal/company) show their
+ * name + a `hq dm <slug>` hint; unnamed group DMs are identified by their
+ * members (caller excluded), matching how HQ Sync renders them. Pure →
+ * unit-testable.
+ */
+export function describeChannel(c: ChannelSummary): string {
+  if (c.scope === "group") {
+    const names = (c.members ?? [])
+      .map((m) => m.displayName)
+      .filter((n): n is string => !!n);
+    const who =
+      names.length > 0
+        ? names.join(", ")
+        : `${c.memberCount ?? "?"}-person group`;
+    return `${who}  ${chalk.dim("(group DM)")}`;
+  }
+  const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
+  const scopeTag = c.scope ? chalk.dim(`(${c.scope})`) : "";
+  const hint = slug ? chalk.dim(`— hq dm ${slug} "…"`) : "";
+  return `${chalk.bold(c.name ?? slug ?? c.channelId)} ${scopeTag} ${hint}`.trim();
+}
+
+/**
+ * Render the caller's channels for `hq channels`. Pure (takes the already
+ * fetched list) so the formatting is unit-testable without network/auth.
+ */
+export function formatChannelsList(channels: ChannelSummary[]): string {
+  if (channels.length === 0) {
+    return chalk.dim(
+      "No channels yet. Group DMs and named channels you're in will appear here.",
+    );
+  }
+  const lines = [
+    chalk.green(
+      `${channels.length} channel${channels.length === 1 ? "" : "s"}:`,
+    ),
+  ];
+  for (const c of channels) {
+    lines.push(`  ${describeChannel(c)}`);
+  }
+  return lines.join("\n");
+}
+
+async function runChannelsList(): Promise<void> {
+  try {
+    const token = await ensureCognitoToken();
+    const res = await vaultApiFetch({ token, path: "/v1/notify/channels" });
+    if (!res.ok) {
+      if (res.status === 401) {
+        console.error(chalk.red("Not authenticated — run `hq login` and try again."));
+      } else {
+        const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+        console.error(
+          chalk.red(`Could not list channels: ${err.error ?? err.message ?? res.statusText}`),
+        );
+      }
+      process.exit(1);
+    }
+    const data = (await res.json()) as { channels?: ChannelSummary[] };
+    console.log(formatChannelsList(data.channels ?? []));
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
+export function registerChannelsCommand(program: Command): void {
+  const channels = program
+    .command("channels")
+    .description("List the DM channels you're in (name them with `hq dm <name> \"…\"`).");
+
+  channels
+    .command("list", { isDefault: true })
+    .description("List your DM channels — named channels and group DMs.")
+    .action(async () => {
+      await runChannelsList();
+    });
+}

package/src/commands/dm.test.ts

@@ -26,7 +26,11 @@ import {
   matchRequest,
   buildConnectionActionBody,
   registerDmCommand,
+  channelSlug,
+  parseChannelName,
+  matchChannelsByName,
   type ConnectionRequest,
+  type ChannelSummary,
 } from "./dm.js";
 
 describe("parseGroupRecipients", () => {
@@ -42,6 +46,59 @@ describe("parseGroupRecipients", () => {
   });
 });
 
+describe("channelSlug", () => {
+  it("mirrors the server: lowercases, hyphenates, trims", () => {
+    expect(channelSlug("vyg-dev")).toBe("vyg-dev");
+    expect(channelSlug("VYG Dev!!")).toBe("vyg-dev");
+    expect(channelSlug("  --Team  Room--  ")).toBe("team-room");
+  });
+});
+
+describe("parseChannelName", () => {
+  it("treats a bare non-email/uid token as a channel name", () => {
+    expect(parseChannelName("vyg-dev")).toBe("vyg-dev");
+    expect(parseChannelName("  design  ")).toBe("design");
+  });
+  it("strips a leading # (hash-channel form)", () => {
+    expect(parseChannelName("#vyg-dev")).toBe("vyg-dev");
+    expect(parseChannelName("#")).toBeNull();
+  });
+  it("returns null for person paths and group lists", () => {
+    expect(parseChannelName("a@b.com")).toBeNull();
+    expect(parseChannelName("prs_01ABC")).toBeNull();
+    expect(parseChannelName("agt_01ABC")).toBeNull();
+    expect(parseChannelName("a@x.com,b@y.com")).toBeNull();
+    expect(parseChannelName("")).toBeNull();
+  });
+});
+
+describe("matchChannelsByName", () => {
+  const channels: ChannelSummary[] = [
+    { channelId: "chn_1", name: "VYG Dev", slug: "vyg-dev", scope: "company" },
+    { channelId: "chn_2", name: "Design", slug: "design", scope: "personal" },
+    { channelId: "chn_grp", scope: "group", memberCount: 2 },
+  ];
+  it("matches a named channel by slug (case/punctuation-insensitive)", () => {
+    expect(matchChannelsByName(channels, "vyg-dev").map((c) => c.channelId)).toEqual([
+      "chn_1",
+    ]);
+    expect(matchChannelsByName(channels, "VYG Dev").map((c) => c.channelId)).toEqual([
+      "chn_1",
+    ]);
+  });
+  it("never matches an unnamed group DM", () => {
+    expect(matchChannelsByName(channels, "chn_grp")).toEqual([]);
+    expect(matchChannelsByName(channels, "")).toEqual([]);
+  });
+  it("returns every match so an ambiguous name can be detected", () => {
+    const dup: ChannelSummary[] = [
+      { channelId: "a", name: "ops", slug: "ops", scope: "personal" },
+      { channelId: "b", name: "Ops", slug: "ops", scope: "company" },
+    ];
+    expect(matchChannelsByName(dup, "ops").map((c) => c.channelId)).toEqual(["a", "b"]);
+  });
+});
+
 describe("detectRecipient", () => {
   it("classifies an email", () => {
     expect(detectRecipient("Stefan@Getindigo.ai")).toEqual({
@@ -277,6 +334,78 @@ describe("dm command actions", () => {
     expect(String(fetchSpy.mock.calls[0][0])).toContain("/v1/notify/dm");
   });
 
+  const channelsPayload = {
+    channels: [
+      { channelId: "chn_v", name: "VYG Dev", slug: "vyg-dev", scope: "company" },
+      { channelId: "chn_grp", scope: "group", memberCount: 2 },
+    ],
+  };
+
+  it("channel send (bare name): resolves the channel then posts the message", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, channelsPayload)) // GET channels
+      .mockResolvedValueOnce(jsonResponse(200, { eventId: "evt_c" })); // POST message
+    await program.parseAsync(["dm", "vyg-dev", "hello channel"], { from: "user" });
+    // 1st call lists the caller's channels...
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("/v1/notify/channels");
+    // ...2nd posts into the resolved channel id.
+    const sendCall = fetchSpy.mock.calls[1];
+    expect(String(sendCall[0])).toContain("/v1/notify/channels/chn_v/messages");
+    expect(JSON.parse((sendCall[1]?.body as string) ?? "{}").body).toBe("hello channel");
+    expect(logged()).toMatch(/Message posted to #VYG Dev\./);
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("channel send (#hash form) resolves the same channel", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, channelsPayload))
+      .mockResolvedValueOnce(jsonResponse(200, { eventId: "evt_c" }));
+    await program.parseAsync(["dm", "#vyg-dev", "yo"], { from: "user" });
+    expect(String(fetchSpy.mock.calls[1][0])).toContain("/v1/notify/channels/chn_v/messages");
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("channel send (--channel flag) takes the message from the positional", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, channelsPayload))
+      .mockResolvedValueOnce(jsonResponse(200, { eventId: "evt_c" }));
+    await program.parseAsync(["dm", "--channel", "vyg-dev", "flagged hello"], {
+      from: "user",
+    });
+    const sendCall = fetchSpy.mock.calls[1];
+    expect(String(sendCall[0])).toContain("/v1/notify/channels/chn_v/messages");
+    expect(JSON.parse((sendCall[1]?.body as string) ?? "{}").body).toBe("flagged hello");
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("channel send: unknown name errors and never posts", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, channelsPayload));
+    await program
+      .parseAsync(["dm", "nope-channel", "hi"], { from: "user" })
+      .catch(() => undefined); // process.exit is mocked to throw
+    expect(errSpy.mock.calls.map((c) => String(c[1] ?? c[0])).join("\n")).toMatch(
+      /No channel named 'nope-channel'/,
+    );
+    // Only the GET happened — no message POST.
+    expect(fetchSpy.mock.calls).toHaveLength(1);
+  });
+
+  it("channel send: an ambiguous name errors and never posts", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        channels: [
+          { channelId: "a", name: "ops", slug: "ops", scope: "personal" },
+          { channelId: "b", name: "Ops", slug: "ops", scope: "company" },
+        ],
+      }),
+    );
+    await program
+      .parseAsync(["dm", "ops", "hi"], { from: "user" })
+      .catch(() => undefined);
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toMatch(/ambiguous/);
+    expect(fetchSpy.mock.calls).toHaveLength(1);
+  });
+
   it("send: prints pending request on 202 connection_requested (not an error)", async () => {
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(202, { state: "connection_requested" }),

package/src/commands/dm.ts

@@ -42,6 +42,80 @@ export function parseGroupRecipients(recipient: string): string[] | null {
   return [...new Set(parts)];
 }
 
+/**
+ * Normalize a channel name into a stable slug for name matching. MIRRORS the
+ * server's `channelSlug` (hq-pro src/vault-service/lib/channels.ts): lowercase,
+ * collapse runs of non-alphanumerics to single hyphens, trim leading/trailing
+ * hyphens. Keep in lockstep with the server so `hq dm vyg-dev` matches the
+ * channel the server stored as slug `vyg-dev`. Pure → unit-testable.
+ */
+export function channelSlug(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Decide whether a positional recipient token addresses a DM CHANNEL by name
+ * (rather than a person/agent or a group). Returns the bare channel name to
+ * resolve, or null when the token is a person path (email / prs_ / agt_ uid) or
+ * a comma group. Pure → unit-testable.
+ *
+ *   "#vyg-dev" → "vyg-dev"   (explicit hash form)
+ *   "vyg-dev"  → "vyg-dev"   (bare name — not an email/uid/group)
+ *   "a@b.com"  → null        (person)
+ *   "prs_…"    → null        (person)   "agt_…" → null (agent)
+ *   "a@x,b@y"  → null        (group DM)
+ */
+export function parseChannelName(recipient: string): string | null {
+  const r = recipient.trim();
+  if (!r) return null;
+  if (r.startsWith("#")) {
+    const name = r.slice(1).trim();
+    return name || null;
+  }
+  // A comma is the group-DM signal; emails and prs_/agt_ uids are person paths.
+  if (r.includes(",")) return null;
+  if (EMAIL_PATTERN.test(r)) return null;
+  if (RECIPIENT_UID_PATTERN.test(r)) return null;
+  return r;
+}
+
+/** Minimal channel shape the CLI reads back from GET /v1/notify/channels. */
+export interface ChannelSummary {
+  channelId: string;
+  name?: string;
+  slug?: string;
+  scope?: string;
+  memberCount?: number;
+  members?: { personUid: string; displayName?: string }[];
+}
+
+/**
+ * Find the caller's channel(s) whose name matches `name`, by slug or
+ * case-insensitive display name. Group DMs are unnamed (participant-keyed), so
+ * they never match a name. Returns ALL matches so the caller can detect an
+ * ambiguous name (same slug across personal + company scope). Pure →
+ * unit-testable.
+ */
+export function matchChannelsByName(
+  channels: ChannelSummary[],
+  name: string,
+): ChannelSummary[] {
+  const targetSlug = channelSlug(name);
+  const targetName = name.trim().toLowerCase();
+  if (!targetSlug && !targetName) return [];
+  return channels.filter((c) => {
+    if (c.scope === "group") return false;
+    const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
+    if (slug && slug === targetSlug) return true;
+    if (c.name && c.name.trim().toLowerCase() === targetName) return true;
+    return false;
+  });
+}
+
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.
@@ -265,6 +339,7 @@ interface DmSendOpts {
   detailsFile?: string;
   at?: string;
   in?: string;
+  channel?: string;
 }
 
 /**
@@ -384,17 +459,136 @@ async function runGroupSend(
   }
 }
 
+/** Fetch the caller's channels (GET /v1/notify/channels). */
+async function fetchChannels(token: string): Promise<ChannelSummary[]> {
+  const res = await vaultApiFetch({ token, path: "/v1/notify/channels" });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new Error(
+      friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+    );
+  }
+  const data = (await res.json()) as { channels?: ChannelSummary[] };
+  return data.channels ?? [];
+}
+
+/**
+ * Channel DM path: `hq dm vyg-dev "msg"`, `hq dm '#vyg-dev' "msg"`, or
+ * `hq dm --channel vyg-dev "msg"`. Resolves the caller's channel by name via
+ * GET /v1/notify/channels, then posts the message into it. Scheduling /
+ * prompt / details are 1:1-DM features and are rejected here rather than
+ * silently dropped.
+ */
+async function runChannelSend(
+  channelName: string,
+  message: string | undefined,
+  opts: DmSendOpts,
+): Promise<void> {
+  try {
+    const body = (message ?? "").trim();
+    if (!body) {
+      console.error(
+        chalk.red(
+          `A message body is required: hq dm ${channelName} "<message>" (or hq dm --channel ${channelName} "<message>").`,
+        ),
+      );
+      process.exit(1);
+    }
+    const unsupported = [
+      opts.prompt || opts.promptFile ? "--prompt/--prompt-file" : null,
+      opts.details || opts.detailsFile ? "--details/--details-file" : null,
+      opts.at ? "--at" : null,
+      opts.in ? "--in" : null,
+    ].filter(Boolean);
+    if (unsupported.length > 0) {
+      console.error(
+        chalk.red(
+          `${unsupported.join(", ")} ${
+            unsupported.length === 1 ? "is" : "are"
+          } only supported for 1:1 DMs, not channel messages.`,
+        ),
+      );
+      process.exit(1);
+    }
+
+    const token = await ensureCognitoToken();
+    const channels = await fetchChannels(token);
+    const matches = matchChannelsByName(channels, channelName);
+
+    if (matches.length === 0) {
+      console.error(
+        chalk.red(`No channel named '${channelName}' — run \`hq channels\` to see your channels.`),
+      );
+      process.exit(1);
+    }
+    if (matches.length > 1) {
+      const scopes = matches.map((m) => m.scope ?? "?").join(", ");
+      console.error(
+        chalk.red(
+          `'${channelName}' matches ${matches.length} channels (${scopes}) — this is ambiguous. Open the channel in HQ Sync to post, or rename one.`,
+        ),
+      );
+      process.exit(1);
+    }
+
+    const channel = matches[0];
+    const sendRes = await vaultApiFetch({
+      token,
+      path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/messages`,
+      method: "POST",
+      body: { body },
+    });
+    if (!sendRes.ok) {
+      const err = (await sendRes.json().catch(() => ({}))) as Record<string, string>;
+      console.error(
+        chalk.red(
+          friendlyDmError(sendRes.status, err.code, err.error ?? err.message ?? sendRes.statusText),
+        ),
+      );
+      process.exit(1);
+    }
+    console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.`));
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
 async function runDmSend(
-  recipient: string,
+  recipient: string | undefined,
   message: string | undefined,
   opts: DmSendOpts,
 ): Promise<void> {
+  // --channel <name> is an explicit channel target; the positional carries the
+  // message (recipient slot), e.g. `hq dm --channel vyg-dev "hello"`.
+  if (opts.channel !== undefined) {
+    await runChannelSend(opts.channel, message ?? recipient, opts);
+    return;
+  }
+  if (recipient === undefined) {
+    console.error(
+      chalk.red(
+        'A recipient is required: hq dm <email|personUid|#channel> "<message>" (or --channel <name>).',
+      ),
+    );
+    process.exit(1);
+    return;
+  }
   // A comma in the recipient means a group DM — fan into the channel path.
   const group = parseGroupRecipients(recipient);
   if (group) {
     await runGroupSend(group, message);
     return;
   }
+  // A bare name or #hash addresses a named DM channel.
+  const channelName = parseChannelName(recipient);
+  if (channelName !== null) {
+    await runChannelSend(channelName, message, opts);
+    return;
+  }
   try {
     // Resolve prompt/details from inline text or a file.
     let prompt = opts.prompt;
@@ -516,31 +710,35 @@ export function registerDmCommand(program: Command): void {
     );
 
   dm
-    .command("send <recipient> [message]", { isDefault: true, hidden: true })
+    .command("send [recipient] [message]", { isDefault: true, hidden: true })
     .description(
-      'Send a direct message to someone (email, personUid, or agentUid). A person receives it as an HQ Sync notification; an agent receives it in its durable box inbox and replies by DM. If you aren\'t connected yet, it sends a connection request that holds your message. For a GROUP DM, pass a comma-separated recipient: hq dm send "a@x.com,b@y.com" "hi".',
+      'Send a direct message. RECIPIENT can be a person (email, personUid, or agentUid), a GROUP DM (comma-separated: "a@x.com,b@y.com"), or one of your DM CHANNELS by name — bare (hq dm vyg-dev "hi"), hash form (hq dm "#vyg-dev" "hi"), or via --channel (hq dm --channel vyg-dev "hi"). A person receives a DM as an HQ Sync notification; an agent receives it in its durable box inbox. If you aren\'t connected yet, it sends a connection request that holds your message. See your channels with `hq channels`.',
+    )
+    .option(
+      "--channel <name>",
+      "Post the message to one of your DM channels by name (e.g. --channel vyg-dev)",
     )
     .option(
       "--prompt <text>",
-      "Agent-context prompt the recipient can one-click copy into their agent",
+      "Agent-context prompt the recipient can one-click copy into their agent (1:1 DMs only)",
     )
-    .option("--prompt-file <path>", "Read the agent prompt from a file")
+    .option("--prompt-file <path>", "Read the agent prompt from a file (1:1 DMs only)")
     .option(
       "--details <text>",
-      "Longer detail shown in the recipient's DM detail window",
+      "Longer detail shown in the recipient's DM detail window (1:1 DMs only)",
     )
-    .option("--details-file <path>", "Read the details from a file")
+    .option("--details-file <path>", "Read the details from a file (1:1 DMs only)")
     .option(
       "--at <iso>",
-      "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time)",
+      "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time; 1:1 DMs only)",
     )
     .option(
       "--in <duration>",
-      "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d",
+      "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d (1:1 DMs only)",
     )
     .action(
       async (
-        recipient: string,
+        recipient: string | undefined,
         message: string | undefined,
         opts: DmSendOpts,
       ) => {

package/src/index.ts

@@ -41,6 +41,7 @@ import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
 import { registerPeopleCommand } from "./commands/people.js";
 import { registerDmCommand } from "./commands/dm.js";
+import { registerChannelsCommand } from "./commands/channels.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
 import { registerSourcesCommand } from "./commands/sources.js";
@@ -184,6 +185,7 @@ registerMembersCommand(program);
 // the local companies/<co>/people store scoped to one company.
 registerPeopleCommand(program);
 registerDmCommand(program);
+registerChannelsCommand(program);
 
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);