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 triggers list and info discovery commands

haxzie9e2799af969c
diff --git a/ts/packages/cli/src/commands/triggers/commands/triggers.info.cmd.ts b/ts/packages/cli/src/commands/triggers/commands/triggers.info.cmd.ts
new file mode 100644
index 000000000..ced642f35
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/commands/triggers.info.cmd.ts
@@ -0,0 +1,68 @@
+import { Args, Command } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { requireAuth } from 'src/effects/require-auth';
+import { ComposioToolkitsRepository } from 'src/services/composio-clients';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { formatTriggerTypeInfo } from '../format';
+
+const slug = Args.text({ name: 'slug' }).pipe(
+ Args.withDescription('Trigger slug (e.g. "GMAIL_NEW_GMAIL_MESSAGE")'),
+ Args.optional
+);
+
+/**
+ * View details of a specific trigger type including config and payload schemas.
+ *
+ * @example
+ * ```bash
+ * composio triggers info "GMAIL_NEW_GMAIL_MESSAGE"
+ * ```
+ */
+export const triggersCmd$Info = Command.make('info', { slug }, ({ slug }) =>
+ Effect.gen(function* () {
+ if (!(yield* requireAuth)) return;
+
+ const ui = yield* TerminalUI;
+ const repo = yield* ComposioToolkitsRepository;
+
+ if (Option.isNone(slug)) {
+ yield* ui.log.warn('Missing required argument: <slug>');
+ yield* ui.log.step(
+ 'Try specifying a trigger slug, e.g.:\n> composio triggers info "GMAIL_NEW_GMAIL_MESSAGE"'
+ );
+ return;
+ }
+
+ const slugValue = slug.value;
+ const triggerTypes = yield* ui.withSpinner('Fetching trigger types...', repo.getTriggerTypes());
+ const normalizedSlug = slugValue.toUpperCase();
+ const triggerType = triggerTypes.find(item => item.slug.toUpperCase() === normalizedSlug);
+
+ if (!triggerType) {
+ yield* ui.log.error(`Trigger "${slugValue}" not found.`);
+ const suggestions = triggerTypes
+ .filter(item => item.slug.toUpperCase().includes(normalizedSlug))
+ .slice(0, 3);
+ if (suggestions.length > 0) {
+ yield* ui.log.step('Did you mean:');
+ yield* Effect.forEach(suggestions, item =>
+ ui.log.step(`> composio triggers info "${item.slug}"`)
+ );
+ } else {
+ yield* ui.log.step('Browse available trigger types:\n> composio triggers list');
+ }
+ return;
+ }
+
+ yield* ui.note(formatTriggerTypeInfo(triggerType), `Trigger: ${triggerType.name}`);
+
+ const toolkitSlug = triggerType.slug.split('_')[0]?.toLowerCase();
+ if (toolkitSlug) {
+ yield* ui.log.step(
+ `To list more trigger types in this toolkit:\n> composio triggers list --toolkits "${toolkitSlug}"`
+ );
+ }
+
+ yield* ui.output(JSON.stringify(triggerType, null, 2));
+ })
+).pipe(Command.withDescription('View details of a specific trigger type.'));
diff --git a/ts/packages/cli/src/commands/triggers/commands/triggers.list.cmd.ts b/ts/packages/cli/src/commands/triggers/commands/triggers.list.cmd.ts
new file mode 100644
index 000000000..3ede1a6f4
--- /dev/null
+++ b/ts/packages/cli/src/commands/triggers/commands/triggers.list.cmd.ts
@@ -0,0 +1,65 @@
+import { Command, Options } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { requireAuth } from 'src/effects/require-auth';
+import { ComposioToolkitsRepository } from 'src/services/composio-clients';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { clampLimit } from 'src/ui/clamp-limit';
+import { formatTriggerTypesJson, formatTriggerTypesTable } from '../format';
+
+const toolkits = Options.text('toolkits').pipe(
+ Options.withDescription(
+ 'Filter by toolkit slugs, comma-separated (e.g. "gmail" or "gmail,slack")'
+ ),
+ Options.optional
+);
+
+const limit = Options.integer('limit').pipe(
+ Options.withDefault(30),
+ Options.withDescription('Maximum number of trigger types to show (1-1000)')
+);
+
+const parseCsv = (value: string): ReadonlyArray<string> =>
+ value
+ .split(',')
+ .map(item => item.trim())
+ .filter(Boolean);
+
+/**
+ * List available trigger types with optional toolkit filters.
+ *
+ * @example
+ * ```bash
+ * composio triggers list
+ * composio triggers list --toolkits "gmail"
+ * composio triggers list --toolkits "gmail,slack"
+ * ```
+ */
+export const triggersCmd$List = Command.make('list', { toolkits, limit }, ({ toolkits, limit }) =>
+ Effect.gen(function* () {
+ if (!(yield* requireAuth)) return;
+
+ const ui = yield* TerminalUI;
+ const repo = yield* ComposioToolkitsRepository;
+ const toolkitFilters = Option.isSome(toolkits) ? parseCsv(toolkits.value) : undefined;
+ const clampedLimit = clampLimit(limit);
+
+ const allTriggerTypes = yield* ui.withSpinner(
+ 'Fetching trigger types...',
+ repo.getTriggerTypes(toolkitFilters)
+ );
+ const triggerTypes = allTriggerTypes.slice(0, clampedLimit);
+
+ if (triggerTypes.length === 0) {
+ const hint = Option.isSome(toolkits)
+ ? `No trigger types found in toolkit "${toolkits.value}". Verify the toolkit slug with:\n> composio toolkits list`
+ : 'No trigger types found.';
+ yield* ui.log.warn(hint);
+ return;
+ }
+
+ yield* ui.log.info(
+ `Listing ${triggerTypes.length} trigger types\n\n${formatTriggerTypesTable(triggerTypes)}`
+ );
+ yield* ui.output(formatTriggerTypesJson(triggerTypes));
+ })
+).pipe(Command.withDescription('List available trigger types.'));
diff --git a/ts/packages/cli/src/commands/triggers/format.ts b/ts/packages/cli/src/commands/triggers/format.ts
index 2ed47e18d..ef7e4347b 100644
--- a/ts/packages/cli/src/commands/triggers/format.ts
+++ b/ts/packages/cli/src/commands/triggers/format.ts
@@ -1,3 +1,4 @@
+import type { TriggerType } from 'src/models/trigger-types';
import type { TriggerListenEvent } from './types';
import { bold, gray } from 'src/ui/colors';
import { truncate } from 'src/ui/truncate';
@@ -56,3 +57,102 @@ export const formatTriggerListenTableRow = ({
truncate(connectedAccountId, TRIGGER_TABLE.connectedAccountId),
].join(' ');
};
+
+const TRIGGER_TYPES_TABLE = {
+ slug: 35,
+ name: 26,
+ type: 8,
+} as const;
+
+export const formatTriggerTypesTable = (triggerTypes: ReadonlyArray<TriggerType>): string => {
+ const header = [
+ bold('Slug'.padEnd(TRIGGER_TYPES_TABLE.slug)),
+ bold('Name'.padEnd(TRIGGER_TYPES_TABLE.name)),
+ bold('Type'.padEnd(TRIGGER_TYPES_TABLE.type)),
+ bold('Description'),
+ ].join(' ');
+
+ const rows = triggerTypes.map(triggerType => {
+ const slug = truncate(triggerType.slug, TRIGGER_TYPES_TABLE.slug).padEnd(
+ TRIGGER_TYPES_TABLE.slug
+ );
+ const name = truncate(triggerType.name, TRIGGER_TYPES_TABLE.name).padEnd(
+ TRIGGER_TYPES_TABLE.name
+ );
+ const type = triggerType.type.padEnd(TRIGGER_TYPES_TABLE.type);
+ const description = gray(truncate(triggerType.description, 50));
+ return `${slug} ${name} ${type} ${description}`;
+ });
+
+ return [header, ...rows].join('\n');
+};
+
+export const formatTriggerTypesJson = (triggerTypes: ReadonlyArray<TriggerType>): string =>
+ JSON.stringify(
+ triggerTypes.map(triggerType => ({
+ slug: triggerType.slug,
+ name: triggerType.name,
+ type: triggerType.type,
+ description: triggerType.description,
+ })),
+ null,
+ 2
+ );
+
+function formatSchemaProperties(schema: Record<string, unknown>): string {
+ const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
+ if (!properties || Object.keys(properties).length === 0) {
+ return ' (none)';
+ }
+
+ const requiredArr = (schema['required'] as string[] | undefined) ?? [];
+ const requiredSet = new Set(requiredArr);
+
+ const entries = Object.entries(properties).map(([name, prop]) => {
+ const type = (prop['type'] as string) ?? 'unknown';
+ const label = requiredSet.has(name) ? 'required' : 'optional';
+ const description = prop['description'] as string | undefined;
+ const hasDefault = Object.prototype.hasOwnProperty.call(prop, 'default');
+ const defaultValue = hasDefault ? prop['default'] : undefined;
+ return { name, type, label, description, hasDefault, defaultValue };
+ });
+
+ const typeWidth = Math.max(...entries.map(e => e.type.length));
+ const labelWidth = Math.max(...entries.map(e => e.label.length));
+
+ return entries
+ .map(e => {
+ const lines: string[] = [];
+ lines.push(` ${bold(e.name)}`);
+ lines.push(
+ ` ${bold('description:')} ${e.description ? gray(truncate(e.description, 70)) : '-'}`
+ );
+ lines.push(` ${bold('type:')} ${e.type.padEnd(typeWidth)}`);
+ lines.push(` ${bold('required:')} ${e.label.padEnd(labelWidth)}`);
+ if (e.hasDefault) {
+ lines.push(` ${bold('default:')} ${gray(truncate(JSON.stringify(e.defaultValue), 40))}`);
+ }
+ return lines.join('\n');
+ })
+ .join('\n\n');
+}
+
+export const formatTriggerTypeInfo = (triggerType: TriggerType): string => {
+ const lines: string[] = [];
+
+ lines.push(`${bold('Name:')} ${triggerType.name}`);
+ lines.push(`${bold('Slug:')} ${triggerType.slug}`);
+ lines.push(`${bold('Type:')} ${triggerType.type}`);
+ lines.push(`${bold('Description:')} ${triggerType.description}`);
+ lines.push(`${bold('Instructions:')} ${triggerType.instructions}`);
+
+ lines.push('');
+ lines.push(bold('Config Fields:'));
+ lines.push(formatSchemaProperties(triggerType.config));
+
+ lines.push('');
+ lines.push(bold('Payload Fields:'));
+ lines.push(formatSchemaProperties(triggerType.payload));
+
+ return lines.join('\n');
+};
diff --git a/ts/packages/cli/src/commands/triggers/triggers.cmd.ts b/ts/packages/cli/src/commands/triggers/triggers.cmd.ts
index ac9b76938..cda313099 100644
--- a/ts/packages/cli/src/commands/triggers/triggers.cmd.ts
+++ b/ts/packages/cli/src/commands/triggers/triggers.cmd.ts
@@ -1,4 +1,6 @@
import { Command } from '@effect/cli';
+import { triggersCmd$Info } from './commands/triggers.info.cmd';
+import { triggersCmd$List } from './commands/triggers.list.cmd';
import { triggersCmd$Listen } from './commands/triggers.listen.cmd';
/**
@@ -10,6 +12,6 @@ import { triggersCmd$Listen } from './commands/triggers.listen.cmd';
* ```
*/
export const triggersCmd = Command.make('triggers').pipe(
- Command.withDescription('Subscribe to realtime trigger events.'),
- Command.withSubcommands([triggersCmd$Listen])
+ Command.withDescription('List trigger types and subscribe to realtime trigger events.'),
+ Command.withSubcommands([triggersCmd$List, triggersCmd$Info, triggersCmd$Listen])
);
diff --git a/ts/packages/cli/test/src/commands/triggers/triggers.info.cmd.test.ts b/ts/packages/cli/test/src/commands/triggers/triggers.info.cmd.test.ts
new file mode 100644
index 000000000..417cc8cd6
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/triggers/triggers.info.cmd.test.ts
@@ -0,0 +1,121 @@
+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 type { TriggerTypes } from 'src/models/trigger-types';
+import type { TestLiveInput } from 'test/__utils__/services/test-layer';
+
+const testTriggerTypes: TriggerTypes = [
+ {
+ slug: 'GMAIL_NEW_GMAIL_MESSAGE',
+ name: 'NEW_GMAIL_MESSAGE',
+ description: 'Fires when a new message arrives in Gmail',
+ instructions: 'Connect Gmail and subscribe to this trigger',
+ type: 'webhook',
+ config: {
+ type: 'object',
+ properties: {
+ label: { type: 'string', description: 'Label filter for inbox messages' },
+ include_spam: {
+ type: 'boolean',
+ description: 'Include spam messages',
+ default: false,
+ },
+ },
+ required: ['label'],
+ },
+ payload: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string', description: 'Email subject line' },
+ from: { type: 'string', description: 'Sender email address' },
+ },
+ required: ['subject'],
+ },
+ },
+ {
+ slug: 'SLACK_NEW_MESSAGE',
+ name: 'NEW_MESSAGE',
+ description: 'Fires when a new message is posted in Slack',
+ instructions: 'Connect Slack and subscribe to this trigger',
+ type: 'webhook',
+ config: { type: 'object', properties: {} },
+ payload: { type: 'object', properties: {} },
+ },
+];
+
+const toolkitsData = {
+ triggerTypes: testTriggerTypes,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio triggers info', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] valid slug [Then] displays trigger type info',
+ it => {
+ it.scoped('shows trigger details with config and payload fields', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'info', 'GMAIL_NEW_GMAIL_MESSAGE']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('NEW_GMAIL_MESSAGE');
+ expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
+ expect(output).toContain('Config Fields');
+ expect(output).toContain('label');
+ expect(output).toContain('required');
+ expect(output).toContain('Payload Fields');
+ expect(output).toContain('subject');
+ expect(output).toContain('default: false');
+ expect(output).toContain('composio triggers list --toolkits "gmail"');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] no slug [Then] warns missing argument',
+ it => {
+ it.scoped('shows missing argument warning', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'info']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Missing required argument');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] invalid slug [Then] shows not found hint',
+ it => {
+ it.scoped('shows not found fallback hint', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'info', 'NONEXISTENT_TRIGGER']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not found');
+ expect(output).toContain('composio triggers list');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'info', 'GMAIL_NEW_GMAIL_MESSAGE']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+});
diff --git a/ts/packages/cli/test/src/commands/triggers/triggers.list.cmd.test.ts b/ts/packages/cli/test/src/commands/triggers/triggers.list.cmd.test.ts
new file mode 100644
index 000000000..0b6669589
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/triggers/triggers.list.cmd.test.ts
@@ -0,0 +1,139 @@
+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 type { TriggerTypes } from 'src/models/trigger-types';
+import type { TestLiveInput } from 'test/__utils__/services/test-layer';
+
+const testTriggerTypes: TriggerTypes = [
+ {
+ slug: 'GMAIL_NEW_GMAIL_MESSAGE',
+ name: 'NEW_GMAIL_MESSAGE',
+ description: 'Fires when a new message arrives in Gmail',
+ instructions: 'Connect Gmail and subscribe to this trigger',
+ type: 'webhook',
+ config: { type: 'object', properties: {} },
+ payload: { type: 'object', properties: {} },
+ },
+ {
+ slug: 'GMAIL_NEW_LABEL',
+ name: 'NEW_LABEL',
+ description: 'Fires when a new label is created in Gmail',
+ instructions: 'Connect Gmail and subscribe to this trigger',
+ type: 'poll',
+ config: { type: 'object', properties: {} },
+ payload: { type: 'object', properties: {} },
+ },
+ {
+ slug: 'SLACK_NEW_MESSAGE',
+ name: 'NEW_MESSAGE',
+ description: 'Fires when a new message is posted in Slack',
+ instructions: 'Connect Slack and subscribe to this trigger',
+ type: 'webhook',
+ config: { type: 'object', properties: {} },
+ payload: { type: 'object', properties: {} },
+ },
+];
+
+const toolkitsData = {
+ triggerTypes: testTriggerTypes,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio triggers list', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] no flags [Then] lists all trigger types',
+ it => {
+ it.scoped('lists all trigger types', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
+ expect(output).toContain('SLACK_NEW_MESSAGE');
+ expect(output).toContain('Listing 3 trigger types');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --toolkits "gmail" [Then] lists only gmail trigger types',
+ it => {
+ it.scoped('filters by toolkit', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'list', '--toolkits', 'gmail']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
+ expect(output).toContain('GMAIL_NEW_LABEL');
+ expect(output).not.toContain('SLACK_NEW_MESSAGE');
+ expect(output).toContain('Listing 2 trigger types');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --limit 1 [Then] lists one trigger type',
+ it => {
+ it.scoped('respects limit', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'list', '--limit', '1']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Listing 1 trigger types');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider }))(
+ '[Given] empty results [Then] shows no trigger types found',
+ it => {
+ it.scoped('shows no trigger types found', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('No trigger types found');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --toolkits "nonexistent" [Then] shows no trigger types found with hint',
+ it => {
+ it.scoped('shows hint about verifying toolkit slug', () =>
+ Effect.gen(function* () {
+ yield* cli(['triggers', 'list', '--toolkits', 'nonexistent']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('No trigger types found');
+ expect(output).toContain('composio toolkits list');
+ })
+ );
+ }
+ );
+});