@wirecat/cli-core 0.392.0 → 0.393.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## 0.393.0 — 23.10.2026
+
+### Added
+
+- Tag commands include concrete examples in help and command discovery.
+
+- Chat commands include concrete examples in help and command discovery.
+- Contact commands include concrete examples in help and command discovery.
+- **`@wirecat/cli-base` 0.50.0 is accepted beside 0.49.** The peer range is now `>=0.49.0 <0.51.0`, so a CLI that
+  takes cli-base 0.50.0 for `adaptOpenApi` (whatsapp-cli's bot API) keeps one copy of cli-base instead of two.
+  Nothing in cli-core calls what 0.50.0 added.
+
 ## 0.392.0 — 23.10.2026
 
 ### Added

package/dist/cli/messenger/chats-command.js

@@ -6,6 +6,7 @@ import { LOCAL_READ, REMOTE_READ } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { withQuery } from "../list-query.js";
 import { withPaging } from "../paging.js";
+import { commandAt } from "../steps.js";
 import { groupCommands } from "./admin-commands.js";
 import { foldersCommand } from "./admin-folders-command.js";
 import { moderateCommand, rulesCommand } from "./admin-moderation-command.js";
@@ -102,6 +103,55 @@ export const chatsCommand = (messenger) => {
     if (messenger.personalBots === true)
         for (const command of botChatCommands(messenger))
             chats.addCommand(command);
+    const examples = {
+        "admins add": `"Book club" "Alex Example"${messenger.pickAdminRights === false ? "" : ` --can ${messenger.adminRights?.[0] ?? "info"}`}`,
+        "admins remove": '"Book club" "Alex Example"',
+        create: '"Book club" "Alex Example"',
+        "documents list": '"Project room" --limit 10',
+        events: '"Book club"',
+        "folders create": '"Reading" --chat "Book club"',
+        "folders delete": '"Reading"',
+        "folders join": "https://t.me/addlist/example",
+        "folders list": "",
+        "folders order": '"Reading" "Work"',
+        "folders show": '"Reading"',
+        "folders update": '"Reading" --title "Books"',
+        inspect: "https://example.com/invite/book-club",
+        join: "https://example.com/invite/book-club",
+        leave: '"Book club"',
+        "link create": '"Book club"',
+        "link list": '"Book club"',
+        "link reset": '"Book club"',
+        "link revoke": '"Book club" https://example.com/invite/book-club',
+        "link show": '"Book club"',
+        list: "--limit 10",
+        "mark-read": '"Book club" --until-id 101',
+        "members add": '"Book club" "Alex Example"',
+        "members audit": '"Book club"',
+        "members fetch": '"Book club"',
+        "members history": '"Book club"',
+        "members list": '"Book club"',
+        "members remove": '"Book club" "Alex Example"',
+        moderate: '"Book club" --dry-run',
+        "requests accept": '"Book club" "Alex Example"',
+        "requests decline": '"Book club" "Alex Example"',
+        "requests list": '"Book club"',
+        "rules set": '"Book club" links report',
+        "rules show": '"Book club"',
+        "rules unset": '"Book club" links',
+        "send-as": '"Project room"',
+        show: '"Book club"',
+        "tracking add": '"Book club"',
+        "tracking list": "",
+        "tracking remove": '"Book club"',
+        "tracking show": '"Book club"',
+        update: '"Book club" --title "Reading group"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(chats, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal chats ${path} ${args}`.trimEnd()] });
+    }
     return chats;
 };
 /** Where the history is pushed, the chat list and a chat's card answer from the store and never connect. */

package/dist/cli/messenger/contacts-command.js

@@ -15,7 +15,7 @@ import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { listQuery, nativeTerms, typedQuery, withQuery } from "../list-query.js";
 import { positiveCount, window, withPaging } from "../paging.js";
 import { casKey } from "../registry-keys.js";
-import { nextStep } from "../steps.js";
+import { commandAt, nextStep } from "../steps.js";
 import { contactWriteCommands } from "./admin-contacts-command.js";
 import { contactAnswer, lines, pageOf } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
@@ -250,5 +250,35 @@ export const contactsCommand = (messenger) => {
         contacts.addCommand(command);
     for (const command of contactWriteCommands(messenger))
         contacts.addCommand(command);
+    const examples = {
+        add: '"Alex Example"',
+        "alias rm": '"Alex Example"',
+        "alias set": '"Alex Example" "Reading partner"',
+        block: '"Alex Example"',
+        check: '"Alex Example"',
+        context: '"Alex Example" --limit 10',
+        import: "./contacts.csv",
+        link: '"Alex Example" zoom:101',
+        list: "--limit 10",
+        lookup: "",
+        "notes add": '"Alex Example" --file ./note.txt',
+        "notes edit": '"Alex Example" 1 --revision 1 --file ./note.txt',
+        "notes list": '"Alex Example"',
+        "notes remove": '"Alex Example" 1',
+        "notes show": '"Alex Example" 1',
+        profile: '"Alex Example"',
+        remove: '"Alex Example"',
+        rename: '"Alex Example" Alex Example',
+        show: '"Alex Example"',
+        sync: "",
+        timeline: '"Alex Example" --limit 10',
+        unblock: '"Alex Example"',
+        unlink: '"Alex Example"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(contacts, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal contacts ${path} ${args}`.trimEnd()] });
+    }
     return contacts;
 };

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -2,9 +2,9 @@ import { Command } from "commander";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
-    error?: undefined;
     path: string;
     exists: boolean;
+    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/cli/messenger/tags-command.js

@@ -28,8 +28,9 @@ const sourceOf = (value) => {
 };
 /** The owner's labels, in the local store only: `tag:` in a search finds what they label. */
 export const tagsCommand = (messenger) => {
+    const tool = `${messenger.app.command} personal`;
     const tags = new Command("tags").description("your own labels on chats, people, messages and tasks, kept in the local store and never sent; tag: in a search finds them");
-    changesStore(annotate(tags.command("auto"), { effects: FETCH }))
+    changesStore(annotate(tags.command("auto"), { effects: FETCH, examples: [`${tool} tags auto --chat "Book club" --dry-run`] }))
         .description("derive local group/channel tags from cached metadata using keyword rules")
         .option("--chat <chat>", "a stored group/channel; repeat to select several", (value, previous) => [...previous, value], [])
         .option("--limit <number>", "process at most 1–500 chats", positiveCount("--limit"), 50)
@@ -43,7 +44,10 @@ export const tagsCommand = (messenger) => {
         const done = await context.withServices((services) => services.metadata.auto({ chats: chat, limit: Number(limit), refresh: syncFirst, dryRun }));
         renderAnswer(this, context, itemOf(snakeKeys(done)));
     });
-    targetOptions(annotate(tags.command("add"), { effects: LOCAL_WRITE }).description("put tags on one chat, person, message or task"), messenger, "tag").action(async function (given) {
+    targetOptions(annotate(tags.command("add"), {
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tags add reading --chat "Book club"`],
+    }).description("put tags on one chat, person, message or task"), messenger, "tag").action(async function (given) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "tags.add");
         const target = this.opts();
@@ -52,7 +56,10 @@ export const tagsCommand = (messenger) => {
         if (done.unchanged.length && context.format === "pretty")
             context.renderer.note(`already there: ${done.unchanged.join(", ")}`);
     });
-    targetOptions(annotate(tags.command("remove"), { effects: LOCAL_WRITE }).description("take tags off one chat, person, message or task"), messenger, "untag")
+    targetOptions(annotate(tags.command("remove"), {
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tags remove reading --chat "Book club"`],
+    }).description("take tags off one chat, person, message or task"), messenger, "untag")
         .option("--source <manual|auto>", "remove only this ownership claim", sourceOf)
         .action(async function (given) {
         const context = messengerContext(this, messenger);
@@ -63,7 +70,10 @@ export const tagsCommand = (messenger) => {
         if (done.unchanged.length && context.format === "pretty")
             context.renderer.note(`not there: ${done.unchanged.join(", ")}`);
     });
-    withQuery(annotate(tags.command("list"), { effects: LOCAL_READ }).description("what is tagged: this account's chats, messages and tasks, and the people of its messenger"), TAGGING_QUERY).action(async function (words) {
+    withQuery(annotate(tags.command("list"), {
+        effects: LOCAL_READ,
+        examples: [`${tool} tags list`, `${tool} tags list tag:reading`],
+    }).description("what is tagged: this account's chats, messages and tasks, and the people of its messenger"), TAGGING_QUERY).action(async function (words) {
         const context = messengerContext(this, messenger);
         const query = listQuery(typedQuery(words), TAGGING_QUERY, "tags list");
         const found = await context.withServices((services) => services.tags.list({ ...(query ? { query } : {}), ...pageOf(context.settings) }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.392.0",
+  "version": "0.393.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -207,7 +207,7 @@
     "@types/node": "^22.20.4",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.2",
-    "@wirecat/cli-base": "0.49.0",
+    "@wirecat/cli-base": "0.50.0",
     "commander": "15.0.0",
     "cspell": "10.3.6",
     "drizzle-kit": "1.0.0-rc.4",
@@ -227,7 +227,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.49.0 <0.50.0",
+    "@wirecat/cli-base": ">=0.49.0 <0.51.0",
     "commander": ">=15"
   },
   "bin": {