Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 07:00 UTC
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
+});