@avgvstvs96/pigeon 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bassim Shahidy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,280 @@
-# Temporary Holding Version
+# pigeon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your messages, from the terminal. Read, search, watch and send iMessage, with
+filters that decide what anything reading through pigeon gets to see.
+
+Built for people and for agents: plain-text transcripts by default, JSON lines
+with `--json`. Runs on Bun.
+
+```
+$ pigeon read
+── Mom · +12125550101
+Oct 11 13:24  Mom: are you still coming sunday?
+Oct 11 13:34  me: yes! bringing dessert
+── Riley Quinn · +12125550102
+Oct 12 14:24  Riley Quinn: the wifi password is [redacted]
+Oct 12 14:34  me: thank you!!
+── Book club · chat204
+Oct 13 05:24  Sam Okafor: chapter 9 for thursday?
+Oct 13 05:39  me: on it [attachment: IMG_2041.heic]
+```
+
+- **Read and search** every chat, with names from your Contacts
+- **Watch** new messages as they arrive, ready to pipe into a script or an agent
+- **Send** text and files through Messages
+- **Redact** a chat, a day, a sender or a string, on every command, with no way around it from the CLI
+- **Make it yours** in one `config.ts`: [filters](#filters) and [sources](#sources) for Telegram, WhatsApp, anything, built on the same API as iMessage
+
+## Install
+
+pigeon needs [Bun](https://bun.sh) and macOS for iMessage. On Linux it can
+still read a `chat.db` copied from a Mac.
+
+```bash
+bun add -g github:AVGVSTVS96/pigeon
+pigeon --help
+```
+
+Give your terminal **Full Disk Access** (System Settings › Privacy & Security)
+so it can read `~/Library/Messages/chat.db`. The first `pigeon send` asks once
+for permission to control Messages.
+
+## Usage
+
+```bash
+pigeon chats                 # chats, most recent first
+pigeon chats book            # chats whose name contains "book"
+pigeon read mom              # the last 30 messages with Mom
+pigeon read                  # the last 30 messages anywhere
+pigeon read -s 1d            # everything from the last 24 hours
+pigeon read -s yesterday -u today  # all of yesterday
+pigeon search dinner sunday  # messages with every word, newest 30
+pigeon search pie -c mom     # ...in one chat
+pigeon watch                 # new messages, live
+pigeon watch --json | jq .   # ...as JSON lines
+pigeon send mom "landed!"    # send a message (to an id or a chat's full name)
+pigeon send mom -f pie.jpg   # send a file
+echo "on my way" | pigeon send +12125550101
+pigeon config                # which config loaded, and how many filters
+```
+
+A chat is its id or its name. For a 1:1 iMessage chat the id is the other
+person's phone number or email, written any way you like (`+1 212 555 0101`,
+`2125550101`). Group chats have ids like `chat204`, shown by `pigeon chats`.
+
+| Flag | Meaning |
+| ---- | ------- |
+| `-n`, `--limit <n>` | how many to show (default 30) |
+| `-s`, `--since <when>` | `30m`, `12h`, `3d`, `2w`, `today`, `yesterday`, or a date like `2026-10-01` |
+| `-u`, `--until <when>` | same forms as `--since` |
+| `-c`, `--chat <chat>` | limit `search` or `watch` to one chat |
+| `-f`, `--file <path>` | attach a file to `send` (repeatable) |
+| `--json` | one JSON object per line |
+
+`read` and `search` show the newest matches, printed oldest first like a
+conversation. Dates are local time, in text and in JSON.
+
+<details>
+<summary>The JSON shape</summary>
+
+```json
+{
+  "id": "6A1F3B7C-…",
+  "source": "imessage",
+  "chat": { "id": "+12125550102", "name": "Riley Quinn" },
+  "from": { "id": "+12125550102", "name": "Riley Quinn" },
+  "text": "the wifi password is [redacted]",
+  "date": "2026-10-12T14:24:45-07:00",
+  "attachments": [],
+  "service": "iMessage",
+  "redacted": true
+}
+```
+
+`from.id` is `"me"` for messages you sent. `replyTo` holds the id of the
+message being replied to. `attachments` entries have a `name`, a `mime`
+when known, and a `path` when the file is on this Mac (with Messages in
+iCloud, older files may only be in the cloud).
+
+</details>
+
+## Make it yours
+
+Everything is configured from one file, `~/.config/pigeon/config.ts`. It's
+plain TypeScript: export a function that receives pigeon's API and returns
+your `sources` and `filters`.
+
+```ts
+// ~/.config/pigeon/config.ts
+import type { ConfigFactory } from "@avgvstvs96/pigeon";
+
+export default (({ imessage, redact }) => ({
+  sources: [imessage()],
+  filters: [
+    redact({ chat: "+12125550102", on: "2026-10-06" }),   // one chat, one day
+    redact({ match: /\b\d{3}-\d{2}-\d{4}\b/ }),             // anything shaped like an SSN
+    (m) => !/verification code/i.test(m.text),             // drop 2FA texts entirely
+  ],
+})) satisfies ConfigFactory;
+```
+
+Without a config, pigeon reads iMessage with no filters.
+
+### Filters
+
+A filter is a function that gets each message and returns:
+
+| Return | Effect |
+| ------ | ------ |
+| `true` | keep it |
+| `false` | drop it |
+| a message | show this one instead |
+
+Filters run in order, on every command: `read`, `search`, `watch`, and the
+[library](#library). There is no flag to skip them, so whatever reads your
+messages through pigeon (you, a script, an agent) sees exactly what your
+filters allow.
+
+pigeon fails closed. A filter that throws drops the message it threw on. A
+config that fails to load stops pigeon with an error instead of running
+without its filters, and so does one with a typo in it (`filter:` instead of
+`filters:`). Search runs *after* filters, so hidden text can't be found by
+searching for it.
+
+Filters apply to messages. `pigeon chats` still lists every chat, with its
+name, people and the time of its last message.
+
+### Redact
+
+`redact()` is the built-in filter for hiding things. It keeps the message
+but replaces its text with `[redacted]`, so a reader still sees that
+something was said, and when, but not what. Every field narrows the rule:
+
+```ts
+redact({ chat: "+12125550102" })                     // a whole chat
+redact({ chat: "chat204", on: "2026-10-06" })        // one day of a group chat
+redact({ from: "+12125550102", since: "2026-09-01" }) // one person, from a date on
+redact({ from: "me", until: "2020-01-01" })          // everything you sent before 2020
+redact({ match: ["gate code", /\d{4}/] })            // just these strings, everywhere
+```
+
+| Field | Matches |
+| ----- | ------- |
+| `chat` | a chat id (one or a list): a phone number or email for 1:1 chats, the id from `pigeon chats` for groups |
+| `from` | a sender's handle, or `"me"` (one or a list) |
+| `on` | a whole day, local time: `"2026-10-06"` |
+| `since` / `until` | a time range: a `Date`, a timestamp, or a date string |
+| `match` | strings (case-insensitive) or regexes to hide in the text and attachment names; without it, the whole message is hidden along with its attachments |
+
+Phone numbers match however they're written, so `"212-555-0102"` and
+`"+12125550102"` are the same person. Rules take ids, not names: a contact
+or group can be renamed, and a rule that quietly stopped matching would show
+everything it was hiding.
+
+### Sources
+
+iMessage isn't special: it's declared with the same `defineSource` your
+config gets. A source needs an `id` and two functions:
+
+```ts
+import type { Source } from "@avgvstvs96/pigeon";
+
+const notes: Source = {
+  id: "notes",
+  chats: () => [{ id: "inbox", source: "notes", name: "Inbox", people: [], group: false }],
+  *messages() {
+    yield {
+      id: "1",
+      source: "notes",
+      chat: { id: "inbox", name: "Inbox" },
+      from: { id: "me", name: "me" },
+      text: "remember the pie",
+      date: new Date(),
+      attachments: [],
+    };
+  },
+};
+```
+
+`messages()` yields newest first and may ignore its query (`chat`,
+`since`, `until`): pigeon re-checks every message, so the simplest source is
+just "here are my messages". Add `watch()` to make `pigeon watch` work for it
+and `send()` for `pigeon send`. [`examples/telegram.ts`](examples/telegram.ts)
+is a complete source for Telegram Desktop's JSON export in about 80 lines.
+
+Sources merge into one stream by date, and filters apply to all of them:
+
+```ts
+import { telegram } from "./telegram.ts";
+
+export default (({ imessage, redact }) => ({
+  sources: [imessage(), telegram("~/Downloads/Telegram Desktop/DataExport/result.json")],
+  filters: [redact({ match: "the gate code" })],
+})) satisfies ConfigFactory;
+```
+
+`imessage()` takes options too: `db` to read another `chat.db` (a backup,
+or a copy on Linux), `contacts` to point at another Contacts folder or
+`false` to show raw handles, and `id` to tell two iMessage sources apart.
+
+## Library
+
+The CLI is a thin layer over the same API, which you can use directly:
+
+```ts
+import { open } from "@avgvstvs96/pigeon";
+
+const pigeon = await open(); // your config, your filters
+
+for await (const m of pigeon.messages({ chat: "mom", since: new Date("2026-10-01") })) {
+  console.log(m.from.name, m.text);
+}
+
+for await (const m of pigeon.watch()) {
+  if (m.text.includes("call me")) await pigeon.send(m.chat.id, { text: "calling in 5" });
+}
+```
+
+`pigeon({ sources, filters })` builds one without reading a config file.
+
+## For agents
+
+Agents read the same transcripts you do, and `--json` when they need
+structure. [`skills/pigeon/SKILL.md`](skills/pigeon/SKILL.md) teaches Claude
+Code, Codex and other skill-aware agents to use pigeon instead of opening
+`chat.db` themselves:
+
+```bash
+cp -r skills/pigeon ~/.claude/skills/
+```
+
+## How it reads iMessage
+
+pigeon opens `chat.db` read-only and never writes to it. It reads message
+text from `attributedBody` when newer macOS leaves `text` empty, merges a
+person's iMessage and SMS threads into one chat like Messages does, and
+reads names straight from the Contacts database, so it works over ssh too.
+Tapbacks and system events (renames, people joining) aren't messages and are
+skipped; tapbacks also quote the message they react to, so skipping them keeps
+hidden text from leaking out through a "Loved …".
+
+`watch` wakes on every write to the database and checks every few seconds in
+case an event is missed. `send` uses AppleScript, so it needs Messages to be
+signed in and permission to control it.
+
+## What redaction promises
+
+pigeon never hands out what your filters hide, through any command or the
+library. It can't stop other programs from opening `chat.db` themselves:
+anything with Full Disk Access can. Give your agents pigeon and they have no
+reason to go around it. Anything truly sensitive is safest deleted from
+Messages.
+
+## Credits
+
+[imsg](https://github.com/steipete/imsg) by Peter Steinberger was a great map
+of `chat.db`'s quirks.
+
+## License
+
+MIT

package/examples/telegram.ts

@@ -0,0 +1,82 @@
+import { homedir } from "node:os";
+import type { Chat, Message, Source } from "@avgvstvs96/pigeon";
+
+type Text = string | ({ text: string } & Record<string, unknown>);
+
+interface Export {
+  personal_information?: { user_id: number };
+  chats: {
+    list: {
+      id: number;
+      name?: string;
+      type: string;
+      messages: {
+        id: number;
+        type: string;
+        date_unixtime: string;
+        from?: string;
+        from_id?: string;
+        text: Text | Text[];
+        file?: string;
+        photo?: string;
+        reply_to_message_id?: number;
+      }[];
+    }[];
+  };
+}
+
+const plain = (text: Text | Text[]) => [text].flat().map((t) => (typeof t === "string" ? t : t.text)).join("");
+
+/**
+ * Telegram Desktop's "Export chat history" (JSON) as a pigeon source.
+ * Read-only: no watch, no send. Copy this file next to your config to use it.
+ */
+export function telegram(path: string): Source {
+  let loaded: Promise<{ chats: Chat[]; messages: Message[] }> | undefined;
+
+  const load = async () => {
+    const data: Export = await Bun.file(path.replace(/^~(?=\/)/, homedir())).json();
+    const me = data.personal_information && `user${data.personal_information.user_id}`;
+    const chats: Chat[] = [];
+    const messages: Message[] = [];
+    for (const c of data.chats.list) {
+      const chat = { id: String(c.id), name: c.name ?? "Saved Messages" };
+      const people = new Map<string, string>();
+      let last: Date | undefined;
+      for (const m of c.messages) {
+        if (m.type !== "message") continue;
+        const fromMe = m.from_id === me;
+        if (!fromMe && m.from_id) people.set(m.from_id, m.from ?? m.from_id);
+        last = new Date(Number(m.date_unixtime) * 1000);
+        messages.push({
+          id: `${c.id}/${m.id}`,
+          source: "telegram",
+          chat,
+          from: fromMe ? { id: "me", name: "me" } : { id: m.from_id ?? "unknown", name: m.from ?? "unknown" },
+          text: plain(m.text),
+          date: last,
+          attachments: [m.photo, m.file].filter((f) => f !== undefined).map((f) => ({ name: f.split("/").pop()! })),
+          ...(m.reply_to_message_id && { replyTo: `${c.id}/${m.reply_to_message_id}` }),
+        });
+      }
+      chats.push({
+        ...chat,
+        source: "telegram",
+        people: [...people].map(([id, name]) => ({ id, name })),
+        group: !c.type.startsWith("personal"),
+        date: last,
+      });
+    }
+    messages.sort((a, b) => b.date.getTime() - a.date.getTime());
+    return { chats, messages };
+  };
+
+  return {
+    id: "telegram",
+    label: "Telegram",
+    chats: async () => (await (loaded ??= load())).chats,
+    async *messages() {
+      yield* (await (loaded ??= load())).messages;
+    },
+  };
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@avgvstvs96/pigeon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Your messages, from the terminal. An iMessage CLI with pluggable sources and filters.",
+  "license": "MIT",
+  "type": "module",
+  "repository": "github:AVGVSTVS96/pigeon",
+  "keywords": ["imessage", "messages", "cli", "chat.db", "agents", "redaction"],
+  "bin": {
+    "pigeon": "src/cli/main.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src", "examples", "skills", "README.md", "LICENSE"],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/pigeon/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: pigeon
+description: Read, search, watch and send the user's iMessages (and any other sources they've configured) with the pigeon CLI. Use whenever a task involves their texts or chats, instead of opening chat.db or any Messages database directly.
+---
+
+# pigeon
+
+`pigeon` reads the user's messages with their filters already applied. Messages
+they've hidden show up as `[redacted]`; that is intentional, so never try to
+recover them, and never read `chat.db` or a copy of it directly.
+
+```bash
+pigeon chats [name]               # find a chat and its id
+pigeon read <chat> [-n 30]        # recent messages, oldest first
+pigeon read -s 1d                 # everything from the last day, all chats
+pigeon search <words...> [-c chat] [-s 2w]
+pigeon watch [chat] --json        # stream new messages
+pigeon send <chat> "text" [-f file]
+```
+
+- A chat is its id (a phone number or email for 1:1 chats, `chat…` for groups) or its name. If a name matches several chats, pigeon lists them; retry with the id.
+- `-s/--since` and `-u/--until` take `30m`, `12h`, `3d`, `2w`, `today`, `yesterday` or a date.
+- Add `--json` for one object per line: `chat`, `from` (`id` is `"me"` for the user), `text`, `date` (local time), `attachments`, `replyTo`, `redacted`.
+- Default output is a compact transcript; prefer it for reading, `--json` for processing.
+- Sending is visible to other people: only send when the user asked for that message.

package/src/cli/format.ts

@@ -0,0 +1,65 @@
+import type { Chat, Message } from "../types.ts";
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const pad = (n: number) => String(n).padStart(2, "0");
+
+export interface Style {
+  dim(text: string): string;
+  bold(text: string): string;
+}
+
+export const plain: Style = { dim: (t) => t, bold: (t) => t };
+export const ansi: Style = { dim: (t) => `\x1b[2m${t}\x1b[22m`, bold: (t) => `\x1b[1m${t}\x1b[22m` };
+
+/** "Oct 6 21:14", with the year when it isn't this one. */
+export function shortDate(date: Date, now = new Date()): string {
+  const year = date.getFullYear() === now.getFullYear() ? "" : ` ${date.getFullYear()}`;
+  return `${MONTHS[date.getMonth()]} ${date.getDate()}${year} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/** ISO 8601 in local time with its offset, so a reader sees the same day you do. */
+export function localIso(date: Date): string {
+  const offset = -date.getTimezoneOffset();
+  const sign = offset >= 0 ? "+" : "-";
+  const zone = `${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`;
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${zone}`
+  );
+}
+
+export function json(value: Chat | Message): string {
+  return JSON.stringify(value, function (this: Record<string, unknown>, key, v) {
+    const original = this[key];
+    return original instanceof Date ? localIso(original) : v;
+  });
+}
+
+export function chatLine(chat: Chat, style: Style, width: number): string {
+  const when = chat.date ? shortDate(chat.date) : "";
+  const tag = chat.group ? style.dim(`  group of ${chat.people.length + 1}`) : "";
+  return `${style.dim(when.padEnd(12))}  ${style.bold(chat.name.padEnd(width))}  ${style.dim(chat.id)}${tag}`;
+}
+
+function body(message: Message): string {
+  const files = message.attachments.map((a) => `[attachment: ${a.name}]`);
+  return [message.text, ...files].filter(Boolean).join(" ");
+}
+
+/** Messages as a transcript, with a header each time the chat changes. */
+export function transcript(style: Style) {
+  let chat: string | undefined;
+  return (message: Message): string => {
+    const lines: string[] = [];
+    const key = `${message.source}\0${message.chat.id}`;
+    if (key !== chat) {
+      chat = key;
+      lines.push(style.bold(`── ${message.chat.name}`) + style.dim(` · ${message.chat.id}`));
+    }
+    const when = shortDate(message.date);
+    const [first, ...rest] = `${message.from.name}: ${body(message)}`.split("\n");
+    lines.push(`${style.dim(when)}  ${first}`);
+    for (const line of rest) lines.push(`${" ".repeat(when.length)}  ${line}`);
+    return lines.join("\n");
+  };
+}

package/src/cli/main.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { findConfig, loadConfig } from "../config.ts";
+import { pigeon } from "../pigeon.ts";
+import { parseWhen } from "../time.ts";
+import type { Message } from "../types.ts";
+import { ansi, chatLine, json, plain, transcript } from "./format.ts";
+
+export const HELP = `pigeon: your messages, from the terminal
+
+Usage
+  pigeon chats [name]           chats, most recent first
+  pigeon read [chat]            recent messages in a chat, or across all of them
+  pigeon search <words...>      messages containing every word
+  pigeon watch [chat]           new messages as they arrive
+  pigeon send <chat> [text...]  send a message (text from stdin if omitted)
+  pigeon config                 where the config is and what it loaded
+
+A chat is its id (a phone number or email for 1:1 chats) or its name.
+
+Options
+  -n, --limit <n>     how many to show (default 30)
+  -s, --since <when>  "30m", "12h", "3d", "2w", today, yesterday, or a date
+  -u, --until <when>  same forms as --since
+  -c, --chat <chat>   limit search or watch to one chat
+  -f, --file <path>   attach a file to send (repeatable)
+      --json          one JSON object per line
+  -h, --help
+
+Filters in ~/.config/pigeon/config.ts apply to every command and can't be skipped.`;
+
+const OPTIONS = {
+  limit: { type: "string", short: "n" },
+  since: { type: "string", short: "s" },
+  until: { type: "string", short: "u" },
+  chat: { type: "string", short: "c" },
+  file: { type: "string", short: "f", multiple: true },
+  json: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+} as const;
+
+export function parse(argv: string[]) {
+  const { values, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true });
+  const limit = values.limit === undefined ? 30 : Number(values.limit);
+  if (!Number.isInteger(limit) || limit < 1) throw new Error(`--limit must be a positive whole number`);
+  const [command, ...rest] = positionals;
+  return {
+    command,
+    args: rest,
+    limit,
+    since: values.since === undefined ? undefined : parseWhen(values.since),
+    until: values.until === undefined ? undefined : parseWhen(values.until),
+    chat: values.chat,
+    files: values.file ?? [],
+    json: values.json ?? false,
+    help: values.help ?? false,
+  };
+}
+
+type Args = ReturnType<typeof parse>;
+
+async function collect(messages: AsyncIterable<Message>): Promise<Message[]> {
+  const all: Message[] = [];
+  for await (const m of messages) all.push(m);
+  return all.reverse();
+}
+
+async function run(args: Args, out: (line: string) => void): Promise<void> {
+  const style = !args.json && process.stdout.isTTY && !process.env.NO_COLOR ? ansi : plain;
+  const format = args.json ? json : transcript(style);
+  const print = (m: Message) => out(format(m));
+  const config = await loadConfig();
+  const p = pigeon(config);
+  const { since, until, limit } = args;
+
+  switch (args.command) {
+    case "chats": {
+      const query = args.args.join(" ");
+      const chats = (query ? await p.findChats(query) : await p.chats()).slice(0, limit);
+      const width = Math.min(28, Math.max(0, ...chats.map((c) => c.name.length)));
+      for (const chat of chats) out(args.json ? json(chat) : chatLine(chat, style, width));
+      return;
+    }
+    case "read": {
+      const chat = args.args.join(" ") || args.chat || undefined;
+      (await collect(p.messages({ chat, since, until, limit }))).forEach(print);
+      return;
+    }
+    case "search": {
+      const text = args.args.join(" ");
+      if (!text) throw new Error("search needs some words to look for");
+      (await collect(p.messages({ chat: args.chat, text, since, until, limit }))).forEach(print);
+      return;
+    }
+    case "watch": {
+      const chat = args.args.join(" ") || args.chat || undefined;
+      for await (const m of p.watch({ chat })) print(m);
+      return;
+    }
+    case "send": {
+      const [chat, ...words] = args.args;
+      if (!chat) throw new Error("send needs a chat: pigeon send <chat> <text>");
+      const piped = words.length === 0 && args.files.length === 0 && !process.stdin.isTTY;
+      const text = piped ? (await Bun.stdin.text()).trimEnd() : words.join(" ");
+      await p.send(chat, { text, files: args.files });
+      return;
+    }
+    case "config": {
+      out(`config   ${(await findConfig()) ?? "none"}`);
+      out(`sources  ${p.sources.map((s) => s.label ?? s.id).join(", ")}`);
+      out(`filters  ${config.filters?.length ?? 0}`);
+      return;
+    }
+    default:
+      throw new Error(`unknown command "${args.command}", see pigeon --help`);
+  }
+}
+
+export async function main(argv = Bun.argv.slice(2)): Promise<number> {
+  try {
+    const args = parse(argv);
+    if (args.help || !args.command) {
+      console.log(HELP);
+      return 0;
+    }
+    await run(args, (line) => console.log(line));
+    return 0;
+  } catch (err) {
+    console.error(`pigeon: ${err instanceof Error ? err.message : err}`);
+    return 1;
+  }
+}
+
+if (import.meta.main) process.exit(await main());