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(cli): improve error UX for toolkits info command
- Make slug argument optional and show a helpful tip when missing instead of dumping @effect/cli's raw ValidationError JSON - Enrich HttpServerError with structured `details` (message, suggestedFix) so commands can render API errors cleanly with clack - Show "Did you mean?" suggestions when a slug doesn't match - Suppress @effect/cli ValidationErrors from the generic error box (they already print their own help text)
jkomyno committed
Feb 18, 2026 at 19:57 UTC
65bf97b271b8ca7399d5b3e41e448921155505ae
4 files changed
+85
-22
ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts
+34
-20
@@ -6,7 +6,10 @@ import { TerminalUI } from 'src/services/terminal-ui';
6
import type { ToolkitDetailed, AuthConfigDetail } from 'src/models/toolkits';
7
import { bold, gray } from 'src/ui/colors';
8
9
-const slug = Args.text({ name: 'slug' }).pipe(Args.withDescription('Toolkit slug (e.g. "gmail")'));
9
+const slug = Args.text({ name: 'slug' }).pipe(
10
+ Args.withDescription('Toolkit slug (e.g. "gmail")'),
11
+ Args.optional
12
+);
13
14
/**
15
* Format auth config fields for display.
@@ -96,30 +99,41 @@ export const toolkitsCmd$Info = Command.make('info', { slug }, ({ slug }) =>
99
return;
100
}
101
102
+ // Missing slug guard
103
+ if (Option.isNone(slug)) {
104
+ yield* ui.log.warn('Missing required argument: <slug>');
105
+ yield* ui.log.step('Try specifying a toolkit slug, e.g.:\n> composio toolkits info "gmail"');
106
+ return;
107
+ }
108
+
109
+ const slugValue = slug.value;
110
+
111
const toolkit = yield* ui
100
- .withSpinner(`Fetching toolkit "${slug}"...`, repo.getToolkitDetailed(slug))
112
+ .withSpinner(`Fetching toolkit "${slugValue}"...`, repo.getToolkitDetailed(slugValue))
113
.pipe(
114
Effect.catchTag('services/HttpServerError', (e: HttpServerError) =>
115
Effect.gen(function* () {
104
- if (e.status === 404) {
105
- // Try to suggest similar toolkits
106
- const suggestions = yield* repo.searchToolkits({ search: slug, limit: 3 }).pipe(
107
- Effect.map(r => r.items),
108
- Effect.catchAll(() => Effect.succeed([]))
109
- );
116
+ // Show structured error message and suggested fix from the API
117
+ if (e.details) {
118
+ yield* ui.log.error(e.details.message);
119
+ yield* ui.log.step(e.details.suggestedFix);
120
+ } else {
121
+ yield* ui.log.error(`Failed to fetch toolkit "${slugValue}".`);
122
+ }
123
111
- if (suggestions.length > 0) {
112
- const suggestionLines = suggestions
113
- .map(s => ` ${s.slug} — ${s.meta.description}`)
114
- .join('\n');
115
- yield* ui.log.error(
116
- `Toolkit "${slug}" not found.\n\nDid you mean?\n${suggestionLines}\n\n> composio toolkits info "${suggestions[0]!.slug}"`
117
- );
118
- } else {
119
- yield* ui.log.error(`Toolkit "${slug}" not found.`);
120
- }
121
-
122
- return yield* Effect.fail(e);
124
+ // Try to suggest similar toolkits
125
+ const suggestions = yield* repo.searchToolkits({ search: slugValue, limit: 3 }).pipe(
126
+ Effect.map(r => r.items),
127
+ Effect.catchAll(() => Effect.succeed([]))
128
+ );
129
+
130
+ if (suggestions.length > 0) {
131
+ const suggestionLines = suggestions
132
+ .map(s => ` ${s.slug} — ${s.meta.description}`)
133
+ .join('\n');
134
+ yield* ui.log.step(
135
+ `Did you mean?\n${suggestionLines}\n\n> composio toolkits info "${suggestions[0]!.slug}"`
136
+ );
137
}
138
139
return yield* Effect.fail(e);
ts/packages/cli/src/services/composio-clients.ts
+15
@@ -36,12 +36,22 @@ import { renderPrettyError } from './utils/pretty-error';
36
* Error types
37
*/
38
39
+/**
40
+ * Structured error details from the Composio API.
41
+ */
42
+export interface HttpErrorDetails {
43
+ readonly message: string;
44
+ readonly suggestedFix: string;
45
+ readonly code: number;
46
+}
47
+
48
/**
49
* Error thrown when a HTTP request fails.
50
*/
51
export class HttpServerError extends Data.TaggedError('services/HttpServerError')<{
52
readonly cause?: unknown;
53
readonly status?: number;
54
+ readonly details?: HttpErrorDetails;
55
}> {}
56
57
/**
@@ -347,6 +357,11 @@ const handleHttpErrorResponse = (response: Response): Effect.Effect<never, HttpS
357
new HttpServerError({
358
cause: `HTTP ${status}\n${pretty}`,
359
status,
360
+ details: {
361
+ message: error.message,
362
+ suggestedFix: error.suggested_fix,
363
+ code: error.code,
364
+ },
365
})
366
);
367
}
ts/packages/cli/test/src/commands/$default.cmd.test.ts
+1
-1
@@ -88,7 +88,7 @@ describe('CLI: composio', () => {
88
89
- toolkits list [--query text] [--category text] [--limit integer] List available toolkits.
90
91
- - toolkits info <slug> View details of a specific toolkit.
91
+ - toolkits info [<slug>] View details of a specific toolkit.
92
93
- toolkits search [--limit integer] <query> Search toolkits by use case.
94
"
ts/packages/cli/test/src/commands/toolkits/toolkits.info.cmd.test.ts
+35
-1
@@ -160,7 +160,41 @@ describe('CLI: composio toolkits info', () => {
160
const lines = yield* MockConsole.getLines({ stripAnsi: true });
161
const output = lines.join('\n');
162
163
- expect(output).toContain('not found');
163
+ expect(output).toContain('Failed to fetch toolkit "gmal"');
164
+ })
165
+ );
166
+ }
167
+ );
168
+
169
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
170
+ '[Given] invalid slug with substring match',
171
+ it => {
172
+ it.scoped('shows error with suggestion', () =>
173
+ Effect.gen(function* () {
174
+ // "gma" is a substring of "gmail", so the mock will find suggestions
175
+ const result = yield* cli(['toolkits', 'info', 'gma']).pipe(Effect.either);
176
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
177
+ const output = lines.join('\n');
178
+
179
+ expect(output).toContain('Failed to fetch toolkit "gma"');
180
+ expect(output).toContain('Did you mean?');
181
+ expect(output).toContain('gmail');
182
+ })
183
+ );
184
+ }
185
+ );
186
+
187
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
188
+ '[Given] no slug argument',
189
+ it => {
190
+ it.scoped('shows missing argument warning with tip', () =>
191
+ Effect.gen(function* () {
192
+ yield* cli(['toolkits', 'info']);
193
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
194
+ const output = lines.join('\n');
195
+
196
+ expect(output).toContain('Missing required argument');
197
+ expect(output).toContain('composio toolkits info "gmail"');
198
})
199
);
200
}