1
-import { Effect, Option } from 'effect';
2
-import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
3
-import { TerminalUI } from 'src/services/terminal-ui';
4
-import { bold, dim, gray } from 'src/ui/colors';
5
-import {
6
- type CommandVisibility,
7
- experimental,
8
- type HelpLevel,
9
- full,
10
- isTaggedValueVisible,
11
- isTaggedValueVisibleForHelpLevel,
12
- simple,
13
- tagged,
14
- visibleValues,
15
- type TaggedValue,
16
-} from './feature-tags';
1
+import { Console, Context, Effect } from 'effect';
2
+import { CliConfig, CliOutput, Command, GlobalFlag } from 'effect/unstable/cli';
3
18
-type DetailedCommand = {
19
- name: string;
20
- description: string;
21
- usage: string;
22
- options?: ReadonlyArray<{ name: string; description: string }>;
23
-};
24
-
25
-type CompactCommand = {
26
- name: string;
27
- description: string;
28
-};
29
-
30
-// ── Core workflow commands ──────────────────────────────────────────────
31
-
32
-const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
33
- simple({
34
- name: 'search',
35
- description: 'Find tools by use case across all toolkits/apps.',
36
- usage: 'search <query...> [--toolkits text] [--limit integer] [--human]',
37
- options: [
38
- {
39
- name: '<query...>',
40
- description: 'One or more semantic use-case queries (e.g. "send emails" "github issues")',
41
- },
42
- { name: '--toolkits', description: 'Filter by toolkit slugs, comma-separated' },
43
- { name: '--limit', description: 'Maximum number of results (1-1000)' },
44
- { name: '--human', description: 'Show formatted output instead of default JSON' },
45
- ],
46
- }),
47
- simple({
48
- name: 'execute',
49
- description:
50
- 'Execute a tool. Validates inputs and connections automatically; use it aggressively.',
51
- usage:
52
- 'execute <slug> [-d, --data text] [--account selector] [--file path] [--dry-run] [--get-schema] | execute -p <slug> -d <text> <slug> -d <text> ...',
53
- options: [
54
- { name: '<slug>', description: 'Tool slug (e.g. "GITHUB_CREATE_ISSUE")' },
55
- {
56
- name: '-d, --data',
57
- description:
58
- 'JSON or JS-style object arguments, e.g. -d \'{ repo: "foo" }\', @file, or - for stdin',
59
- },
60
- {
61
- name: '-p, --parallel',
62
- description: 'Execute repeated <slug> -d <text> pairs concurrently',
63
- },
64
- {
65
- name: '--account',
66
- description: 'Select a connected account by alias, word_id, or account ID',
67
- },
68
- {
69
- name: '--file',
70
- description: 'Inject a local file path into the single file_uploadable input',
71
- },
72
- { name: '--dry-run', description: 'Validate and preview the tool call without executing it' },
73
- { name: '--get-schema', description: 'Fetch and print the CLI-facing input schema' },
74
- ],
75
- }),
76
- simple({
77
- name: 'link',
78
- description: 'Connect your account for a toolkit/app.',
79
- usage: 'link [<toolkit>] [--alias text]',
80
- options: [
81
- { name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' },
82
- { name: '--alias', description: 'Alias for this connected account' },
83
- ],
84
- }),
85
- tagged({
86
- name: 'run',
87
- description:
88
- 'Run inline TS/JS code with shimmed CLI commands; injected execute(), search(), proxy(), experimental_subAgent(), and z (zod).',
89
- usage: 'run <code> [-- ...args] | run [-f, --file text] [-- ...args] [--dry-run]',
90
- options: [
91
- { name: '<code>', description: 'Inline Bun ESNext code to evaluate' },
92
- { name: '-f, --file', description: 'Run a TS/JS file instead of inline code' },
93
- { name: '--dry-run', description: 'Preview execute() calls without running remote actions' },
94
- ],
95
- }),
96
- experimental(CLI_EXPERIMENTAL_FEATURES.LISTEN, {
97
- name: 'listen',
98
- description:
99
- 'Create a temporary subscription for consumer-project events and persist each payload into the session artifact folder.',
100
- usage:
101
- 'listen <slug> [-p, --params text] [--account selector] [--max-events integer] [--timeout text] [--stream [text]]',
102
- options: [
103
- { name: '<slug>', description: 'Trigger slug (e.g. "GMAIL_NEW_GMAIL_MESSAGE")' },
104
- {
105
- name: '-p, --params',
106
- description:
107
- "Trigger create params as JSON or JS-style object, e.g. -p '{ trigger_config: { ... } }'.",
108
- },
109
- {
110
- name: '--account',
111
- description: 'Select a connected account by alias, word_id, or account ID',
112
- },
113
- {
114
- name: '--max-events',
115
- description: 'Stop after receiving N events, then disable the temporary trigger',
116
- },
117
- {
118
- name: '--timeout',
119
- description:
120
- 'Stop after a duration such as 30s, 5m, or 1hr, then disable the temporary trigger',
121
- },
122
- {
123
- name: '--stream',
124
- description:
125
- 'Also print each payload inline as a single-line stream value. Optionally pass a jq-like path such as ".thread.id".',
126
- },
127
- ],
128
- }),
129
- tagged({
130
- name: 'proxy',
131
- description:
132
- 'curl-like access to any toolkit API through Composio using your connected account.',
133
- usage: 'proxy <url> --toolkit text [--account selector] [-X method] [-H header]... [-d data]',
134
- options: [
135
- { name: '<url>', description: 'Full API endpoint URL' },
136
- { name: '--toolkit', description: 'Toolkit slug whose connected account should be used' },
137
- { name: '--account', description: 'Connected account alias, word_id, or account ID' },
138
- { name: '-X, --method', description: 'HTTP method (GET, POST, PUT, DELETE, PATCH)' },
139
- { name: '-H, --header', description: 'Header in "Name: value" format. Repeat for multiple.' },
140
- { name: '-d, --data', description: 'Request body as raw text, JSON, @file, or - for stdin' },
141
- ],
142
- }),
143
-];
144
-
145
-// ── Developer commands ─────────────────────────────────────────────────
146
-
147
-const OTHER_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
148
- tagged({
149
- name: 'composio tools info <slug>',
150
- description: 'Print tool summary and cache its schema',
151
- }),
152
- tagged({
153
- name: 'composio tools list <toolkit>',
154
- description: 'List tools available in a toolkit',
155
- }),
156
- tagged({
157
- name: 'composio triggers info <slug>',
158
- description: 'Print trigger type details and schema summaries',
159
- }),
160
- tagged({
161
- name: 'composio triggers list <toolkit>',
162
- description: 'List available trigger types in a toolkit',
163
- }),
164
- tagged({
165
- name: 'composio artifacts cwd',
166
- description: 'Print the cwd-scoped session artifact directory',
167
- }),
168
-];
169
-
170
-const GENERATE_COMMAND: TaggedValue<CompactCommand> = tagged({
171
- name: 'generate',
172
- description: 'Generate type stubs for toolkits, tools, and triggers (TypeScript | Python).',
4
+export const RootHelpMarker = Context.Reference<boolean>('commands/RootHelpMarker', {
5
+ defaultValue: () => false,
6
});
7
175
-// ── Account commands ───────────────────────────────────────────────────
176
-
177
-const ACCOUNT_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
178
- tagged({ name: 'setup', description: 'Install or uninstall agent plugins' }),
179
- tagged({ name: 'login', description: 'Log in to Composio' }),
180
- tagged({ name: 'logout', description: 'Log out from Composio' }),
181
- tagged({ name: 'whoami', description: 'Show current account info' }),
182
- tagged({ name: 'orgs', description: 'Manage default global organization/project context.' }),
183
- tagged({ name: 'version', description: 'Display CLI version' }),
184
- tagged({ name: 'upgrade', description: 'Upgrade CLI to the latest version' }),
185
- tagged({ name: 'config', description: 'View and manage CLI configuration' }),
186
-];
187
-
188
-const FULL_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
189
- full({
190
- name: 'files',
191
- description: 'Show where CLI config, cache, and session artifacts live',
192
- }),
193
- full({ name: 'tools list', description: 'List tools for a toolkit with query/tag filters' }),
194
- full({ name: 'tools info', description: 'Inspect a tool summary and cached schema details' }),
195
- full({ name: 'triggers list', description: 'List trigger types for a toolkit' }),
196
- full({ name: 'triggers info', description: 'Inspect a trigger type and schema summary' }),
197
- full({ name: 'connections list', description: 'Print toolkit connection statuses as JSON' }),
198
- full({ name: 'connections remove', description: 'Interactively remove a toolkit connection' }),
199
- full({ name: 'generate ts', description: 'Generate TypeScript stubs for selected toolkits' }),
200
- full({ name: 'generate py', description: 'Generate Python stubs for selected toolkits' }),
201
- full({
202
- name: 'dev init',
203
- description: 'Initialize a developer project in the current directory',
204
- }),
205
- full({
206
- name: 'dev playground-execute',
207
- description: 'Execute tools against developer playground users and auth configs',
208
- }),
209
- full({
210
- name: 'dev listen',
211
- description: 'Stream developer-project realtime trigger events with optional forwarding',
212
- }),
213
-];
214
-
215
-// ── Render helpers ─────────────────────────────────────────────────────
216
-
217
-function renderDetailedCommands(name: string, commands: ReadonlyArray<DetailedCommand>): string[] {
218
- const lines: string[] = [];
219
- for (const cmd of commands) {
220
- lines.push(` ${bold(cmd.name)}`);
221
- lines.push(` ${cmd.description}`);
222
- lines.push(` ${dim('Usage:')} ${name} ${cmd.usage}`);
223
- if (cmd.options && cmd.options.length > 0) {
224
- for (const opt of cmd.options) {
225
- lines.push(` ${dim(opt.name.padEnd(20))}${opt.description}`);
226
- }
227
- }
228
- lines.push('');
229
- }
230
- return lines;
231
-}
232
-
233
-function renderCompactCommands(commands: ReadonlyArray<CompactCommand>): string[] {
234
- const maxLen = Math.max(...commands.map(c => c.name.length));
235
- return commands.map(cmd => ` ${cmd.name.padEnd(maxLen + 2)}${cmd.description}`);
236
-}
237
-
238
-function renderDevHelp(visibility: CommandVisibility, helpLevel: HelpLevel = 'default'): string {
239
- const lines: string[] = [
240
- '',
241
- bold('USAGE'),
242
- visibility.isDevModeEnabled
243
- ? ' composio dev [--mode on|off] <command> [options]'
244
- : ' composio dev [--mode on|off]',
245
- '',
246
- bold('DESCRIPTION'),
247
- visibility.isDevModeEnabled
248
- ? ' Developer workflows for local project setup, playground execution, logs, and developer-scoped management.'
249
- : ' Developer mode is off. Only mode switching is available until you turn it back on.',
250
- '',
251
- bold('MODE'),
252
- ' --mode <on|off> Turn developer mode on or off.',
253
- '',
254
- ];
255
-
256
- if (!visibility.isDevModeEnabled) {
257
- if (helpLevel !== 'simple') {
258
- lines.push(bold('EXAMPLES'));
259
- lines.push(' composio dev --mode on');
260
- lines.push(' composio dev --mode off');
261
- lines.push('');
262
- lines.push(bold('NOTE'));
263
- lines.push(
264
- ' Developer mode is for engineers building with the CLI. It unlocks more advanced commands like creating or updating auth configs and connected accounts.'
265
- );
266
- lines.push('');
267
- }
268
- return lines.join('\n');
269
- }
270
-
271
- lines.push(bold('PROJECT'));
272
- lines.push(' dev init Initialize this directory with a developer project');
273
- lines.push('');
274
-
275
- lines.push(bold('EXECUTION'));
276
- lines.push(' dev playground-execute Execute a tool against a developer playground user');
277
- lines.push(' dev listen Listen to developer-project trigger events');
278
- lines.push(' dev logs tools Browse tool logs');
279
- lines.push(' dev logs triggers Browse trigger logs');
280
- lines.push('');
281
-
282
- lines.push(bold('TOOLKITS'));
283
- lines.push(' dev toolkits list Browse available toolkits');
284
- lines.push(' dev toolkits info Inspect a toolkit');
285
- lines.push(' dev toolkits search Search toolkits');
286
- lines.push(' dev toolkits version Inspect toolkit versions');
287
- lines.push('');
288
-
289
- lines.push(bold('AUTH CONFIGS'));
290
- lines.push(' dev auth-configs list List auth configs');
291
- lines.push(' dev auth-configs info View one auth config');
292
- lines.push(' dev auth-configs create Create an auth config');
293
- lines.push('');
294
-
295
- lines.push(bold('CONNECTED ACCOUNTS'));
296
- lines.push(' dev connected-accounts link Link a connected account');
297
- lines.push(' dev connected-accounts list List connected accounts');
298
- lines.push(' dev connected-accounts info View one connected account');
299
- lines.push(' dev connected-accounts whoami Resolve an account identity');
300
- lines.push('');
301
-
302
- lines.push(bold('TRIGGERS'));
303
- lines.push(' dev triggers list List trigger types');
304
- lines.push(' dev triggers info View one trigger type');
305
- lines.push(' dev triggers status Inspect trigger instances');
306
- lines.push(' dev triggers create Create a trigger instance');
307
- lines.push(' dev triggers enable Enable a trigger instance');
308
- lines.push(' dev triggers disable Disable a trigger instance [guarded]');
309
- lines.push('');
310
-
311
- lines.push(bold('PROJECTS'));
312
- lines.push(' dev projects list List projects');
313
- lines.push(' dev projects switch Switch default project');
314
- lines.push('');
315
-
316
- lines.push(bold('GUARDED'));
317
- lines.push(' dev triggers disable Disable a trigger instance');
318
- lines.push(
319
- ' This requires `developer.destructive_actions: true` in `~/.composio/config.json` and `--dangerously-allow` on the command line.'
320
- );
321
- lines.push('');
322
- if (helpLevel !== 'simple') {
323
- lines.push(bold('EXAMPLES'));
324
- lines.push(' composio dev --mode off');
325
- lines.push(' composio dev toolkits list');
326
- lines.push(
327
- ' composio dev playground-execute GMAIL_SEND_EMAIL --dangerously-allow -d \'{ recipient_email: "a@b.com" }\''
328
- );
329
- lines.push('');
330
- }
331
- return lines.join('\n');
332
-}
333
-export const HELP_LEVELS = [
334
- 'simple',
335
- 'default',
336
- 'full',
337
-] as const satisfies ReadonlyArray<HelpLevel>;
338
-
339
-export const parseHelpLevel = (token: string | undefined): HelpLevel | undefined => {
340
- if (!token) {
341
- return undefined;
342
- }
343
- if (token === 'verbose') {
344
- return 'full';
345
- }
346
- return HELP_LEVELS.find(level => level === token);
347
-};
348
-
349
-const splitTrailingHelpLevel = (
350
- args: ReadonlyArray<string>
351
-): { args: ReadonlyArray<string>; helpLevel: HelpLevel } => {
352
- const trailingLevel = parseHelpLevel(args[args.length - 1]);
353
- if (!trailingLevel) {
354
- return { args, helpLevel: 'default' };
8
+export class RootHelpContext extends Context.Service<
9
+ RootHelpContext,
10
+ {
11
+ readonly command: Command.Command.Any;
12
+ readonly version: string;
13
}
14
+>()('commands/RootHelpContext') {}
15
16
+/** Keep a short root overview; the framework generates every usage, flag, and subcommand. */
17
+export const helpFormatter = () => {
18
+ const formatter = CliOutput.defaultFormatter();
19
return {
358
- args: args.slice(0, -1),
359
- helpLevel: trailingLevel,
360
- };
361
-};
362
-
363
-// ── Subcommand help definitions ────────────────────────────────────────
364
-
365
-type SubcommandHelp = {
366
- usage: string;
367
- description: string;
368
- args?: ReadonlyArray<{ name: string; description: string }>;
369
- options?: ReadonlyArray<{ name: string; description: string }>;
370
- flags?: ReadonlyArray<{ name: string; description: string }>;
371
- injectedHelpers?: ReadonlyArray<{ name: string; description: string }>;
372
- examples?: ReadonlyArray<string>;
373
- seeAlso?: ReadonlyArray<string>;
374
-};
375
-
376
-const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHelp>> = {
377
- search: {
378
- usage: 'composio search <query...> [--toolkits text] [--limit integer] [--human]',
379
- description:
380
- 'Find tools by use case. Defaults to JSON output; use --human for formatted output.',
381
- args: [
382
- {
383
- name: '<query...>',
384
- description:
385
- 'One or more semantic use-case queries (e.g. "send an email", "create github issue")',
386
- },
387
- ],
388
- options: [
389
- { name: '--toolkits <text>', description: 'Filter by toolkit slugs, comma-separated' },
390
- { name: '--limit <integer>', description: 'Maximum number of results (1-1000)' },
391
- { name: '--human', description: 'Show formatted human-readable search output' },
392
- ],
393
- examples: [
394
- '# Find tools for a use case',
395
- 'composio search "send an email"',
396
- 'composio search "send an email" "create github issue"',
397
- 'composio search "my emails" "my github issues" --toolkits gmail,github',
398
- 'composio search "create issue" --toolkits github',
399
- 'composio search "send an email" --human',
400
- '',
401
- '# Cross-app workflow discovery',
402
- 'composio search "post a message to a slack channel"',
403
- 'composio search "add a row to google sheet"',
404
- '',
405
- '# Narrow results to a specific toolkit',
406
- 'composio search "list calendar events" --toolkits google_calendar --limit 5',
407
- ],
408
- seeAlso: [
409
- "composio execute <slug> -d '{ ... }' Run a tool from the results",
410
- "composio tools info <slug> Inspect a tool's full schema",
411
- 'composio link <toolkit> Connect an account if execute tells you to',
412
- ],
413
- },
414
- execute: {
415
- usage:
416
- 'composio execute <slug> [-d, --data text] [--account selector] [--file path] [--dry-run] [--get-schema] [--parallel]',
417
- description:
418
- 'Execute a tool by slug. Validates inputs against cached schemas and checks connections automatically — just try it and it will tell you what to fix.',
419
- args: [
420
- {
421
- name: '<slug>',
422
- description:
423
- 'Tool slug for single execute, or repeated <slug> -d <text> pairs when using -p/--parallel',
424
- },
425
- ],
426
- options: [
427
- {
428
- name: '-d, --data <text>',
429
- description:
430
- 'JSON or JS-style object arguments, e.g. -d \'{ repo: "foo" }\', @file, or - for stdin',
431
- },
432
- {
433
- name: '-p, --parallel',
434
- description: 'Execute repeated TOOL_SLUG -d <text> groups concurrently',
435
- },
436
- {
437
- name: '--account <selector>',
438
- description: 'Select a connected account by alias, word_id, or connected account ID',
439
- },
440
- {
441
- name: '--file <path>',
442
- description: 'Inject a local file path into the single file_uploadable input',
443
- },
444
- {
445
- name: '--get-schema',
446
- description: 'Fetch and print the CLI-facing input schema without executing',
447
- },
448
- {
449
- name: '--dry-run',
450
- description: 'Validate and preview the tool call without executing',
451
- },
452
- ],
453
- flags: [
454
- { name: '--skip-connection-check', description: 'Skip the connected-account check' },
455
- {
456
- name: '--skip-tool-params-check',
457
- description: 'Skip input validation against cached schema',
458
- },
459
- { name: '--skip-checks', description: 'Skip both checks above' },
460
- ],
461
- examples: [
462
- '# Send an email',
463
- `composio execute GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hello", body: "World" }'`,
464
- '',
465
- '# Create a GitHub issue with a named account',
466
- `composio execute GITHUB_CREATE_ISSUE --account work -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'`,
467
- '',
468
- '# Preview what a tool call would send without executing',
469
- `composio execute SLACK_SEND_MESSAGE --dry-run -d '{ channel: "general", markdown_text: "Hello team" }'`,
470
- '',
471
- '# Check what inputs a tool needs',
472
- 'composio execute GMAIL_SEND_EMAIL --get-schema',
473
- '',
474
- '# Read arguments from a file',
475
- 'composio execute GITHUB_CREATE_ISSUE -d @issue.json',
476
- '',
477
- '# Execute multiple tools concurrently',
478
- `composio execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com" }' GITHUB_CREATE_AN_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
479
- ],
480
- seeAlso: [
481
- 'composio search "<query>" Find tool slugs by use case',
482
- 'composio tools info <slug> Schema summary with jq hints',
483
- 'composio link <toolkit> Connect an account for a toolkit',
484
- 'composio artifacts cwd Print the current session artifact directory',
485
- ],
486
- },
487
- listen: experimental(CLI_EXPERIMENTAL_FEATURES.LISTEN, {
488
- usage:
489
- 'composio listen <slug> [-p, --params text] [--account selector] [--max-events integer] [--timeout text] [--stream [text]]',
490
- description:
491
- 'Create a temporary subscription for consumer-project events so background agents can easily consume new emails, Slack messages, and other trigger payloads from artifacts.',
492
- args: [{ name: '<slug>', description: 'Trigger slug to create and listen to' }],
493
- options: [
494
- {
495
- name: '-p, --params <text>',
496
- description:
497
- 'Trigger create params as JSON/JS object, @file, or - for stdin. Pass optional trigger config fields only.',
498
- },
499
- {
500
- name: '--account <selector>',
501
- description: 'Select a connected account by alias, word_id, or connected account ID',
502
- },
503
- {
504
- name: '--max-events <integer>',
505
- description: 'Stop after N events for this temporary trigger and disable it',
506
- },
507
- {
508
- name: '--timeout <text>',
509
- description: 'Stop after a duration such as "30s", "5m", or "1hr" and disable the trigger',
510
- },
511
- {
512
- name: '--stream [text]',
513
- description:
514
- 'Also print each event payload inline. Optionally pass a jq-like path such as ".thread.id" or ".data[0].id".',
515
- },
516
- ],
517
- examples: [
518
- 'composio listen GMAIL_NEW_GMAIL_MESSAGE',
519
- 'composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --max-events 5',
520
- 'composio listen GMAIL_NEW_GMAIL_MESSAGE --account work --timeout 5m',
521
- "composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 1hr --stream '.data.threadId'",
522
- 'composio listen SLACK_CHANNEL_MESSAGE_RECEIVED -p \'{ trigger_config: { channel_id: "C123" } }\'',
523
- 'composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream',
524
- "composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream '.data.threadId'",
525
- ],
526
- seeAlso: [
527
- 'composio artifacts cwd Print the current session artifact directory',
528
- 'composio triggers info <slug> Inspect trigger type details before listening',
529
- 'composio link <toolkit> Connect the required account before creating the trigger',
530
- ],
531
- }),
532
- link: {
533
- usage: 'composio link [<toolkit>] [--no-wait] [--no-browser] [--alias text] [--list]',
534
- description:
535
- 'Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf. Opens a browser for OAuth authorization and waits for confirmation.',
536
- args: [{ name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' }],
537
- options: [
538
- {
539
- name: '--alias <text>',
540
- description:
541
- 'Alias for the connected account. Required when creating an additional account for the same toolkit',
542
- },
543
- ],
544
- flags: [
545
- {
546
- name: '--no-wait',
547
- description: 'Print link info and exit without waiting for authorization',
548
- },
549
- {
550
- name: '--no-browser',
551
- description: 'Do not open the browser automatically; print the URL to open manually',
552
- },
553
- {
554
- name: '--list',
555
- description:
556
- 'List existing connected accounts for the toolkit instead of creating a new link',
557
- },
558
- ],
559
- examples: [
560
- 'composio link github',
561
- 'composio link gmail --alias work',
562
- 'composio link github --list',
563
- ],
564
- seeAlso: [
565
- 'composio search "<query>" Find tools to use after linking',
566
- "composio execute <slug> --account <alias> -d '{ ... }' Use a named account",
567
- 'composio connections list --toolkit <toolkit> List account selectors',
568
- ],
569
- },
570
- connections: {
571
- usage: 'composio connections <subcommand>',
572
- description: 'View and manage Composio connected accounts.',
573
- seeAlso: ['composio connections list', 'composio connections remove'],
574
- },
575
- 'connections list': {
576
- usage: 'composio connections list [--toolkit <text>]',
577
- description:
578
- 'Print connected toolkit statuses as JSON. Adds aliases when a toolkit has multiple connections.',
579
- options: [{ name: '--toolkit <text>', description: 'Filter to a single toolkit slug' }],
580
- examples: ['composio connections list', 'composio connections list --toolkit gmail'],
581
- seeAlso: [
582
- 'composio link <toolkit> Connect a new account for a toolkit',
583
- 'composio dev connected-accounts list Inspect the full connected-account table',
584
- ],
585
- },
586
- 'connections remove': {
587
- usage: 'composio connections remove <account>',
588
- description:
589
- 'Interactively remove a connected toolkit account. The command prompts for confirmation and defaults to No.',
590
- args: [
591
- {
592
- name: '<account>',
593
- description: 'Toolkit slug, alias, word_id, or connected account ID',
594
- },
595
- ],
596
- examples: [
597
- 'composio connections remove gmail',
598
- 'composio connections remove work',
599
- 'composio connections remove castle',
600
- ],
601
- seeAlso: [
602
- 'composio connections list Find connection selectors',
603
- 'composio link <toolkit> Reconnect a toolkit account',
604
- ],
605
- },
606
- run: {
607
- usage: 'composio run <code> [-- ...args] | run -f <file> [-- ...args]',
608
- description:
609
- 'Run inline TS/JS code or a file with injected Composio helpers that behave like their CLI counterparts.',
610
- args: [{ name: '<code>', description: 'Inline Bun ESNext code to evaluate' }],
611
- options: [
612
- { name: '-f, --file <text>', description: 'Run a TS/JS file instead of inline code' },
613
- { name: '--dry-run', description: 'Preview execute() calls without running them' },
614
- { name: '--debug', description: 'Log helper steps while the script runs' },
615
- {
616
- name: '--logs-off',
617
- description: 'Hide the always-on experimental_subAgent streaming logs',
618
- },
619
- ],
620
- flags: [
621
- { name: '--skip-connection-check', description: 'Skip the connected-account check' },
622
- {
623
- name: '--skip-tool-params-check',
624
- description: 'Skip input validation against cached schema',
625
- },
626
- { name: '--skip-checks', description: 'Skip both checks above' },
627
- ],
628
- injectedHelpers: [
629
- {
630
- name: 'execute(slug, data?)',
631
- description: 'Run a tool — same as `composio execute`, returns parsed JSON',
632
- },
633
- { name: 'search(query, opts?)', description: 'Find tools — same as `composio search`' },
634
- { name: 'proxy(toolkit)', description: 'Returns a fetch() bound to your connected account' },
635
- {
636
- name: 'experimental_subAgent(prompt, opts?)',
637
- description: 'Experimental sub-agent helper (Claude/Codex) with optional structured output',
638
- },
639
- {
640
- name: 'result.prompt()',
641
- description: 'Serialize any helper result into an LLM-friendly string',
642
- },
643
- { name: 'z', description: 'Global from zod for defining structured output schemas' },
644
- ],
645
- examples: [
646
- `composio run '`,
647
- ` // execute(slug, data?) — run a tool, returns parsed JSON`,
648
- ` const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");`,
649
- ` console.log(me);`,
650
- `'`,
651
- '',
652
- `composio run '`,
653
- ` // search(query, opts?) — find tools by use case`,
654
- ` const tools = await search("send email");`,
655
- ` console.log(tools);`,
656
- `'`,
657
- '',
658
- '# Sequential: chain tool outputs across services',
659
- `composio run '`,
660
- ` const issue = await execute("GITHUB_CREATE_ISSUE", { owner: "acme", repo: "app", title: "Deploy v2" });`,
661
- ` await execute("SLACK_SEND_MESSAGE", { channel: "eng", markdown_text: "Created: " + issue.data.html_url });`,
662
- `'`,
663
- '',
664
- '# Parallel: fetch from multiple services at once with Promise.all',
665
- `composio run '`,
666
- ` const [emails, issues, events] = await Promise.all([`,
667
- ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,
668
- ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),`,
669
- ` execute("GOOGLECALENDAR_FIND_EVENT", { calendar_id: "primary" }),`,
670
- ` ]);`,
671
- ` console.log({ emails: emails.data, issues: issues.data, events: events.data });`,
672
- `'`,
673
- '',
674
- '# Bulk: fan out with Promise.all + .map()',
675
- `composio run '`,
676
- ` const issues = [101, 102, 103, 104];`,
677
- ` await Promise.all(issues.map(n =>`,
678
- ` execute("GITHUB_ADD_LABELS_TO_ISSUE", { owner: "acme", repo: "app", issue_number: n, labels: ["priority"] })`,
679
- ` ));`,
680
- `'`,
681
- '',
682
- '# proxy(toolkit) — returns a fetch() bound to your connected account',
683
- `composio run '`,
684
- ` const f = await proxy("gmail");`,
685
- ` console.log(await f("https://gmail.googleapis.com/gmail/v1/users/me/profile"));`,
686
- `'`,
687
- '',
688
- '# experimental_subAgent + z + result.prompt() — structured output from a sub-agent',
689
- `composio run '`,
690
- ` const [emails, issues] = await Promise.all([`,
691
- ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,
692
- ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),`,
693
- ` ]);`,
694
- ` // result.prompt() serializes helper output for LLM consumption`,
695
- ` // z is a global from zod for defining structured output schemas`,
696
- ` const brief = await experimental_subAgent(`,
697
- ` \`Summarize these emails and issues.\\n\\n\${emails.prompt()}\\n\\n\${issues.prompt()}\`,`,
698
- ` { schema: z.object({ summary: z.string(), urgent: z.array(z.string()) }) }`,
699
- ` );`,
700
- ` console.log(brief.structuredOutput);`,
701
- `'`,
702
- '',
703
- '# Run from a file',
704
- 'composio run --file ./workflow.ts -- --repo acme/app',
705
- ],
706
- seeAlso: [
707
- 'composio search "<query>" Discover tool slugs before scripting',
708
- 'composio link <toolkit> Connect accounts before scripting',
709
- 'composio execute <slug> --get-schema Inspect tool inputs before scripting',
710
- 'composio artifacts cwd Print the current session artifact directory',
711
- ],
712
- },
713
- proxy: {
714
- usage:
715
- 'composio proxy <url> --toolkit <text> [--account <selector>] [-X method] [-H header]... [-d data]',
716
- description:
717
- 'curl-like access to any toolkit API through Composio using your connected account. Composio handles authentication — just provide the full URL and toolkit.',
718
- args: [{ name: '<url>', description: 'Full API endpoint URL' }],
719
- options: [
720
- {
721
- name: '-t, --toolkit <text>',
722
- description: 'Toolkit slug whose connected account should be used',
723
- },
724
- {
725
- name: '--account <selector>',
726
- description: 'Select a connected account by alias, word_id, or connected account ID',
727
- },
728
- { name: '-X, --method <text>', description: 'HTTP method (GET, POST, PUT, DELETE, PATCH)' },
729
- {
730
- name: '-H, --header <text>',
731
- description: 'Header in "Name: value" format. Repeat for multiple.',
732
- },
733
- {
734
- name: '-d, --data <text>',
735
- description: 'Request body as raw text, JSON, @file, or - for stdin',
736
- },
737
- ],
738
- flags: [{ name: '--skip-connection-check', description: 'Skip the connected-account check' }],
739
- examples: [
740
- 'composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail --account work',
741
- `composio proxy https://gmail.googleapis.com/gmail/v1/users/me/drafts --toolkit gmail \\`,
742
- ` -X POST -H 'content-type: application/json' -d '{"message":{"raw":"..."}}'`,
743
- ],
744
- seeAlso: [
745
- 'composio link <toolkit> Connect an account first',
746
- `composio run 'const f = await proxy("gmail"); ...' Use proxy in a script`,
747
- ],
748
- },
749
-
750
- // ── Account commands ──────────────────────────────────────────────────
751
-
752
- agent: {
753
- usage: 'composio agent <subcommand>',
754
- description: 'Manage Composio agent identity, inbox, and handoff.',
755
- seeAlso: [
756
- 'composio agent signup',
757
- 'composio agent login',
758
- 'composio agent whoami',
759
- 'composio agent inbox',
760
- 'composio agent claim',
761
- ],
762
- },
763
- 'agent signup': {
764
- usage: 'composio agent signup [-f, --force] [--no-wait] [--no-login]',
765
- description: 'Sign up and optionally log in as a Composio agent.',
766
- options: [
767
- {
768
- name: '-f, --force',
769
- description: 'Create a new agent identity even if ~/.composio/agent.json already exists',
770
- },
771
- {
772
- name: '--no-wait',
773
- description: 'Start agent signup and exit without waiting for credentials',
774
- },
775
- {
776
- name: '--no-login',
777
- description: 'Create or verify the agent identity without logging the CLI in',
778
- },
779
- ],
780
- },
781
- 'agent login': {
782
- usage: 'composio agent login <composio_agent_key>',
783
- description: 'Log in with an existing Composio agent key.',
784
- args: [
785
- {
786
- name: '<composio_agent_key>',
787
- description: 'Composio agent key for an existing agent identity',
788
- },
789
- ],
790
- },
791
- 'agent whoami': {
792
- usage: 'composio agent whoami',
793
- description: 'Show the stored Composio agent identity.',
794
- },
795
- 'agent inbox': {
796
- usage: 'composio agent inbox [--limit integer]',
797
- description: 'Read the stored Composio agent inbox.',
798
- options: [
799
- {
800
- name: '--limit <integer>',
801
- description: 'Maximum number of inbox messages to fetch (default: 50)',
802
- },
803
- ],
804
- },
805
- 'agent claim': {
806
- usage: 'composio agent claim <email>',
807
- description: 'Invite a human admin to claim this agent org.',
808
- args: [
809
- {
810
- name: '<email>',
811
- description: 'Human email address to invite as an admin for this agent org',
812
- },
813
- ],
814
- },
815
- signup: {
816
- usage: 'composio signup [-f, --force] [--no-wait] [--no-login]',
817
- description: 'Sign up and optionally log in as a Composio agent.',
818
- options: [
819
- {
820
- name: '-f, --force',
821
- description: 'Create a new agent identity even if ~/.composio/agent.json already exists',
822
- },
823
- {
824
- name: '--no-wait',
825
- description: 'Start agent signup and exit without waiting for credentials',
826
- },
827
- {
828
- name: '--no-login',
829
- description: 'Create or verify the agent identity without logging the CLI in',
830
- },
831
- ],
832
- },
833
- login: {
834
- usage:
835
- 'composio login [--no-browser] [--poll] [--no-wait] [--key text] [--user-api-key text] [--org text] [-y, --yes] [--no-skill-install]',
836
- description:
837
- 'Log in to the Composio CLI session. By default, also installs the composio-cli skill for Claude Code.',
838
- options: [
839
- {
840
- name: '--key <text>',
841
- description: 'Poll and complete login using the session key from composio login',
842
- },
843
- {
844
- name: '--user-api-key <text>',
845
- description: 'Log in directly with a Composio user API key',
846
- },
847
- {
848
- name: '--org <text>',
849
- description: 'Current organization ID or name to store for CLI commands',
850
- },
851
- ],
852
- flags: [
853
- { name: '--no-browser', description: 'Login without browser interaction' },
854
- {
855
- name: '--poll',
856
- description: 'Poll the cached pending login key for up to 10 minutes',
857
- },
858
- { name: '--no-wait', description: 'Print login URL and session info, then exit' },
859
- { name: '-y, --yes', description: 'Skip org picker; use current org' },
860
- {
861
- name: '--no-skill-install',
862
- description: 'Skip installing the composio-cli skill for Claude Code',
863
- },
864
- ],
865
- },
866
- logout: {
867
- usage: 'composio logout',
868
- description: 'Log out from the Composio CLI session.',
869
- },
870
- whoami: {
871
- usage: 'composio whoami',
872
- description: 'Display your account information.',
873
- },
874
- orgs: {
875
- usage: 'composio orgs <subcommand>',
876
- description: 'Manage default global organization/project context.',
877
- seeAlso: ['composio orgs list', 'composio orgs switch'],
878
- },
879
- 'orgs list': {
880
- usage: 'composio orgs list [--limit integer]',
881
- description: 'List organizations and show current global selection.',
882
- options: [
883
- {
884
- name: '--limit <integer>',
885
- description: 'Max organizations to fetch from API (default: 50)',
886
- },
887
- ],
888
- },
889
- 'orgs switch': {
890
- usage: 'composio orgs switch [--org-id text] [--limit integer]',
891
- description: 'Switch current organization context.',
892
- options: [
893
- { name: '--org-id <text>', description: 'Organization ID to use as global default' },
894
- {
895
- name: '--limit <integer>',
896
- description: 'Max orgs to fetch from API (default: 50)',
897
- },
898
- ],
899
- },
900
- setup: {
901
- usage: 'composio setup [--target auto|claude|codex|all] [--uninstall] [--yes] [--if-present]',
902
- description: 'Install or uninstall plugins for supported agent hosts.',
903
- examples: [
904
- 'composio setup',
905
- 'composio setup --target auto --yes',
906
- 'composio setup --uninstall --target auto --yes',
907
- 'composio setup --target all',
908
- ],
909
- options: [
910
- { name: '--target <target>', description: 'auto, claude, codex, or all' },
911
- { name: '-y, --yes', description: 'Accept setup changes without prompting' },
912
- {
913
- name: '--uninstall',
914
- description: 'Uninstall Composio plugins instead of installing them',
915
- },
916
- {
917
- name: '--if-present',
918
- description: 'Exit successfully when automatic detection finds no supported host',
919
- },
920
- ],
921
- },
922
- version: {
923
- usage: 'composio version',
924
- description: 'Display the current Composio CLI version.',
925
- },
926
- upgrade: {
927
- usage: 'composio upgrade',
928
- description: 'Upgrade your Composio CLI to the latest available version.',
929
- },
930
- files: {
931
- usage: 'composio files',
932
- description: 'Where the Composio CLI stores data on disk.',
933
- examples: [
934
- '~/.composio/',
935
- ' CLI configuration and cache directory.',
936
- ' user_data.json Your auth state (API key, org, base URL)',
937
- ' toolkits.json Cached toolkit list from the API',
938
- ' tools.json Cached tool definitions',
939
- ' trigger-types.json Cached trigger type definitions',
940
- ' consumer-short-term-cache.json Per-org connected toolkits cache (15-min TTL)',
941
- ' analytics.json Anonymous install ID for telemetry',
942
- '',
943
- ' All caches are safe to delete — they will be re-fetched on next use.',
944
- '',
945
- '$TMPDIR/composio/ (or COMPOSIO_SESSION_DIR / COMPOSIO_CACHE_DIR)',
946
- ' Session artifacts directory. Each CLI session gets a unique subdirectory',
947
- ' scoped to your working directory. Stores session history and files',
948
- ' created during `run` and `execute` (e.g. large tool outputs).',
949
- ' Use `composio artifacts cwd` to print the current session path.',
950
- '',
951
- '.composio/ (per-project, optional)',
952
- ' Per-directory project config. Scoped to the nearest parent that has one.',
953
- ' .env Allows COMPOSIO_ORG_ID and COMPOSIO_PROJECT_ID overrides',
954
- ' project.json Project context (org, project binding)',
955
- '',
956
- 'Environment variables that control paths:',
957
- ' COMPOSIO_SESSION_DIR Override session artifacts root',
958
- ' COMPOSIO_CACHE_DIR Override cache directory (also used for artifacts fallback)',
959
- ' COMPOSIO_CACHE_DIR is useful in sandboxed environments where ~/.composio or',
960
- ' $TMPDIR may not be writable.',
961
- ],
962
- },
963
-
964
- artifacts: {
965
- usage: 'composio artifacts <subcommand>',
966
- description: 'Inspect session artifact directories.',
967
- seeAlso: ['composio artifacts cwd'],
968
- },
969
- 'artifacts cwd': {
970
- usage: 'composio artifacts cwd',
971
- description: 'Print the cwd-scoped session artifact directory.',
972
- },
973
- install: {
974
- usage: 'composio install [--completions] [--shell zsh|bash|fish]',
975
- description:
976
- 'Set up shell integration (PATH and completions). Set COMPOSIO_BIN_DIR to choose the directory added to PATH; it otherwise defaults to ~/.local/bin when that holds this executable, and to the directory of the running binary.',
977
- options: [
978
- { name: '--completions', description: 'Also install shell completions (skipped by default)' },
979
- {
980
- name: '--shell <shell>',
981
- description: 'Override automatic shell detection: zsh, bash, or fish',
982
- },
983
- {
984
- name: '--no-completions',
985
- description: 'Deprecated: shell completions are skipped by default',
986
- },
987
- ],
988
- },
989
-
990
- // ── Tools commands ──────────────────────────────────────────────────────
991
-
992
- tools: {
993
- usage: 'composio tools <command>',
994
- description: 'Browse and inspect tools before executing them.',
995
- examples: ['composio tools list gmail', 'composio tools info GMAIL_SEND_EMAIL'],
996
- seeAlso: [
997
- 'composio search "<query>" Find tools by use case',
998
- "composio execute <slug> -d '{ ... }' Execute a tool directly",
999
- ],
1000
- },
1001
- 'tools list': {
1002
- usage: 'composio tools list <toolkit> [--query text] [--tags text] [--limit integer]',
1003
- description: 'List available tools for a toolkit.',
1004
- args: [{ name: '<toolkit>', description: 'Toolkit slug to list tools for (e.g. "gmail")' }],
1005
- options: [
1006
- { name: '--query <text>', description: 'Text search by name, slug, or description' },
1007
- { name: '--tags <text>', description: 'Filter by tags (e.g. "important")' },
1008
- { name: '--limit <integer>', description: 'Maximum number of results (1-1000)' },
1009
- ],
1010
- },
1011
- 'tools info': {
1012
- usage: 'composio tools info [<slug>]',
1013
- description:
1014
- 'View a brief summary of a tool and show the CLI-facing schema used by `composio execute --get-schema`.',
1015
- args: [{ name: '<slug>', description: 'Tool slug (e.g. "GMAIL_SEND_EMAIL")' }],
1016
- },
1017
- triggers: {
1018
- usage: 'composio triggers <subcommand>',
1019
- description: 'Inspect and subscribe to trigger events.',
1020
- seeAlso: ['composio triggers list', 'composio triggers info'],
1021
- },
1022
- 'triggers list': {
1023
- usage: 'composio triggers list <toolkit> [--limit integer]',
1024
- description: 'List available trigger types for a toolkit.',
1025
- args: [
1026
- { name: '<toolkit>', description: 'Toolkit slug to list trigger types for (e.g. "gmail")' },
1027
- ],
1028
- options: [{ name: '--limit <integer>', description: 'Number of results' }],
1029
- },
1030
- 'triggers info': {
1031
- usage: 'composio triggers info [<slug>]',
1032
- description: 'View details of a specific trigger type.',
1033
- args: [{ name: '<slug>', description: 'Trigger slug' }],
1034
- },
1035
-
1036
- // ── Generate commands ─────────────────────────────────────────────────
1037
-
1038
- generate: {
1039
- usage: 'composio generate [--output-dir dir] [--type-tools] --toolkits text...',
1040
- description:
1041
- 'Generate type stubs for toolkits, tools, and triggers, auto-detecting project language (TypeScript | Python).',
1042
- options: [
1043
- { name: '-o, --output-dir <dir>', description: 'Output directory for type stubs' },
1044
- {
1045
- name: '--toolkits <text>... (required)',
1046
- description: 'Toolkits to generate for (repeat for multiple)',
1047
- },
1048
- ],
1049
- flags: [
1050
- {
1051
- name: '--type-tools',
1052
- description: 'Generate typed input/output schemas for each tool (slower)',
1053
- },
1054
- ],
1055
- },
1056
- 'generate ts': {
1057
- usage:
1058
- 'composio generate ts [--output-dir dir] [--compact] [--transpiled] [--type-tools] --toolkits text...',
1059
- description: 'Generate TypeScript type stubs for toolkits, tools, and triggers.',
1060
- options: [
1061
- {
1062
- name: '-o, --output-dir <dir>',
1063
- description: 'Output directory for generated TypeScript stubs',
1064
- },
1065
- {
1066
- name: '--toolkits <text>... (required)',
1067
- description: 'Toolkits to generate for (repeat for multiple)',
1068
- },
1069
- ],
1070
- flags: [
1071
- { name: '--compact', description: 'Emit a single TypeScript file' },
1072
- {
1073
- name: '--transpiled',
1074
- description: 'Emit transpiled JavaScript alongside TypeScript files',
1075
- },
1076
- {
1077
- name: '--type-tools',
1078
- description: 'Generate typed input/output schemas for each tool (slower)',
1079
- },
1080
- ],
1081
- },
1082
- 'generate py': {
1083
- usage: 'composio generate py [--output-dir dir] --toolkits text...',
1084
- description: 'Generate Python type stubs for toolkits, tools, and triggers.',
1085
- options: [
1086
- {
1087
- name: '-o, --output-dir <dir>',
1088
- description: 'Output directory for generated Python stubs',
1089
- },
1090
- {
1091
- name: '--toolkits <text>... (required)',
1092
- description: 'Toolkits to generate for (repeat for multiple)',
1093
- },
1094
- ],
1095
- },
1096
-
1097
- // ── Dev commands ──────────────────────────────────────────────────────
1098
-
1099
- 'dev init': {
1100
- usage: 'composio dev init [--no-browser] [-y, --yes]',
1101
- description: 'Initialize this directory with a developer project.',
1102
- flags: [
1103
- { name: '--no-browser', description: 'Login without browser interaction' },
1104
- { name: '-y, --yes', description: 'Auto-select the current org project' },
1105
- ],
1106
- },
1107
- 'dev playground-execute': {
1108
- usage:
1109
- 'composio dev playground-execute <slug> [-d, --data text] [--file path] [--user-id text] [--project-name text] [--dry-run] [--get-schema]',
1110
- description:
1111
- 'Test tool executions against playground users using your developer project auth configs.',
1112
- args: [{ name: '<slug>', description: 'Tool slug (e.g. "GITHUB_CREATE_ISSUE")' }],
1113
- options: [
1114
- { name: '-d, --data <text>', description: 'JSON arguments, @file, or - for stdin' },
1115
- {
1116
- name: '--file <path>',
1117
- description: 'Inject a local file path into the single file_uploadable input',
1118
- },
1119
- { name: '--user-id <text>', description: 'Developer-project user ID override' },
1120
- { name: '--project-name <text>', description: 'Developer project name override' },
1121
- {
1122
- name: '--get-schema',
1123
- description: 'Fetch and print the CLI-facing input schema without executing',
1124
- },
1125
- { name: '--dry-run', description: 'Validate and preview without executing' },
1126
- ],
1127
- flags: [
1128
- { name: '--skip-connection-check', description: 'Skip the connected-account check' },
1129
- {
1130
- name: '--skip-tool-params-check',
1131
- description: 'Skip input validation against cached schema',
1132
- },
1133
- { name: '--skip-checks', description: 'Skip both checks above' },
1134
- ],
1135
- },
1136
- 'dev listen': {
1137
- usage:
1138
- 'composio dev listen [--toolkits text] [--trigger-slug text] [--json] [--table] [--max-events int] [--forward url] [--out file]',
1139
- description:
1140
- 'Listen to realtime trigger events for your developer project and optionally forward them.',
1141
- options: [
1142
- { name: '--toolkits <text>', description: 'Filter by toolkit slugs, comma-separated' },
1143
- { name: '--trigger-id <text>', description: 'Filter by trigger id' },
1144
- { name: '--connected-account-id <text>', description: 'Filter by connected account id' },
1145
- { name: '--trigger-slug <text>', description: 'Filter by trigger slug, comma-separated' },
1146
- { name: '--user-id <text>', description: 'Filter by user id' },
1147
- { name: '--max-events <int>', description: 'Stop after receiving N matching events' },
1148
- { name: '--forward <url>', description: 'Forward each event to the given URL' },
1149
- { name: '--out <file>', description: 'Append each event to this file' },
1150
- ],
1151
- flags: [
1152
- { name: '--json', description: 'Show raw event payload as JSON' },
1153
- { name: '--table', description: 'Show compact table rows' },
1154
- ],
1155
- },
1156
- // ── Dev admin commands ─────────────────────────────────────────────────
1157
-
1158
- 'dev toolkits list': {
1159
- usage:
1160
- 'composio dev toolkits list [--query text] [--limit integer] [--connected] [--user-id text]',
1161
- description: 'List available toolkits with connection status.',
1162
- options: [
1163
- { name: '--query <text>', description: 'Text search by name, slug, or description' },
1164
- { name: '--limit <integer>', description: 'Maximum number of results (1-1000)' },
1165
- { name: '--user-id <text>', description: 'User ID override' },
1166
- ],
1167
- flags: [{ name: '--connected', description: 'Show only connected toolkits' }],
1168
- },
1169
- 'dev toolkits info': {
1170
- usage: 'composio dev toolkits info [--user-id text] [-a, --all] [<slug>]',
1171
- description: 'View details of a specific toolkit.',
1172
- args: [{ name: '<slug>', description: 'Toolkit slug (e.g. "github")' }],
1173
- flags: [{ name: '-a, --all', description: 'Show all details' }],
1174
- },
1175
- 'dev toolkits search': {
1176
- usage: 'composio dev toolkits search <query> [--limit integer]',
1177
- description: 'Search toolkits by use case.',
1178
- args: [{ name: '<query>', description: 'Search query' }],
1179
- options: [{ name: '--limit <integer>', description: 'Number of results' }],
1180
- },
1181
- 'dev toolkits version': {
1182
- usage: 'composio dev toolkits version <slug>',
1183
- description: 'Show latest and recent versions for a toolkit.',
1184
- args: [{ name: '<slug>', description: 'Toolkit slug' }],
1185
- },
1186
- 'dev auth-configs list': {
1187
- usage: 'composio dev auth-configs list [--toolkits text] [--query text] [--limit integer]',
1188
- description: 'List auth configs.',
1189
- options: [
1190
- { name: '--toolkits <text>', description: 'Filter by toolkit slugs' },
1191
- { name: '--query <text>', description: 'Search text' },
1192
- { name: '--limit <integer>', description: 'Number of results' },
1193
- ],
1194
- },
1195
- 'dev auth-configs info': {
1196
- usage: 'composio dev auth-configs info [<id>]',
1197
- description: 'View details of a specific auth config.',
1198
- args: [{ name: '<id>', description: 'Auth config ID' }],
1199
- },
1200
- 'dev auth-configs create': {
1201
- usage:
1202
- 'composio dev auth-configs create --toolkit text [--auth-scheme text] [--scopes text] [--custom-credentials text] [<name>]',
1203
- description: 'Create a new auth config.',
1204
- args: [{ name: '<name>', description: 'Auth config name' }],
1205
- options: [
1206
- { name: '--toolkit <text>', description: 'Toolkit slug' },
1207
- { name: '--auth-scheme <text>', description: 'Authentication scheme' },
1208
- { name: '--scopes <text>', description: 'Comma-separated scopes' },
1209
- { name: '--custom-credentials <text>', description: 'Custom credentials JSON' },
1210
- ],
1211
- },
1212
- 'dev connected-accounts list': {
1213
- usage:
1214
- 'composio dev connected-accounts list [--toolkits text] [--user-id text] [--status text] [--limit integer]',
1215
- description: 'List connected accounts.',
1216
- options: [
1217
- { name: '--toolkits <text>', description: 'Filter by toolkit slugs' },
1218
- { name: '--user-id <text>', description: 'Filter by user id' },
1219
- { name: '--status <text>', description: 'Filter by status (ACTIVE, FAILED, EXPIRED, etc.)' },
1220
- { name: '--limit <integer>', description: 'Number of results' },
1221
- ],
1222
- },
1223
- 'dev connected-accounts info': {
1224
- usage: 'composio dev connected-accounts info [<id>]',
1225
- description: 'View details of a specific connected account.',
1226
- args: [{ name: '<id>', description: 'Connected account ID' }],
1227
- },
1228
- 'dev connected-accounts whoami': {
1229
- usage: 'composio dev connected-accounts whoami [<id>]',
1230
- description: 'Show the external account profile for a connected account.',
1231
- args: [{ name: '<id>', description: 'Connected account ID' }],
1232
- },
1233
- 'dev triggers list': {
1234
- usage: 'composio dev triggers list <toolkit> [--limit integer]',
1235
- description: 'List available trigger types for a toolkit.',
1236
- args: [
1237
- { name: '<toolkit>', description: 'Toolkit slug to list trigger types for (e.g. "gmail")' },
1238
- ],
1239
- options: [{ name: '--limit <integer>', description: 'Number of results' }],
1240
- },
1241
- 'dev triggers info': {
1242
- usage: 'composio dev triggers info [<slug>]',
1243
- description: 'View details of a specific trigger type.',
1244
- args: [{ name: '<slug>', description: 'Trigger slug' }],
1245
- },
1246
- 'dev triggers status': {
1247
- usage:
1248
- 'composio dev triggers status [--user-ids text] [--toolkits text] [--trigger-ids text] [--show-disabled] [--limit integer]',
1249
- description: 'Show active triggers with optional filters.',
1250
- options: [
1251
- { name: '--user-ids <text>', description: 'Filter by user IDs' },
1252
- { name: '--connected-account-ids <text>', description: 'Filter by connected account IDs' },
1253
- { name: '--toolkits <text>', description: 'Filter by toolkit slugs' },
1254
- { name: '--trigger-ids <text>', description: 'Filter by trigger IDs' },
1255
- { name: '--trigger-names <text>', description: 'Filter by trigger names' },
1256
- { name: '--limit <integer>', description: 'Number of results' },
1257
- ],
1258
- flags: [{ name: '--show-disabled', description: 'Include disabled triggers' }],
1259
- },
1260
- 'dev triggers create': {
1261
- usage:
1262
- 'composio dev triggers create [--connected-account-id text] [--trigger-config text] [<trigger-name>]',
1263
- description: 'Create a new trigger instance.',
1264
- args: [{ name: '<trigger-name>', description: 'Trigger type slug' }],
1265
- options: [
1266
- { name: '--connected-account-id <text>', description: 'Connected account to use' },
1267
- { name: '--trigger-config <text>', description: 'Trigger configuration JSON' },
1268
- ],
1269
- },
1270
- 'dev triggers enable': {
1271
- usage: 'composio dev triggers enable [<id>]',
1272
- description: 'Enable a trigger instance.',
1273
- args: [{ name: '<id>', description: 'Trigger instance ID' }],
1274
- },
1275
- 'dev triggers disable': {
1276
- usage: 'composio dev triggers disable [<id>]',
1277
- description: 'Disable a trigger instance.',
1278
- args: [{ name: '<id>', description: 'Trigger instance ID' }],
1279
- },
1280
- 'dev projects list': {
1281
- usage: 'composio dev projects list [--org-id text] [--limit integer]',
1282
- description: 'List developer projects for the current organization.',
1283
- options: [
1284
- { name: '--org-id <text>', description: 'Organization ID override' },
1285
- { name: '--limit <integer>', description: 'Number of results' },
1286
- ],
1287
- },
1288
-
1289
- // ── Dev logs commands ─────────────────────────────────────────────────
1290
-
1291
- 'dev logs tools': {
1292
- usage:
1293
- 'composio dev logs tools [--toolkit text] [--tool text] [--status text] [--limit integer] [<log_id>]',
1294
- description: 'List tool execution logs, or pass a log_id to fetch a specific log.',
1295
- args: [{ name: '<log_id>', description: 'Specific log ID to fetch' }],
1296
- options: [
1297
- { name: '--toolkit <text>', description: 'Filter by toolkit slug' },
1298
- { name: '--tool <text>', description: 'Filter by tool slug' },
1299
- { name: '--status <text>', description: 'Filter by status' },
1300
- { name: '--user-id <text>', description: 'Filter by user id' },
1301
- { name: '--limit <integer>', description: 'Number of results' },
1302
- { name: '--from <integer>', description: 'Start timestamp (epoch ms)' },
1303
- { name: '--to <integer>', description: 'End timestamp (epoch ms)' },
1304
- ],
1305
- flags: [{ name: '--case-sensitive', description: 'Case-sensitive filtering' }],
1306
- },
1307
- config: {
1308
- usage: 'composio config <subcommand>',
1309
- description: 'View and manage CLI configuration.',
1310
- seeAlso: ['composio config experimental'],
1311
- },
1312
- 'config experimental': {
1313
- usage: 'composio config experimental [<feature>] [on|off]',
1314
- description: 'View or toggle experimental feature flags.',
1315
- args: [
1316
- { name: '<feature>', description: 'Feature name (e.g., listen)' },
1317
- { name: 'on|off', description: 'Enable or disable the feature' },
1318
- ],
1319
- examples: [
1320
- 'composio config experimental # List all features',
1321
- 'composio config experimental listen # Show current state',
1322
- 'composio config experimental listen on # Enable listen',
1323
- ],
1324
- },
1325
- 'dev logs triggers': {
1326
- usage:
1327
- 'composio dev logs triggers [--trigger text] [--trigger-id text] [--limit integer] [--time 5m|30m|6h|1d|1w] [<log_id>]',
1328
- description: 'List trigger logs.',
1329
- args: [{ name: '<log_id>', description: 'Specific log ID to fetch' }],
1330
- options: [
1331
- { name: '--trigger <text>', description: 'Filter by trigger slug' },
1332
- { name: '--trigger-id <text>', description: 'Filter by trigger id' },
1333
- { name: '--user-id <text>', description: 'Filter by user id' },
1334
- { name: '--connected-account-id <text>', description: 'Filter by connected account id' },
1335
- { name: '--limit <integer>', description: 'Number of results' },
1336
- { name: '--time <period>', description: 'Time window (5m, 30m, 6h, 1d, 1w, 1month, 1y)' },
1337
- { name: '--search <text>', description: 'Search in log content' },
1338
- ],
1339
- flags: [{ name: '--include-payload', description: 'Include full event payload' }],
1340
- },
1341
-};
1342
-
1343
-const getVisibleSubcommandHelp = (
1344
- cmd: string,
1345
- visibility: CommandVisibility,
1346
- helpLevel: HelpLevel = 'default'
1347
-): Option.Option<SubcommandHelp> => {
1348
- if (cmd === 'dev') {
1349
- return Option.some({
1350
- usage: 'composio dev [--mode on|off]',
1351
- description: 'Developer mode and developer-scoped workflows.',
1352
- });
1353
- }
1354
-
1355
- if (cmd.startsWith('dev ') && !visibility.isDevModeEnabled) {
1356
- return Option.none();
1357
- }
1358
-
1359
- const entry = SUBCOMMAND_HELP[cmd];
1360
- if (!entry) {
1361
- return Option.none();
1362
- }
1363
-
1364
- if (!('value' in entry)) {
1365
- return Option.some(entry);
1366
- }
1367
-
1368
- return isTaggedValueVisible(entry, visibility) &&
1369
- isTaggedValueVisibleForHelpLevel(entry, helpLevel)
1370
- ? Option.some(entry.value)
1371
- : Option.none();
20
+ ...formatter,
21
+ formatVersion: (_name: string, version: string) => version,
22
+ formatHelpDoc: (doc: Parameters<typeof formatter.formatHelpDoc>[0]) => {
23
+ const text = formatter.formatHelpDoc(doc);
24
+ return Context.get(doc.annotations, RootHelpMarker)
25
+ ? `${text}\n\nUse \`composio <command> --help\` for command details.\nDocumentation: https://docs.composio.dev`
26
+ : text;
27
+ },
28
+ } satisfies CliOutput.Formatter;
29
};
30
1374
-function renderSubcommandHelp(cmd: SubcommandHelp, helpLevel: HelpLevel): string {
1375
- const lines: string[] = [
1376
- '',
1377
- bold('USAGE'),
1378
- ` ${cmd.usage}`,
1379
- '',
1380
- bold('DESCRIPTION'),
1381
- ` ${cmd.description}`,
1382
- '',
1383
- ];
1384
-
1385
- if (cmd.args && cmd.args.length > 0) {
1386
- lines.push(bold('ARGUMENTS'));
1387
- for (const arg of cmd.args) {
1388
- lines.push(` ${dim(arg.name.padEnd(24))}${arg.description}`);
1389
- }
1390
- lines.push('');
1391
- }
1392
-
1393
- if (cmd.options && cmd.options.length > 0) {
1394
- lines.push(bold('OPTIONS'));
1395
- for (const opt of cmd.options) {
1396
- lines.push(` ${dim(opt.name.padEnd(24))}${opt.description}`);
1397
- }
1398
- lines.push('');
1399
- }
1400
-
1401
- if (cmd.flags && cmd.flags.length > 0) {
1402
- lines.push(bold('FLAGS'));
1403
- for (const flag of cmd.flags) {
1404
- lines.push(` ${dim(flag.name.padEnd(28))}${flag.description}`);
1405
- }
1406
- lines.push('');
1407
- }
1408
-
1409
- if (helpLevel !== 'simple' && cmd.injectedHelpers && cmd.injectedHelpers.length > 0) {
1410
- lines.push(bold('INJECTED HELPERS'));
1411
- const maxLen = Math.max(...cmd.injectedHelpers.map(h => h.name.length));
1412
- for (const helper of cmd.injectedHelpers) {
1413
- lines.push(` ${dim(helper.name.padEnd(maxLen + 2))}${helper.description}`);
1414
- }
1415
- lines.push('');
1416
- }
1417
-
1418
- if (helpLevel !== 'simple' && cmd.examples && cmd.examples.length > 0) {
1419
- lines.push(bold('EXAMPLES'));
1420
- for (const ex of cmd.examples) {
1421
- lines.push(` ${ex}`);
1422
- }
1423
- lines.push('');
1424
- }
1425
-
1426
- if (helpLevel !== 'simple' && cmd.seeAlso && cmd.seeAlso.length > 0) {
1427
- lines.push(bold('SEE ALSO'));
1428
- for (const sa of cmd.seeAlso) {
1429
- lines.push(` ${sa}`);
1430
- }
1431
- lines.push('');
1432
- }
1433
-
1434
- return lines.join('\n');
1435
-}
1436
-
1437
-/**
1438
- * Check if argv is `composio <subcommand> --help` for a command we have custom help for.
1439
- * Returns the command name if matched, undefined otherwise.
1440
- */
1441
-export function matchSubcommandHelp(
1442
- argv: ReadonlyArray<string>,
1443
- visibility: CommandVisibility
1444
-): string | undefined {
1445
- const { args } = splitTrailingHelpLevel(argv.slice(2));
1446
- if (args.length < 2) return undefined;
1447
- const last = args[args.length - 1];
1448
- if (last !== '--help' && last !== '-h') return undefined;
1449
-
1450
- const cmdParts = args.slice(0, -1);
1451
- // Try longest match first: "dev toolkits list" → "dev toolkits" → "dev"
1452
- for (let len = cmdParts.length; len > 0; len--) {
1453
- const key = cmdParts.slice(0, len).join(' ');
1454
- if (Option.isSome(getVisibleSubcommandHelp(key, visibility))) return key;
1455
- }
1456
- return undefined;
1457
-}
1458
-
1459
-export function printSubcommandHelp(
1460
- cmd: string,
1461
- visibility: CommandVisibility,
1462
- helpLevel: HelpLevel = 'default'
1463
-): Effect.Effect<void, never, TerminalUI> {
1464
- if (cmd === 'dev') {
1465
- return Effect.flatMap(TerminalUI, ui =>
1466
- ui.output(renderDevHelp(visibility, helpLevel), { force: true })
31
+export const showCommandHelp = (parts: ReadonlyArray<string> = []) =>
32
+ Effect.gen(function* () {
33
+ const { command, version } = yield* RootHelpContext;
34
+ const { builtIns } = yield* CliConfig.CliConfig;
35
+ const console = yield* Console.Console;
36
+ yield* GlobalFlag.Help.run(true, {
37
+ command,
38
+ commandPath: [command.name, ...parts],
39
+ version,
40
+ builtIns,
41
+ }).pipe(
42
+ Effect.provideService(Console.Console, {
43
+ ...console,
44
+ log: (...args) => console.info(...args),
45
+ })
46
);
1468
- }
1469
- const help = getVisibleSubcommandHelp(cmd, visibility, helpLevel);
1470
- if (Option.isNone(help)) {
1471
- return Effect.flatMap(TerminalUI, ui => ui.output(`Unknown command: ${cmd}`, { force: true }));
1472
- }
1473
- return Effect.flatMap(TerminalUI, ui =>
1474
- ui.output(renderSubcommandHelp(help.value, helpLevel), { force: true })
1475
- );
1476
-}
1477
-
1478
-/**
1479
- * Match the command name from argv without requiring --help at the end.
1480
- * Used to print contextual help alongside error messages.
1481
- */
1482
-export function matchCommandFromArgv(
1483
- argv: ReadonlyArray<string>,
1484
- visibility: CommandVisibility
1485
-): string | undefined {
1486
- const { args: helpArgs } = splitTrailingHelpLevel(argv.slice(2));
1487
- const args = helpArgs.filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));
1488
- // Try longest match first: "dev toolkits list" → "dev toolkits" → "dev"
1489
- for (let len = Math.min(args.length, 3); len > 0; len--) {
1490
- const key = args.slice(0, len).join(' ');
1491
- if (Option.isSome(getVisibleSubcommandHelp(key, visibility))) return key;
1492
- }
1493
- return undefined;
1494
-}
1495
-
1496
-/**
1497
- * Get rendered help text for a command, or undefined if not found.
1498
- */
1499
-export function getCommandHelpText(cmd: string, visibility: CommandVisibility): string | undefined {
1500
- if (cmd === 'dev') return renderDevHelp(visibility);
1501
- return Option.match(getVisibleSubcommandHelp(cmd, visibility), {
1502
- onNone: () => undefined,
1503
- onSome: help => renderSubcommandHelp(help, 'default'),
47
});
1505
-}
1506
-
1507
-// ── Main help output ───────────────────────────────────────────────────
48
1509
-/**
1510
- * Prints the root-level help output.
1511
- * Core workflow commands are shown first with full usage/options.
1512
- * Housekeeping and developer commands are shown compactly at the bottom.
1513
- */
1514
-export function printRootHelp(
1515
- visibility: CommandVisibility,
1516
- helpLevel: HelpLevel = 'default'
1517
-): Effect.Effect<void, never, TerminalUI> {
1518
- const name = 'composio';
1519
- const developerCommands: ReadonlyArray<CompactCommand> = [
1520
- {
1521
- name: 'dev',
1522
- description: visibility.isDevModeEnabled
1523
- ? 'Developer workflows and management: init, logs, projects, toolkits, accounts, and triggers.'
1524
- : 'Developer mode toggle. Use `composio dev --mode on` to enable developer workflows.',
1525
- },
1526
- GENERATE_COMMAND.value,
1527
- ];
1528
- const coreCommands = visibleValues(CORE_COMMANDS, visibility, helpLevel);
1529
- const otherCommands = visibleValues(OTHER_COMMANDS, visibility, helpLevel);
1530
- const accountCommands = visibleValues(ACCOUNT_COMMANDS, visibility, helpLevel);
1531
- const fullCommands = visibleValues(FULL_COMMANDS, visibility, helpLevel);
1532
- const exampleLines =
1533
- helpLevel === 'simple'
1534
- ? [
1535
- ` ${dim('# Find tools')}`,
1536
- ` ${name} search "send an email"`,
1537
- '',
1538
- ` ${dim('# Execute a tool')}`,
1539
- ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
1540
- '',
1541
- ` ${dim('# Connect an account when execute tells you to')}`,
1542
- ` ${name} link github`,
1543
- '',
1544
- ]
1545
- : [
1546
- ` ${dim('# Find tools — supports multiple queries at once')}`,
1547
- ` ${name} search "send an email" "create github issue"`,
1548
- ` ${name} search "list calendar events" --toolkits google_calendar --limit 5`,
1549
- '',
1550
- ` ${dim('# Connect your account for a toolkit')}`,
1551
- ` ${name} link github`,
1552
- '',
1553
- ` ${dim('# Execute a tool')}`,
1554
- ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
1555
- '',
1556
- ` ${dim('# Execute multiple tools in parallel')}`,
1557
- ` ${name} execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \\`,
1558
- ` SLACK_SEND_MESSAGE -d '{ channel: "general", markdown_text: "Hello" }'`,
1559
- '',
1560
- ` ${dim('# Call an API directly through proxy')}`,
1561
- ` ${name} proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail`,
1562
- '',
1563
- ` ${dim('# Run a script with injected helpers')}`,
1564
- ` ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,
1565
- '',
1566
- ` ${dim('# Manually install the composio skill when auto-install fails')}`,
1567
- ` ${name} --install-skill claude`,
1568
- ` ${name} --install-skill composio-cli codex`,
1569
- '',
1570
- ` ${dim('# Run a multi-step script with Promise.all')}`,
1571
- ` ${name} run '`,
1572
- ` const [emails, issues] = await Promise.all([`,
1573
- ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,
1574
- ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),`,
1575
- ` ]);`,
1576
- ` const brief = await experimental_subAgent(\`Summarize:\\n\${emails.prompt()}\\n\${issues.prompt()}\`);`,
1577
- ` console.log(brief);`,
1578
- ` '`,
1579
- '',
1580
- ];
1581
-
1582
- const lines: string[] = [
1583
- '',
1584
- `Connect AI agents to external tools. ${bold('search')}, ${bold('execute')}, ${bold('link')}, ${bold('proxy')}, and ${bold('run')} let you`,
1585
- 'take actions across 1000+ apps directly; if you can describe it, it is probably supported.',
1586
- `Try ${bold('execute')} sooner than you'd think — it validates inputs, checks connections, and tells`,
1587
- 'you what to fix.',
1588
- '',
1589
- visibility.isDevModeEnabled
1590
- ? `Use ${bold('dev')} when you are building an agent with Composio's SDK and want scaffolding,`
1591
- : `Use ${bold('dev')} to control access to developer-only workflows.`,
1592
- visibility.isDevModeEnabled
1593
- ? 'playground execution, logs, and developer-scoped management commands.'
1594
- : 'Developer mode is currently off.',
1595
- '',
1596
- bold('USAGE'),
1597
- ` ${name} <command> [options]`,
1598
- ` ${name} --help [simple|default|full]`,
1599
- '',
1600
- bold('MODE'),
1601
- ` ${helpLevel} help`,
1602
- '',
1603
- bold('CORE COMMANDS'),
1604
- ...renderDetailedCommands(name, coreCommands),
1605
- gray(' Typical flow: search → execute (link and tools when needed)'),
1606
- '',
1607
- ...(otherCommands.length > 0
1608
- ? [bold('TOOLS'), ...renderCompactCommands(otherCommands), '']
1609
- : []),
1610
- '',
1611
- bold('EXAMPLES'),
1612
- ...exampleLines,
1613
- ...(developerCommands.length > 0
1614
- ? [bold('DEVELOPER COMMANDS'), ...renderCompactCommands(developerCommands), '']
1615
- : []),
1616
- ...(accountCommands.length > 0
1617
- ? [bold('ACCOUNT'), ...renderCompactCommands(accountCommands), '']
1618
- : []),
1619
- ...(fullCommands.length > 0
1620
- ? [bold('MORE COMMANDS'), ...renderCompactCommands(fullCommands), '']
1621
- : []),
1622
- bold('FILES') + dim(' (composio files --help)'),
1623
- ` ${bold('~/.composio/')}`,
1624
- ` CLI configuration and cache directory. Contains your auth state`,
1625
- ` (user_data.json), runtime settings (config.json), cached tool definitions`,
1626
- ` (tools.json, toolkits.json),`,
1627
- ` trigger types, and per-org consumer caches. These caches speed up`,
1628
- ` repeated commands — safe to delete, they will be re-fetched on next use.`,
1629
- '',
1630
- ` ${bold('/tmp/composio/')}`,
1631
- ` Session artifacts directory. Each CLI session gets a unique subdirectory`,
1632
- ` scoped to your working directory. Stores session history and files`,
1633
- ` created during ${bold('run')} and ${bold('execute')} commands (e.g. downloaded attachments,`,
1634
- ` generated outputs). Use \`${name} artifacts cwd\` to print the path for`,
1635
- ` the current directory's session.`,
1636
- '',
1637
- bold('FLAGS'),
1638
- ' -h, --help [mode] Show help for command (simple, default, full)',
1639
- ` --version Show ${name} version`,
1640
- ' --install-skill [skill-name] <claude|codex|openclaw>',
1641
- ' Manually install the composio skill for a supported agent',
1642
- '',
1643
- bold('LEARN MORE'),
1644
- ` Use \`${name} <command> --help\` for more information about a command.`,
1645
- ` Documentation: https://docs.composio.dev`,
1646
- '',
1647
- ];
49
+/** Derive help aliases from the real command tree, letting Effect validate names and suggest fixes. */
50
+export const buildHelpCommand = (commands: ReadonlyArray<Command.Command.Any>) => {
51
+ const makeHelpCommand = (
52
+ name: string,
53
+ path: ReadonlyArray<string>,
54
+ subcommands: ReadonlyArray<Command.Command.Any>,
55
+ description: string | undefined
56
+ ): Command.Command<string, Record<never, never>, Record<never, never>, never, RootHelpContext> =>
57
+ Command.make(name, {}, () => showCommandHelp(path)).pipe(
58
+ Command.withDescription(description ?? 'Show command help.'),
59
+ Command.withSubcommands(
60
+ subcommands.map(child => {
61
+ const help = makeHelpCommand(
62
+ child.name,
63
+ [...path, child.name],
64
+ child.subcommands.flatMap(group => group.commands),
65
+ child.description
66
+ );
67
+ const aliased = child.alias ? help.pipe(Command.withAlias(child.alias)) : help;
68
+ return child.unlisted ? aliased.pipe(Command.unlisted) : aliased;
69
+ })
70
+ )
71
+ );
72
+ return makeHelpCommand('help', [], commands, 'Show help for a command.');
73
+};
74
1649
- return Effect.flatMap(TerminalUI, ui => ui.output(lines.join('\n'), { force: true }));
1650
-}
75
+/** A help flag on the help alias describes the requested command. */
76
+export const Help = GlobalFlag.Action({
77
+ flag: GlobalFlag.Help.flag,
78
+ run: (value, context) =>
79
+ GlobalFlag.Help.run(value, {
80
+ ...context,
81
+ commandPath:
82
+ context.commandPath[1] === 'help'
83
+ ? [context.commandPath[0], ...context.commandPath.slice(2)]
84
+ : context.commandPath,
85
+ }),
86
+});