@circleback/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,104 @@
+# Circleback CLI
+
+Search and access your meetings, transcripts, emails, calendar events, and more from the terminal.
+
+## Installation
+
+```bash
+npm install -g @circleback/cli
+```
+
+Requires Node.js 18 or later. The package installs two binaries: `circleback` and `cb` (shorthand).
+
+## Quick start
+
+```bash
+# Authenticate via browser
+cb login
+
+# Search recent meetings
+cb meetings
+
+# Search by keyword
+cb meetings "product review"
+
+# Read full meeting details
+cb meetings read 12345
+
+# Search transcripts
+cb transcripts "pricing discussion"
+
+# Search emails
+cb emails "from:alice@example.com after:2026-01-01"
+
+# Get raw JSON for scripting
+cb meetings --json
+```
+
+## Commands
+
+| Command                        | Description                                         |
+| ------------------------------ | --------------------------------------------------- |
+| `cb login`                     | Authenticate with Circleback via browser            |
+| `cb logout`                    | Clear stored authentication tokens                  |
+| `cb update`                    | Update CLI to the latest version                    |
+| `cb meetings [search]`         | Search meetings                                     |
+| `cb meetings read <ids...>`    | Read detailed meeting info, notes, and action items |
+| `cb transcripts <search>`      | Search transcript content                           |
+| `cb transcripts read <ids...>` | Read full transcripts                               |
+| `cb calendar`                  | Search calendar events                              |
+| `cb people <names...>`         | Search people by name                               |
+| `cb companies <terms...>`      | Search companies by domain                          |
+| `cb emails [search]`           | Search connected email accounts                     |
+| `cb support [search]`          | Search Circleback support articles                  |
+
+Run `cb --help` or `cb <command> --help` for full usage details.
+
+## Filtering
+
+Meeting, transcript, and calendar searches support filtering by date range. Meeting and transcript searches also support filtering by tag, person, and company:
+
+```bash
+cb meetings --tags 1,2 --profiles 42 --domains acme.com
+cb meetings --last 30              # Last 30 days
+cb meetings --from 2026-01-01 --to 2026-03-01
+cb calendar --last 7                # Next 7 days of events
+```
+
+Email search supports inline filter syntax:
+
+```bash
+cb emails "from:alice@example.com"
+cb emails "to:bob@example.com after:2026-01-01"
+cb emails "participant:carol@example.com before:2026-06-01"
+```
+
+## JSON output
+
+Pass `--json` to any command to get raw JSON instead of formatted tables. Useful for piping to `jq` or integrating with other tools:
+
+```bash
+cb meetings "standup" --json | jq '.[].name'
+```
+
+## Authentication
+
+```bash
+cb login    # Opens browser to authenticate
+cb logout   # Clears stored tokens
+```
+
+## Agents
+
+The CLI is designed to work well with AI agents and tool-use systems:
+
+- Every command accepts `--json` for structured, parseable output
+- Commands follow a consistent `<resource> <action>` pattern
+- All options have long-form names for clarity
+- Error messages include actionable instructions
+- Exit codes follow standard conventions (0 = success, 1 = error)
+
+## Links
+
+- [Circleback](https://circleback.ai)
+- [Support](https://support.circleback.ai)

package/dist/commands/meetings.js

@@ -64,7 +64,7 @@ exports.searchMeetingsCommand = new commander_1.Command('search')
 });
 exports.readMeetingsCommand = new commander_1.Command('read')
     .description('Get detailed information for meetings.')
-    .argument('<ids…>', 'Meeting IDs')
+    .argument('<ids...>', 'Meeting IDs')
     .action(async (ids) => {
     try {
         const jsonMode = exports.readMeetingsCommand.parent?.parent?.opts().json ?? false;

package/dist/commands/transcripts.js

@@ -12,18 +12,18 @@ const formatter_1 = require("../helpers/formatter");
 const parse_1 = require("../helpers/parse");
 exports.searchTranscriptsCommand = new commander_1.Command('search')
     .description('Search meeting transcripts.')
-    .argument('[search]', 'Search term')
+    .argument('<search>', 'Search term')
     .option('--tags <ids>', 'Comma-separated tag IDs')
     .option('--profiles <ids>', 'Comma-separated profile IDs')
     .option('--domains <domains>', 'Comma-separated domains')
+    .showHelpAfterError(true)
     .action(async (query, options) => {
     try {
         const jsonMode = exports.searchTranscriptsCommand.parent?.parent?.opts().json ?? false;
         const arguments_ = {
-            intent: query ?? 'Listing recent transcripts.',
+            intent: query,
+            searchTerm: query,
         };
-        if (query)
-            arguments_['searchTerm'] = query;
         if (options.tags)
             arguments_['tags'] = (0, parse_1.parseNumericIds)(options.tags, 'tag ID');
         if (options.profiles)
@@ -41,7 +41,7 @@ exports.searchTranscriptsCommand = new commander_1.Command('search')
 });
 exports.getTranscriptsCommand = new commander_1.Command('read')
     .description('Get full transcripts for meetings.')
-    .argument('<meetingId…>', 'Meeting IDs (max 50)')
+    .argument('<meetingId...>', 'Meeting IDs (max 50)')
     .showHelpAfterError(true)
     .action(async (ids) => {
     try {

package/dist/helpers/formatter.js

@@ -11,7 +11,7 @@ const safeParse = (rawText) => {
     }
 };
 const stringify = (value) => typeof value === 'string' ? value : JSON.stringify(value, null, 2);
-const formatArrayForTool = (toolName, data) => {
+const formatForTool = (toolName, data) => {
     if (!Array.isArray(data))
         return;
     switch (toolName) {
@@ -43,7 +43,7 @@ const formatOutput = (toolName, rawText, jsonMode) => {
         console.log(stringify(parsed));
         return;
     }
-    const formatted = formatArrayForTool(toolName, parsed);
+    const formatted = formatForTool(toolName, parsed);
     console.log(formatted ?? stringify(parsed));
 };
 exports.formatOutput = formatOutput;

package/dist/helpers/table.js

@@ -13,8 +13,21 @@ const idColumnWidth = (ids) => {
     const maxLength = ids.reduce((max, id) => Math.max(max, String(id).length), 2);
     return maxLength + 2;
 };
-const formatAttendee = (attendee) => attendee.email ? `${attendee.name} (${attendee.email})` : attendee.name;
+const formatAttendee = (attendee) => {
+    if (attendee.name && attendee.email)
+        return `${attendee.name} (${attendee.email})`;
+    return attendee.name ?? attendee.email ?? 'Unknown';
+};
+const formatAssignee = (assignee) => {
+    if (!assignee)
+        return 'Unassigned';
+    if (assignee.name && assignee.email)
+        return `${assignee.name} (${assignee.email})`;
+    return assignee.name ?? assignee.email ?? 'Unassigned';
+};
 const formatSender = (sender) => {
+    if (!sender)
+        return 'Unknown';
     if (typeof sender === 'string')
         return sender;
     if (sender.name && sender.email)
@@ -62,9 +75,9 @@ const formatMeetingDetails = (meetings) => {
             meeting.duration
                 ? `${chalk_1.default.bold('Duration:')} ${Math.round(meeting.duration / 60)} min`
                 : null,
-            `${chalk_1.default.bold('Attendees:')}\n${meeting.attendees.map((attendee) => `  ${formatAttendee(attendee)}`).join('\n')}`,
-            meeting.tags.length > 0
-                ? `${chalk_1.default.bold('Tags:')} ${meeting.tags.map((tag) => tag.name).join(', ')}`
+            `${chalk_1.default.bold('Attendees:')}\n${(meeting.attendees ?? []).map((attendee) => `  ${formatAttendee(attendee)}`).join('\n')}`,
+            (meeting.tags ?? []).length > 0
+                ? `${chalk_1.default.bold('Tags:')} ${(meeting.tags ?? []).join(', ')}`
                 : null,
         ]
             .filter(Boolean)
@@ -73,7 +86,7 @@ const formatMeetingDetails = (meetings) => {
             ? `\n${chalk_1.default.bold('Notes:')}\n${meeting.notes}`
             : '';
         const actionItems = meeting.actionItems && meeting.actionItems.length > 0
-            ? `\n${chalk_1.default.bold('Action Items:')}\n${meeting.actionItems.map((item) => `  - ${item.text}${item.assignee ? ` (${item.assignee})` : ''}`).join('\n')}`
+            ? `\n${chalk_1.default.bold('Action Items:')}\n${meeting.actionItems.map((item) => `  - ${item.title} [${formatAssignee(item.assignee)}]`).join('\n')}`
             : '';
         return `${header}\n${meta}${notes}${actionItems}`;
     })
@@ -108,7 +121,7 @@ const formatTranscriptSearchResults = (results) => {
     });
     results.forEach((result) => {
         table.push([
-            (0, string_1.truncate)(result.meetingName ?? 'Unknown', meetingWidth - 2),
+            (0, string_1.truncate)(result.meetingName || 'New meeting', meetingWidth - 2),
             result.meetingId,
             (0, string_1.truncate)(result.content, contentWidth - 2),
         ]);
@@ -137,7 +150,7 @@ const formatCalendarEvents = (events) => {
             (0, date_1.formatDateTime)(event.startTime),
             (0, date_1.formatDateTime)(event.endTime),
             event.platform ?? '-',
-            event.attendees.map(formatAttendee).join('\n'),
+            event.attendees?.map(formatAttendee).join('\n') ?? '-',
         ]);
     });
     return `${chalk_1.default.bold((0, string_1.pluralize)(events.length, 'event', 'events'))}\n${table.toString()}`;
@@ -189,23 +202,19 @@ const formatSupportArticles = (articles) => {
         .join('\n\n');
 };
 exports.formatSupportArticles = formatSupportArticles;
+const formatMessage = (message) => {
+    const header = chalk_1.default.bold.cyan(message.subject ?? 'No subject');
+    const meta = `${chalk_1.default.bold('From:')} ${formatSender(message.sender)}  ${chalk_1.default.dim((0, date_1.formatDateTime)(message.receivedOn))}`;
+    const preview = message.content
+        ? (0, string_1.truncate)(message.content.replace(/\s+/g, ' ').trim(), 200)
+        : '';
+    return `${header}\n${meta}\n${preview}`;
+};
 const formatEmails = (threads) => {
     if (threads.length === 0)
         return chalk_1.default.yellow('No emails found.');
     return threads
-        .map((thread) => {
-        const latestMessage = thread.messages[0];
-        if (!latestMessage)
-            return '';
-        const header = chalk_1.default.bold.cyan(latestMessage.subject);
-        const meta = `${chalk_1.default.bold('From:')} ${formatSender(latestMessage.sender)}  ${chalk_1.default.dim((0, date_1.formatDateTime)(latestMessage.receivedOn))}`;
-        const messageCount = thread.messages.length > 1
-            ? chalk_1.default.dim(`(${thread.messages.length} messages in thread)`)
-            : '';
-        const preview = (0, string_1.truncate)(latestMessage.content.replace(/\s+/g, ' ').trim(), 200);
-        return `${header}\n${meta} ${messageCount}\n${preview}`;
-    })
-        .filter(Boolean)
+        .flatMap((thread) => thread.messages.map(formatMessage))
         .join('\n\n---\n');
 };
 exports.formatEmails = formatEmails;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circleback/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Circleback CLI. Search and access meetings, emails, calendar events, and more.",
   "license": "MIT",
   "author": "Circleback <support@circleback.ai> (https://circleback.ai)",
@@ -25,6 +25,7 @@
     "prebuild": "rm -rf dist",
     "build": "tsc && chmod +x dist/index.js",
     "typecheck": "tsc --noEmit",
+    "postinstall": "echo '\n  Welcome to the Circleback CLI. Run `circleback` or `cb` to get started.\n'",
     "prepublishOnly": "npm run build"
   },
   "publishConfig": {