Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Add help verbosity modes to CLI help output (#3205)
Rahul Tarak9a6f1a0abc1c
diff --git a/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts b/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.tsindex 71cd838a3..69b3086b1 100644--- a/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts+++ b/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts@@ -1,10 +1,17 @@import { Command, Options } from '@effect/cli';-import { Effect, Option } from 'effect';-import { ComposioToolkitsRepository } from 'src/services/composio-clients';+import { Effect, Option, Schema } from 'effect';+import {+ ComposioClientSingleton,+ ConnectedAccountListResponse,+} from 'src/services/composio-clients';import { TerminalUI } from 'src/services/terminal-ui';import { requireAuth } from 'src/effects/require-auth';import { clampLimit } from 'src/ui/clamp-limit';import { redact } from 'src/ui/redact';+import {+ formatResolveCommandProjectError,+ resolveCommandProject,+} from 'src/services/command-project';import { formatConnectedAccountsTable, formatConnectedAccountsJson } from '../format';const toolkits = Options.text('toolkits').pipe(@@ -51,21 +58,31 @@ export const connectedAccountsCmd$List = Command.make(if (!(yield* requireAuth)) return;const ui = yield* TerminalUI;- const repo = yield* ComposioToolkitsRepository;+ const clientSingleton = yield* ComposioClientSingleton;const toolkitSlugs = Option.isSome(toolkits)? toolkits.value.split(',').map(s => s.trim()): undefined;+ const resolvedProject = yield* resolveCommandProject({+ mode: 'developer',+ }).pipe(Effect.mapError(formatResolveCommandProjectError));+ const client = yield* clientSingleton.getFor({+ orgId: resolvedProject.orgId,+ projectId: resolvedProject.projectId,+ });- const result = yield* ui.withSpinner(+ const rawResult = yield* ui.withSpinner('Fetching connected accounts...',- repo.listConnectedAccounts({- toolkit_slugs: toolkitSlugs,- user_ids: Option.isSome(userId) ? [userId.value] : undefined,- statuses: Option.isSome(status) ? [status.value] : undefined,- limit: clampLimit(limit),- })+ Effect.tryPromise(() =>+ client.connectedAccounts.list({+ toolkit_slugs: toolkitSlugs,+ user_ids: Option.isSome(userId) ? [userId.value] : undefined,+ statuses: Option.isSome(status) ? [status.value] : undefined,+ limit: clampLimit(limit),+ })+ ));+ const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult);if (result.items.length === 0) {let hint: string;diff --git a/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts b/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.tsindex 31e2b42f9..a2a95abf9 100644--- a/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts+++ b/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts@@ -1,8 +1,15 @@import { Command, Options } from '@effect/cli';-import { Effect, Option } from 'effect';+import { Effect, Option, Schema } from 'effect';import { requireAuth } from 'src/effects/require-auth';import type { ConnectedAccountItem } from 'src/models/connected-accounts';-import { ComposioToolkitsRepository } from 'src/services/composio-clients';+import {+ ComposioClientSingleton,+ ConnectedAccountListResponse,+} from 'src/services/composio-clients';+import {+ formatResolveCommandProjectError,+ resolveCommandProject,+} from 'src/services/command-project';import { TerminalUI } from 'src/services/terminal-ui';const toolkit = Options.text('toolkit').pipe(@@ -16,22 +23,23 @@ const formatConnectionsJson = (items: ReadonlyArray<ConnectedAccountItem>): strireturn acc;}, new Map());- const grouped = items.reduce<Record<string, Array<{ status: string; alias?: string | null }>>>(- (acc, item) => {- const toolkit = item.toolkit.slug;- const entry = {- status: item.status,- ...(toolkitCounts.get(toolkit)! > 1 ? { alias: item.alias ?? null } : {}),- };-- if (!acc[toolkit]) {- acc[toolkit] = [];- }- acc[toolkit].push(entry);- return acc;- },- {}- );+ const grouped = items.reduce<+ Record<string, Array<{ status: string; alias?: string | null; word_id?: string | null }>>+ >((acc, item) => {+ const toolkit = item.toolkit.slug;+ const includeAlias = toolkitCounts.get(toolkit)! > 1;+ const entry = {+ status: item.status,+ ...(includeAlias ? { alias: item.alias ?? null } : {}),+ ...(item.word_id != null ? { word_id: item.word_id } : {}),+ };++ if (!acc[toolkit]) {+ acc[toolkit] = [];+ }+ acc[toolkit].push(entry);+ return acc;+ }, {});return JSON.stringify(grouped, null, 2);};@@ -41,21 +49,36 @@ export const connectionsCmd$List = Command.make('list', { toolkit }, ({ toolkitif (!(yield* requireAuth)) return;const ui = yield* TerminalUI;- const repo = yield* ComposioToolkitsRepository;+ const clientSingleton = yield* ComposioClientSingleton;const toolkitSlug = Option.getOrUndefined(toolkit);+ const resolvedProject = yield* resolveCommandProject({+ mode: 'consumer',+ }).pipe(Effect.mapError(formatResolveCommandProjectError));++ const consumerUserId = resolvedProject.consumerUserId;+ if (!consumerUserId) {+ return yield* Effect.fail(+ new Error('Missing consumer user id. Run `composio login` and try again.')+ );+ }- const result = yield* ui.withSpinner(- 'Fetching connections...',- repo.listConnectedAccounts({+ const client = yield* clientSingleton.getFor({+ orgId: resolvedProject.orgId,+ projectId: resolvedProject.projectId,+ });+ const rawResult = yield* Effect.tryPromise(() =>+ client.connectedAccounts.list({toolkit_slugs: toolkitSlug ? [toolkitSlug] : undefined,+ user_ids: [consumerUserId],limit: 1000,}));+ const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult);- yield* ui.output(formatConnectionsJson(result.items));+ yield* ui.output(formatConnectionsJson(result.items), { force: true });})).pipe(Command.withDescription(- 'List connection statuses as JSON. Includes aliases when a toolkit has multiple connections.'+ 'List connection statuses as JSON. Includes aliases for duplicate toolkits and word_ids when available.'));diff --git a/ts/packages/cli/src/commands/feature-tags.ts b/ts/packages/cli/src/commands/feature-tags.tsindex e2f0d8cab..43ceb4f8e 100644--- a/ts/packages/cli/src/commands/feature-tags.ts+++ b/ts/packages/cli/src/commands/feature-tags.ts@@ -1,8 +1,10 @@export type CliFeatureTag = string;+export type HelpLevel = 'simple' | 'default' | 'full';export type TaggedValue<T> = {readonly value: T;readonly tags?: ReadonlyArray<CliFeatureTag>;+ readonly helpLevel?: HelpLevel;};export type CommandVisibility = {@@ -15,11 +17,34 @@ export const tagged = <T>(value: T, tags?: ReadonlyArray<CliFeatureTag>): Taggedtags,});+export const simple = <T>(value: T, tags?: ReadonlyArray<CliFeatureTag>): TaggedValue<T> => ({+ value,+ tags,+ helpLevel: 'simple',+});++export const full = <T>(value: T, tags?: ReadonlyArray<CliFeatureTag>): TaggedValue<T> => ({+ value,+ tags,+ helpLevel: 'full',+});+export const experimental = <T>(feature: string, value: T): TaggedValue<T> => ({value,tags: [feature],});+const HELP_LEVEL_ORDER: Record<HelpLevel, number> = {+ simple: 0,+ default: 1,+ full: 2,+};++export const isTaggedValueVisibleForHelpLevel = <T>(+ entry: TaggedValue<T>,+ helpLevel: HelpLevel = 'default'+): boolean => HELP_LEVEL_ORDER[helpLevel] >= HELP_LEVEL_ORDER[entry.helpLevel ?? 'default'];+export const isTaggedValueVisible = <T>(entry: TaggedValue<T>,visibility: CommandVisibility@@ -33,6 +58,13 @@ export const isTaggedValueVisible = <T>(export const visibleValues = <T>(entries: ReadonlyArray<TaggedValue<T>>,- visibility: CommandVisibility+ visibility: CommandVisibility,+ helpLevel: HelpLevel = 'default'): Array<T> =>- entries.filter(entry => isTaggedValueVisible(entry, visibility)).map(entry => entry.value);+ entries+ .filter(+ entry =>+ isTaggedValueVisible(entry, visibility) &&+ isTaggedValueVisibleForHelpLevel(entry, helpLevel)+ )+ .map(entry => entry.value);diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.tsindex 2a2fe4bda..53fba1f81 100644--- a/ts/packages/cli/src/commands/index.ts+++ b/ts/packages/cli/src/commands/index.ts@@ -19,7 +19,12 @@ import {runParallelToolsExecuteFromArgv,showToolsExecuteInputHelp,} from './tools/commands/tools.execute.cmd';-import { printRootHelp, matchSubcommandHelp, printSubcommandHelp } from './root-help';+import {+ printRootHelp,+ matchSubcommandHelp,+ parseHelpLevel,+ printSubcommandHelp,+} from './root-help';import { rootToolsCmd$Search } from './tools/commands/tools.search.cmd';import { rootToolsCmd$Execute } from './tools/commands/tools.execute.cmd';import { rootToolsCmd } from './tools/tools.cmd';@@ -413,7 +418,13 @@ const normalizeHiddenDebugFlags = (argv: ReadonlyArray<string>): ReadonlyArray<sconst isRootHelp = (argv: ReadonlyArray<string>): boolean => {const args = argv.slice(2);- return args.length === 0 || (args.length === 1 && (args[0] === '--help' || args[0] === '-h'));+ return (+ args.length === 0 ||+ (args.length >= 1 &&+ args.length <= 2 &&+ (args[0] === '--help' || args[0] === '-h') &&+ (args.length === 1 || parseHelpLevel(args[1]) !== undefined))+ );};const isGenerateGraph = (argv: ReadonlyArray<string>): boolean => {@@ -503,11 +514,12 @@ export const runWithConfig = Effect.gen(function* () {});}if (isRootHelp(normalizedArgv)) {- return printRootHelp(visibility);+ return printRootHelp(visibility, parseHelpLevel(normalizedArgv[3]) ?? 'default');}const subHelp = matchSubcommandHelp(normalizedArgv, visibility);if (subHelp) {- return printSubcommandHelp(subHelp, visibility);+ const helpLevel = parseHelpLevel(normalizedArgv[normalizedArgv.length - 1]) ?? 'default';+ return printSubcommandHelp(subHelp, visibility, helpLevel);}const nestedMismatch = findNestedSubcommandMismatch(normalizedArgv, rootCommand);if (nestedMismatch) {diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.tsindex b7518115a..19c8ab65e 100644--- a/ts/packages/cli/src/commands/root-help.ts+++ b/ts/packages/cli/src/commands/root-help.ts@@ -4,6 +4,11 @@ import { bold, dim, gray } from 'src/ui/colors';import {type CommandVisibility,experimental,+ type HelpLevel,+ full,+ isTaggedValueVisible,+ isTaggedValueVisibleForHelpLevel,+ simple,tagged,visibleValues,type TaggedValue,@@ -24,7 +29,7 @@ type CompactCommand = {// ── Core workflow commands ──────────────────────────────────────────────const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [- tagged({+ simple({name: 'search',description: 'Find tools by use case across all toolkits/apps.',usage: 'search <query...> [--toolkits text] [--limit integer] [--human]',@@ -38,7 +43,7 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [{ name: '--human', description: 'Show formatted output instead of default JSON' },],}),- tagged({+ simple({name: 'execute',description:'Execute a tool. Validates inputs and connections automatically; use it aggressively.',@@ -63,7 +68,7 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [{ name: '--get-schema', description: 'Fetch and print the CLI-facing input schema' },],}),- tagged({+ simple({name: 'link',description: 'Connect your account for a toolkit/app.',usage: 'link [<toolkit>]',@@ -143,10 +148,6 @@ const OTHER_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [name: 'composio triggers list <toolkit>',description: 'List available trigger types in a toolkit',}),- tagged({- name: 'composio connections list',- description: 'Print toolkit connection statuses as JSON',- }),tagged({name: 'composio artifacts cwd',description: 'Print the cwd-scoped session artifact directory',@@ -170,6 +171,32 @@ const ACCOUNT_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [tagged({ name: 'config', description: 'View and manage CLI configuration' }),];+const FULL_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [+ full({+ name: 'files',+ description: 'Show where CLI config, cache, and session artifacts live',+ }),+ full({ name: 'tools list', description: 'List tools for a toolkit with query/tag filters' }),+ full({ name: 'tools info', description: 'Inspect a tool summary and cached schema details' }),+ full({ name: 'triggers list', description: 'List trigger types for a toolkit' }),+ full({ name: 'triggers info', description: 'Inspect a trigger type and schema summary' }),+ full({ name: 'connections list', description: 'Print toolkit connection statuses as JSON' }),+ full({ name: 'generate ts', description: 'Generate TypeScript stubs for selected toolkits' }),+ full({ name: 'generate py', description: 'Generate Python stubs for selected toolkits' }),+ full({+ name: 'dev init',+ description: 'Initialize a developer project in the current directory',+ }),+ full({+ name: 'dev playground-execute',+ description: 'Execute tools against developer playground users and auth configs',+ }),+ full({+ name: 'dev listen',+ description: 'Stream developer-project realtime trigger events with optional forwarding',+ }),+];+// ── Render helpers ─────────────────────────────────────────────────────function renderDetailedCommands(name: string, commands: ReadonlyArray<DetailedCommand>): string[] {@@ -193,7 +220,7 @@ function renderCompactCommands(commands: ReadonlyArray<CompactCommand>): string[return commands.map(cmd => ` ${cmd.name.padEnd(maxLen + 2)}${cmd.description}`);}-function renderDevHelp(visibility: CommandVisibility): string {+function renderDevHelp(visibility: CommandVisibility, helpLevel: HelpLevel = 'default'): string {const lines: string[] = ['',bold('USAGE'),@@ -212,15 +239,17 @@ function renderDevHelp(visibility: CommandVisibility): string {];if (!visibility.isDevModeEnabled) {- lines.push(bold('EXAMPLES'));- lines.push(' composio dev --mode on');- lines.push(' composio dev --mode off');- lines.push('');- lines.push(bold('NOTE'));- lines.push(- ' Developer mode is for engineers building with the CLI. It unlocks more advanced commands like creating or updating auth configs and connected accounts.'- );- lines.push('');+ if (helpLevel !== 'simple') {+ lines.push(bold('EXAMPLES'));+ lines.push(' composio dev --mode on');+ lines.push(' composio dev --mode off');+ lines.push('');+ lines.push(bold('NOTE'));+ lines.push(+ ' Developer mode is for engineers building with the CLI. It unlocks more advanced commands like creating or updating auth configs and connected accounts.'+ );+ lines.push('');+ }return lines.join('\n');}@@ -275,15 +304,46 @@ function renderDevHelp(visibility: CommandVisibility): string {' This requires `developer.destructive_actions: true` in `~/.composio/config.json` and `--dangerously-allow` on the command line.');lines.push('');- lines.push(bold('EXAMPLES'));- lines.push(' composio dev --mode off');- lines.push(' composio dev toolkits list');- lines.push(- ' composio dev playground-execute GMAIL_SEND_EMAIL --dangerously-allow -d \'{ recipient_email: "[email protected]" }\''- );- lines.push('');+ if (helpLevel !== 'simple') {+ lines.push(bold('EXAMPLES'));+ lines.push(' composio dev --mode off');+ lines.push(' composio dev toolkits list');+ lines.push(+ ' composio dev playground-execute GMAIL_SEND_EMAIL --dangerously-allow -d \'{ recipient_email: "[email protected]" }\''+ );+ lines.push('');+ }return lines.join('\n');}+export const HELP_LEVELS = [+ 'simple',+ 'default',+ 'full',+] as const satisfies ReadonlyArray<HelpLevel>;++export const parseHelpLevel = (token: string | undefined): HelpLevel | undefined => {+ if (!token) {+ return undefined;+ }+ if (token === 'verbose') {+ return 'full';+ }+ return HELP_LEVELS.find(level => level === token);+};++const splitTrailingHelpLevel = (+ args: ReadonlyArray<string>+): { args: ReadonlyArray<string>; helpLevel: HelpLevel } => {+ const trailingLevel = parseHelpLevel(args[args.length - 1]);+ if (!trailingLevel) {+ return { args, helpLevel: 'default' };+ }++ return {+ args: args.slice(0, -1),+ helpLevel: trailingLevel,+ };+};// ── Subcommand help definitions ────────────────────────────────────────@@ -1061,7 +1121,8 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHelconst getVisibleSubcommandHelp = (cmd: string,- visibility: CommandVisibility+ visibility: CommandVisibility,+ helpLevel: HelpLevel = 'default'): Option.Option<SubcommandHelp> => {if (cmd === 'dev') {return Option.some({@@ -1083,16 +1144,13 @@ const getVisibleSubcommandHelp = (return Option.some(entry);}- if (!entry.tags || entry.tags.length === 0) {- return Option.some(entry.value);- }-- return entry.tags.every(tag => visibility.isExperimentalFeatureEnabled(tag))+ return isTaggedValueVisible(entry, visibility) &&+ isTaggedValueVisibleForHelpLevel(entry, helpLevel)? Option.some(entry.value): Option.none();};-function renderSubcommandHelp(cmd: SubcommandHelp): string {+function renderSubcommandHelp(cmd: SubcommandHelp, helpLevel: HelpLevel): string {const lines: string[] = ['',bold('USAGE'),@@ -1127,7 +1185,7 @@ function renderSubcommandHelp(cmd: SubcommandHelp): string {lines.push('');}- if (cmd.injectedHelpers && cmd.injectedHelpers.length > 0) {+ if (helpLevel !== 'simple' && cmd.injectedHelpers && cmd.injectedHelpers.length > 0) {lines.push(bold('INJECTED HELPERS'));const maxLen = Math.max(...cmd.injectedHelpers.map(h => h.name.length));for (const helper of cmd.injectedHelpers) {@@ -1136,7 +1194,7 @@ function renderSubcommandHelp(cmd: SubcommandHelp): string {lines.push('');}- if (cmd.examples && cmd.examples.length > 0) {+ if (helpLevel !== 'simple' && cmd.examples && cmd.examples.length > 0) {lines.push(bold('EXAMPLES'));for (const ex of cmd.examples) {lines.push(` ${ex}`);@@ -1144,7 +1202,7 @@ function renderSubcommandHelp(cmd: SubcommandHelp): string {lines.push('');}- if (cmd.seeAlso && cmd.seeAlso.length > 0) {+ if (helpLevel !== 'simple' && cmd.seeAlso && cmd.seeAlso.length > 0) {lines.push(bold('SEE ALSO'));for (const sa of cmd.seeAlso) {lines.push(` ${sa}`);@@ -1163,7 +1221,7 @@ export function matchSubcommandHelp(argv: ReadonlyArray<string>,visibility: CommandVisibility): string | undefined {- const args = argv.slice(2);+ const { args } = splitTrailingHelpLevel(argv.slice(2));if (args.length < 2) return undefined;const last = args[args.length - 1];if (last !== '--help' && last !== '-h') return undefined;@@ -1179,12 +1237,13 @@ export function matchSubcommandHelp(export function printSubcommandHelp(cmd: string,- visibility: CommandVisibility+ visibility: CommandVisibility,+ helpLevel: HelpLevel = 'default'): Effect.Effect<void> {- if (cmd === 'dev') return Console.log(renderDevHelp(visibility));- const help = getVisibleSubcommandHelp(cmd, visibility);+ if (cmd === 'dev') return Console.log(renderDevHelp(visibility, helpLevel));+ const help = getVisibleSubcommandHelp(cmd, visibility, helpLevel);if (Option.isNone(help)) return Console.log(`Unknown command: ${cmd}`);- return Console.log(renderSubcommandHelp(help.value));+ return Console.log(renderSubcommandHelp(help.value, helpLevel));}/**@@ -1195,7 +1254,8 @@ export function matchCommandFromArgv(argv: ReadonlyArray<string>,visibility: CommandVisibility): string | undefined {- const args = argv.slice(2).filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));+ const { args: helpArgs } = splitTrailingHelpLevel(argv.slice(2));+ const args = helpArgs.filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));// Try longest match first: "dev toolkits list" → "dev toolkits" → "dev"for (let len = Math.min(args.length, 3); len > 0; len--) {const key = args.slice(0, len).join(' ');@@ -1211,7 +1271,7 @@ export function getCommandHelpText(cmd: string, visibility: CommandVisibility):if (cmd === 'dev') return renderDevHelp(visibility);return Option.match(getVisibleSubcommandHelp(cmd, visibility), {onNone: () => undefined,- onSome: help => renderSubcommandHelp(help),+ onSome: help => renderSubcommandHelp(help, 'default'),});}@@ -1222,7 +1282,10 @@ export function getCommandHelpText(cmd: string, visibility: CommandVisibility):* Core workflow commands are shown first with full usage/options.* Housekeeping and developer commands are shown compactly at the bottom.*/-export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void> {+export function printRootHelp(+ visibility: CommandVisibility,+ helpLevel: HelpLevel = 'default'+): Effect.Effect<void> {const name = 'composio';const developerCommands: ReadonlyArray<CompactCommand> = [{@@ -1233,6 +1296,59 @@ export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void},GENERATE_COMMAND.value,];+ const coreCommands = visibleValues(CORE_COMMANDS, visibility, helpLevel);+ const otherCommands = visibleValues(OTHER_COMMANDS, visibility, helpLevel);+ const accountCommands = visibleValues(ACCOUNT_COMMANDS, visibility, helpLevel);+ const fullCommands = visibleValues(FULL_COMMANDS, visibility, helpLevel);+ const exampleLines =+ helpLevel === 'simple'+ ? [+ ` ${dim('# Find tools')}`,+ ` ${name} search "send an email"`,+ '',+ ` ${dim('# Execute a tool')}`,+ ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,+ '',+ ` ${dim('# Connect an account when execute tells you to')}`,+ ` ${name} link github`,+ '',+ ]+ : [+ ` ${dim('# Find tools — supports multiple queries at once')}`,+ ` ${name} search "send an email" "create github issue"`,+ ` ${name} search "list calendar events" --toolkits google_calendar --limit 5`,+ '',+ ` ${dim('# Connect your account for a toolkit')}`,+ ` ${name} link github`,+ '',+ ` ${dim('# Execute a tool')}`,+ ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,+ '',+ ` ${dim('# Execute multiple tools in parallel')}`,+ ` ${name} execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "[email protected]", subject: "Hi" }' \\`,+ ` SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL -d '{ channel: "general", text: "Hello" }'`,+ '',+ ` ${dim('# Call an API directly through proxy')}`,+ ` ${name} proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail`,+ '',+ ` ${dim('# Run a script with injected helpers')}`,+ ` ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,+ '',+ ` ${dim('# Manually install the composio skill when auto-install fails')}`,+ ` ${name} --instal-skill claude`,+ ` ${name} --instal-skill composio-cli codex`,+ '',+ ` ${dim('# Run a multi-step script with Promise.all')}`,+ ` ${name} run '`,+ ` const [emails, issues] = await Promise.all([`,+ ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,+ ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),`,+ ` ]);`,+ ` const brief = await experimental_subAgent(\`Summarize:\\n\${emails.prompt()}\\n\${issues.prompt()}\`);`,+ ` console.log(brief);`,+ ` '`,+ '',+ ];const lines: string[] = ['',@@ -1250,55 +1366,30 @@ export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void'',bold('USAGE'),` ${name} <command> [options]`,+ ` ${name} --help [simple|default|full]`,+ '',+ bold('MODE'),+ ` ${helpLevel} help`,'',bold('CORE COMMANDS'),- ...renderDetailedCommands(name, visibleValues(CORE_COMMANDS, visibility)),+ ...renderDetailedCommands(name, coreCommands),gray(' Typical flow: search → execute (link and tools when needed)'),'',- bold('TOOLS'),- ...renderCompactCommands(visibleValues(OTHER_COMMANDS, visibility)),+ ...(otherCommands.length > 0+ ? [bold('TOOLS'), ...renderCompactCommands(otherCommands), '']+ : []),'',bold('EXAMPLES'),- ` ${dim('# Find tools — supports multiple queries at once')}`,- ` ${name} search "send an email" "create github issue"`,- ` ${name} search "list calendar events" --toolkits google_calendar --limit 5`,- '',- ` ${dim('# Connect your account for a toolkit')}`,- ` ${name} link github`,- '',- ` ${dim('# Execute a tool')}`,- ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,- '',- ` ${dim('# Execute multiple tools in parallel')}`,- ` ${name} execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "[email protected]", subject: "Hi" }' \\`,- ` SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL -d '{ channel: "general", text: "Hello" }'`,- '',- ` ${dim('# Call an API directly through proxy')}`,- ` ${name} proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail`,- '',- ` ${dim('# Run a script with injected helpers')}`,- ` ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,- '',- ` ${dim('# Manually install the composio skill when auto-install fails')}`,- ` ${name} --instal-skill claude`,- ` ${name} --instal-skill composio-cli codex`,- '',- ` ${dim('# Run a multi-step script with Promise.all')}`,- ` ${name} run '`,- ` const [emails, issues] = await Promise.all([`,- ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,- ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),`,- ` ]);`,- ` const brief = await experimental_subAgent(\`Summarize:\\n\${emails.prompt()}\\n\${issues.prompt()}\`);`,- ` console.log(brief);`,- ` '`,- '',- bold('DEVELOPER COMMANDS'),- ...renderCompactCommands(developerCommands),- '',- bold('ACCOUNT'),- ...renderCompactCommands(visibleValues(ACCOUNT_COMMANDS, visibility)),- '',+ ...exampleLines,+ ...(developerCommands.length > 0+ ? [bold('DEVELOPER COMMANDS'), ...renderCompactCommands(developerCommands), '']+ : []),+ ...(accountCommands.length > 0+ ? [bold('ACCOUNT'), ...renderCompactCommands(accountCommands), '']+ : []),+ ...(fullCommands.length > 0+ ? [bold('MORE COMMANDS'), ...renderCompactCommands(fullCommands), '']+ : []),bold('FILES') + dim(' (composio files --help)'),` ${bold('~/.composio/')}`,` CLI configuration and cache directory. Contains your auth state`,@@ -1315,7 +1406,7 @@ export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void` the current directory's session.`,'',bold('FLAGS'),- ' -h, --help Show help for command',+ ' -h, --help [mode] Show help for command (simple, default, full)',` --version Show ${name} version`,' --instal-skill [skill-name] <claude|codex|openclaw>',' Manually install the composio skill for a supported agent',diff --git a/ts/packages/cli/test/src/commands/$default.cmd.test.ts b/ts/packages/cli/test/src/commands/$default.cmd.test.tsindex 84eea88f7..a7fe10659 100644--- a/ts/packages/cli/test/src/commands/$default.cmd.test.ts+++ b/ts/packages/cli/test/src/commands/$default.cmd.test.ts@@ -71,7 +71,7 @@ describe('CLI: composio', () => {const output = lines.join('\n');expect(output).toContain('Usage:');expect(output).toContain('composio');- expect(output).toContain('composio connections list');+ expect(output).not.toContain('composio connections list');}));});@@ -85,6 +85,38 @@ describe('CLI: composio', () => {const output = lines.join('\n');expect(output.trim().length).toBeGreaterThan(0);expect(output).toContain('config.json');+ expect(output).not.toContain('connections list');+ })+ );+ });++ layer(TestLive())(it => {+ it.scoped('[Given] --help simple [Then] prints the compact root help mode', () =>+ Effect.gen(function* () {+ yield* cli(['--help', 'simple']);+ const lines = yield* MockConsole.getLines({ stripAnsi: true });+ const output = lines.join('\n');++ expect(output).toContain('simple help');+ expect(output).toContain('composio --help [simple|default|full]');+ expect(output).not.toContain('composio run');+ expect(output).not.toContain('MORE COMMANDS');+ })+ );+ });++ layer(TestLive())(it => {+ it.scoped('[Given] --help full [Then] prints the expanded root help mode', () =>+ Effect.gen(function* () {+ yield* cli(['--help', 'full']);+ const lines = yield* MockConsole.getLines({ stripAnsi: true });+ const output = lines.join('\n');++ expect(output).toContain('full help');+ expect(output).toContain('MORE COMMANDS');+ expect(output).toContain('dev playground-execute');+ expect(output).toContain('generate ts');+ expect(output).toContain('connections list');}));});diff --git a/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts b/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.tsindex b52869ece..b4d097bdb 100644--- a/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts+++ b/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts@@ -1,6 +1,7 @@import { describe, expect, layer } from '@effect/vitest';import { ConfigProvider, Effect } from 'effect';import { extendConfigProvider } from 'src/services/config';+import { ComposioUserContext } from 'src/services/user-context';import { cli, TestLive, MockConsole } from 'test/__utils__';import type { TestLiveInput } from 'test/__utils__/services/test-layer';import type { ConnectedAccountItem } from 'src/models/connected-accounts';@@ -67,12 +68,22 @@ const testConfigProvider = ConfigProvider.fromMap(new Map([['COMPOSIO_USER_API_KEY', 'test_api_key']])).pipe(extendConfigProvider);+const testDevConfigProvider = ConfigProvider.fromMap(+ new Map([+ ['COMPOSIO_USER_API_KEY', 'test_api_key'],+ ['COMPOSIO_ORG_ID', 'dev_org_test'],+ ['COMPOSIO_PROJECT_ID', 'dev_project_test'],+ ])+).pipe(extendConfigProvider);+describe('CLI: composio dev connected-accounts list', () => {- layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(+ layer(TestLive({ baseConfigProvider: testDevConfigProvider, connectedAccountsData }))('[Given] no flags [Then] lists all connected accounts',it => {it.scoped('lists all connected accounts with table', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['dev', 'connected-accounts', 'list']);const lines = yield* MockConsole.getLines({ stripAnsi: true });const output = lines.join('\n');@@ -86,11 +97,13 @@ describe('CLI: composio dev connected-accounts list', () => {});- layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(+ layer(TestLive({ baseConfigProvider: testDevConfigProvider, connectedAccountsData }))('[Given] --toolkits "gmail" [Then] lists only gmail connected accounts',it => {it.scoped('filters by toolkit', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['dev', 'connected-accounts', 'list', '--toolkits', 'gmail']);const lines = yield* MockConsole.getLines({ stripAnsi: true });const output = lines.join('\n');@@ -103,11 +116,13 @@ describe('CLI: composio dev connected-accounts list', () => {});- layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(+ layer(TestLive({ baseConfigProvider: testDevConfigProvider, connectedAccountsData }))('[Given] --user-id "default" [Then] lists only default user accounts',it => {it.scoped('filters by user ID', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['dev', 'connected-accounts', 'list', '--user-id', 'default']);const lines = yield* MockConsole.getLines({ stripAnsi: true });const output = lines.join('\n');@@ -121,11 +136,13 @@ describe('CLI: composio dev connected-accounts list', () => {});- layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(+ layer(TestLive({ baseConfigProvider: testDevConfigProvider, connectedAccountsData }))('[Given] --status ACTIVE [Then] lists only active accounts',it => {it.scoped('filters by status', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['dev', 'connected-accounts', 'list', '--status', 'ACTIVE']);const lines = yield* MockConsole.getLines({ stripAnsi: true });const output = lines.join('\n');@@ -139,11 +156,13 @@ describe('CLI: composio dev connected-accounts list', () => {});- layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(+ layer(TestLive({ baseConfigProvider: testDevConfigProvider, connectedAccountsData }))('[Given] --limit 1 [Then] respects limit',it => {it.scoped('respects limit', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['dev', 'connected-accounts', 'list', '--limit', '1']);const lines = yield* MockConsole.getLines({ stripAnsi: true });const output = lines.join('\n');@@ -154,6 +173,18 @@ describe('CLI: composio dev connected-accounts list', () => {});+ layer(TestLive({ baseConfigProvider: testDevConfigProvider }))(+ '[Given] no org in user context [Then] warns user to login',+ it => {+ it.scoped('warns user to login', () =>+ Effect.gen(function* () {+ const error = yield* Effect.flip(cli(['dev', 'connected-accounts', 'list']));+ expect(String(error)).toContain('No default org configured');+ })+ );+ }+ );+layer(TestLive())('[Given] no API key [Then] warns user to login', it => {it.scoped('warns user to login', () =>Effect.gen(function* () {@@ -166,11 +197,13 @@ describe('CLI: composio dev connected-accounts list', () => {);});- layer(TestLive({ baseConfigProvider: testConfigProvider }))(+ layer(TestLive({ baseConfigProvider: testDevConfigProvider }))('[Given] empty results [Then] shows no connected accounts found',it => {it.scoped('shows no connected accounts found', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['dev', 'connected-accounts', 'list']);const lines = yield* MockConsole.getLines({ stripAnsi: true });const output = lines.join('\n');@@ -181,11 +214,13 @@ describe('CLI: composio dev connected-accounts list', () => {});- layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(+ layer(TestLive({ baseConfigProvider: testDevConfigProvider, connectedAccountsData }))('[Given] --toolkits "nonexistent" [Then] shows hint about toolkit slug',it => {it.scoped('shows toolkit hint', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['dev', 'connected-accounts', 'list', '--toolkits', 'nonexistent']);const lines = yield* MockConsole.getLines({ stripAnsi: true });const output = lines.join('\n');diff --git a/ts/packages/cli/test/src/commands/connections/connections.list.cmd.test.ts b/ts/packages/cli/test/src/commands/connections/connections.list.cmd.test.tsindex 8e7fb2b6b..d3a95efd5 100644--- a/ts/packages/cli/test/src/commands/connections/connections.list.cmd.test.ts+++ b/ts/packages/cli/test/src/commands/connections/connections.list.cmd.test.ts@@ -2,6 +2,7 @@ import { describe, expect, layer } from '@effect/vitest';import { ConfigProvider, Effect } from 'effect';import type { ConnectedAccountItem } from 'src/models/connected-accounts';import { extendConfigProvider } from 'src/services/config';+import { ComposioUserContext } from 'src/services/user-context';import { cli, TestLive, MockConsole } from 'test/__utils__';import type { TestLiveInput } from 'test/__utils__/services/test-layer';@@ -26,7 +27,7 @@ const testConnections: ConnectedAccountItem[] = [status: 'ACTIVE',status_reason: null,is_disabled: false,- user_id: 'default',+ user_id: 'consumer-user-org_test',toolkit: { slug: 'gmail' },auth_config: {id: 'ac_gmail_oauth',@@ -41,11 +42,11 @@ const testConnections: ConnectedAccountItem[] = [{id: 'con_github_work',alias: 'work',- word_id: null,+ word_id: 'castle',status: 'ACTIVE',status_reason: null,is_disabled: false,- user_id: 'default',+ user_id: 'consumer-user-org_test',toolkit: { slug: 'github' },auth_config: {id: 'ac_github_oauth',@@ -60,11 +61,11 @@ const testConnections: ConnectedAccountItem[] = [{id: 'con_github_personal',alias: 'personal',- word_id: null,+ word_id: 'forest',status: 'FAILED',status_reason: 'Token expired',is_disabled: false,- user_id: 'default',+ user_id: 'consumer-user-org_test',toolkit: { slug: 'github' },auth_config: {id: 'ac_github_oauth_2',@@ -90,6 +91,8 @@ describe('CLI: composio connections list', () => {layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(it => {it.scoped('[Given] no filter [Then] prints connection JSON with aliases for duplicates', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['connections', 'list']);const lines = yield* MockConsole.getLines({ stripAnsi: true });@@ -98,8 +101,35 @@ describe('CLI: composio connections list', () => {expect(parsed).toEqual({gmail: [{ status: 'ACTIVE' }],github: [- { status: 'ACTIVE', alias: 'work' },- { status: 'FAILED', alias: 'personal' },+ { status: 'ACTIVE', alias: 'work', word_id: 'castle' },+ { status: 'FAILED', alias: 'personal', word_id: 'forest' },+ ],+ });+ })+ );+ });++ layer(+ TestLive({+ baseConfigProvider: testConfigProvider,+ connectedAccountsData,+ stdin: { isTTY: true, data: '' },+ })+ )(it => {+ it.scoped('[Given] interactive stdout [Then] still prints the JSON payload', () =>+ Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');+ yield* cli(['connections', 'list']);++ const lines = yield* MockConsole.getLines({ stripAnsi: true });+ const parsed = parseJsonFromLines(lines);++ expect(parsed).toEqual({+ gmail: [{ status: 'ACTIVE' }],+ github: [+ { status: 'ACTIVE', alias: 'work', word_id: 'castle' },+ { status: 'FAILED', alias: 'personal', word_id: 'forest' },],});})@@ -109,6 +139,8 @@ describe('CLI: composio connections list', () => {layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(it => {it.scoped('[Given] --toolkit github [Then] filters the JSON output', () =>Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');yield* cli(['connections', 'list', '--toolkit', 'github']);const lines = yield* MockConsole.getLines({ stripAnsi: true });@@ -116,11 +148,54 @@ describe('CLI: composio connections list', () => {expect(parsed).toEqual({github: [- { status: 'ACTIVE', alias: 'work' },- { status: 'FAILED', alias: 'personal' },+ { status: 'ACTIVE', alias: 'work', word_id: 'castle' },+ { status: 'FAILED', alias: 'personal', word_id: 'forest' },],});}));});++ layer(+ TestLive({+ baseConfigProvider: testConfigProvider,+ connectedAccountsData: {+ items: [+ ...testConnections,+ {+ id: 'con_slack_dev_only',+ alias: null,+ word_id: null,+ status: 'ACTIVE',+ status_reason: null,+ is_disabled: false,+ user_id: 'developer-user-org_test',+ toolkit: { slug: 'slack' },+ auth_config: {+ id: 'ac_slack_oauth',+ auth_scheme: 'OAUTH2',+ is_composio_managed: true,+ is_disabled: false,+ },+ created_at: '2026-03-01T00:00:00Z',+ updated_at: '2026-03-05T00:00:00Z',+ test_request_endpoint: '',+ },+ ],+ },+ })+ )(it => {+ it.scoped('[Given] mixed user scopes [Then] only consumer-project connections are listed', () =>+ Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ yield* userContext.login('test_api_key', 'org_test');+ yield* cli(['connections', 'list']);++ const lines = yield* MockConsole.getLines({ stripAnsi: true });+ const parsed = parseJsonFromLines(lines);++ expect(parsed).not.toHaveProperty('slack');+ })+ );+ });});diff --git a/ts/packages/cli/test/src/commands/feature-visibility.test.ts b/ts/packages/cli/test/src/commands/feature-visibility.test.tsindex 651e7029c..530aa4b3a 100644--- a/ts/packages/cli/test/src/commands/feature-visibility.test.ts+++ b/ts/packages/cli/test/src/commands/feature-visibility.test.ts@@ -1,12 +1,15 @@import { CommandDescriptor } from '@effect/cli';-import { HashMap } from 'effect';+import { layer } from '@effect/vitest';+import { Effect, HashMap } from 'effect';import { describe, expect, it } from 'vitest';import { buildRootCommand } from 'src/commands';import {getCommandHelpText,matchCommandFromArgv,matchSubcommandHelp,+ printSubcommandHelp,} from 'src/commands/root-help';+import { MockConsole, TestLive } from 'test/__utils__';const stableVisibility = {isDevModeEnabled: true,@@ -44,4 +47,29 @@ describe('CLI experimental feature visibility', () => {expect(getCommandHelpText('listen', stableVisibility)).toBe(undefined);expect(getCommandHelpText('listen', betaVisibility)).toContain('composio listen');});++ it('accepts help mode suffixes when matching subcommand help', () => {+ expect(+ matchSubcommandHelp(['bun', 'composio', 'search', '--help', 'simple'], stableVisibility)+ ).toBe('search');+ expect(+ matchSubcommandHelp(['bun', 'composio', 'search', '--help', 'full'], stableVisibility)+ ).toBe('search');+ });+});++describe('CLI help levels', () => {+ layer(TestLive())(it => {+ it.scoped('renders compact subcommand help in simple mode', () =>+ Effect.gen(function* () {+ yield* printSubcommandHelp('run', stableVisibility, 'simple');+ const output = (yield* MockConsole.getLines({ stripAnsi: true })).join('\n');++ expect(output).toContain('USAGE');+ expect(output).toContain('DESCRIPTION');+ expect(output).not.toContain('EXAMPLES');+ expect(output).not.toContain('INJECTED HELPERS');+ })+ );+ });});