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.

Fix nested tools subcommand mismatch handling (#3157)

Rahul Tarak5877ef48407a
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index 1f0093f9d..5d7ffe967 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -1,6 +1,6 @@
import process from 'node:process';
import { Effect, Option } from 'effect';
-import { Command } from '@effect/cli';
+import { Command, HelpDoc, ValidationError } from '@effect/cli';
import { $defaultCmd } from './$default.cmd';
import { getVersion } from 'src/effects/version';
import { versionCmd } from './version.cmd';
@@ -76,10 +76,101 @@ export const buildRootCommand = (visibility: CommandVisibility) => {
return $defaultCmd.pipe(Command.withSubcommands(subcommands as any));
};
+const formatSubcommandChoices = (choices: ReadonlyArray<string>) =>
+ choices.map(choice => `'${choice}'`).join(', ');
+
+/**
+ * Internal shape of an `@effect/cli` command descriptor. The public
+ * `CommandDescriptor.getSubcommands` helper flattens nested subcommand trees
+ * and only returns the *parent* Standard node for each branch, which means we
+ * can't use it to walk deeper than one level. Walking the `_tag`-based
+ * internal tree directly is the only way to recover the full descendable
+ * structure without losing subcommand context on descent.
+ */
+type InternalDescriptor =
+ | { _tag: 'Standard'; name: string }
+ | { _tag: 'GetUserInput'; name: string }
+ | { _tag: 'Map'; command: InternalDescriptor }
+ | {
+ _tag: 'Subcommands';
+ parent: InternalDescriptor;
+ children: ReadonlyArray<InternalDescriptor>;
+ };
+
+type UnwrappedDescriptor = Exclude<InternalDescriptor, { _tag: 'Map' }>;
+
+const unwrapMaps = (cmd: InternalDescriptor): UnwrappedDescriptor => {
+ let current: InternalDescriptor = cmd;
+ while (current._tag === 'Map') {
+ current = current.command;
+ }
+ return current;
+};
+
+const getCommandName = (cmd: InternalDescriptor): string => {
+ const unwrapped = unwrapMaps(cmd);
+ if (unwrapped._tag === 'Subcommands') {
+ return getCommandName(unwrapped.parent);
+ }
+ return unwrapped.name;
+};
+
+const getChildEntries = (
+ cmd: InternalDescriptor
+): ReadonlyArray<readonly [string, InternalDescriptor]> => {
+ const unwrapped = unwrapMaps(cmd);
+ if (unwrapped._tag !== 'Subcommands') {
+ return [];
+ }
+ return unwrapped.children.map(child => [getCommandName(child), child] as const);
+};
+
+const findNestedSubcommandMismatch = (
+ argv: ReadonlyArray<string>,
+ rootCommand: ReturnType<typeof buildRootCommand>
+): ReturnType<typeof ValidationError.commandMismatch> | undefined => {
+ const args = argv.slice(2);
+ let current: InternalDescriptor = rootCommand.descriptor as unknown as InternalDescriptor;
+ const path = ['composio'];
+
+ for (const token of args) {
+ if (!token || token === '--' || token === '--help' || token === '-h' || token.startsWith('-')) {
+ return undefined;
+ }
+
+ const children = getChildEntries(current);
+ if (children.length === 0) {
+ return undefined;
+ }
+
+ const match = children.find(([name]) => name === token);
+ if (match) {
+ current = match[1];
+ path.push(token);
+ continue;
+ }
+
+ if (path.length === 1) {
+ return undefined;
+ }
+
+ const available = children.map(([name]) => name).sort();
+ return ValidationError.commandMismatch(
+ HelpDoc.p(
+ `Invalid subcommand for ${path.join(' ')} - use one of ${formatSubcommandChoices(available)}`
+ )
+ );
+ }
+
+ return undefined;
+};
+
const ROOT_INSTALL_SKILL_FLAGS = ['--instal-skill', '--install-skill'] as const;
-const SKILL_INSTALL_TARGETS = ['claude', 'codex', 'openclaw'] as const satisfies ReadonlyArray<
- SkillInstallTarget
->;
+const SKILL_INSTALL_TARGETS = [
+ 'claude',
+ 'codex',
+ 'openclaw',
+] as const satisfies ReadonlyArray<SkillInstallTarget>;
type RootInstallSkillRequest =
| {
@@ -122,8 +213,7 @@ export const parseRootInstallSkillRequest = (
if (!isSkillInstallTarget(target)) {
return {
_tag: 'error',
- message:
- 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
+ message: 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
};
}
return { _tag: 'parsed', target };
@@ -134,8 +224,7 @@ export const parseRootInstallSkillRequest = (
if (!isSkillInstallTarget(target)) {
return {
_tag: 'error',
- message:
- 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
+ message: 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
};
}
return { _tag: 'parsed', skillName, target };
@@ -375,6 +464,10 @@ export const runWithConfig = Effect.gen(function* () {
if (subHelp) {
return printSubcommandHelp(subHelp, visibility);
}
+ const nestedMismatch = findNestedSubcommandMismatch(normalizedArgv, rootCommand);
+ if (nestedMismatch) {
+ return Effect.fail(nestedMismatch);
+ }
const parallelExecute = runParallelToolsExecuteFromArgv(normalizedArgv);
if (parallelExecute) {
return parallelExecute;
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
index 2cd85267d..401cb4442 100644
--- a/ts/packages/cli/src/commands/root-help.ts
+++ b/ts/packages/cli/src/commands/root-help.ts
@@ -613,6 +613,15 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
// ── Tools commands ────────────────────────────────────────────────────
+ tools: {
+ usage: 'composio tools <command>',
+ description: 'Browse and inspect tools before executing them.',
+ examples: ['composio tools list gmail', 'composio tools info GMAIL_SEND_EMAIL'],
+ seeAlso: [
+ 'composio search "<query>" Find tools by use case',
+ "composio execute <slug> -d '{ ... }' Execute a tool directly",
+ ],
+ },
'tools list': {
usage: 'composio tools list <toolkit> [--query text] [--tags text] [--limit integer]',
description: 'List available tools for a toolkit.',
diff --git a/ts/packages/cli/src/effects/install-skill.ts b/ts/packages/cli/src/effects/install-skill.ts
index 3bf59e1b4..3121da144 100644
--- a/ts/packages/cli/src/effects/install-skill.ts
+++ b/ts/packages/cli/src/effects/install-skill.ts
@@ -39,11 +39,7 @@ export const resolveInstalledSkillName = (skillName?: string): string => {
if (!normalized) {
return SKILL_NAME;
}
- if (
- normalized === '.' ||
- normalized === '..' ||
- !SKILL_NAME_PATTERN.test(normalized)
- ) {
+ if (normalized === '.' || normalized === '..' || !SKILL_NAME_PATTERN.test(normalized)) {
throw new Error(
'Invalid skill name. Use letters, numbers, dots, underscores, or hyphens only.'
);
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 3ecf46f42..0b1e160bf 100644
--- a/ts/packages/cli/test/src/commands/$default.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
@@ -41,6 +41,26 @@ describe('CLI: composio', () => {
);
});
+ layer(TestLive())(it => {
+ it.scoped('[Given] invalid tools subcommand [Then] report tools-scoped mismatch', () =>
+ Effect.gen(function* () {
+ const args = ['tools', 'search', 'metabase', 'put'];
+
+ const result = yield* cli(args).pipe(Effect.catchAll(e => Effect.succeed(e)));
+ const commandMismatch = result as CommandMismatchResult;
+
+ expect(result).toEqual(expect.any(Object));
+ expect(commandMismatch._tag).toBe(ValidationError.commandMismatch(HelpDoc.p(''))._tag);
+ expect(commandMismatch.error._tag).toBe('Paragraph');
+ expect(commandMismatch.error.value._tag).toBe('Text');
+ expect(commandMismatch.error.value.value).toContain('Invalid subcommand for composio tools');
+ expect(commandMismatch.error.value.value).toContain("'info'");
+ expect(commandMismatch.error.value.value).toContain("'list'");
+ expect(commandMismatch.error.value.value).not.toContain("'version'");
+ })
+ );
+ });
+
layer(TestLive())(it => {
it.scoped('[Given] no args [Then] prints help message', () =>
Effect.gen(function* () {
diff --git a/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts b/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts
index 257f672bf..015fd54f1 100644
--- a/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts
+++ b/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts
@@ -11,13 +11,7 @@ describe('CLI: --instal-skill', () => {
it('parses an explicit skill name and target', () => {
expect(
- parseRootInstallSkillRequest([
- 'node',
- 'composio',
- '--instal-skill',
- 'composio-cli',
- 'codex',
- ])
+ parseRootInstallSkillRequest(['node', 'composio', '--instal-skill', 'composio-cli', 'codex'])
).toEqual({
_tag: 'parsed',
skillName: 'composio-cli',
@@ -26,12 +20,12 @@ describe('CLI: --instal-skill', () => {
});
it('accepts the --install-skill alias', () => {
- expect(parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'openclaw'])).toEqual(
- {
- _tag: 'parsed',
- target: 'openclaw',
- }
- );
+ expect(
+ parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'openclaw'])
+ ).toEqual({
+ _tag: 'parsed',
+ target: 'openclaw',
+ });
});
it('accepts the root flag after leading global options', () => {