@devries-cameron20 / composio-1 / commits / 9e2799af9
Fork 0

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

Improve local trigger development UX by adding `composio triggers list` (with toolkit and limit filters) and `composio triggers info` with readable per-field schema details, including defaults. Co-authored-by: Cursor <cursoragent@cursor.com>

haxzie committed Feb 23, 2026 at 18:55 UTC 9e2799af969ca063daf19d21bf1538e947339c45
6 files changed +497 -2
ts/packages/cli/src/commands/triggers/commands/triggers.info.cmd.ts new
+68
@@ -0,0 +1,68 @@
1 +import { Args, Command } from '@effect/cli';
2 +import { Effect, Option } from 'effect';
3 +import { requireAuth } from 'src/effects/require-auth';
4 +import { ComposioToolkitsRepository } from 'src/services/composio-clients';
5 +import { TerminalUI } from 'src/services/terminal-ui';
6 +import { formatTriggerTypeInfo } from '../format';
7 +
8 +const slug = Args.text({ name: 'slug' }).pipe(
9 + Args.withDescription('Trigger slug (e.g. "GMAIL_NEW_GMAIL_MESSAGE")'),
10 + Args.optional
11 +);
12 +
13 +/**
14 + * View details of a specific trigger type including config and payload schemas.
15 + *
16 + * @example
17 + * ```bash
18 + * composio triggers info "GMAIL_NEW_GMAIL_MESSAGE"
19 + * ```
20 + */
21 +export const triggersCmd$Info = Command.make('info', { slug }, ({ slug }) =>
22 + Effect.gen(function* () {
23 + if (!(yield* requireAuth)) return;
24 +
25 + const ui = yield* TerminalUI;
26 + const repo = yield* ComposioToolkitsRepository;
27 +
28 + if (Option.isNone(slug)) {
29 + yield* ui.log.warn('Missing required argument: <slug>');
30 + yield* ui.log.step(
31 + 'Try specifying a trigger slug, e.g.:\n> composio triggers info "GMAIL_NEW_GMAIL_MESSAGE"'
32 + );
33 + return;
34 + }
35 +
36 + const slugValue = slug.value;
37 + const triggerTypes = yield* ui.withSpinner('Fetching trigger types...', repo.getTriggerTypes());
38 + const normalizedSlug = slugValue.toUpperCase();
39 + const triggerType = triggerTypes.find(item => item.slug.toUpperCase() === normalizedSlug);
40 +
41 + if (!triggerType) {
42 + yield* ui.log.error(`Trigger "${slugValue}" not found.`);
43 + const suggestions = triggerTypes
44 + .filter(item => item.slug.toUpperCase().includes(normalizedSlug))
45 + .slice(0, 3);
46 + if (suggestions.length > 0) {
47 + yield* ui.log.step('Did you mean:');
48 + yield* Effect.forEach(suggestions, item =>
49 + ui.log.step(`> composio triggers info "${item.slug}"`)
50 + );
51 + } else {
52 + yield* ui.log.step('Browse available trigger types:\n> composio triggers list');
53 + }
54 + return;
55 + }
56 +
57 + yield* ui.note(formatTriggerTypeInfo(triggerType), `Trigger: ${triggerType.name}`);
58 +
59 + const toolkitSlug = triggerType.slug.split('_')[0]?.toLowerCase();
60 + if (toolkitSlug) {
61 + yield* ui.log.step(
62 + `To list more trigger types in this toolkit:\n> composio triggers list --toolkits "${toolkitSlug}"`
63 + );
64 + }
65 +
66 + yield* ui.output(JSON.stringify(triggerType, null, 2));
67 + })
68 +).pipe(Command.withDescription('View details of a specific trigger type.'));
ts/packages/cli/src/commands/triggers/commands/triggers.list.cmd.ts new
+65
@@ -0,0 +1,65 @@
1 +import { Command, Options } from '@effect/cli';
2 +import { Effect, Option } from 'effect';
3 +import { requireAuth } from 'src/effects/require-auth';
4 +import { ComposioToolkitsRepository } from 'src/services/composio-clients';
5 +import { TerminalUI } from 'src/services/terminal-ui';
6 +import { clampLimit } from 'src/ui/clamp-limit';
7 +import { formatTriggerTypesJson, formatTriggerTypesTable } from '../format';
8 +
9 +const toolkits = Options.text('toolkits').pipe(
10 + Options.withDescription(
11 + 'Filter by toolkit slugs, comma-separated (e.g. "gmail" or "gmail,slack")'
12 + ),
13 + Options.optional
14 +);
15 +
16 +const limit = Options.integer('limit').pipe(
17 + Options.withDefault(30),
18 + Options.withDescription('Maximum number of trigger types to show (1-1000)')
19 +);
20 +
21 +const parseCsv = (value: string): ReadonlyArray<string> =>
22 + value
23 + .split(',')
24 + .map(item => item.trim())
25 + .filter(Boolean);
26 +
27 +/**
28 + * List available trigger types with optional toolkit filters.
29 + *
30 + * @example
31 + * ```bash
32 + * composio triggers list
33 + * composio triggers list --toolkits "gmail"
34 + * composio triggers list --toolkits "gmail,slack"
35 + * ```
36 + */
37 +export const triggersCmd$List = Command.make('list', { toolkits, limit }, ({ toolkits, limit }) =>
38 + Effect.gen(function* () {
39 + if (!(yield* requireAuth)) return;
40 +
41 + const ui = yield* TerminalUI;
42 + const repo = yield* ComposioToolkitsRepository;
43 + const toolkitFilters = Option.isSome(toolkits) ? parseCsv(toolkits.value) : undefined;
44 + const clampedLimit = clampLimit(limit);
45 +
46 + const allTriggerTypes = yield* ui.withSpinner(
47 + 'Fetching trigger types...',
48 + repo.getTriggerTypes(toolkitFilters)
49 + );
50 + const triggerTypes = allTriggerTypes.slice(0, clampedLimit);
51 +
52 + if (triggerTypes.length === 0) {
53 + const hint = Option.isSome(toolkits)
54 + ? `No trigger types found in toolkit "${toolkits.value}". Verify the toolkit slug with:\n> composio toolkits list`
55 + : 'No trigger types found.';
56 + yield* ui.log.warn(hint);
57 + return;
58 + }
59 +
60 + yield* ui.log.info(
61 + `Listing ${triggerTypes.length} trigger types\n\n${formatTriggerTypesTable(triggerTypes)}`
62 + );
63 + yield* ui.output(formatTriggerTypesJson(triggerTypes));
64 + })
65 +).pipe(Command.withDescription('List available trigger types.'));
ts/packages/cli/src/commands/triggers/format.ts
+100
@@ -1,3 +1,4 @@
1 +import type { TriggerType } from 'src/models/trigger-types';
2 import type { TriggerListenEvent } from './types';
3 import { bold, gray } from 'src/ui/colors';
4 import { truncate } from 'src/ui/truncate';
@@ -56,3 +57,102 @@ export const formatTriggerListenTableRow = ({
57 truncate(connectedAccountId, TRIGGER_TABLE.connectedAccountId),
58 ].join(' ');
59 };
60 +
61 +const TRIGGER_TYPES_TABLE = {
62 + slug: 35,
63 + name: 26,
64 + type: 8,
65 +} as const;
66 +
67 +export const formatTriggerTypesTable = (triggerTypes: ReadonlyArray<TriggerType>): string => {
68 + const header = [
69 + bold('Slug'.padEnd(TRIGGER_TYPES_TABLE.slug)),
70 + bold('Name'.padEnd(TRIGGER_TYPES_TABLE.name)),
71 + bold('Type'.padEnd(TRIGGER_TYPES_TABLE.type)),
72 + bold('Description'),
73 + ].join(' ');
74 +
75 + const rows = triggerTypes.map(triggerType => {
76 + const slug = truncate(triggerType.slug, TRIGGER_TYPES_TABLE.slug).padEnd(
77 + TRIGGER_TYPES_TABLE.slug
78 + );
79 + const name = truncate(triggerType.name, TRIGGER_TYPES_TABLE.name).padEnd(
80 + TRIGGER_TYPES_TABLE.name
81 + );
82 + const type = triggerType.type.padEnd(TRIGGER_TYPES_TABLE.type);
83 + const description = gray(truncate(triggerType.description, 50));
84 + return `${slug} ${name} ${type} ${description}`;
85 + });
86 +
87 + return [header, ...rows].join('\n');
88 +};
89 +
90 +export const formatTriggerTypesJson = (triggerTypes: ReadonlyArray<TriggerType>): string =>
91 + JSON.stringify(
92 + triggerTypes.map(triggerType => ({
93 + slug: triggerType.slug,
94 + name: triggerType.name,
95 + type: triggerType.type,
96 + description: triggerType.description,
97 + })),
98 + null,
99 + 2
100 + );
101 +
102 +function formatSchemaProperties(schema: Record<string, unknown>): string {
103 + const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
104 + if (!properties || Object.keys(properties).length === 0) {
105 + return ' (none)';
106 + }
107 +
108 + const requiredArr = (schema['required'] as string[] | undefined) ?? [];
109 + const requiredSet = new Set(requiredArr);
110 +
111 + const entries = Object.entries(properties).map(([name, prop]) => {
112 + const type = (prop['type'] as string) ?? 'unknown';
113 + const label = requiredSet.has(name) ? 'required' : 'optional';
114 + const description = prop['description'] as string | undefined;
115 + const hasDefault = Object.prototype.hasOwnProperty.call(prop, 'default');
116 + const defaultValue = hasDefault ? prop['default'] : undefined;
117 + return { name, type, label, description, hasDefault, defaultValue };
118 + });
119 +
120 + const typeWidth = Math.max(...entries.map(e => e.type.length));
121 + const labelWidth = Math.max(...entries.map(e => e.label.length));
122 +
123 + return entries
124 + .map(e => {
125 + const lines: string[] = [];
126 + lines.push(` ${bold(e.name)}`);
127 + lines.push(
128 + ` ${bold('description:')} ${e.description ? gray(truncate(e.description, 70)) : '-'}`
129 + );
130 + lines.push(` ${bold('type:')} ${e.type.padEnd(typeWidth)}`);
131 + lines.push(` ${bold('required:')} ${e.label.padEnd(labelWidth)}`);
132 + if (e.hasDefault) {
133 + lines.push(` ${bold('default:')} ${gray(truncate(JSON.stringify(e.defaultValue), 40))}`);
134 + }
135 + return lines.join('\n');
136 + })
137 + .join('\n\n');
138 +}
139 +
140 +export const formatTriggerTypeInfo = (triggerType: TriggerType): string => {
141 + const lines: string[] = [];
142 +
143 + lines.push(`${bold('Name:')} ${triggerType.name}`);
144 + lines.push(`${bold('Slug:')} ${triggerType.slug}`);
145 + lines.push(`${bold('Type:')} ${triggerType.type}`);
146 + lines.push(`${bold('Description:')} ${triggerType.description}`);
147 + lines.push(`${bold('Instructions:')} ${triggerType.instructions}`);
148 +
149 + lines.push('');
150 + lines.push(bold('Config Fields:'));
151 + lines.push(formatSchemaProperties(triggerType.config));
152 +
153 + lines.push('');
154 + lines.push(bold('Payload Fields:'));
155 + lines.push(formatSchemaProperties(triggerType.payload));
156 +
157 + return lines.join('\n');
158 +};
ts/packages/cli/src/commands/triggers/triggers.cmd.ts
+4 -2
@@ -1,4 +1,6 @@
1 import { Command } from '@effect/cli';
2 +import { triggersCmd$Info } from './commands/triggers.info.cmd';
3 +import { triggersCmd$List } from './commands/triggers.list.cmd';
4 import { triggersCmd$Listen } from './commands/triggers.listen.cmd';
5
6 /**
@@ -10,6 +12,6 @@ import { triggersCmd$Listen } from './commands/triggers.listen.cmd';
12 * ```
13 */
14 export const triggersCmd = Command.make('triggers').pipe(
13 - Command.withDescription('Subscribe to realtime trigger events.'),
14 - Command.withSubcommands([triggersCmd$Listen])
15 + Command.withDescription('List trigger types and subscribe to realtime trigger events.'),
16 + Command.withSubcommands([triggersCmd$List, triggersCmd$Info, triggersCmd$Listen])
17 );
ts/packages/cli/test/src/commands/triggers/triggers.info.cmd.test.ts new
+121
@@ -0,0 +1,121 @@
1 +import { describe, expect, layer } from '@effect/vitest';
2 +import { ConfigProvider, Effect } from 'effect';
3 +import { extendConfigProvider } from 'src/services/config';
4 +import { cli, MockConsole, TestLive } from 'test/__utils__';
5 +import type { TriggerTypes } from 'src/models/trigger-types';
6 +import type { TestLiveInput } from 'test/__utils__/services/test-layer';
7 +
8 +const testTriggerTypes: TriggerTypes = [
9 + {
10 + slug: 'GMAIL_NEW_GMAIL_MESSAGE',
11 + name: 'NEW_GMAIL_MESSAGE',
12 + description: 'Fires when a new message arrives in Gmail',
13 + instructions: 'Connect Gmail and subscribe to this trigger',
14 + type: 'webhook',
15 + config: {
16 + type: 'object',
17 + properties: {
18 + label: { type: 'string', description: 'Label filter for inbox messages' },
19 + include_spam: {
20 + type: 'boolean',
21 + description: 'Include spam messages',
22 + default: false,
23 + },
24 + },
25 + required: ['label'],
26 + },
27 + payload: {
28 + type: 'object',
29 + properties: {
30 + subject: { type: 'string', description: 'Email subject line' },
31 + from: { type: 'string', description: 'Sender email address' },
32 + },
33 + required: ['subject'],
34 + },
35 + },
36 + {
37 + slug: 'SLACK_NEW_MESSAGE',
38 + name: 'NEW_MESSAGE',
39 + description: 'Fires when a new message is posted in Slack',
40 + instructions: 'Connect Slack and subscribe to this trigger',
41 + type: 'webhook',
42 + config: { type: 'object', properties: {} },
43 + payload: { type: 'object', properties: {} },
44 + },
45 +];
46 +
47 +const toolkitsData = {
48 + triggerTypes: testTriggerTypes,
49 +} satisfies TestLiveInput['toolkitsData'];
50 +
51 +const testConfigProvider = ConfigProvider.fromMap(
52 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
53 +).pipe(extendConfigProvider);
54 +
55 +describe('CLI: composio triggers info', () => {
56 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
57 + '[Given] valid slug [Then] displays trigger type info',
58 + it => {
59 + it.scoped('shows trigger details with config and payload fields', () =>
60 + Effect.gen(function* () {
61 + yield* cli(['triggers', 'info', 'GMAIL_NEW_GMAIL_MESSAGE']);
62 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
63 + const output = lines.join('\n');
64 +
65 + expect(output).toContain('NEW_GMAIL_MESSAGE');
66 + expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
67 + expect(output).toContain('Config Fields');
68 + expect(output).toContain('label');
69 + expect(output).toContain('required');
70 + expect(output).toContain('Payload Fields');
71 + expect(output).toContain('subject');
72 + expect(output).toContain('default: false');
73 + expect(output).toContain('composio triggers list --toolkits "gmail"');
74 + })
75 + );
76 + }
77 + );
78 +
79 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
80 + '[Given] no slug [Then] warns missing argument',
81 + it => {
82 + it.scoped('shows missing argument warning', () =>
83 + Effect.gen(function* () {
84 + yield* cli(['triggers', 'info']);
85 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
86 + const output = lines.join('\n');
87 +
88 + expect(output).toContain('Missing required argument');
89 + })
90 + );
91 + }
92 + );
93 +
94 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
95 + '[Given] invalid slug [Then] shows not found hint',
96 + it => {
97 + it.scoped('shows not found fallback hint', () =>
98 + Effect.gen(function* () {
99 + yield* cli(['triggers', 'info', 'NONEXISTENT_TRIGGER']);
100 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
101 + const output = lines.join('\n');
102 +
103 + expect(output).toContain('not found');
104 + expect(output).toContain('composio triggers list');
105 + })
106 + );
107 + }
108 + );
109 +
110 + layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
111 + it.scoped('warns user to login', () =>
112 + Effect.gen(function* () {
113 + yield* cli(['triggers', 'info', 'GMAIL_NEW_GMAIL_MESSAGE']);
114 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
115 + const output = lines.join('\n');
116 +
117 + expect(output).toContain('not logged in');
118 + })
119 + );
120 + });
121 +});
ts/packages/cli/test/src/commands/triggers/triggers.list.cmd.test.ts new
+139
@@ -0,0 +1,139 @@
1 +import { describe, expect, layer } from '@effect/vitest';
2 +import { ConfigProvider, Effect } from 'effect';
3 +import { extendConfigProvider } from 'src/services/config';
4 +import { cli, MockConsole, TestLive } from 'test/__utils__';
5 +import type { TriggerTypes } from 'src/models/trigger-types';
6 +import type { TestLiveInput } from 'test/__utils__/services/test-layer';
7 +
8 +const testTriggerTypes: TriggerTypes = [
9 + {
10 + slug: 'GMAIL_NEW_GMAIL_MESSAGE',
11 + name: 'NEW_GMAIL_MESSAGE',
12 + description: 'Fires when a new message arrives in Gmail',
13 + instructions: 'Connect Gmail and subscribe to this trigger',
14 + type: 'webhook',
15 + config: { type: 'object', properties: {} },
16 + payload: { type: 'object', properties: {} },
17 + },
18 + {
19 + slug: 'GMAIL_NEW_LABEL',
20 + name: 'NEW_LABEL',
21 + description: 'Fires when a new label is created in Gmail',
22 + instructions: 'Connect Gmail and subscribe to this trigger',
23 + type: 'poll',
24 + config: { type: 'object', properties: {} },
25 + payload: { type: 'object', properties: {} },
26 + },
27 + {
28 + slug: 'SLACK_NEW_MESSAGE',
29 + name: 'NEW_MESSAGE',
30 + description: 'Fires when a new message is posted in Slack',
31 + instructions: 'Connect Slack and subscribe to this trigger',
32 + type: 'webhook',
33 + config: { type: 'object', properties: {} },
34 + payload: { type: 'object', properties: {} },
35 + },
36 +];
37 +
38 +const toolkitsData = {
39 + triggerTypes: testTriggerTypes,
40 +} satisfies TestLiveInput['toolkitsData'];
41 +
42 +const testConfigProvider = ConfigProvider.fromMap(
43 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
44 +).pipe(extendConfigProvider);
45 +
46 +describe('CLI: composio triggers list', () => {
47 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
48 + '[Given] no flags [Then] lists all trigger types',
49 + it => {
50 + it.scoped('lists all trigger types', () =>
51 + Effect.gen(function* () {
52 + yield* cli(['triggers', 'list']);
53 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
54 + const output = lines.join('\n');
55 +
56 + expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
57 + expect(output).toContain('SLACK_NEW_MESSAGE');
58 + expect(output).toContain('Listing 3 trigger types');
59 + })
60 + );
61 + }
62 + );
63 +
64 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
65 + '[Given] --toolkits "gmail" [Then] lists only gmail trigger types',
66 + it => {
67 + it.scoped('filters by toolkit', () =>
68 + Effect.gen(function* () {
69 + yield* cli(['triggers', 'list', '--toolkits', 'gmail']);
70 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
71 + const output = lines.join('\n');
72 +
73 + expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
74 + expect(output).toContain('GMAIL_NEW_LABEL');
75 + expect(output).not.toContain('SLACK_NEW_MESSAGE');
76 + expect(output).toContain('Listing 2 trigger types');
77 + })
78 + );
79 + }
80 + );
81 +
82 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
83 + '[Given] --limit 1 [Then] lists one trigger type',
84 + it => {
85 + it.scoped('respects limit', () =>
86 + Effect.gen(function* () {
87 + yield* cli(['triggers', 'list', '--limit', '1']);
88 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
89 + const output = lines.join('\n');
90 +
91 + expect(output).toContain('Listing 1 trigger types');
92 + })
93 + );
94 + }
95 + );
96 +
97 + layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
98 + it.scoped('warns user to login', () =>
99 + Effect.gen(function* () {
100 + yield* cli(['triggers', 'list']);
101 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
102 + const output = lines.join('\n');
103 +
104 + expect(output).toContain('not logged in');
105 + })
106 + );
107 + });
108 +
109 + layer(TestLive({ baseConfigProvider: testConfigProvider }))(
110 + '[Given] empty results [Then] shows no trigger types found',
111 + it => {
112 + it.scoped('shows no trigger types found', () =>
113 + Effect.gen(function* () {
114 + yield* cli(['triggers', 'list']);
115 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
116 + const output = lines.join('\n');
117 +
118 + expect(output).toContain('No trigger types found');
119 + })
120 + );
121 + }
122 + );
123 +
124 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
125 + '[Given] --toolkits "nonexistent" [Then] shows no trigger types found with hint',
126 + it => {
127 + it.scoped('shows hint about verifying toolkit slug', () =>
128 + Effect.gen(function* () {
129 + yield* cli(['triggers', 'list', '--toolkits', 'nonexistent']);
130 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
131 + const output = lines.join('\n');
132 +
133 + expect(output).toContain('No trigger types found');
134 + expect(output).toContain('composio toolkits list');
135 + })
136 + );
137 + }
138 + );
139 +});