jmisilo · jmisilo · Jul 16, 2026 · Jul 16, 2026
diff --git a/.changeset/pre.json b/.changeset/pre.json
@@ -0,0 +1,14 @@
+{
+  "mode": "pre",
+  "tag": "beta",
+  "initialVersions": {
+    "@imessage-sdk/example-basic-blooio": "0.0.0",
+    "@imessage-sdk/chat-adapter": "0.1.0",
+    "imessage-cli": "0.0.0",
+    "imessage-sdk": "0.1.3",
+    "@imessage-sdk/blooio": "0.1.2",
+    "@imessage-sdk/photon": "0.1.2",
+    "@imessage-sdk/sendblue": "0.1.0"
+  },
+  "changesets": []
+}
diff --git a/.changeset/quiet-messages-cli.md b/.changeset/quiet-messages-cli.md
@@ -0,0 +1,7 @@
+---
+'imessage-cli': minor
+---
+
+Add the first provider-neutral iMessage CLI with bundled Blooio, Photon, and Sendblue support,
+secure named connections, JSON agent input and output, normalized messaging commands, provider
+extensions, and an opt-in experimental Hono-based local signed-webhook server.
diff --git a/AGENTS.md b/AGENTS.md
@@ -36,7 +36,7 @@ depend on the public `imessage-sdk` interface rather than provider internals.
 | `packages/providers/<provider>` | Independently published provider package                              |
 | `packages/providers/README.md`  | Cross-provider feature support matrix                                 |
 | `packages/chat-adapter`         | Chat SDK integration (`@imessage-sdk/chat-adapter`)                   |
-| `packages/cli`                  | Private placeholder for `@imessage-sdk/cli`                           |
+| `packages/cli`                  | Provider-neutral CLI (`imessage-cli`)                                 |
 | `examples/basic-blooio`         | Opt-in live example using only published Blooio and core APIs         |
 | `test/package-consumer`         | Clean TypeScript consumer used by package smoke tests                 |
 | `.changeset`                    | Changesets configuration, prerelease state, and pending release notes |
@@ -51,7 +51,7 @@ The repository does not use Turborepo. Workspace membership is defined only by
 ```text
 @imessage-sdk/<provider>     -> imessage-sdk
 @imessage-sdk/chat-adapter   -> imessage-sdk
-future adapters and CLI      -> imessage-sdk
+imessage-cli                 -> imessage-sdk + every official provider
 ```
 
 Workspace packages import package names, never source files from another package:
@@ -263,8 +263,9 @@ When adding a provider:
 6. Add an opt-in live integration test when real API verification is possible.
 7. Add the provider to `packages/providers/README.md` and its support matrix.
 8. Add the package to `scripts/check-packages.sh` and `test/package-consumer`.
-9. Document install, configuration, verified operations, and known limitations.
-10. Add a Changeset for all affected public packages.
+9. Add the provider to the `imessage-cli` registry; its completeness test must pass.
+10. Document install, configuration, verified operations, and known limitations.
+11. Add a Changeset for all affected public packages.
 
 ## Coding standards
 
@@ -324,7 +325,7 @@ Use conventional SemVer:
 - `major`: breaking changes
 
 Select only public packages actually affected. Tests, internal refactors, documentation-only
-changes, and private placeholder packages do not need a changeset unless they alter a published
+changes, and private workspace packages do not need a changeset unless they alter a published
 artifact. When Changesets prerelease mode is active, eligible releases receive the configured
 prerelease suffix.
 

diff --git a/README.md b/README.md
@@ -3,9 +3,10 @@
 A provider-neutral TypeScript conversation layer for iMessage infrastructure.
 
 The repository contains the provider-neutral [`imessage-sdk`](./packages/imessage-sdk)
-core, independently installable providers, and the
+core, independently installable providers, the
 [`@imessage-sdk/chat-adapter`](./packages/chat-adapter) for
-[Chat SDK](https://chat-sdk.dev). The core also exposes a public contract for custom providers.
+[Chat SDK](https://chat-sdk.dev), and [`imessage-cli`](./packages/cli) for local users and agents.
+The core also exposes a public contract for custom providers.
 
 ## Install
 
@@ -62,13 +63,29 @@ packages/
 │   ├── photon/            @imessage-sdk/photon
 │   └── sendblue/          @imessage-sdk/sendblue
 ├── chat-adapter/          @imessage-sdk/chat-adapter
-└── cli/                   Private placeholder for @imessage-sdk/cli
+└── cli/                   imessage-cli
 examples/
 └── basic-blooio/          Opt-in live Blooio API and webhook example
 ```
 
-The core, provider packages, and Chat SDK adapter are independently publishable. The repository
-root and remaining future package placeholders are private.
+The core, provider packages, Chat SDK adapter, and CLI are independently publishable. The
+repository root is private.
+
+## CLI
+
+The CLI bundles every official provider and supports flags, saved OS-keychain connections, stable
+JSON input/output, attachments, replies, normalized operations, and an experimental Hono-based
+local signed-webhook server:
+
+```bash
+npx imessage-cli@beta send \
+  --provider blooio \
+  --to +15551234567 \
+  --text 'Hello'
+```
+
+See the [CLI README](./packages/cli/README.md) for credential storage, agent input, provider
+commands, and ngrok or Cloudflare Tunnel setup.
 
 ## Chat SDK
 
@@ -119,7 +136,8 @@ then creates package-specific Git tags and GitHub Releases, such as
 
 Before publishing, the same release command used by automation also packs each
 public package, runs Publint and Are the Types Wrong, installs all tarballs in
-a clean strict-TypeScript consumer, and checks every public import.
+a clean strict-TypeScript consumer, checks every public import, and invokes the
+installed CLI.
 
 Stable releases publish under npm's `latest` dist-tag, while prereleases publish under `beta`. See
 [RELEASING.md](./RELEASING.md) for the complete maintainer workflow.

diff --git a/RELEASING.md b/RELEASING.md
@@ -5,14 +5,14 @@ requests, npm trusted publishing, and package-specific GitHub Releases.
 
 ## What is published
 
-| Directory                     | npm package                  | Status              |
-| ----------------------------- | ---------------------------- | ------------------- |
-| `packages/imessage-sdk`       | `imessage-sdk`               | Public              |
-| `packages/providers/blooio`   | `@imessage-sdk/blooio`       | Public              |
-| `packages/providers/photon`   | `@imessage-sdk/photon`       | Public              |
-| `packages/providers/sendblue` | `@imessage-sdk/sendblue`     | Public              |
-| `packages/chat-adapter`       | `@imessage-sdk/chat-adapter` | Public              |
-| `packages/cli`                | `@imessage-sdk/cli`          | Private placeholder |
+| Directory                     | npm package                  | Status |
+| ----------------------------- | ---------------------------- | ------ |
+| `packages/imessage-sdk`       | `imessage-sdk`               | Public |
+| `packages/providers/blooio`   | `@imessage-sdk/blooio`       | Public |
+| `packages/providers/photon`   | `@imessage-sdk/photon`       | Public |
+| `packages/providers/sendblue` | `@imessage-sdk/sendblue`     | Public |
+| `packages/chat-adapter`       | `@imessage-sdk/chat-adapter` | Public |
+| `packages/cli`                | `imessage-cli`               | Public |
 
 ## One-time local setup
 
@@ -102,7 +102,7 @@ changelogs.
 
 Configure trusted publishing separately in the settings for `imessage-sdk`,
 `@imessage-sdk/blooio`, `@imessage-sdk/photon`, `@imessage-sdk/sendblue`, and
-`@imessage-sdk/chat-adapter`:
+`@imessage-sdk/chat-adapter`, and `imessage-cli`:
 
 ```text
 Provider: GitHub Actions
@@ -154,6 +154,25 @@ pnpm --filter @imessage-sdk/<provider> pack --pack-destination "$PACKAGE_DIR"
 npm publish "$PACKAGE_DIR/<tarball>.tgz" --access public --provenance=false
 ```
 
+For the first `imessage-cli` beta, enter Changesets prerelease mode before the Version Packages
+pull request is generated:
+
+```bash
+pnpm changeset pre enter beta
+```
+
+After that pull request versions the package, bootstrap its exact tarball locally with `--tag beta`,
+then configure `imessage-cli` as another trusted publisher using the settings above:
+
+```bash
+PACKAGE_DIR=$(mktemp -d)
+pnpm --filter imessage-cli pack --pack-destination "$PACKAGE_DIR"
+npm publish "$PACKAGE_DIR/imessage-cli-0.1.0-beta.0.tgz" \
+  --tag beta \
+  --access public \
+  --provenance=false
+```
+
 Add `--tag beta` when bootstrapping a prerelease. For the initial stable Sendblue release, use:
 
 ```bash
@@ -282,6 +301,8 @@ npm view @imessage-sdk/blooio version
 npm dist-tag ls @imessage-sdk/blooio
 npm view @imessage-sdk/sendblue version
 npm dist-tag ls @imessage-sdk/sendblue
+npm view imessage-cli@beta version
+npm dist-tag ls imessage-cli
 ```
 
 Then install the release in a clean external project using `@beta` during the

diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imessage-sdk contributors
+
+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.