4
import {
5
type CommandVisibility,
6
experimental,
7
+ type HelpLevel,
8
+ full,
9
+ isTaggedValueVisible,
10
+ isTaggedValueVisibleForHelpLevel,
11
+ simple,
12
tagged,
13
visibleValues,
14
type TaggedValue,
29
// ── Core workflow commands ──────────────────────────────────────────────
30
31
const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
27
- tagged({
32
+ simple({
33
name: 'search',
34
description: 'Find tools by use case across all toolkits/apps.',
35
usage: 'search <query...> [--toolkits text] [--limit integer] [--human]',
43
{ name: '--human', description: 'Show formatted output instead of default JSON' },
44
],
45
}),
41
- tagged({
46
+ simple({
47
name: 'execute',
48
description:
49
'Execute a tool. Validates inputs and connections automatically; use it aggressively.',
68
{ name: '--get-schema', description: 'Fetch and print the CLI-facing input schema' },
69
],
70
}),
66
- tagged({
71
+ simple({
72
name: 'link',
73
description: 'Connect your account for a toolkit/app.',
74
usage: 'link [<toolkit>]',
148
name: 'composio triggers list <toolkit>',
149
description: 'List available trigger types in a toolkit',
150
}),
146
- tagged({
147
- name: 'composio connections list',
148
- description: 'Print toolkit connection statuses as JSON',
149
- }),
151
tagged({
152
name: 'composio artifacts cwd',
153
description: 'Print the cwd-scoped session artifact directory',
171
tagged({ name: 'config', description: 'View and manage CLI configuration' }),
172
];
173
174
+const FULL_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
175
+ full({
176
+ name: 'files',
177
+ description: 'Show where CLI config, cache, and session artifacts live',
178
+ }),
179
+ full({ name: 'tools list', description: 'List tools for a toolkit with query/tag filters' }),
180
+ full({ name: 'tools info', description: 'Inspect a tool summary and cached schema details' }),
181
+ full({ name: 'triggers list', description: 'List trigger types for a toolkit' }),
182
+ full({ name: 'triggers info', description: 'Inspect a trigger type and schema summary' }),
183
+ full({ name: 'connections list', description: 'Print toolkit connection statuses as JSON' }),
184
+ full({ name: 'generate ts', description: 'Generate TypeScript stubs for selected toolkits' }),
185
+ full({ name: 'generate py', description: 'Generate Python stubs for selected toolkits' }),
186
+ full({
187
+ name: 'dev init',
188
+ description: 'Initialize a developer project in the current directory',
189
+ }),
190
+ full({
191
+ name: 'dev playground-execute',
192
+ description: 'Execute tools against developer playground users and auth configs',
193
+ }),
194
+ full({
195
+ name: 'dev listen',
196
+ description: 'Stream developer-project realtime trigger events with optional forwarding',
197
+ }),
198
+];
199
+
200
// ── Render helpers ─────────────────────────────────────────────────────
201
202
function renderDetailedCommands(name: string, commands: ReadonlyArray<DetailedCommand>): string[] {
220
return commands.map(cmd => ` ${cmd.name.padEnd(maxLen + 2)}${cmd.description}`);
221
}
222
196
-function renderDevHelp(visibility: CommandVisibility): string {
223
+function renderDevHelp(visibility: CommandVisibility, helpLevel: HelpLevel = 'default'): string {
224
const lines: string[] = [
225
'',
226
bold('USAGE'),
239
];
240
241
if (!visibility.isDevModeEnabled) {
215
- lines.push(bold('EXAMPLES'));
216
- lines.push(' composio dev --mode on');
217
- lines.push(' composio dev --mode off');
218
- lines.push('');
219
- lines.push(bold('NOTE'));
220
- lines.push(
221
- ' Developer mode is for engineers building with the CLI. It unlocks more advanced commands like creating or updating auth configs and connected accounts.'
222
- );
223
- lines.push('');
242
+ if (helpLevel !== 'simple') {
243
+ lines.push(bold('EXAMPLES'));
244
+ lines.push(' composio dev --mode on');
245
+ lines.push(' composio dev --mode off');
246
+ lines.push('');
247
+ lines.push(bold('NOTE'));
248
+ lines.push(
249
+ ' Developer mode is for engineers building with the CLI. It unlocks more advanced commands like creating or updating auth configs and connected accounts.'
250
+ );
251
+ lines.push('');
252
+ }
253
return lines.join('\n');
254
}
255
304
' This requires `developer.destructive_actions: true` in `~/.composio/config.json` and `--dangerously-allow` on the command line.'
305
);
306
lines.push('');
278
- lines.push(bold('EXAMPLES'));
279
- lines.push(' composio dev --mode off');
280
- lines.push(' composio dev toolkits list');
281
- lines.push(
282
- ' composio dev playground-execute GMAIL_SEND_EMAIL --dangerously-allow -d \'{ recipient_email: "a@b.com" }\''
283
- );
284
- lines.push('');
307
+ if (helpLevel !== 'simple') {
308
+ lines.push(bold('EXAMPLES'));
309
+ lines.push(' composio dev --mode off');
310
+ lines.push(' composio dev toolkits list');
311
+ lines.push(
312
+ ' composio dev playground-execute GMAIL_SEND_EMAIL --dangerously-allow -d \'{ recipient_email: "a@b.com" }\''
313
+ );
314
+ lines.push('');
315
+ }
316
return lines.join('\n');
317
}
318
+export const HELP_LEVELS = [
319
+ 'simple',
320
+ 'default',
321
+ 'full',
322
+] as const satisfies ReadonlyArray<HelpLevel>;
323
+
324
+export const parseHelpLevel = (token: string | undefined): HelpLevel | undefined => {
325
+ if (!token) {
326
+ return undefined;
327
+ }
328
+ if (token === 'verbose') {
329
+ return 'full';
330
+ }
331
+ return HELP_LEVELS.find(level => level === token);
332
+};
333
+
334
+const splitTrailingHelpLevel = (
335
+ args: ReadonlyArray<string>
336
+): { args: ReadonlyArray<string>; helpLevel: HelpLevel } => {
337
+ const trailingLevel = parseHelpLevel(args[args.length - 1]);
338
+ if (!trailingLevel) {
339
+ return { args, helpLevel: 'default' };
340
+ }
341
+
342
+ return {
343
+ args: args.slice(0, -1),
344
+ helpLevel: trailingLevel,
345
+ };
346
+};
347
348
// ── Subcommand help definitions ────────────────────────────────────────
349
1121
1122
const getVisibleSubcommandHelp = (
1123
cmd: string,
1064
- visibility: CommandVisibility
1124
+ visibility: CommandVisibility,
1125
+ helpLevel: HelpLevel = 'default'
1126
): Option.Option<SubcommandHelp> => {
1127
if (cmd === 'dev') {
1128
return Option.some({
1144
return Option.some(entry);
1145
}
1146
1086
- if (!entry.tags || entry.tags.length === 0) {
1087
- return Option.some(entry.value);
1088
- }
1089
-
1090
- return entry.tags.every(tag => visibility.isExperimentalFeatureEnabled(tag))
1147
+ return isTaggedValueVisible(entry, visibility) &&
1148
+ isTaggedValueVisibleForHelpLevel(entry, helpLevel)
1149
? Option.some(entry.value)
1150
: Option.none();
1151
};
1152
1095
-function renderSubcommandHelp(cmd: SubcommandHelp): string {
1153
+function renderSubcommandHelp(cmd: SubcommandHelp, helpLevel: HelpLevel): string {
1154
const lines: string[] = [
1155
'',
1156
bold('USAGE'),
1185
lines.push('');
1186
}
1187
1130
- if (cmd.injectedHelpers && cmd.injectedHelpers.length > 0) {
1188
+ if (helpLevel !== 'simple' && cmd.injectedHelpers && cmd.injectedHelpers.length > 0) {
1189
lines.push(bold('INJECTED HELPERS'));
1190
const maxLen = Math.max(...cmd.injectedHelpers.map(h => h.name.length));
1191
for (const helper of cmd.injectedHelpers) {
1194
lines.push('');
1195
}
1196
1139
- if (cmd.examples && cmd.examples.length > 0) {
1197
+ if (helpLevel !== 'simple' && cmd.examples && cmd.examples.length > 0) {
1198
lines.push(bold('EXAMPLES'));
1199
for (const ex of cmd.examples) {
1200
lines.push(` ${ex}`);
1202
lines.push('');
1203
}
1204
1147
- if (cmd.seeAlso && cmd.seeAlso.length > 0) {
1205
+ if (helpLevel !== 'simple' && cmd.seeAlso && cmd.seeAlso.length > 0) {
1206
lines.push(bold('SEE ALSO'));
1207
for (const sa of cmd.seeAlso) {
1208
lines.push(` ${sa}`);
1221
argv: ReadonlyArray<string>,
1222
visibility: CommandVisibility
1223
): string | undefined {
1166
- const args = argv.slice(2);
1224
+ const { args } = splitTrailingHelpLevel(argv.slice(2));
1225
if (args.length < 2) return undefined;
1226
const last = args[args.length - 1];
1227
if (last !== '--help' && last !== '-h') return undefined;
1237
1238
export function printSubcommandHelp(
1239
cmd: string,
1182
- visibility: CommandVisibility
1240
+ visibility: CommandVisibility,
1241
+ helpLevel: HelpLevel = 'default'
1242
): Effect.Effect<void> {
1184
- if (cmd === 'dev') return Console.log(renderDevHelp(visibility));
1185
- const help = getVisibleSubcommandHelp(cmd, visibility);
1243
+ if (cmd === 'dev') return Console.log(renderDevHelp(visibility, helpLevel));
1244
+ const help = getVisibleSubcommandHelp(cmd, visibility, helpLevel);
1245
if (Option.isNone(help)) return Console.log(`Unknown command: ${cmd}`);
1187
- return Console.log(renderSubcommandHelp(help.value));
1246
+ return Console.log(renderSubcommandHelp(help.value, helpLevel));
1247
}
1248
1249
/**
1254
argv: ReadonlyArray<string>,
1255
visibility: CommandVisibility
1256
): string | undefined {
1198
- const args = argv.slice(2).filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));
1257
+ const { args: helpArgs } = splitTrailingHelpLevel(argv.slice(2));
1258
+ const args = helpArgs.filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));
1259
// Try longest match first: "dev toolkits list" → "dev toolkits" → "dev"
1260
for (let len = Math.min(args.length, 3); len > 0; len--) {
1261
const key = args.slice(0, len).join(' ');
1271
if (cmd === 'dev') return renderDevHelp(visibility);
1272
return Option.match(getVisibleSubcommandHelp(cmd, visibility), {
1273
onNone: () => undefined,
1214
- onSome: help => renderSubcommandHelp(help),
1274
+ onSome: help => renderSubcommandHelp(help, 'default'),
1275
});
1276
}
1277
1282
* Core workflow commands are shown first with full usage/options.
1283
* Housekeeping and developer commands are shown compactly at the bottom.
1284
*/
1225
-export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void> {
1285
+export function printRootHelp(
1286
+ visibility: CommandVisibility,
1287
+ helpLevel: HelpLevel = 'default'
1288
+): Effect.Effect<void> {
1289
const name = 'composio';
1290
const developerCommands: ReadonlyArray<CompactCommand> = [
1291
{
1296
},
1297
GENERATE_COMMAND.value,
1298
];
1299
+ const coreCommands = visibleValues(CORE_COMMANDS, visibility, helpLevel);
1300
+ const otherCommands = visibleValues(OTHER_COMMANDS, visibility, helpLevel);
1301
+ const accountCommands = visibleValues(ACCOUNT_COMMANDS, visibility, helpLevel);
1302
+ const fullCommands = visibleValues(FULL_COMMANDS, visibility, helpLevel);
1303
+ const exampleLines =
1304
+ helpLevel === 'simple'
1305
+ ? [
1306
+ ` ${dim('# Find tools')}`,
1307
+ ` ${name} search "send an email"`,
1308
+ '',
1309
+ ` ${dim('# Execute a tool')}`,
1310
+ ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
1311
+ '',
1312
+ ` ${dim('# Connect an account when execute tells you to')}`,
1313
+ ` ${name} link github`,
1314
+ '',
1315
+ ]
1316
+ : [
1317
+ ` ${dim('# Find tools — supports multiple queries at once')}`,
1318
+ ` ${name} search "send an email" "create github issue"`,
1319
+ ` ${name} search "list calendar events" --toolkits google_calendar --limit 5`,
1320
+ '',
1321
+ ` ${dim('# Connect your account for a toolkit')}`,
1322
+ ` ${name} link github`,
1323
+ '',
1324
+ ` ${dim('# Execute a tool')}`,
1325
+ ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
1326
+ '',
1327
+ ` ${dim('# Execute multiple tools in parallel')}`,
1328
+ ` ${name} execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \\`,
1329
+ ` SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL -d '{ channel: "general", text: "Hello" }'`,
1330
+ '',
1331
+ ` ${dim('# Call an API directly through proxy')}`,
1332
+ ` ${name} proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail`,
1333
+ '',
1334
+ ` ${dim('# Run a script with injected helpers')}`,
1335
+ ` ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,
1336
+ '',
1337
+ ` ${dim('# Manually install the composio skill when auto-install fails')}`,
1338
+ ` ${name} --instal-skill claude`,
1339
+ ` ${name} --instal-skill composio-cli codex`,
1340
+ '',
1341
+ ` ${dim('# Run a multi-step script with Promise.all')}`,
1342
+ ` ${name} run '`,
1343
+ ` const [emails, issues] = await Promise.all([`,
1344
+ ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,
1345
+ ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),`,
1346
+ ` ]);`,
1347
+ ` const brief = await experimental_subAgent(\`Summarize:\\n\${emails.prompt()}\\n\${issues.prompt()}\`);`,
1348
+ ` console.log(brief);`,
1349
+ ` '`,
1350
+ '',
1351
+ ];
1352
1353
const lines: string[] = [
1354
'',
1366
'',
1367
bold('USAGE'),
1368
` ${name} <command> [options]`,
1369
+ ` ${name} --help [simple|default|full]`,
1370
+ '',
1371
+ bold('MODE'),
1372
+ ` ${helpLevel} help`,
1373
'',
1374
bold('CORE COMMANDS'),
1255
- ...renderDetailedCommands(name, visibleValues(CORE_COMMANDS, visibility)),
1375
+ ...renderDetailedCommands(name, coreCommands),
1376
gray(' Typical flow: search → execute (link and tools when needed)'),
1377
'',
1258
- bold('TOOLS'),
1259
- ...renderCompactCommands(visibleValues(OTHER_COMMANDS, visibility)),
1378
+ ...(otherCommands.length > 0
1379
+ ? [bold('TOOLS'), ...renderCompactCommands(otherCommands), '']
1380
+ : []),
1381
'',
1382
bold('EXAMPLES'),
1262
- ` ${dim('# Find tools — supports multiple queries at once')}`,
1263
- ` ${name} search "send an email" "create github issue"`,
1264
- ` ${name} search "list calendar events" --toolkits google_calendar --limit 5`,
1265
- '',
1266
- ` ${dim('# Connect your account for a toolkit')}`,
1267
- ` ${name} link github`,
1268
- '',
1269
- ` ${dim('# Execute a tool')}`,
1270
- ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
1271
- '',
1272
- ` ${dim('# Execute multiple tools in parallel')}`,
1273
- ` ${name} execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \\`,
1274
- ` SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL -d '{ channel: "general", text: "Hello" }'`,
1275
- '',
1276
- ` ${dim('# Call an API directly through proxy')}`,
1277
- ` ${name} proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail`,
1278
- '',
1279
- ` ${dim('# Run a script with injected helpers')}`,
1280
- ` ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,
1281
- '',
1282
- ` ${dim('# Manually install the composio skill when auto-install fails')}`,
1283
- ` ${name} --instal-skill claude`,
1284
- ` ${name} --instal-skill composio-cli codex`,
1285
- '',
1286
- ` ${dim('# Run a multi-step script with Promise.all')}`,
1287
- ` ${name} run '`,
1288
- ` const [emails, issues] = await Promise.all([`,
1289
- ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,
1290
- ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),`,
1291
- ` ]);`,
1292
- ` const brief = await experimental_subAgent(\`Summarize:\\n\${emails.prompt()}\\n\${issues.prompt()}\`);`,
1293
- ` console.log(brief);`,
1294
- ` '`,
1295
- '',
1296
- bold('DEVELOPER COMMANDS'),
1297
- ...renderCompactCommands(developerCommands),
1298
- '',
1299
- bold('ACCOUNT'),
1300
- ...renderCompactCommands(visibleValues(ACCOUNT_COMMANDS, visibility)),
1301
- '',
1383
+ ...exampleLines,
1384
+ ...(developerCommands.length > 0
1385
+ ? [bold('DEVELOPER COMMANDS'), ...renderCompactCommands(developerCommands), '']
1386
+ : []),
1387
+ ...(accountCommands.length > 0
1388
+ ? [bold('ACCOUNT'), ...renderCompactCommands(accountCommands), '']
1389
+ : []),
1390
+ ...(fullCommands.length > 0
1391
+ ? [bold('MORE COMMANDS'), ...renderCompactCommands(fullCommands), '']
1392
+ : []),
1393
bold('FILES') + dim(' (composio files --help)'),
1394
` ${bold('~/.composio/')}`,
1395
` CLI configuration and cache directory. Contains your auth state`,
1406
` the current directory's session.`,
1407
'',
1408
bold('FLAGS'),
1318
- ' -h, --help Show help for command',
1409
+ ' -h, --help [mode] Show help for command (simple, default, full)',
1410
` --version Show ${name} version`,
1411
' --instal-skill [skill-name] <claude|codex|openclaw>',
1412
' Manually install the composio skill for a supported agent',