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)
## Summary - Fixes nested `composio tools ...` subcommand validation so invalid child commands report a tools-scoped mismatch instead of falling through to generic handling. - Adds root help text for the `tools` command group to better reflect discoverable subcommands. - Covers the regression with a CLI test asserting the mismatch message and available subcommand list. ## Testing - Added/updated `ts/packages/cli/test/src/commands/$default.cmd.test.ts` to verify invalid nested tools subcommands return the expected mismatch. - Not run locally.
Rahul Tarak committed
Apr 9, 2026 at 23:02 UTC
5877ef48407a077f0b7e085c9baf29ef5b3163cf
5 files changed
+138
-26
ts/packages/cli/src/commands/index.ts
+101
-8
@@ -1,6 +1,6 @@
1
import process from 'node:process';
2
import { Effect, Option } from 'effect';
3
-import { Command } from '@effect/cli';
3
+import { Command, HelpDoc, ValidationError } from '@effect/cli';
4
import { $defaultCmd } from './$default.cmd';
5
import { getVersion } from 'src/effects/version';
6
import { versionCmd } from './version.cmd';
@@ -76,10 +76,101 @@ export const buildRootCommand = (visibility: CommandVisibility) => {
76
return $defaultCmd.pipe(Command.withSubcommands(subcommands as any));
77
};
78
79
+const formatSubcommandChoices = (choices: ReadonlyArray<string>) =>
80
+ choices.map(choice => `'${choice}'`).join(', ');
81
+
82
+/**
83
+ * Internal shape of an `@effect/cli` command descriptor. The public
84
+ * `CommandDescriptor.getSubcommands` helper flattens nested subcommand trees
85
+ * and only returns the *parent* Standard node for each branch, which means we
86
+ * can't use it to walk deeper than one level. Walking the `_tag`-based
87
+ * internal tree directly is the only way to recover the full descendable
88
+ * structure without losing subcommand context on descent.
89
+ */
90
+type InternalDescriptor =
91
+ | { _tag: 'Standard'; name: string }
92
+ | { _tag: 'GetUserInput'; name: string }
93
+ | { _tag: 'Map'; command: InternalDescriptor }
94
+ | {
95
+ _tag: 'Subcommands';
96
+ parent: InternalDescriptor;
97
+ children: ReadonlyArray<InternalDescriptor>;
98
+ };
99
+
100
+type UnwrappedDescriptor = Exclude<InternalDescriptor, { _tag: 'Map' }>;
101
+
102
+const unwrapMaps = (cmd: InternalDescriptor): UnwrappedDescriptor => {
103
+ let current: InternalDescriptor = cmd;
104
+ while (current._tag === 'Map') {
105
+ current = current.command;
106
+ }
107
+ return current;
108
+};
109
+
110
+const getCommandName = (cmd: InternalDescriptor): string => {
111
+ const unwrapped = unwrapMaps(cmd);
112
+ if (unwrapped._tag === 'Subcommands') {
113
+ return getCommandName(unwrapped.parent);
114
+ }
115
+ return unwrapped.name;
116
+};
117
+
118
+const getChildEntries = (
119
+ cmd: InternalDescriptor
120
+): ReadonlyArray<readonly [string, InternalDescriptor]> => {
121
+ const unwrapped = unwrapMaps(cmd);
122
+ if (unwrapped._tag !== 'Subcommands') {
123
+ return [];
124
+ }
125
+ return unwrapped.children.map(child => [getCommandName(child), child] as const);
126
+};
127
+
128
+const findNestedSubcommandMismatch = (
129
+ argv: ReadonlyArray<string>,
130
+ rootCommand: ReturnType<typeof buildRootCommand>
131
+): ReturnType<typeof ValidationError.commandMismatch> | undefined => {
132
+ const args = argv.slice(2);
133
+ let current: InternalDescriptor = rootCommand.descriptor as unknown as InternalDescriptor;
134
+ const path = ['composio'];
135
+
136
+ for (const token of args) {
137
+ if (!token || token === '--' || token === '--help' || token === '-h' || token.startsWith('-')) {
138
+ return undefined;
139
+ }
140
+
141
+ const children = getChildEntries(current);
142
+ if (children.length === 0) {
143
+ return undefined;
144
+ }
145
+
146
+ const match = children.find(([name]) => name === token);
147
+ if (match) {
148
+ current = match[1];
149
+ path.push(token);
150
+ continue;
151
+ }
152
+
153
+ if (path.length === 1) {
154
+ return undefined;
155
+ }
156
+
157
+ const available = children.map(([name]) => name).sort();
158
+ return ValidationError.commandMismatch(
159
+ HelpDoc.p(
160
+ `Invalid subcommand for ${path.join(' ')} - use one of ${formatSubcommandChoices(available)}`
161
+ )
162
+ );
163
+ }
164
+
165
+ return undefined;
166
+};
167
+
168
const ROOT_INSTALL_SKILL_FLAGS = ['--instal-skill', '--install-skill'] as const;
80
-const SKILL_INSTALL_TARGETS = ['claude', 'codex', 'openclaw'] as const satisfies ReadonlyArray<
81
- SkillInstallTarget
82
->;
169
+const SKILL_INSTALL_TARGETS = [
170
+ 'claude',
171
+ 'codex',
172
+ 'openclaw',
173
+] as const satisfies ReadonlyArray<SkillInstallTarget>;
174
175
type RootInstallSkillRequest =
176
| {
@@ -122,8 +213,7 @@ export const parseRootInstallSkillRequest = (
213
if (!isSkillInstallTarget(target)) {
214
return {
215
_tag: 'error',
125
- message:
126
- 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
216
+ message: 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
217
};
218
}
219
return { _tag: 'parsed', target };
@@ -134,8 +224,7 @@ export const parseRootInstallSkillRequest = (
224
if (!isSkillInstallTarget(target)) {
225
return {
226
_tag: 'error',
137
- message:
138
- 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
227
+ message: 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
228
};
229
}
230
return { _tag: 'parsed', skillName, target };
@@ -375,6 +464,10 @@ export const runWithConfig = Effect.gen(function* () {
464
if (subHelp) {
465
return printSubcommandHelp(subHelp, visibility);
466
}
467
+ const nestedMismatch = findNestedSubcommandMismatch(normalizedArgv, rootCommand);
468
+ if (nestedMismatch) {
469
+ return Effect.fail(nestedMismatch);
470
+ }
471
const parallelExecute = runParallelToolsExecuteFromArgv(normalizedArgv);
472
if (parallelExecute) {
473
return parallelExecute;
ts/packages/cli/src/commands/root-help.ts
+9
@@ -613,6 +613,15 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
613
614
// ── Tools commands ────────────────────────────────────────────────────
615
616
+ tools: {
617
+ usage: 'composio tools <command>',
618
+ description: 'Browse and inspect tools before executing them.',
619
+ examples: ['composio tools list gmail', 'composio tools info GMAIL_SEND_EMAIL'],
620
+ seeAlso: [
621
+ 'composio search "<query>" Find tools by use case',
622
+ "composio execute <slug> -d '{ ... }' Execute a tool directly",
623
+ ],
624
+ },
625
'tools list': {
626
usage: 'composio tools list <toolkit> [--query text] [--tags text] [--limit integer]',
627
description: 'List available tools for a toolkit.',
ts/packages/cli/src/effects/install-skill.ts
+1
-5
@@ -39,11 +39,7 @@ export const resolveInstalledSkillName = (skillName?: string): string => {
39
if (!normalized) {
40
return SKILL_NAME;
41
}
42
- if (
43
- normalized === '.' ||
44
- normalized === '..' ||
45
- !SKILL_NAME_PATTERN.test(normalized)
46
- ) {
42
+ if (normalized === '.' || normalized === '..' || !SKILL_NAME_PATTERN.test(normalized)) {
43
throw new Error(
44
'Invalid skill name. Use letters, numbers, dots, underscores, or hyphens only.'
45
);
ts/packages/cli/test/src/commands/$default.cmd.test.ts
+20
@@ -41,6 +41,26 @@ describe('CLI: composio', () => {
41
);
42
});
43
44
+ layer(TestLive())(it => {
45
+ it.scoped('[Given] invalid tools subcommand [Then] report tools-scoped mismatch', () =>
46
+ Effect.gen(function* () {
47
+ const args = ['tools', 'search', 'metabase', 'put'];
48
+
49
+ const result = yield* cli(args).pipe(Effect.catchAll(e => Effect.succeed(e)));
50
+ const commandMismatch = result as CommandMismatchResult;
51
+
52
+ expect(result).toEqual(expect.any(Object));
53
+ expect(commandMismatch._tag).toBe(ValidationError.commandMismatch(HelpDoc.p(''))._tag);
54
+ expect(commandMismatch.error._tag).toBe('Paragraph');
55
+ expect(commandMismatch.error.value._tag).toBe('Text');
56
+ expect(commandMismatch.error.value.value).toContain('Invalid subcommand for composio tools');
57
+ expect(commandMismatch.error.value.value).toContain("'info'");
58
+ expect(commandMismatch.error.value.value).toContain("'list'");
59
+ expect(commandMismatch.error.value.value).not.toContain("'version'");
60
+ })
61
+ );
62
+ });
63
+
64
layer(TestLive())(it => {
65
it.scoped('[Given] no args [Then] prints help message', () =>
66
Effect.gen(function* () {
ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts
+7
-13
@@ -11,13 +11,7 @@ describe('CLI: --instal-skill', () => {
11
12
it('parses an explicit skill name and target', () => {
13
expect(
14
- parseRootInstallSkillRequest([
15
- 'node',
16
- 'composio',
17
- '--instal-skill',
18
- 'composio-cli',
19
- 'codex',
20
- ])
14
+ parseRootInstallSkillRequest(['node', 'composio', '--instal-skill', 'composio-cli', 'codex'])
15
).toEqual({
16
_tag: 'parsed',
17
skillName: 'composio-cli',
@@ -26,12 +20,12 @@ describe('CLI: --instal-skill', () => {
20
});
21
22
it('accepts the --install-skill alias', () => {
29
- expect(parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'openclaw'])).toEqual(
30
- {
31
- _tag: 'parsed',
32
- target: 'openclaw',
33
- }
34
- );
23
+ expect(
24
+ parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'openclaw'])
25
+ ).toEqual({
26
+ _tag: 'parsed',
27
+ target: 'openclaw',
28
+ });
29
});
30
31
it('accepts the root flag after leading global options', () => {