Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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.ts
index 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.ts
index 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>): stri
return 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 }, ({ toolkit
if (!(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.ts
index 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>): Tagged
tags,
});
+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.ts
index 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<s
const 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.ts
index 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<SubcommandHel
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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');
+ })
+ );
+ });
});