Build a CLI that lets people and AI agents search a messenger, a mailbox or any service with a history, in TypeScript on Node or Bun. You write the adapter that talks to the service, and cli-core gives it a local store with search, the shared commands and an MCP server.
import { type Messenger, mcpCommand, messagesCommand, run, searchCommand, settingsFor } from "@wirecat/cli-core/cli"
import { acmeAdapter } from "./adapter.js" // your code: the only part that speaks to Acme Chat
const app = { command: "acme", appName: "acme-cli", envPrefix: "ACME", description: "Acme Chat", version: "0.1.0" }
const settings = settingsFor(app)
const acme: Messenger = {
app,
provider: "acme",
resolveSettings: settings.resolveSettings,
connect: async () => acmeAdapter(),
chatArgument: "a chat: its name or its Acme id",
}
process.exitCode = await run(process.argv.slice(2), {
app,
configuration: settings,
commands: () => [messagesCommand(acme), searchCommand(acme), mcpCommand(acme)],
})acme personal messages sync --all # every chat's history into the local store
acme personal search messages come --json=excerpt # {"items":[{"excerpt":"are you coming?",…}],…}
acme personal mcp check # {"item":{"healthy":true,…,"tools":3,…},…}That output is real, from this program with the in-memory fakeAdapter of @wirecat/cli-core/testing in place of
Acme. The search found "are you coming?" from the word "come", with no network.
Built on it: tg-cli, max-cli, gcal-cli and 12 more WireCat CLIs, such as the mail and notes tool cli-memo, the WhatsApp tool, zoom-cli and drive-cli.
npm install --save-exact @wirecat/cli-corenpm 7+ and pnpm also install its peers: @wirecat/cli-base in the range package.json names, and commander 15 or
later. @napi-rs/canvas is optional, and charts need it only for PNG output. It runs on Node 22.16+ and 24+, and on
Bun. Pin an exact version, because any release before 1.0 may break a caller (Build on it).
Architecture · Write an adapter · Query language · Messenger rules · API reference · Changelog · wirecat.dev
flowchart LR
cli["Your CLI"] -->|"keeps messages, mail or files to search"| core["@wirecat/cli-core"]
cli -->|"any other CLI"| base["@wirecat/cli-base"]
core --> base
base --> runtime["Node or Bun"]
cli-core is for a tool that keeps what it reads in a local store and searches it. It is built on
@wirecat/cli-base, the layer every CLI needs: two output streams, closed
error codes, the keyring, injectable clocks and the query parser. cli-base is a peer dependency, so an install holds
one copy. A CLI with nothing to store needs only cli-base.
- Search that finds the message, not only the word. One query language for every list and every source, a
TypeScript port of the Apache Lucene 9.12.3 parsers: phrases,
from:(alice OR bob),date:[2026-01-01 TO 2026-02-01},size>10MB. Word forms in Russian, English and Spanish (встречаfindsвстречи), any three letters inside a word, and search by meaning when you opt in. A question over 100,341 synthetic messages took 54 ms at the median (measured, every search measurement). Syntax · grammar · image search - One store for every source. Messages from Telegram and MAX, mail, notes and meeting transcripts sit side by side
in one SQLite file,
wirecat.db, so one query searches all of them. Edits are kept as revisions and deletions as tombstones. Migrations only move forward, and an older CLI keeps reading a file a newer one migrated. Storage · why SQLite FTS5 and no daemon - An MCP server that leaves room in the agent's context. The shared commands reach an agent as 3 MCP tools: find a command, run a read, run a write. It runs over stdio, or over HTTP on 127.0.0.1 behind the owner's tunnel with a one-owner OAuth login.
- Every write behind a guard. A permission level per command path (deny, readonly, ask or allow), a list of allowed recipients, and at most 30 sends an hour by default. A write whose outcome is unknown is never retried, and a retry under the same send id cannot send twice.
- Knowledge, tasks and meetings across sources. What an agent proposes stays proposed until the owner accepts it.
Tasks have project keys like
RES-12, and a meeting transcript is kept by revision. Knowledge · Meetings · Mentions - Files and voice as text. Readers for PDF, Word, HTML and more, each loaded on first use, and speech recognition on your computer from a pinned model catalogue. Document workflows · Media archives
flowchart TB
tools["tg · max · wa · memo · zm · drive"] --> interface
subgraph core ["@wirecat/cli-core"]
interface["Interface: CLI commands and MCP tools"] --> services["Services: one use case each"]
services --> ports["Ports: MessengerAdapter · MeetingSource · TaskStore"]
services --> store[("Store: one SQLite file, wirecat.db")]
ports --> domain["Domain types"]
store --> domain
end
adapters["Adapters, in each tool: Telegram, MAX, IMAP, Zoom…"] -. implement .-> ports
core --> base["@wirecat/cli-base: output, exit codes, keyring, clocks, query parser"]
Five layers, and each calls only the layers below it: domain, adapters behind a port, ports, services, interface.
- The CLI and the MCP server are two adapters over the same services. A command and its MCP tool answer with the same data, because one service produces it.
- A port with one required core and optional groups.
MessengerCoreis what every messenger must do. Groups such as polls or forums are optional and reached throughcapability(). A messenger without a group refuses the command before it connects. It never crashes and never drops an option in silence. - Override a use case, not a command. A tool replaces one service through
Messenger.services, and every command and tool that uses it follows. - The build keeps the lines. Biome import rules refuse any messenger library under
src/,commanderin a service, and the SQLite tables outside the store. Tests refuse a gap in the migration numbers and a search plan that reads an index once per message.
A new messenger is three pieces: an adapter that implements MessengerCore (and any optional groups), a
Messenger that describes it, and the contract cases run against it. The
adapter guide walks through each one.
This runs as it is under vitest and gives 29 cases. fakeAdapter is the in-memory adapter the kit ships. Put your own
adapter there, built over a fake client filled from seed. The ./testing kit is not stable yet.
import { contractCases, digitIds, fakeAdapter } from "@wirecat/cli-core/testing"
import { describe, it } from "vitest"
describe("the adapter keeps the port's promises", () => {
for (const one of contractCases({ connect: (seed) => fakeAdapter(seed), ids: digitIds }))
it(one.name, async (context) => {
const result = await one.run()
if (result) context.skip(result.skipped)
})
})Before 1.0, any release may break a caller. Releases are frequent, sometimes several a day, and any of them may change any entry point. The changelog lists every such change in its own section, with what to change. tg-cli and max-cli pin an exact version and move to a new one in their own pull request. Pin an exact version too. The full list of entry points and what each holds is in the API reference.
⚠ Errors are recognised by shape, not by class (isCliFailure). A package linked during development brings its
own copy of cli-base, and an error built by one copy is not an instanceof the other's class.
The WireCat CLI standards handbook in cli-base binds every WireCat CLI, and the messenger rules add what binds tg, max and wa. They measure themselves against POSIX, GNU, Command Line Interface Guidelines, the MCP specification and JSON Schema 2020-12, and say where they differ on purpose.
- Tests that cannot touch real data. A sandbox keeps every test away from the owner's store, and no test may sleep. The coverage floor is 92% of lines, and at least half of every file.
- Checked against the tools that use it. Every pull request builds tg-cli, max-cli, whatsapp-cli and cli-template against the branch. Which checks run on macOS and Windows is in Testing.
- One shared toolchain. Biome, markdownlint, CSpell and Lefthook configs come from the WireCat standards, and CI fails when a copy drifts.
pnpm install
pnpm lint && pnpm typecheck && pnpm test
pnpm smoke:bun # the same exports, run under BunReleases go through bin/release from main. It refuses a dirty tree, runs every check, publishes to npm and tags
v<version>. The steps and the release rules are in RELEASING.md.
| Document | What it answers |
|---|---|
| Architecture | The layers, the module map, the store internals and migrations, who consumes what |
| Document workflows | Shared file ingestion, sync, scoped knowledge and extraction, and the ports a file provider supplies |
| Media archives | Independent verified file copies, interruption recovery and opt-in daily timers |
| Write an adapter | How to add a messenger: the port, the Messenger description, the contract cases |
| Messenger rules | What binds tg, max and wa beyond the CLI standards handbook: parity, the option catalogue, bot |
| Glossary | One word, one meaning across the tools |
| Query language · spec · Image search | The search syntax and its exact grammar, and finding pictures by context and by what they show |
| Mentions · how they work | Phones, e-mail, links, documents and names found in messages: search, review, rebuild, the tables and the rules |
| Storage | The schema, the search indexes and the decisions behind them |
| Knowledge · Meetings | Labels, links and proposals across sources, the meetings module and its providers |
| Testing · Parity audit | The sandbox, the coverage floor, the checks across tg and max |
| Tool boundaries | Which tool owns which command |
| API reference | Every entry point and the detailed contract of each feature |
| Roadmap | What is being built next for developers on this package |
| Changelog | What each version changed, and what may break callers |
Up to 0.261.0 the package was named @wirecat/cli-messaging, which is deprecated. The npm versions 0.0.0-stage, 0.0.0
and 0.18 to 0.20 of @wirecat/cli-core are deprecated too: they are placeholders and the old cli-base.
