Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(cli): add realtime triggers listen with forward and file options

haxzie28446d5a7960
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 77d41afd0..9309cf851 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -680,16 +680,16 @@ importers:
version: link:../../packages/providers/llamaindex
'@llamaindex/openai':
specifier: ^0.4.20
- version: 0.4.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
+ version: 0.4.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
'@llamaindex/workflow':
specifier: ^1.1.24
- version: 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])
+ version: 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])
dotenv:
specifier: ^16.4.1
version: 16.6.1
llamaindex:
specifier: ^0.12.0
devDependencies:
'@types/bun':
specifier: ^1.2.9
@@ -1059,6 +1059,9 @@ importers:
picocolors:
specifier: ^1.1.1
version: 1.1.1
+ pusher-js:
+ specifier: ^8.4.0
+ version: 8.4.0
semver:
specifier: ^7.7.2
version: 7.7.4
@@ -1286,7 +1289,7 @@ importers:
dependencies:
llamaindex:
specifier: ^0.12.0
devDependencies:
'@composio/core':
specifier: workspace:*
@@ -7548,26 +7551,43 @@ snapshots:
tree-sitter: 0.22.4
web-tree-sitter: 0.24.7
dependencies:
'@llamaindex/core': 0.6.22
'@llamaindex/env': 0.1.30
transitivePeerDependencies:
- ws
- zod
optionalDependencies:
- '@modelcontextprotocol/sdk': 1.26.0(@cfworker/[email protected])([email protected])
+ '@modelcontextprotocol/sdk': 1.26.0(@cfworker/[email protected])([email protected])
hono: 4.11.9
+ zod: 3.25.76
+
+ optionalDependencies:
zod: 4.3.6
dependencies:
'@llamaindex/core': 0.6.22
'@llamaindex/env': 0.1.30
- '@llamaindex/workflow-core': 1.3.3(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])
+ '@llamaindex/workflow-core': 1.3.3(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])
+ transitivePeerDependencies:
+ - '@modelcontextprotocol/sdk'
+ - hono
+ - next
+ - p-retry
+ - rxjs
+ - zod
+
+ dependencies:
+ '@llamaindex/core': 0.6.22
+ '@llamaindex/env': 0.1.30
+ '@llamaindex/workflow-core': 1.3.3([email protected])
transitivePeerDependencies:
- '@modelcontextprotocol/sdk'
- hono
@@ -8552,6 +8572,14 @@ snapshots:
optionalDependencies:
+ dependencies:
+ '@vitest/spy': 3.2.4
+ estree-walker: 3.0.3
+ magic-string: 0.30.21
+ optionalDependencies:
+
'@vitest/[email protected]':
dependencies:
tinyrainbow: 2.0.0
@@ -8581,7 +8609,7 @@ snapshots:
sirv: 3.0.2
tinyglobby: 0.2.15
tinyrainbow: 2.0.0
'@vitest/[email protected]':
dependencies:
@@ -9948,12 +9976,34 @@ snapshots:
rfdc: 1.4.1
wrap-ansi: 9.0.2
+ dependencies:
+ '@llamaindex/core': 0.6.22
+ '@llamaindex/env': 0.1.30
+ '@llamaindex/node-parser': 2.0.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
+ '@llamaindex/workflow': 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])
+ '@types/lodash': 4.17.23
+ '@types/node': 24.10.13
+ lodash: 4.17.23
+ magic-bytes.js: 1.13.0
+ transitivePeerDependencies:
+ - '@huggingface/transformers'
+ - '@modelcontextprotocol/sdk'
+ - gpt-tokenizer
+ - hono
+ - next
+ - p-retry
+ - rxjs
+ - tree-sitter
+ - web-tree-sitter
+ - zod
+
dependencies:
'@llamaindex/core': 0.6.22
'@llamaindex/env': 0.1.30
'@llamaindex/node-parser': 2.0.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
- '@llamaindex/workflow': 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])
+ '@llamaindex/workflow': 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])
'@types/lodash': 4.17.23
'@types/node': 24.10.13
lodash: 4.17.23
@@ -10233,6 +10283,11 @@ snapshots:
is-inside-container: 1.0.0
wsl-utils: 0.1.0
+ optionalDependencies:
+ ws: 8.19.0
+ zod: 3.25.76
+
optionalDependencies:
ws: 8.19.0
@@ -11330,7 +11385,7 @@ snapshots:
dependencies:
'@types/chai': 5.2.3
'@vitest/expect': 3.2.4
'@vitest/pretty-format': 3.2.4
'@vitest/runner': 3.2.4
'@vitest/snapshot': 3.2.4
diff --git a/ts/packages/cli/package.json b/ts/packages/cli/package.json
index 4c1b9abe5..ac3ef33c6 100644
--- a/ts/packages/cli/package.json
+++ b/ts/packages/cli/package.json
@@ -78,6 +78,7 @@
"open": "^10.2.0",
"openapi-typescript": "^7.8.0",
"picocolors": "^1.1.1",
+ "pusher-js": "^8.4.0",
"semver": "^7.7.2",
"source-map-js": "^1.2.1",
"superjson": "^2.2.2",
diff --git a/ts/packages/cli/src/bin.ts b/ts/packages/cli/src/bin.ts
index 30216d285..23f8f116a 100644
--- a/ts/packages/cli/src/bin.ts
+++ b/ts/packages/cli/src/bin.ts
@@ -21,6 +21,7 @@ import { JsPackageManagerDetector } from 'src/services/js-package-manager-detect
import { ComposioUserContextLive as _ComposioUserContextLive } from 'src/services/user-context';
import { UpgradeBinary } from 'src/services/upgrade-binary';
import { TerminalUILive } from 'src/services/terminal-ui';
+import { TriggersRealtime } from 'src/services/triggers-realtime';
/**
* Concrete Effect layer compositions for the Composio CLI runtime.
@@ -65,6 +66,11 @@ export const UpgradeBinaryLive = Layer.provide(
Layer.mergeAll(BunFileSystem.layer, FetchHttpClient.layer)
) satisfies RequiredLayer;
+export const TriggersRealtimeLive = Layer.provide(
+ TriggersRealtime.Default,
+ Layer.mergeAll(BunFileSystem.layer, NodeOs.Default)
+) satisfies RequiredLayer;
+
const layers = Layer.mergeAll(
CliConfigLive.pipe(Layer.provide(ConfigLive)),
NodeOs.Default,
@@ -75,6 +81,7 @@ const layers = Layer.mergeAll(
ComposioToolkitsRepositoryCachedLive, // Use the cached layer instead of the regular one
EnvLangDetector.Default,
JsPackageManagerDetector.Default,
+ TriggersRealtimeLive,
BunContext.layer,
BunFileSystem.layer,
TerminalUILive,
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index 931eb7acd..edf56e732 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -15,6 +15,7 @@ import { toolkitsCmd } from './toolkits/toolkits.cmd';
import { toolsCmd } from './tools/tools.cmd';
import { authConfigsCmd } from './auth-configs/auth-configs.cmd';
import { connectedAccountsCmd } from './connected-accounts/connected-accounts.cmd';
+import { triggersCmd } from './triggers/triggers.cmd';
const $cmd = $defaultCmd.pipe(
Command.withSubcommands([
@@ -30,6 +31,7 @@ const $cmd = $defaultCmd.pipe(
toolsCmd,
authConfigsCmd,
connectedAccountsCmd,
+ triggersCmd,
])
);
diff --git a/ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts b/ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts
new file mode 100644
index 000000000..e945a2933
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts
@@ -0,0 +1,304 @@
+import { Command, Options } from '@effect/cli';
+import { Deferred, Effect, Option, Runtime } from 'effect';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { requireAuth } from 'src/effects/require-auth';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { TriggersRealtime } from 'src/services/triggers-realtime';
+import { matchesTriggerListenFilters } from '../filter';
+import { formatTriggerListenSummary } from '../format';
+import { parseTriggerListenEvent } from '../parse';
+import type { TriggerListenFilters } from '../types';
+
+const toolkits = Options.text('toolkits').pipe(
+ Options.withDescription(
+ 'Filter by toolkit slugs, comma-separated (e.g. "gmail" or "gmail,slack")'
+ ),
+ Options.optional
+);
+
+const triggerId = Options.text('trigger-id').pipe(
+ Options.withDescription('Filter by trigger id'),
+ Options.optional
+);
+
+const connectedAccountId = Options.text('connected-account-id').pipe(
+ Options.withDescription('Filter by connected account id'),
+ Options.optional
+);
+
+const triggerSlug = Options.text('trigger-slug').pipe(
+ Options.withDescription(
+ 'Filter by trigger slug, comma-separated (e.g. "GMAIL_NEW_GMAIL_MESSAGE")'
+ ),
+ Options.optional
+);
+
+const userId = Options.text('user-id').pipe(
+ Options.withDescription('Filter by user id'),
+ Options.optional
+);
+
+const json = Options.boolean('json').pipe(
+ Options.withDefault(false),
+ Options.withDescription('Show raw event payload as JSON in interactive mode')
+);
+
+const maxEvents = Options.integer('max-events').pipe(
+ Options.withDescription('Stop after receiving N matching events'),
+ Options.optional
+);
+
+const forward = Options.text('forward').pipe(
+ Options.withDescription(
+ 'Forward each matching event to the given URL (signed with COMPOSIO_WEBHOOK_SECRET)'
+ ),
+ Options.optional
+);
+
+const out = Options.text('out').pipe(
+ Options.withDescription('Append each matching event to this file'),
+ Options.optional
+);
+
+const parseCsv = (value: string): ReadonlyArray<string> =>
+ value
+ .split(',')
+ .map(item => item.trim())
+ .filter(Boolean);
+
+const randomUUID = () => crypto.randomUUID();
+
+const signWebhookPayload = async ({
+ secret,
+ webhookId,
+ webhookTimestamp,
+ payload,
+}: {
+ secret: string;
+ webhookId: string;
+ webhookTimestamp: string;
+ payload: string;
+}) => {
+ const toSign = `${webhookId}.${webhookTimestamp}.${payload}`;
+ const key = await crypto.subtle.importKey(
+ 'raw',
+ new TextEncoder().encode(secret),
+ { name: 'HMAC', hash: 'SHA-256' },
+ false,
+ ['sign']
+ );
+ const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(toSign));
+ const bytes = new Uint8Array(signature);
+ const digest = btoa(String.fromCharCode(...bytes));
+ return `v1,${digest}`;
+};
+
+const detectWebhookPayloadVersion = (eventData: Record<string, unknown>): 'V1' | 'V2' | 'V3' => {
+ if (
+ typeof eventData.id === 'string' &&
+ typeof eventData.type === 'string' &&
+ typeof eventData.timestamp === 'string' &&
+ typeof eventData.metadata === 'object' &&
+ eventData.metadata !== null &&
+ typeof eventData.data === 'object' &&
+ eventData.data !== null
+ ) {
+ return 'V3';
+ }
+
+ if (
+ typeof eventData.type === 'string' &&
+ typeof eventData.timestamp === 'string' &&
+ typeof eventData.log_id === 'string' &&
+ typeof eventData.data === 'object' &&
+ eventData.data !== null
+ ) {
+ return 'V2';
+ }
+
+ return 'V1';
+};
+
+export const triggersCmd$Listen = Command.make(
+ 'listen',
+ {
+ toolkits,
+ triggerId,
+ connectedAccountId,
+ triggerSlug,
+ userId,
+ json,
+ maxEvents,
+ forward,
+ out,
+ },
+ ({
+ toolkits,
+ triggerId,
+ connectedAccountId,
+ triggerSlug,
+ userId,
+ json,
+ maxEvents,
+ forward,
+ out,
+ }) =>
+ Effect.gen(function* () {
+ if (!(yield* requireAuth)) return;
+
+ const ui = yield* TerminalUI;
+ const realtime = yield* TriggersRealtime;
+ const runtime = yield* Effect.runtime<never>();
+ const forwardUrl = Option.getOrUndefined(forward);
+ const generatedWebhookSecret = `composio-forward-secret-${randomUUID()}`;
+ const webhookSecret = process.env.COMPOSIO_WEBHOOK_SECRET ?? generatedWebhookSecret;
+ const outputFilePathOption = Option.getOrUndefined(out);
+ const outputFilePath = outputFilePathOption ? path.resolve(outputFilePathOption) : undefined;
+
+ if (outputFilePath) {
+ // Ensure output directory exists before listening.
+ yield* Effect.tryPromise({
+ try: async () => {
+ await fs.mkdir(path.dirname(outputFilePath), { recursive: true });
+ },
+ catch: error => new Error(`Failed to prepare output file directory: ${String(error)}`),
+ }).pipe(
+ Effect.catchAll(error =>
+ Effect.gen(function* () {
+ yield* ui.log.error(String(error));
+ return yield* Effect.fail(error);
+ })
+ )
+ );
+ }
+
+ const filters: TriggerListenFilters = {
+ toolkits: Option.isSome(toolkits) ? parseCsv(toolkits.value) : undefined,
+ triggerId: Option.getOrUndefined(triggerId),
+ connectedAccountId: Option.getOrUndefined(connectedAccountId),
+ triggerSlug: Option.isSome(triggerSlug) ? parseCsv(triggerSlug.value) : undefined,
+ userId: Option.getOrUndefined(userId),
+ };
+
+ const maxEventsLimit = Option.getOrUndefined(maxEvents);
+ const stopWhenDone = yield* Deferred.make<void>();
+ let matchingEvents = 0;
+
+ yield* ui.intro('composio triggers listen');
+ if (forwardUrl) {
+ if (process.env.COMPOSIO_WEBHOOK_SECRET) {
+ yield* ui.note(
+ `Forward URL: ${forwardUrl}\nSigning secret: ${webhookSecret}`,
+ 'Forwarding'
+ );
+ } else {
+ yield* ui.log.warn(
+ 'No COMPOSIO_WEBHOOK_SECRET found. Generating a signing secret for this session.'
+ );
+ yield* ui.note(
+ `Forward URL: ${forwardUrl}\nGenerated signing secret: ${webhookSecret}`,
+ 'Forwarding'
+ );
+ }
+ }
+ yield* ui.log.info('Listening for realtime trigger events. Press Ctrl+C to stop.');
+ if (outputFilePath) {
+ yield* ui.log.info(`Writing matching events to: ${outputFilePath}`);
+ }
+ if (forwardUrl) {
+ yield* ui.log.info(`Forwarding matching events to: ${forwardUrl}`);
+ }
+
+ if (maxEventsLimit !== undefined) {
+ yield* ui.log.info(`Auto-stop after ${maxEventsLimit} matching events.`);
+ }
+
+ const onEvent = (eventData: Record<string, unknown>) => {
+ Runtime.runFork(runtime)(
+ Effect.gen(function* () {
+ const parsed = parseTriggerListenEvent(eventData);
+ if (!matchesTriggerListenFilters(filters, parsed)) {
+ return;
+ }
+
+ matchingEvents += 1;
+ yield* ui.note(formatTriggerListenSummary(parsed), `Event #${matchingEvents}`);
+
+ if (json) {
+ yield* ui.log.message(JSON.stringify(eventData, null, 2));
+ } else {
+ yield* ui.log.message(JSON.stringify(parsed.payload, null, 2));
+ }
+ yield* ui.output(JSON.stringify(eventData));
+
+ const payloadForForwarding = JSON.stringify(eventData);
+ const logLine = `${payloadForForwarding}\n`;
+
+ if (outputFilePath) {
+ yield* Effect.tryPromise({
+ try: () => fs.appendFile(outputFilePath, logLine, 'utf8'),
+ catch: error => new Error(`Failed writing to ${outputFilePath}: ${String(error)}`),
+ }).pipe(Effect.catchAll(error => ui.log.warn(String(error))));
+ }
+
+ if (forwardUrl && webhookSecret) {
+ const webhookId =
+ typeof eventData.id === 'string' && eventData.id.length > 0
+ ? eventData.id
+ : randomUUID();
+ const webhookTimestamp = `${Math.floor(Date.now() / 1000)}`;
+ const webhookSignature = yield* Effect.tryPromise(() =>
+ signWebhookPayload({
+ secret: webhookSecret,
+ webhookId,
+ webhookTimestamp,
+ payload: payloadForForwarding,
+ })
+ );
+ const webhookVersion = detectWebhookPayloadVersion(eventData);
+
+ yield* Effect.tryPromise({
+ try: async () => {
+ const response = await fetch(forwardUrl, {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ 'webhook-id': webhookId,
+ 'webhook-timestamp': webhookTimestamp,
+ 'webhook-signature': webhookSignature,
+ 'x-composio-webhook-version': webhookVersion,
+ },
+ body: payloadForForwarding,
+ });
+ if (!response.ok) {
+ throw new Error(`Forwarding failed with HTTP ${response.status}`);
+ }
+ },
+ catch: error =>
+ new Error(`Failed forwarding event to ${forwardUrl}: ${String(error)}`),
+ }).pipe(Effect.catchAll(error => ui.log.warn(String(error))));
+ }
+
+ if (maxEventsLimit !== undefined && matchingEvents >= maxEventsLimit) {
+ yield* Deferred.succeed(stopWhenDone, undefined).pipe(Effect.ignore);
+ }
+ })
+ );
+ };
+
+ const listenEffect = realtime
+ .listen(onEvent)
+ .pipe(
+ Effect.onInterrupt(() => ui.log.info('Stopped listening for realtime trigger events.'))
+ );
+
+ if (maxEventsLimit === undefined) {
+ yield* listenEffect;
+ return;
+ }
+
+ yield* Effect.raceFirst(listenEffect, Deferred.await(stopWhenDone));
+ yield* ui.outro(`Stopped after receiving ${matchingEvents} matching events.`);
+ })
+).pipe(Command.withDescription('Listen to realtime trigger events for your project.'));
diff --git a/ts/packages/cli/src/commands/triggers/filter.ts b/ts/packages/cli/src/commands/triggers/filter.ts
new file mode 100644
index 000000000..6e11540bf
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/filter.ts
@@ -0,0 +1,37 @@
+import type { TriggerListenEvent, TriggerListenFilters } from './types';
+
+export const matchesTriggerListenFilters = (
+ filters: TriggerListenFilters,
+ data: TriggerListenEvent
+): boolean => {
+ if (
+ filters.toolkits?.length &&
+ !filters.toolkits.map(x => x.toLowerCase()).includes(data.toolkitSlug.toLowerCase())
+ ) {
+ return false;
+ }
+
+ if (filters.triggerId && filters.triggerId !== data.id) {
+ return false;
+ }
+
+ if (
+ filters.connectedAccountId &&
+ filters.connectedAccountId !== data.metadata.connectedAccount.id
+ ) {
+ return false;
+ }
+
+ if (
+ filters.triggerSlug?.length &&
+ !filters.triggerSlug.map(x => x.toLowerCase()).includes(data.triggerSlug.toLowerCase())
+ ) {
+ return false;
+ }
+
+ if (filters.userId && filters.userId !== data.metadata.connectedAccount.userId) {
+ return false;
+ }
+
+ return true;
+};
diff --git a/ts/packages/cli/src/commands/triggers/format.ts b/ts/packages/cli/src/commands/triggers/format.ts
new file mode 100644
index 000000000..b6eecaa75
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/format.ts
@@ -0,0 +1,13 @@
+import type { TriggerListenEvent } from './types';
+
+export const formatTriggerListenSummary = (event: TriggerListenEvent): string => {
+ const userId = event.userId || '-';
+ const connectedAccountId = event.metadata.connectedAccount.id || '-';
+ return [
+ `Trigger: ${event.triggerSlug}`,
+ `Toolkit: ${event.toolkitSlug}`,
+ `Trigger Id: ${event.id}`,
+ `Connected Account: ${connectedAccountId}`,
+ `User Id: ${userId}`,
+ ].join('\n');
+};
diff --git a/ts/packages/cli/src/commands/triggers/parse.ts b/ts/packages/cli/src/commands/triggers/parse.ts
new file mode 100644
index 000000000..229085c7f
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/parse.ts
@@ -0,0 +1,204 @@
+import type { TriggerListenEvent } from './types';
+
+const toStringOrDefault = (value: unknown, defaultValue: string): string => {
+ if (value === null || value === undefined) {
+ return defaultValue;
+ }
+ const str = String(value);
+ return str.length > 0 ? str : defaultValue;
+};
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+ typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+
+export const parseTriggerListenEvent = (data: Record<string, unknown>): TriggerListenEvent => {
+ // V3 payload (trigger event)
+ if (
+ data.type === 'composio.trigger.message' &&
+ typeof data.id === 'string' &&
+ typeof data.metadata === 'object' &&
+ data.metadata !== null
+ ) {
+ const metadata = asRecord(data.metadata);
+ if (typeof metadata.trigger_slug === 'string') {
+ const triggerSlug = metadata.trigger_slug;
+ const toolkitSlug = triggerSlug.split('_')[0]?.toUpperCase() || 'UNKNOWN';
+
+ return {
+ id: toStringOrDefault(metadata.trigger_id, data.id),
+ uuid: toStringOrDefault(metadata.trigger_id, data.id),
+ triggerSlug,
+ toolkitSlug,
+ userId: toStringOrDefault(metadata.user_id, ''),
+ payload: asRecord(data.data),
+ originalPayload: asRecord(data),
+ metadata: {
+ id: toStringOrDefault(metadata.trigger_id, data.id),
+ uuid: toStringOrDefault(metadata.trigger_id, data.id),
+ toolkitSlug,
+ triggerSlug,
+ triggerConfig: {},
+ connectedAccount: {
+ id: toStringOrDefault(metadata.connected_account_id, ''),
+ uuid: toStringOrDefault(metadata.connected_account_id, ''),
+ authConfigId: toStringOrDefault(metadata.auth_config_id, ''),
+ authConfigUUID: toStringOrDefault(metadata.auth_config_id, ''),
+ userId: toStringOrDefault(metadata.user_id, ''),
+ status: 'ACTIVE',
+ },
+ },
+ };
+ }
+ }
+
+ // V2 payload
+ if (
+ typeof data.type === 'string' &&
+ typeof data.data === 'object' &&
+ data.data !== null &&
+ typeof asRecord(data.data).trigger_nano_id === 'string'
+ ) {
+ const v2 = asRecord(data.data);
+ const triggerSlug = data.type.toUpperCase();
+ const toolkitSlug = triggerSlug.split('_')[0] || 'UNKNOWN';
+ const payload = { ...v2 };
+ delete payload.connection_id;
+ delete payload.connection_nano_id;
+ delete payload.trigger_nano_id;
+ delete payload.trigger_id;
+ delete payload.user_id;
+
+ return {
+ id: toStringOrDefault(v2.trigger_nano_id, ''),
+ uuid: toStringOrDefault(v2.trigger_id, toStringOrDefault(v2.trigger_nano_id, '')),
+ triggerSlug,
+ toolkitSlug,
+ userId: toStringOrDefault(v2.user_id, ''),
+ payload,
+ originalPayload: asRecord(data),
+ metadata: {
+ id: toStringOrDefault(v2.trigger_nano_id, ''),
+ uuid: toStringOrDefault(v2.trigger_id, toStringOrDefault(v2.trigger_nano_id, '')),
+ toolkitSlug,
+ triggerSlug,
+ triggerConfig: {},
+ connectedAccount: {
+ id: toStringOrDefault(v2.connection_nano_id, ''),
+ uuid: toStringOrDefault(v2.connection_id, ''),
+ authConfigId: '',
+ authConfigUUID: '',
+ userId: toStringOrDefault(v2.user_id, ''),
+ status: 'ACTIVE',
+ },
+ },
+ };
+ }
+
+ // V1 payload
+ if (
+ typeof data.trigger_name === 'string' &&
+ typeof data.connection_id === 'string' &&
+ typeof data.trigger_id === 'string'
+ ) {
+ const triggerSlug = data.trigger_name;
+ const toolkitSlug = triggerSlug.split('_')[0]?.toUpperCase() || 'UNKNOWN';
+ return {
+ id: data.trigger_id,
+ uuid: data.trigger_id,
+ triggerSlug,
+ toolkitSlug,
+ userId: '',
+ payload: asRecord(data.payload),
+ originalPayload: asRecord(data),
+ metadata: {
+ id: data.trigger_id,
+ uuid: data.trigger_id,
+ toolkitSlug,
+ triggerSlug,
+ triggerConfig: {},
+ connectedAccount: {
+ id: data.connection_id,
+ uuid: data.connection_id,
+ authConfigId: '',
+ authConfigUUID: '',
+ userId: '',
+ status: 'ACTIVE',
+ },
+ },
+ };
+ }
+
+ // Legacy payload
+ if (
+ typeof data.appName === 'string' &&
+ typeof data.metadata === 'object' &&
+ data.metadata !== null &&
+ typeof asRecord(data.metadata).nanoId === 'string'
+ ) {
+ const metadata = asRecord(data.metadata);
+ const connection = asRecord(metadata.connection);
+ return {
+ id: toStringOrDefault(metadata.nanoId, toStringOrDefault(metadata.id, 'unknown')),
+ uuid: toStringOrDefault(metadata.id, toStringOrDefault(metadata.nanoId, 'unknown')),
+ triggerSlug: toStringOrDefault(metadata.triggerName, 'UNKNOWN'),
+ toolkitSlug: toStringOrDefault(data.appName, 'UNKNOWN'),
+ userId: toStringOrDefault(connection.clientUniqueUserId, ''),
+ payload: asRecord(data.payload),
+ originalPayload: asRecord(data.originalPayload ?? data.payload),
+ metadata: {
+ id: toStringOrDefault(metadata.nanoId, toStringOrDefault(metadata.id, 'unknown')),
+ uuid: toStringOrDefault(metadata.id, toStringOrDefault(metadata.nanoId, 'unknown')),
+ toolkitSlug: toStringOrDefault(data.appName, 'UNKNOWN'),
+ triggerSlug: toStringOrDefault(metadata.triggerName, 'UNKNOWN'),
+ triggerData: toStringOrDefault(metadata.triggerData, ''),
+ triggerConfig: asRecord(metadata.triggerConfig),
+ connectedAccount: {
+ id: toStringOrDefault(connection.connectedAccountNanoId, ''),
+ uuid: toStringOrDefault(connection.id, ''),
+ authConfigId: toStringOrDefault(connection.authConfigNanoId, ''),
+ authConfigUUID: toStringOrDefault(connection.integrationId, ''),
+ userId: toStringOrDefault(connection.clientUniqueUserId, ''),
+ status: toStringOrDefault(connection.status, 'ACTIVE'),
+ },
+ },
+ };
+ }
+
+ // Fallback
+ const id = toStringOrDefault(data.id, toStringOrDefault(data.trigger_id, 'unknown'));
+ const uuid = toStringOrDefault(data.uuid, id);
+ const triggerSlug = toStringOrDefault(
+ data.triggerSlug,
+ toStringOrDefault(data.trigger_name, 'UNKNOWN')
+ );
+ const toolkitSlug = toStringOrDefault(
+ data.toolkitSlug,
+ toStringOrDefault(data.appName, 'UNKNOWN')
+ );
+ const userId = toStringOrDefault(data.userId, '');
+
+ return {
+ id,
+ uuid,
+ triggerSlug,
+ toolkitSlug,
+ userId,
+ payload: asRecord(data.payload ?? data),
+ originalPayload: asRecord(data.originalPayload ?? data),
+ metadata: {
+ id,
+ uuid,
+ toolkitSlug,
+ triggerSlug,
+ triggerConfig: {},
+ connectedAccount: {
+ id: '',
+ uuid: '',
+ authConfigId: '',
+ authConfigUUID: '',
+ userId: '',
+ status: 'ACTIVE',
+ },
+ },
+ };
+};
diff --git a/ts/packages/cli/src/commands/triggers/triggers.cmd.ts b/ts/packages/cli/src/commands/triggers/triggers.cmd.ts
new file mode 100644
index 000000000..ac9b76938
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/triggers.cmd.ts
@@ -0,0 +1,15 @@
+import { Command } from '@effect/cli';
+import { triggersCmd$Listen } from './commands/triggers.listen.cmd';
+
+/**
+ * CLI entry point for realtime trigger commands.
+ *
+ * @example
+ * ```bash
+ * composio triggers <command>
+ * ```
+ */
+export const triggersCmd = Command.make('triggers').pipe(
+ Command.withDescription('Subscribe to realtime trigger events.'),
+ Command.withSubcommands([triggersCmd$Listen])
+);
diff --git a/ts/packages/cli/src/commands/triggers/types.ts b/ts/packages/cli/src/commands/triggers/types.ts
new file mode 100644
index 000000000..5f563de45
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/types.ts
@@ -0,0 +1,33 @@
+export type TriggerListenEvent = {
+ id: string;
+ uuid: string;
+ triggerSlug: string;
+ toolkitSlug: string;
+ userId: string;
+ payload: Record<string, unknown>;
+ originalPayload: Record<string, unknown>;
+ metadata: {
+ id: string;
+ uuid: string;
+ toolkitSlug: string;
+ triggerSlug: string;
+ triggerData?: string;
+ triggerConfig: Record<string, unknown>;
+ connectedAccount: {
+ id: string;
+ uuid: string;
+ authConfigId: string;
+ authConfigUUID: string;
+ userId: string;
+ status: string;
+ };
+ };
+};
+
+export type TriggerListenFilters = {
+ toolkits?: ReadonlyArray<string>;
+ triggerId?: string;
+ connectedAccountId?: string;
+ triggerSlug?: ReadonlyArray<string>;
+ userId?: string;
+};
diff --git a/ts/packages/cli/src/services/composio-clients.ts b/ts/packages/cli/src/services/composio-clients.ts
index a7fc35495..11eb988d2 100644
--- a/ts/packages/cli/src/services/composio-clients.ts
+++ b/ts/packages/cli/src/services/composio-clients.ts
@@ -221,6 +221,21 @@ export type CliCreateSessionResponse = Schema.Schema.Type<typeof CliCreateSessio
export const CliGetSessionResponse = RetrievedSession;
export type CliRetrieveSessionResponse = Schema.Schema.Type<typeof CliGetSessionResponse>;
+export const CliRealtimeCredentialsResponse = Schema.Struct({
+ project_id: Schema.String,
+ pusher_key: Schema.String,
+ pusher_cluster: Schema.String,
+}).annotations({ identifier: 'CliRealtimeCredentialsResponse' });
+export type CliRealtimeCredentialsResponse = Schema.Schema.Type<
+ typeof CliRealtimeCredentialsResponse
+>;
+
+export const CliRealtimeAuthResponse = Schema.Struct({
+ auth: Schema.String,
+ channel_data: Schema.optional(Schema.String),
+}).annotations({ identifier: 'CliRealtimeAuthResponse' });
+export type CliRealtimeAuthResponse = Schema.Schema.Type<typeof CliRealtimeAuthResponse>;
+
export const ToolkitsResponse = Schema.Struct({
items: Toolkits,
total_pages: Schema.Int,
@@ -1110,6 +1125,22 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
CliGetSessionResponse
)
),
+ getRealtimeCredentials: () =>
+ withMetrics(
+ callClient(
+ clientSingleton,
+ client => client.cli.realtime.credentials(),
+ CliRealtimeCredentialsResponse
+ )
+ ),
+ authRealtimeChannel: (params: { channel_name: string; socket_id: string }) =>
+ withMetrics(
+ callClient(
+ clientSingleton,
+ client => client.cli.realtime.auth(params),
+ CliRealtimeAuthResponse
+ )
+ ),
},
authConfigs: buildAuthConfigsNamespace(clientSingleton, withMetrics),
connectedAccounts: buildConnectedAccountsNamespace(clientSingleton, withMetrics),
@@ -1375,6 +1406,9 @@ export class ComposioSessionRepository extends Effect.Service<ComposioSessionRep
return {
createSession: () => client.cli.createSession(),
getSession: (session: { id: string }) => client.cli.getSession({ id: session.id }),
+ getRealtimeCredentials: () => client.cli.getRealtimeCredentials(),
+ authRealtimeChannel: (params: { channel_name: string; socket_id: string }) =>
+ client.cli.authRealtimeChannel(params),
};
}),
dependencies: [ComposioClientLive.Default],
diff --git a/ts/packages/cli/src/services/triggers-realtime.ts b/ts/packages/cli/src/services/triggers-realtime.ts
new file mode 100644
index 000000000..60bf6b905
--- /dev/null
+++ b/ts/packages/cli/src/services/triggers-realtime.ts
@@ -0,0 +1,183 @@
+import { Data, Effect } from 'effect';
+import { ComposioSessionRepository } from 'src/services/composio-clients';
+
+type RawRealtimeEvent = Record<string, unknown>;
+
+type PusherAuthOptions = {
+ params?: {
+ channel_name?: string;
+ socket_id?: string;
+ channelName?: string;
+ socketId?: string;
+ };
+ channel_name?: string;
+ socket_id?: string;
+ channelName?: string;
+ socketId?: string;
+};
+
+type PusherAuthCallback = (error: unknown, data?: unknown) => void;
+
+type PusherChannel = {
+ bind: (event: string, callback: (data: unknown) => void) => void;
+ bind_global?: (callback: (eventName: string, data: unknown) => void) => void;
+ unbind?: (event?: string, callback?: (data: unknown) => void) => void;
+};
+
+type PusherClient = {
+ subscribe: (channelName: string) => PusherChannel;
+ unsubscribe: (channelName: string) => void;
+ disconnect: () => void;
+ connection?: {
+ bind?: (event: string, callback: (data: unknown) => void) => void;
+ };
+};
+
+type PusherCtor = new (
+ key: string,
+ options: {
+ cluster: string;
+ channelAuthorization: {
+ customHandler: (
+ authOptions: PusherAuthOptions,
+ callback?: PusherAuthCallback
+ ) => Promise<unknown> | void;
+ };
+ }
+) => PusherClient;
+
+type ChunkedRealtimeEvent = {
+ id: string;
+ index: number;
+ chunk: string;
+ final: boolean;
+};
+
+export class TriggerRealtimeSubscriptionError extends Data.TaggedError(
+ 'services/TriggerRealtimeSubscriptionError'
+)<{
+ readonly cause?: unknown;
+}> {}
+
+/**
+ * Service for listening to trigger events over Composio CLI realtime channels.
+ * Uses:
+ * - `cli.realtime.credentials` to fetch Pusher credentials + project nano id
+ * - `cli.realtime.auth` for private channel auth callbacks
+ */
+export class TriggersRealtime extends Effect.Service<TriggersRealtime>()(
+ 'services/TriggersRealtime',
+ {
+ effect: Effect.gen(function* () {
+ const sessionRepo = yield* ComposioSessionRepository;
+
+ const listen = (onEvent: (data: RawRealtimeEvent) => void) =>
+ Effect.acquireUseRelease(
+ Effect.gen(function* () {
+ const creds = yield* sessionRepo.getRealtimeCredentials();
+ const channelName = `private-cli-${creds.project_id}`;
+
+ const pusherModule = yield* Effect.tryPromise({
+ try: () => import('pusher-js'),
+ catch: cause => new TriggerRealtimeSubscriptionError({ cause }),
+ });
+
+ const Pusher = pusherModule.default as unknown as PusherCtor;
+
+ const pusher = new Pusher(creds.pusher_key, {
+ cluster: creds.pusher_cluster,
+ channelAuthorization: {
+ customHandler: (authOptions: PusherAuthOptions, callback?: PusherAuthCallback) => {
+ const params = authOptions.params ?? authOptions;
+ const channel_name = params.channel_name ?? params.channelName;
+ const socket_id = params.socket_id ?? params.socketId;
+
+ const doAuth = async () => {
+ if (!channel_name || !socket_id) {
+ throw new Error('Missing channel_name or socket_id for realtime auth');
+ }
+
+ const response = await Effect.runPromise(
+ sessionRepo.authRealtimeChannel({
+ channel_name,
+ socket_id,
+ })
+ );
+ // Pusher private channels verify signatures without channel_data.
+ // Some auth endpoints may still return channel_data, which can cause
+ // "Invalid signature" if included in the verification input.
+ const normalizedResponse = channel_name.startsWith('private-')
+ ? { auth: response.auth }
+ : response;
+ return normalizedResponse;
+ };
+
+ if (callback) {
+ void doAuth()
+ .then(data => callback(null, data))
+ .catch(error => callback(error));
+ return;
+ }
+
+ return doAuth();
+ },
+ },
+ });
+
+ const channel = pusher.subscribe(channelName);
+ const chunkedEvents = new Map<string, { chunks: string[]; receivedFinal: boolean }>();
+
+ channel.bind('trigger_to_client', eventData => {
+ onEvent((eventData ?? {}) as RawRealtimeEvent);
+ });
+
+ channel.bind('chunked-trigger_to_client', data => {
+ const typed = data as ChunkedRealtimeEvent;
+ if (!typed || typeof typed.id !== 'string' || typeof typed.index !== 'number') {
+ return;
+ }
+
+ if (!chunkedEvents.has(typed.id)) {
+ chunkedEvents.set(typed.id, { chunks: [], receivedFinal: false });
+ }
+
+ const current = chunkedEvents.get(typed.id)!;
+ current.chunks[typed.index] = typed.chunk;
+ if (typed.final) {
+ current.receivedFinal = true;
+ }
+
+ if (
+ current.receivedFinal &&
+ current.chunks.length === Object.keys(current.chunks).length
+ ) {
+ try {
+ const parsed = JSON.parse(current.chunks.join('')) as RawRealtimeEvent;
+ onEvent(parsed);
+ } finally {
+ chunkedEvents.delete(typed.id);
+ }
+ }
+ });
+
+ return {
+ shutdown: async () => {
+ channel.unbind?.();
+ pusher.unsubscribe(channelName);
+ pusher.disconnect();
+ },
+ };
+ }),
+ () => Effect.never,
+ resource =>
+ Effect.tryPromise({
+ try: () => resource.shutdown(),
+ catch: cause => new TriggerRealtimeSubscriptionError({ cause }),
+ }).pipe(Effect.catchAll(() => Effect.void))
+ );
+
+ return { listen };
+ }),
+ dependencies: [ComposioSessionRepository.Default],
+ }
+) {}
diff --git a/ts/packages/cli/test/__utils__/services/test-layer.ts b/ts/packages/cli/test/__utils__/services/test-layer.ts
index 25e3fbfb6..a8d61b5b7 100644
--- a/ts/packages/cli/test/__utils__/services/test-layer.ts
+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts
@@ -40,6 +40,7 @@ import type { ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
import { ComposioUserContextLive } from 'src/services/user-context';
import { UpgradeBinary } from 'src/services/upgrade-binary';
import { NodeOs } from 'src/services/node-os';
+import { TriggersRealtime } from 'src/services/triggers-realtime';
export interface TestLiveInput {
/**
@@ -80,6 +81,13 @@ export interface TestLiveInput {
items?: ConnectedAccountItem[];
linkResponse?: LinkCreateResponse;
};
+
+ /**
+ * Mock realtime trigger data to use in test.
+ */
+ realtimeData?: {
+ events?: ReadonlyArray<Record<string, unknown>>;
+ };
}
/**
@@ -133,6 +141,14 @@ export const TestLayer = (input?: TestLiveInput) =>
...(input?.connectedAccountsData ?? {}),
};
+ const defaultRealtimeData = {
+ events: [] as ReadonlyArray<Record<string, unknown>>,
+ } satisfies TestLiveInput['realtimeData'];
+ const realtimeData = {
+ ...defaultRealtimeData,
+ ...(input?.realtimeData ?? {}),
+ };
+
const tempDir = tempy.temporaryDirectory({ prefix: 'test' });
const cwd = (yield* setupFixtureFolder({ fixture, tempDir })) ?? tempDir;
@@ -501,6 +517,16 @@ export const TestLayer = (input?: TestLiveInput) =>
})
);
const ComposioSessionRepositoryTest = yield* setupComposioSessionRepository();
+ const TriggersRealtimeTest = Layer.succeed(
+ TriggersRealtime,
+ new TriggersRealtime({
+ listen: onEvent =>
+ Effect.gen(function* () {
+ yield* Effect.forEach(realtimeData.events, event => Effect.sync(() => onEvent(event)));
+ return yield* Effect.never;
+ }),
+ })
+ );
// Mock `node:os`
const NodeOsTest = Layer.succeed(
@@ -543,6 +569,7 @@ export const TestLayer = (input?: TestLiveInput) =>
UpgradeBinaryTest,
ComposioUserContextTest,
ComposioSessionRepositoryTest,
+ TriggersRealtimeTest,
ComposioToolkitsRepositoryTest,
EnvLangDetector.Default,
JsPackageManagerDetector.Default,
@@ -747,6 +774,17 @@ function setupComposioSessionRepository() {
status: 'pending',
api_key: null,
}),
+ getRealtimeCredentials: () =>
+ Effect.succeed({
+ project_id: 'proj_test',
+ pusher_key: 'pusher_test_key',
+ pusher_cluster: 'mt1',
+ }),
+ authRealtimeChannel: () =>
+ Effect.succeed({
+ auth: 'mock:auth',
+ channel_data: undefined,
+ }),
});
const ComposioSessionRepositoryTest = Layer.succeed(
ComposioSessionRepository,
diff --git a/ts/packages/cli/test/src/commands/$default.cmd.test.ts b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
index 3bbfe44fa..2869fbb55 100644
--- a/ts/packages/cli/test/src/commands/$default.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
@@ -15,7 +15,7 @@ describe('CLI: composio', () => {
expect(result).toEqual(
ValidationError.commandMismatch(
HelpDoc.p(
- "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits', 'tools', 'auth-configs', 'connected-accounts'"
+ "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits', 'tools', 'auth-configs', 'connected-accounts', 'triggers'"
)
)
);
@@ -56,71 +56,75 @@ describe('CLI: composio', () => {
COMMANDS
- - version Display the current Composio CLI version.
+ - version Display the current Composio CLI version.
- - upgrade Upgrade your Composio CLI to the latest available version.
+ - upgrade Upgrade your Composio CLI to the latest available version.
- - whoami Display your account information.
+ - whoami Display your account information.
- - login [--no-browser] Log in to the Composio SDK.
+ - login [--no-browser] Log in to the Composio SDK.
- - logout Log out from the Composio SDK.
+ - logout Log out from the Composio SDK.
- - generate [(-o, --output-dir directory)] [--type-tools] --toolkits text... Generate type stubs for toolkits, tools, and triggers, auto-detecting project language (TypeScript | Python)
+ - generate [(-o, --output-dir directory)] [--type-tools] --toolkits text... Generate type stubs for toolkits, tools, and triggers, auto-detecting project language (TypeScript | Python)
- - py Handle Python projects.
+ - py Handle Python projects.
- - py generate [(-o, --output-dir directory)] --toolkits text... Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
+ - py generate [(-o, --output-dir directory)] --toolkits text... Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
Environment Variables:
COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
Use "latest" or unset to use the latest version.
- - ts Handle TypeScript projects.
+ - ts Handle TypeScript projects.
- - ts generate [(-o, --output-dir directory)] [--compact] [--transpiled] [--type-tools] --toolkits text... Generate TypeScript types for toolkits, tools, and triggers from the Composio API.
+ - ts generate [(-o, --output-dir directory)] [--compact] [--transpiled] [--type-tools] --toolkits text... Generate TypeScript types for toolkits, tools, and triggers from the Composio API.
Environment Variables:
COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
Use "latest" or unset to use the latest version.
- - toolkits Discover and inspect Composio toolkits.
+ - toolkits Discover and inspect Composio toolkits.
- - toolkits list [--query text] [--limit integer] List available toolkits.
+ - toolkits list [--query text] [--limit integer] List available toolkits.
- - toolkits info [<slug>] View details of a specific toolkit.
+ - toolkits info [<slug>] View details of a specific toolkit.
- - toolkits search [--limit integer] <query> Search toolkits by use case.
+ - toolkits search [--limit integer] <query> Search toolkits by use case.
- - tools Discover and inspect Composio tools.
+ - tools Discover and inspect Composio tools.
- - tools list [--query text] [--toolkits text] [--tags text] [--limit integer] List available tools.
+ - tools list [--query text] [--toolkits text] [--tags text] [--limit integer] List available tools.
- - tools info [<slug>] View details of a specific tool.
+ - tools info [<slug>] View details of a specific tool.
- - tools search [--toolkits text] [--limit integer] <query> Search tools by use case.
+ - tools search [--toolkits text] [--limit integer] <query> Search tools by use case.
- - auth-configs View and manage Composio auth configs.
+ - auth-configs View and manage Composio auth configs.
- - auth-configs list [--toolkits text] [--query text] [--limit integer] List auth configs.
+ - auth-configs list [--toolkits text] [--query text] [--limit integer] List auth configs.
- - auth-configs info [<id>] View details of a specific auth config.
+ - auth-configs info [<id>] View details of a specific auth config.
- - auth-configs create --toolkit text [--auth-scheme text] [--scopes text] [--custom-credentials text] [<name>] Create a new auth config.
+ - auth-configs create --toolkit text [--auth-scheme text] [--scopes text] [--custom-credentials text] [<name>] Create a new auth config.
- - auth-configs delete [(-y, --yes)] [<id>] Delete an auth config.
+ - auth-configs delete [(-y, --yes)] [<id>] Delete an auth config.
- - connected-accounts View and manage Composio connected accounts.
+ - connected-accounts View and manage Composio connected accounts.
- - connected-accounts list [--toolkits text] [--user-id text] [--status INITIALIZING | INITIATED | ACTIVE | FAILED | EXPIRED | INACTIVE] [--limit integer] List connected accounts.
+ - connected-accounts list [--toolkits text] [--user-id text] [--status INITIALIZING | INITIATED | ACTIVE | FAILED | EXPIRED | INACTIVE] [--limit integer] List connected accounts.
- - connected-accounts info [<id>] View details of a specific connected account.
+ - connected-accounts info [<id>] View details of a specific connected account.
- - connected-accounts whoami [<id>] Show the external account profile for a connected account.
+ - connected-accounts whoami [<id>] Show the external account profile for a connected account.
- - connected-accounts delete [(-y, --yes)] [<id>] Delete a connected account.
+ - connected-accounts delete [(-y, --yes)] [<id>] Delete a connected account.
- - connected-accounts link --auth-config text [--user-id text] [--no-browser] Link an external account via OAuth redirect.
+ - connected-accounts link --auth-config text [--user-id text] [--no-browser] Link an external account via OAuth redirect.
+
+ - triggers Subscribe to realtime trigger events.
+
+ - triggers listen [--toolkits text] [--trigger-id text] [--connected-account-id text] [--trigger-slug text] [--user-id text] [--json] [--max-events integer] [--forward text] [--out text] Listen to realtime trigger events for your project.
"
`);
})
diff --git a/ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts b/ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts
new file mode 100644
index 000000000..10b774762
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts
@@ -0,0 +1,242 @@
+import { describe, expect, layer } from '@effect/vitest';
+import { ConfigProvider, Effect } from 'effect';
+import { extendConfigProvider } from 'src/services/config';
+import { cli, MockConsole, TestLive } from 'test/__utils__';
+import { createServer, type IncomingMessage } from 'node:http';
+import { Composio } from '@composio/core';
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+const mockV3TriggerEvent = {
+ id: 'msg-123',
+ timestamp: '2026-02-23T12:00:00Z',
+ type: 'composio.trigger.message',
+ metadata: {
+ log_id: 'log-123',
+ trigger_slug: 'GMAIL_NEW_GMAIL_MESSAGE',
+ trigger_id: 'trg_123',
+ connected_account_id: 'con_123',
+ auth_config_id: 'ac_123',
+ user_id: 'user_123',
+ },
+ data: {
+ subject: 'Hello',
+ },
+} as const;
+
+type CapturedWebhookRequest = {
+ body: string;
+ headers: {
+ webhookId: string;
+ webhookTimestamp: string;
+ webhookSignature: string;
+ webhookVersion: string;
+ };
+};
+
+const startWebhookServer = async (): Promise<{
+ url: string;
+ waitForRequest: Promise<CapturedWebhookRequest>;
+ close: () => Promise<void>;
+}> => {
+ let resolveRequest: ((value: CapturedWebhookRequest) => void) | undefined;
+ let rejectRequest: ((reason?: unknown) => void) | undefined;
+
+ const waitForRequest = new Promise<CapturedWebhookRequest>((resolve, reject) => {
+ resolveRequest = resolve;
+ rejectRequest = reject;
+ });
+
+ const readBody = (req: IncomingMessage): Promise<string> =>
+ new Promise((resolve, reject) => {
+ const chunks: Buffer[] = [];
+ req.on('data', chunk => {
+ chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+ });
+ req.on('end', () => {
+ resolve(Buffer.concat(chunks).toString('utf8'));
+ });
+ req.on('error', reject);
+ });
+
+ const server = createServer(async (req, res) => {
+ try {
+ const body = await readBody(req);
+ resolveRequest?.({
+ body,
+ headers: {
+ webhookId: (req.headers['webhook-id'] as string | undefined) ?? '',
+ webhookTimestamp: (req.headers['webhook-timestamp'] as string | undefined) ?? '',
+ webhookSignature: (req.headers['webhook-signature'] as string | undefined) ?? '',
+ webhookVersion: (req.headers['x-composio-webhook-version'] as string | undefined) ?? '',
+ },
+ });
+ res.statusCode = 200;
+ res.end('ok');
+ } catch (error) {
+ rejectRequest?.(error);
+ res.statusCode = 500;
+ res.end('error');
+ }
+ });
+
+ await new Promise<void>((resolve, reject) => {
+ server.listen(0, '127.0.0.1', () => resolve());
+ server.on('error', reject);
+ });
+
+ const address = server.address();
+ if (!address || typeof address === 'string') {
+ throw new Error('Failed to bind webhook test server');
+ }
+
+ return {
+ url: `http://127.0.0.1:${address.port}/webhook`,
+ waitForRequest,
+ close: () =>
+ new Promise((resolve, reject) => {
+ server.close(error => {
+ if (error) reject(error);
+ else resolve();
+ });
+ }),
+ };
+};
+
+describe('CLI: composio triggers listen', () => {
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ realtimeData: {
+ events: [mockV3TriggerEvent],
+ },
+ })
+ )('[Given] one realtime event [Then] prints normalized event output', it => {
+ it.scoped('prints event summary and payload', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'listen', '--max-events', '1']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Listening for realtime trigger events');
+ expect(output).not.toContain('Writing matching events to:');
+ expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
+ expect(output).toContain('"subject":"Hello"');
+ expect(output).toContain('Stopped after receiving 1 matching events');
+ })
+ );
+ });
+
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'listen']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ realtimeData: { events: [mockV3TriggerEvent] },
+ })
+ )(
+ '[Given] --forward without COMPOSIO_WEBHOOK_SECRET [Then] generates session signing secret',
+ it => {
+ it.scoped('shows generated signing secret for forward mode', () =>
+ Effect.gen(function* () {
+ delete process.env.COMPOSIO_WEBHOOK_SECRET;
+ yield* cli([
+ 'triggers',
+ 'listen',
+ '--forward',
+ 'http://localhost:8080/webhook',
+ '--max-events',
+ '1',
+ ]);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+ expect(output).toContain('No COMPOSIO_WEBHOOK_SECRET found');
+ expect(output).toContain('Forward URL: http://localhost:8080/webhook');
+ expect(output).toContain('Generated signing secret: composio-forward-secret-');
+ })
+ );
+ }
+ );
+
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ realtimeData: { events: [mockV3TriggerEvent] },
+ })
+ )('[Given] --forward [Then] sends signed webhook verifiable by composio/core', it => {
+ it.scoped('forwards request with headers and valid signature', () => {
+ const previousSecret = process.env.COMPOSIO_WEBHOOK_SECRET;
+ const restoreWebhookSecret = () => {
+ if (previousSecret === undefined) {
+ delete process.env.COMPOSIO_WEBHOOK_SECRET;
+ return;
+ }
+ process.env.COMPOSIO_WEBHOOK_SECRET = previousSecret;
+ };
+
+ return Effect.gen(function* () {
+ process.env.COMPOSIO_WEBHOOK_SECRET = 'test-webhook-secret';
+
+ const server = yield* Effect.acquireRelease(
+ Effect.tryPromise(() => startWebhookServer()),
+ resource =>
+ Effect.tryPromise(() => resource.close()).pipe(Effect.catchAll(() => Effect.void))
+ );
+
+ yield* cli(['triggers', 'listen', '--forward', server.url, '--max-events', '1']);
+
+ const request = yield* Effect.tryPromise({
+ try: () =>
+ Promise.race([
+ server.waitForRequest,
+ new Promise<never>((_, reject) =>
+ setTimeout(() => reject(new Error('Timed out waiting for forwarded webhook')), 3000)
+ ),
+ ]),
+ catch: error => new Error(String(error)),
+ });
+
+ expect(request.headers.webhookId).not.toEqual('');
+ expect(request.headers.webhookTimestamp).not.toEqual('');
+ expect(request.headers.webhookSignature).toContain('v1,');
+ expect(request.headers.webhookVersion).toEqual('V3');
+
+ const composio = new Composio({
+ apiKey: 'test-api-key',
+ disableVersionCheck: true,
+ allowTracking: false,
+ });
+
+ const verification = yield* Effect.tryPromise(() =>
+ composio.triggers.verifyWebhook({
+ payload: request.body,
+ id: request.headers.webhookId,
+ timestamp: request.headers.webhookTimestamp,
+ signature: request.headers.webhookSignature,
+ secret: 'test-webhook-secret',
+ })
+ );
+
+ expect(verification.rawPayload).toEqual(mockV3TriggerEvent);
+ }).pipe(
+ Effect.ensuring(
+ Effect.sync(() => {
+ restoreWebhookSecret();
+ })
+ )
+ );
+ });
+ });
+});