411
// ── Account commands ──────────────────────────────────────────────────
412
413
login: {
414
- usage: 'composio login [--no-browser] [--no-wait] [--key text] [-y, --yes]',
415
- description: 'Log in to the Composio CLI session.',
414
+ usage:
415
+ 'composio login [--no-browser] [--no-wait] [--key text] [-y, --yes] [--no-skill-install]',
416
+ description:
417
+ 'Log in to the Composio CLI session. By default, also installs the composio-cli skill for Claude Code.',
418
options: [
419
{
420
name: '--key <text>',
425
{ name: '--no-browser', description: 'Login without browser interaction' },
426
{ name: '--no-wait', description: 'Print login URL and session info, then exit' },
427
{ name: '-y, --yes', description: 'Skip org picker; use session default org' },
428
+ {
429
+ name: '--no-skill-install',
430
+ description: 'Skip installing the composio-cli skill for Claude Code',
431
+ },
432
],
433
},
434
logout: {
447
usage: 'composio upgrade',
448
description: 'Upgrade your Composio CLI to the latest available version.',
449
},
450
+ files: {
451
+ usage: 'composio files',
452
+ description: 'Where the Composio CLI stores data on disk.',
453
+ examples: [
454
+ '~/.composio/',
455
+ ' CLI configuration and cache directory.',
456
+ ' user_data.json Your auth state (API key, org, base URL)',
457
+ ' toolkits.json Cached toolkit list from the API',
458
+ ' tools.json Cached tool definitions',
459
+ ' trigger-types.json Cached trigger type definitions',
460
+ ' consumer-short-term-cache.json Per-org connected toolkits cache (15-min TTL)',
461
+ ' analytics.json Anonymous install ID for telemetry',
462
+ '',
463
+ ' All caches are safe to delete — they will be re-fetched on next use.',
464
+ '',
465
+ '$TMPDIR/composio/ (or COMPOSIO_SESSION_DIR / COMPOSIO_CACHE_DIR)',
466
+ ' Session artifacts directory. Each CLI session gets a unique subdirectory',
467
+ ' scoped to your working directory. Stores session history and files',
468
+ ' created during `run` and `execute` (e.g. large tool outputs).',
469
+ ' Use `composio artifacts cwd` to print the current session path.',
470
+ '',
471
+ '.composio/ (per-project, optional)',
472
+ ' Per-directory project config. Scoped to the nearest parent that has one.',
473
+ ' .env Allows COMPOSIO_ORG_ID and COMPOSIO_PROJECT_ID overrides',
474
+ ' project.json Project context (org, project binding)',
475
+ '',
476
+ 'Environment variables that control paths:',
477
+ ' COMPOSIO_SESSION_DIR Override session artifacts root',
478
+ ' COMPOSIO_CACHE_DIR Override cache directory (also used for artifacts fallback)',
479
+ ' COMPOSIO_CACHE_DIR is useful in sandboxed environments where ~/.composio or',
480
+ ' $TMPDIR may not be writable.',
481
+ ],
482
+ },
483
484
// ── Tools commands ────────────────────────────────────────────────────
485
904
return Console.log(renderSubcommandHelp(help));
905
}
906
907
+/**
908
+ * Match the command name from argv without requiring --help at the end.
909
+ * Used to print contextual help alongside error messages.
910
+ */
911
+export function matchCommandFromArgv(argv: ReadonlyArray<string>): string | undefined {
912
+ const args = argv.slice(2).filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));
913
+ // Try longest match first: "dev toolkits list" → "dev toolkits" → "dev"
914
+ for (let len = Math.min(args.length, 3); len > 0; len--) {
915
+ const key = args.slice(0, len).join(' ');
916
+ if (key in SUBCOMMAND_HELP) return key;
917
+ }
918
+ return undefined;
919
+}
920
+
921
+/**
922
+ * Get rendered help text for a command, or undefined if not found.
923
+ */
924
+export function getCommandHelpText(cmd: string): string | undefined {
925
+ const help = SUBCOMMAND_HELP[cmd];
926
+ if (!help) return undefined;
927
+ return renderSubcommandHelp(help);
928
+}
929
+
930
// ── Main help output ───────────────────────────────────────────────────
931
932
/**
958
...renderCompactCommands(OTHER_COMMANDS),
959
'',
960
bold('EXAMPLES'),
899
- ` ${dim('# Find a tool')}`,
900
- ` ${name} search "create github issue"`,
961
+ ` ${dim('# Find tools — supports multiple queries at once')}`,
962
+ ` ${name} search "send an email" "create github issue"`,
963
+ ` ${name} search "list calendar events" --toolkits google_calendar --limit 5`,
964
'',
902
- ` ${dim('# Connect your GitHub account')}`,
965
+ ` ${dim('# Connect your account for a toolkit')}`,
966
` ${name} link github`,
967
'',
968
` ${dim('# Execute a tool')}`,
906
- ` ${name} execute GITHUB_CREATE_ISSUE -d '{ repo: "owner/repo", title: "Bug" }'`,
969
+ ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
970
+ '',
971
+ ` ${dim('# Execute multiple tools in parallel')}`,
972
+ ` ${name} execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \\`,
973
+ ` SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL -d '{ channel: "general", text: "Hello" }'`,
974
'',
975
` ${dim('# Call an API directly through proxy')}`,
976
` ${name} proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail`,
978
` ${dim('# Run a script with injected helpers')}`,
979
` ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,
980
'',
981
+ ` ${dim('# Run a multi-step script with Promise.all')}`,
982
+ ` ${name} run '`,
983
+ ` const [emails, issues] = await Promise.all([`,
984
+ ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,
985
+ ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),`,
986
+ ` ]);`,
987
+ ` const brief = await subAgent(\`Summarize:\\n\${emails.prompt()}\\n\${issues.prompt()}\`);`,
988
+ ` console.log(brief);`,
989
+ ` '`,
990
+ '',
991
bold('DEVELOPER COMMANDS'),
992
...renderCompactCommands(DEVELOPER_COMMANDS),
993
'',
994
bold('ACCOUNT'),
995
...renderCompactCommands(ACCOUNT_COMMANDS),
996
'',
997
+ bold('FILES') + dim(' (composio files --help)'),
998
+ ` ${bold('~/.composio/')}`,
999
+ ` CLI configuration and cache directory. Contains your auth state`,
1000
+ ` (user_data.json), cached tool definitions (tools.json, toolkits.json),`,
1001
+ ` trigger types, and per-org consumer caches. These caches speed up`,
1002
+ ` repeated commands — safe to delete, they will be re-fetched on next use.`,
1003
+ '',
1004
+ ` ${bold('/tmp/composio/')}`,
1005
+ ` Session artifacts directory. Each CLI session gets a unique subdirectory`,
1006
+ ` scoped to your working directory. Stores session history and files`,
1007
+ ` created during ${bold('run')} and ${bold('execute')} commands (e.g. downloaded attachments,`,
1008
+ ` generated outputs). Use \`${name} artifacts cwd\` to print the path for`,
1009
+ ` the current directory's session.`,
1010
+ '',
1011
bold('FLAGS'),
1012
' -h, --help Show help for command',
1013
` --version Show ${name} version`,