@devries-cameron20 / composio-1 / commits / 0a8557d6c
Fork 0

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

feat(cli): add `composio tools` command with list, info, search subcommands

Implements PLEN-1583. Agents and developers can now discover, search, and inspect Composio tools directly from the CLI. Subcommands: - `composio tools list` — list tools with --toolkits, --search, --tags, --limit filters - `composio tools info <slug>` — view tool details including input/output JSON schemas - `composio tools search <query>` — search tools by use case with optional --toolkits scope Service layer: - Add searchTools() and getToolDetailed() to ComposioToolkitsRepository - Extract buildToolsNamespace() helper for tools API methods - Add ToolDetailedResponse schema for retrieve endpoint - Pass-through in cached repository layer Tests: - 18 new tests covering list, info, search with various filter combinations - Updated default command snapshots to include tools subcommands

jkomyno committed Feb 19, 2026 at 10:27 UTC 0a8557d6cb3497d4b5bbdb13dfe64054f1a79139
13 files changed +994 -68
ts/packages/cli/src/commands/index.ts
+2
@@ -12,6 +12,7 @@ import { pyCmd } from './py/py.cmd';
12 import { tsCmd } from './ts/ts.cmd';
13 import { generateCmd } from './generate.cmd';
14 import { toolkitsCmd } from './toolkits/toolkits.cmd';
15 +import { toolsCmd } from './tools/tools.cmd';
16
17 const $cmd = $defaultCmd.pipe(
18 Command.withSubcommands([
@@ -24,6 +25,7 @@ const $cmd = $defaultCmd.pipe(
25 pyCmd,
26 tsCmd,
27 toolkitsCmd,
28 + toolsCmd,
29 ])
30 );
31
ts/packages/cli/src/commands/tools/commands/tools.info.cmd.ts new
+98
@@ -0,0 +1,98 @@
1 +import { Args, Command } from '@effect/cli';
2 +import { Effect, Option } from 'effect';
3 +import { ComposioToolkitsRepository, HttpServerError } from 'src/services/composio-clients';
4 +import { ComposioUserContext } from 'src/services/user-context';
5 +import { TerminalUI } from 'src/services/terminal-ui';
6 +import { formatToolInfo } from '../format';
7 +
8 +const slug = Args.text({ name: 'slug' }).pipe(
9 + Args.withDescription('Tool slug (e.g. "GMAIL_SEND_EMAIL")'),
10 + Args.optional
11 +);
12 +
13 +/**
14 + * View details of a specific tool including input/output schemas.
15 + *
16 + * @example
17 + * ```bash
18 + * composio tools info "GMAIL_SEND_EMAIL"
19 + * ```
20 + */
21 +export const toolsCmd$Info = Command.make('info', { slug }, ({ slug }) =>
22 + Effect.gen(function* () {
23 + const ui = yield* TerminalUI;
24 + const ctx = yield* ComposioUserContext;
25 + const repo = yield* ComposioToolkitsRepository;
26 +
27 + // Auth guard
28 + if (Option.isNone(ctx.data.apiKey)) {
29 + yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
30 + return;
31 + }
32 +
33 + // Missing slug guard
34 + if (Option.isNone(slug)) {
35 + yield* ui.log.warn('Missing required argument: <slug>');
36 + yield* ui.log.step(
37 + 'Try specifying a tool slug, e.g.:\n> composio tools info "GMAIL_SEND_EMAIL"'
38 + );
39 + return;
40 + }
41 +
42 + const slugValue = slug.value;
43 +
44 + const toolOpt = yield* ui
45 + .withSpinner(`Fetching tool "${slugValue}"...`, repo.getToolDetailed(slugValue))
46 + .pipe(
47 + Effect.asSome,
48 + Effect.catchTag('services/HttpServerError', (e: HttpServerError) =>
49 + Effect.gen(function* () {
50 + // Show structured error message and suggested fix from the API
51 + if (e.details) {
52 + yield* ui.log.error(e.details.message);
53 + yield* ui.log.step(e.details.suggestedFix);
54 + } else {
55 + yield* ui.log.error(`Tool "${slugValue}" not found.`);
56 + }
57 +
58 + // Try to suggest similar tools
59 + const suggestions = yield* repo.searchTools({ search: slugValue, limit: 3 }).pipe(
60 + Effect.map(r => r.items),
61 + Effect.catchAll(() => Effect.succeed([]))
62 + );
63 +
64 + if (suggestions.length > 0) {
65 + const suggestionLines = suggestions
66 + .map(s => ` ${s.slug} — ${s.description}`)
67 + .join('\n');
68 + yield* ui.log.step(
69 + `Did you mean?\n${suggestionLines}\n\n> composio tools info "${suggestions[0]!.slug}"`
70 + );
71 + } else {
72 + yield* ui.log.step('Browse available tools:\n> composio tools list');
73 + }
74 +
75 + return Option.none();
76 + })
77 + )
78 + );
79 +
80 + if (Option.isNone(toolOpt)) {
81 + return;
82 + }
83 +
84 + const tool = toolOpt.value;
85 +
86 + yield* ui.note(formatToolInfo(tool), `Tool: ${tool.name}`);
87 +
88 + // Next step hint
89 + const toolkitSlug = tool.toolkit.slug;
90 + if (toolkitSlug) {
91 + yield* ui.log.step(
92 + `To list more tools in this toolkit:\n> composio tools list --toolkits "${toolkitSlug}"`
93 + );
94 + }
95 +
96 + yield* ui.output(JSON.stringify(tool, null, 2));
97 + })
98 +).pipe(Command.withDescription('View details of a specific tool.'));
ts/packages/cli/src/commands/tools/commands/tools.list.cmd.ts new
+92
@@ -0,0 +1,92 @@
1 +import { Command, Options } from '@effect/cli';
2 +import { Effect, Option } from 'effect';
3 +import { ComposioToolkitsRepository } from 'src/services/composio-clients';
4 +import { ComposioUserContext } from 'src/services/user-context';
5 +import { TerminalUI } from 'src/services/terminal-ui';
6 +import { formatToolsTable, formatToolsJson } from '../format';
7 +
8 +const search = Options.text('search').pipe(
9 + Options.withDescription('Text search by name, slug, or description'),
10 + Options.optional
11 +);
12 +
13 +const toolkits = Options.text('toolkits').pipe(
14 + Options.withDescription(
15 + 'Filter by toolkit slugs, comma-separated (e.g. "gmail" or "gmail,slack")'
16 + ),
17 + Options.optional
18 +);
19 +
20 +const tags = Options.text('tags').pipe(
21 + Options.withDescription('Filter by tags (e.g. "important")'),
22 + Options.optional
23 +);
24 +
25 +const limit = Options.integer('limit').pipe(
26 + Options.withDefault(30),
27 + Options.withDescription('Number of results per page (1-1000)')
28 +);
29 +
30 +/**
31 + * List available tools with optional filters.
32 + *
33 + * @example
34 + * ```bash
35 + * composio tools list --toolkits "gmail"
36 + * composio tools list --search "send email" --toolkits "gmail"
37 + * composio tools list --tags "important" --limit 10
38 + * ```
39 + */
40 +export const toolsCmd$List = Command.make(
41 + 'list',
42 + { search, toolkits, tags, limit },
43 + ({ search, toolkits, tags, limit }) =>
44 + Effect.gen(function* () {
45 + const ui = yield* TerminalUI;
46 + const ctx = yield* ComposioUserContext;
47 + const repo = yield* ComposioToolkitsRepository;
48 +
49 + // Auth guard
50 + if (Option.isNone(ctx.data.apiKey)) {
51 + yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
52 + return;
53 + }
54 +
55 + const clampedLimit = Math.max(1, Math.min(1000, limit));
56 +
57 + const result = yield* ui.withSpinner(
58 + 'Fetching tools...',
59 + repo.searchTools({
60 + search: Option.getOrUndefined(search),
61 + toolkit_slug: Option.getOrUndefined(toolkits),
62 + tags: Option.getOrUndefined(tags),
63 + limit: clampedLimit,
64 + })
65 + );
66 +
67 + if (result.items.length === 0) {
68 + const hint = Option.isSome(toolkits)
69 + ? `No tools found in toolkit "${toolkits.value}". Verify the toolkit slug with:\n> composio toolkits list`
70 + : 'No tools found. Try broadening your search.';
71 + yield* ui.log.warn(hint);
72 + return;
73 + }
74 +
75 + const showing = result.items.length;
76 + const totalPages = result.total_pages;
77 +
78 + yield* ui.log.info(
79 + totalPages > 1
80 + ? `Listing ${showing} tools (page 1 of ${totalPages})\n\n${formatToolsTable(result.items)}`
81 + : `Fetched ${showing} tools\n\n${formatToolsTable(result.items)}`
82 + );
83 +
84 + // Next step hint
85 + const firstSlug = result.items[0]?.slug;
86 + if (firstSlug) {
87 + yield* ui.log.step(`To view details of a tool:\n> composio tools info "${firstSlug}"`);
88 + }
89 +
90 + yield* ui.output(formatToolsJson(result.items));
91 + })
92 +).pipe(Command.withDescription('List available tools.'));
ts/packages/cli/src/commands/tools/commands/tools.search.cmd.ts new
+73
@@ -0,0 +1,73 @@
1 +import { Args, Command, Options } from '@effect/cli';
2 +import { Effect, Option } from 'effect';
3 +import { ComposioToolkitsRepository } from 'src/services/composio-clients';
4 +import { ComposioUserContext } from 'src/services/user-context';
5 +import { TerminalUI } from 'src/services/terminal-ui';
6 +import { formatToolsTable, formatToolsJson } from '../format';
7 +
8 +const query = Args.text({ name: 'query' }).pipe(
9 + Args.withDescription('Search query (e.g. "send emails")')
10 +);
11 +
12 +const toolkits = Options.text('toolkits').pipe(
13 + Options.withDescription('Filter by toolkit slugs, comma-separated (e.g. "gmail,outlook")'),
14 + Options.optional
15 +);
16 +
17 +const limit = Options.integer('limit').pipe(
18 + Options.withDefault(10),
19 + Options.withDescription('Number of results per page (1-1000)')
20 +);
21 +
22 +/**
23 + * Search tools by use case.
24 + *
25 + * @example
26 + * ```bash
27 + * composio tools search "send emails"
28 + * composio tools search "send emails" --toolkits "gmail,outlook"
29 + * composio tools search "messaging" --limit 5
30 + * ```
31 + */
32 +export const toolsCmd$Search = Command.make(
33 + 'search',
34 + { query, toolkits, limit },
35 + ({ query, toolkits, limit }) =>
36 + Effect.gen(function* () {
37 + const ui = yield* TerminalUI;
38 + const ctx = yield* ComposioUserContext;
39 + const repo = yield* ComposioToolkitsRepository;
40 +
41 + // Auth guard
42 + if (Option.isNone(ctx.data.apiKey)) {
43 + yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
44 + return;
45 + }
46 +
47 + const clampedLimit = Math.max(1, Math.min(1000, limit));
48 +
49 + const result = yield* ui.withSpinner(
50 + `Searching tools for "${query}"...`,
51 + repo.searchTools({
52 + search: query,
53 + toolkit_slug: Option.getOrUndefined(toolkits),
54 + limit: clampedLimit,
55 + })
56 + );
57 +
58 + if (result.items.length === 0) {
59 + yield* ui.log.warn(`No tools found matching "${query}". Try broadening your search.`);
60 + return;
61 + }
62 +
63 + yield* ui.log.info(`Found ${result.items.length} tools\n\n${formatToolsTable(result.items)}`);
64 +
65 + // Next step hint
66 + const firstSlug = result.items[0]?.slug;
67 + if (firstSlug) {
68 + yield* ui.log.step(`To view details:\n> composio tools info "${firstSlug}"`);
69 + }
70 +
71 + yield* ui.output(formatToolsJson(result.items));
72 + })
73 +).pipe(Command.withDescription('Search tools by use case.'));
ts/packages/cli/src/commands/tools/format.ts new
+115
@@ -0,0 +1,115 @@
1 +import type { Tool } from 'src/models/tools';
2 +import type { ToolDetailedResponse } from 'src/services/composio-clients';
3 +import { bold, gray } from 'src/ui/colors';
4 +
5 +/**
6 + * Truncate a string to the given max length, appending "..." if truncated.
7 + */
8 +function truncate(str: string, max: number): string {
9 + if (str.length <= max) return str;
10 + return str.slice(0, max - 3) + '...';
11 +}
12 +
13 +/**
14 + * Format a list of tools as a human-readable table.
15 + */
16 +export function formatToolsTable(tools: ReadonlyArray<Tool>): string {
17 + const header = `${bold('Slug'.padEnd(35))} ${bold('Name'.padEnd(20))} ${bold('Description')}`;
18 +
19 + const rows = tools.map(t => {
20 + const slug = truncate(t.slug, 35).padEnd(35);
21 + const name = truncate(t.name, 20).padEnd(20);
22 + const desc = gray(truncate(t.description, 50));
23 + return `${slug} ${name} ${desc}`;
24 + });
25 +
26 + return [header, ...rows].join('\n');
27 +}
28 +
29 +/**
30 + * Format tools as JSON for piped output.
31 + */
32 +export function formatToolsJson(tools: ReadonlyArray<Tool>): string {
33 + return JSON.stringify(
34 + tools.map(t => ({
35 + slug: t.slug,
36 + name: t.name,
37 + description: t.description,
38 + tags: t.tags,
39 + })),
40 + null,
41 + 2
42 + );
43 +}
44 +
45 +/**
46 + * Format JSON Schema properties as a human-readable parameter table.
47 + * Extracts `properties` entries, cross-references `required` array.
48 + */
49 +function formatSchemaProperties(schema: Record<string, unknown>): string {
50 + const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
51 + if (!properties || Object.keys(properties).length === 0) {
52 + return ' (none)';
53 + }
54 +
55 + const requiredArr = (schema['required'] as string[] | undefined) ?? [];
56 + const requiredSet = new Set(requiredArr);
57 +
58 + const entries = Object.entries(properties).map(([name, prop]) => {
59 + const type = (prop['type'] as string) ?? 'unknown';
60 + const label = requiredSet.has(name) ? 'required' : 'optional';
61 + const description = prop['description'] as string | undefined;
62 + return { name, type, label, description };
63 + });
64 +
65 + if (entries.length === 0) {
66 + return ' (none)';
67 + }
68 +
69 + const nameWidth = Math.max(...entries.map(e => e.name.length));
70 + const typeWidth = Math.max(...entries.map(e => e.type.length));
71 + const labelWidth = Math.max(...entries.map(e => e.label.length));
72 +
73 + return entries
74 + .map(e => {
75 + const desc = e.description ? ` ${gray(`"${truncate(e.description, 50)}"`)}` : '';
76 + return ` ${e.name.padEnd(nameWidth)} ${e.type.padEnd(typeWidth)} ${e.label.padEnd(labelWidth)}${desc}`;
77 + })
78 + .join('\n');
79 +}
80 +
81 +/**
82 + * Format a detailed tool for interactive display.
83 + */
84 +export function formatToolInfo(tool: ToolDetailedResponse): string {
85 + const lines: string[] = [];
86 +
87 + lines.push(`${bold('Name:')} ${tool.name}`);
88 + lines.push(`${bold('Slug:')} ${tool.slug}`);
89 + lines.push(`${bold('Description:')} ${tool.description}`);
90 + lines.push(`${bold('Tags:')} ${tool.tags.length > 0 ? tool.tags.join(', ') : '(none)'}`);
91 +
92 + if (tool.toolkit.slug) {
93 + lines.push(`${bold('Toolkit:')} ${tool.toolkit.name} (${tool.toolkit.slug})`);
94 + }
95 +
96 + if (tool.no_auth) {
97 + lines.push(`${bold('Auth:')} No authentication required`);
98 + }
99 +
100 + if (tool.available_versions.length > 0) {
101 + lines.push(`${bold('Versions:')} ${tool.available_versions.join(', ')}`);
102 + }
103 +
104 + // Input parameters
105 + lines.push('');
106 + lines.push(bold('Input Parameters:'));
107 + lines.push(formatSchemaProperties(tool.input_parameters as Record<string, unknown>));
108 +
109 + // Output parameters
110 + lines.push('');
111 + lines.push(bold('Output Parameters:'));
112 + lines.push(formatSchemaProperties(tool.output_parameters as Record<string, unknown>));
113 +
114 + return lines.join('\n');
115 +}
ts/packages/cli/src/commands/tools/tools.cmd.ts new
+17
@@ -0,0 +1,17 @@
1 +import { Command } from '@effect/cli';
2 +import { toolsCmd$List } from './commands/tools.list.cmd';
3 +import { toolsCmd$Info } from './commands/tools.info.cmd';
4 +import { toolsCmd$Search } from './commands/tools.search.cmd';
5 +
6 +/**
7 + * CLI entry point for tool discovery commands.
8 + *
9 + * @example
10 + * ```bash
11 + * composio tools <command>
12 + * ```
13 + */
14 +export const toolsCmd = Command.make('tools').pipe(
15 + Command.withDescription('Discover and inspect Composio tools.'),
16 + Command.withSubcommands([toolsCmd$List, toolsCmd$Info, toolsCmd$Search])
17 +);
ts/packages/cli/src/services/composio-clients-cached.ts
+3
@@ -245,6 +245,9 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
245 searchToolkits: params => underlyingRepository.searchToolkits(params),
246 getToolkitDetailed: slug => underlyingRepository.getToolkitDetailed(slug),
247 getCategories: () => underlyingRepository.getCategories(),
248 + // Tool search/detail should NOT be cached (query-dependent, should be fresh)
249 + searchTools: params => underlyingRepository.searchTools(params),
250 + getToolDetailed: slug => underlyingRepository.getToolDetailed(slug),
251 });
252 })
253 ).pipe(
ts/packages/cli/src/services/composio-clients.ts
+149 -67
@@ -262,6 +262,25 @@ export const ToolsResponse = Schema.Struct({
262 }).annotations({ identifier: 'ToolsResponse' });
263 export type ToolsResponse = Schema.Schema.Type<typeof ToolsResponse>;
264
265 +export const ToolDetailedResponse = Schema.Struct({
266 + name: Schema.String,
267 + slug: Schema.String,
268 + description: Schema.String,
269 + tags: Schema.Array(Schema.String),
270 + available_versions: Schema.Array(Schema.String),
271 + input_parameters: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
272 + output_parameters: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
273 + no_auth: Schema.optionalWith(Schema.Boolean, { default: () => false }),
274 + toolkit: Schema.optionalWith(
275 + Schema.Struct({
276 + name: Schema.String,
277 + slug: Schema.String,
278 + }),
279 + { default: () => ({ name: '', slug: '' }) }
280 + ),
281 +}).annotations({ identifier: 'ToolDetailedResponse' });
282 +export type ToolDetailedResponse = Schema.Schema.Type<typeof ToolDetailedResponse>;
283 +
284 export const TriggerTypesAsEnumsResponse = TriggerTypesAsEnums;
285 export type TriggerTypesAsEnumsResponse = Schema.Schema.Type<typeof TriggerTypesAsEnumsResponse>;
286
@@ -621,6 +640,119 @@ class ComposioClientSingleton extends Effect.Service<ComposioClientSingleton>()(
640 }
641 ) {}
642
643 +/**
644 + * Build the `tools` namespace for ComposioClientLive.
645 + * Extracted to keep the main generator under the max-lines-per-function limit.
646 + */
647 +function buildToolsNamespace(
648 + clientSingleton: ComposioClientSingleton,
649 + withMetrics: <A, E, R>(
650 + effect: Effect.Effect<{ data: A; metrics: Metrics }, E, R>
651 + ) => Effect.Effect<A, E, R>
652 +) {
653 + return {
654 + /**
655 + * Retrieve a list of all available tool enumeration values (tool slugs) for the project.
656 + */
657 + retrieveEnum: () =>
658 + withMetrics(
659 + callClient(clientSingleton, client => client.tools.retrieveEnum(), ToolsAsEnumsResponse)
660 + ),
661 + /**
662 + * Retrieve a list of tools, automatically handling pagination.
663 + * It always fetches the latest version of tools for each toolkit.
664 + * For more granular toolkit version control, use `listByVersionSpecs`.
665 + * @param toolkitSlugs - Array of toolkit slugs to filter by
666 + */
667 + list: (toolkitSlugs: ReadonlyArray<string>) =>
668 + withMetrics(
669 + callClientWithPagination(
670 + clientSingleton,
671 + (client, cursor, limit) =>
672 + client.tools.list({
673 + cursor,
674 + toolkit_slug: toolkitSlugs.length > 0 ? toolkitSlugs.join(',') : undefined,
675 + toolkit_versions: 'latest',
676 + limit,
677 + }),
678 + ToolsResponse
679 + )
680 + ),
681 + /**
682 + * Retrieve tools for multiple toolkits, grouped by version.
683 + * Makes parallel API calls for each version group, then merges results.
684 + * @param specs - Array of toolkit version specifications
685 + */
686 + listByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
687 + Effect.gen(function* () {
688 + const grouped = groupByVersion(specs);
689 + const versionGroups = [...grouped.entries()];
690 +
691 + // Fetch all version groups in parallel with bounded concurrency
692 + const responses = yield* Effect.all(
693 + versionGroups.map(([version, slugs]) =>
694 + withMetrics(
695 + callClientWithPagination(
696 + clientSingleton,
697 + (client, cursor, limit) =>
698 + client.tools.list({
699 + cursor,
700 + toolkit_slug: slugs.join(','),
701 + toolkit_versions: version,
702 + limit,
703 + }),
704 + ToolsResponse
705 + )
706 + )
707 + ),
708 + { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
709 + );
710 +
711 + // Merge all tools from all version groups
712 + const allTools = responses.flatMap(response => response.items);
713 + return { items: allTools };
714 + }),
715 + /**
716 + * Search tools with optional filters. Returns a single page of results (no auto-pagination).
717 + * @param params - Search/filter parameters
718 + */
719 + search: (params: {
720 + search?: string;
721 + toolkit_slug?: string;
722 + tags?: string;
723 + limit?: number;
724 + cursor?: string;
725 + }) =>
726 + withMetrics(
727 + callClient(
728 + clientSingleton,
729 + client =>
730 + client.tools.list({
731 + search: params.search,
732 + toolkit_slug: params.toolkit_slug,
733 + tags: params.tags ? params.tags.split(',').map(t => t.trim()) : undefined,
734 + limit: params.limit,
735 + cursor: params.cursor,
736 + toolkit_versions: 'latest',
737 + }),
738 + ToolsResponse
739 + )
740 + ),
741 + /**
742 + * Retrieves detailed info about a single tool by slug.
743 + * @param slug - Tool slug (e.g. "GMAIL_SEND_EMAIL")
744 + */
745 + retrieve: (slug: string) =>
746 + withMetrics(
747 + callClient(
748 + clientSingleton,
749 + client => client.tools.retrieve(slug, { toolkit_versions: 'latest' }),
750 + ToolDetailedResponse
751 + )
752 + ),
753 + };
754 +}
755 +
756 // Service that wraps the raw Composio client, which is shared by all client services.
757 export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
758 'services/ComposioClientLive',
@@ -745,73 +877,7 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
877 )
878 ).pipe(Effect.map(response => response.items)),
879 },
748 - tools: {
749 - /**
750 - * Retrieve a list of all available tool enumeration values (tool slugs) for the project.
751 - */
752 - retrieveEnum: () =>
753 - withMetrics(
754 - callClient(
755 - clientSingleton,
756 - client => client.tools.retrieveEnum(),
757 - ToolsAsEnumsResponse
758 - )
759 - ),
760 - /**
761 - * Retrieve a list of tools, automatically handling pagination.
762 - * It always fetches the latest version of tools for each toolkit.
763 - * For more granular toolkit version control, use `listByVersionSpecs`.
764 - * @param toolkitSlugs - Array of toolkit slugs to filter by
765 - */
766 - list: (toolkitSlugs: ReadonlyArray<string>) =>
767 - withMetrics(
768 - callClientWithPagination(
769 - clientSingleton,
770 - (client, cursor, limit) =>
771 - client.tools.list({
772 - cursor,
773 - toolkit_slug: toolkitSlugs.length > 0 ? toolkitSlugs.join(',') : undefined,
774 - toolkit_versions: 'latest',
775 - limit,
776 - }),
777 - ToolsResponse
778 - )
779 - ),
780 - /**
781 - * Retrieve tools for multiple toolkits, grouped by version.
782 - * Makes parallel API calls for each version group, then merges results.
783 - * @param specs - Array of toolkit version specifications
784 - */
785 - listByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
786 - Effect.gen(function* () {
787 - const grouped = groupByVersion(specs);
788 - const versionGroups = [...grouped.entries()];
789 -
790 - // Fetch all version groups in parallel with bounded concurrency
791 - const responses = yield* Effect.all(
792 - versionGroups.map(([version, slugs]) =>
793 - withMetrics(
794 - callClientWithPagination(
795 - clientSingleton,
796 - (client, cursor, limit) =>
797 - client.tools.list({
798 - cursor,
799 - toolkit_slug: slugs.join(','),
800 - toolkit_versions: version,
801 - limit,
802 - }),
803 - ToolsResponse
804 - )
805 - )
806 - ),
807 - { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
808 - );
809 -
810 - // Merge all tools from all version groups
811 - const allTools = responses.flatMap(response => response.items);
812 - return { items: allTools };
813 - }),
814 - },
880 + tools: buildToolsNamespace(clientSingleton, withMetrics),
881 triggersTypes: {
882 /**
883 * Retrieves a list of all available trigger type enum values that can be used across the API.
@@ -1070,6 +1136,22 @@ export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsR
1136 * Retrieves all available toolkit categories.
1137 */
1138 getCategories: () => client.toolkits.retrieveCategories(),
1139 + /**
1140 + * Searches tools with optional filters. Returns a single page of results.
1141 + * @param params - Search/filter parameters
1142 + */
1143 + searchTools: (params: {
1144 + search?: string;
1145 + toolkit_slug?: string;
1146 + tags?: string;
1147 + limit?: number;
1148 + cursor?: string;
1149 + }) => client.tools.search(params),
1150 + /**
1151 + * Retrieves detailed info about a single tool by slug.
1152 + * @param slug - Tool slug (e.g. "GMAIL_SEND_EMAIL")
1153 + */
1154 + getToolDetailed: (slug: string) => client.tools.retrieve(slug),
1155 };
1156 }),
1157 dependencies: [ComposioClientLive.Default],
ts/packages/cli/test/__utils__/services/test-layer.ts
+45
@@ -246,6 +246,51 @@ export const TestLayer = (input?: TestLiveInput) =>
246 next_cursor: null,
247 });
248 },
249 + searchTools: (params: {
250 + search?: string;
251 + toolkit_slug?: string;
252 + tags?: string;
253 + limit?: number;
254 + cursor?: string;
255 + }) => {
256 + let results = [...toolkitsData.tools];
257 +
258 + if (params.toolkit_slug) {
259 + const slugs = params.toolkit_slug.split(',').map(s => s.trim().toUpperCase() + '_');
260 + results = results.filter(t => slugs.some(p => t.slug.toUpperCase().startsWith(p)));
261 + }
262 +
263 + if (params.search) {
264 + const q = params.search.toLowerCase();
265 + results = results.filter(
266 + t =>
267 + t.name.toLowerCase().includes(q) ||
268 + t.slug.toLowerCase().includes(q) ||
269 + t.description.toLowerCase().includes(q)
270 + );
271 + }
272 +
273 + const limit = params.limit ?? 30;
274 + const items = results.slice(0, limit);
275 + return Effect.succeed({
276 + items,
277 + total_pages: Math.ceil(results.length / limit),
278 + next_cursor: null,
279 + });
280 + },
281 + getToolDetailed: (slug: string) => {
282 + const found = toolkitsData.tools.find(t => t.slug.toUpperCase() === slug.toUpperCase());
283 + if (!found) {
284 + return Effect.fail(
285 + new HttpServerError({ cause: `Tool "${slug}" not found`, status: 404 })
286 + );
287 + }
288 + return Effect.succeed({
289 + ...found,
290 + no_auth: false,
291 + toolkit: { name: '', slug: '' },
292 + });
293 + },
294 getToolkitDetailed: (slug: string) => {
295 const found = toolkitsData.detailedToolkits.find(
296 t => t.slug.toLowerCase() === slug.toLowerCase()
ts/packages/cli/test/src/commands/$default.cmd.test.ts
+9 -1
@@ -15,7 +15,7 @@ describe('CLI: composio', () => {
15 expect(result).toEqual(
16 ValidationError.commandMismatch(
17 HelpDoc.p(
18 - "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits'"
18 + "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits', 'tools'"
19 )
20 )
21 );
@@ -91,6 +91,14 @@ describe('CLI: composio', () => {
91 - toolkits info [<slug>] View details of a specific toolkit.
92
93 - toolkits search [--limit integer] <query> Search toolkits by use case.
94 +
95 + - tools Discover and inspect Composio tools.
96 +
97 + - tools list [--search text] [--toolkits text] [--tags text] [--limit integer] List available tools.
98 +
99 + - tools info [<slug>] View details of a specific tool.
100 +
101 + - tools search [--toolkits text] [--limit integer] <query> Search tools by use case.
102 "
103 `);
104 })
ts/packages/cli/test/src/commands/tools/tools.info.cmd.test.ts new
+115
@@ -0,0 +1,115 @@
1 +import { describe, expect, layer } from '@effect/vitest';
2 +import { ConfigProvider, Effect } from 'effect';
3 +import { extendConfigProvider } from 'src/services/config';
4 +import { cli, TestLive, MockConsole } from 'test/__utils__';
5 +import type { TestLiveInput } from 'test/__utils__/services/test-layer';
6 +import type { Tools } from 'src/models/tools';
7 +
8 +const testTools: Tools = [
9 + {
10 + name: 'Send Email',
11 + slug: 'GMAIL_SEND_EMAIL',
12 + description: 'Sends an email to a recipient using Gmail',
13 + tags: ['messaging', 'email'],
14 + available_versions: ['20260101_00'],
15 + input_parameters: {
16 + type: 'object',
17 + properties: {
18 + recipient: { type: 'string', description: 'Email address of recipient' },
19 + subject: { type: 'string', description: 'Email subject line' },
20 + body: { type: 'string', description: 'Email body content' },
21 + cc: { type: 'string', description: 'CC recipients' },
22 + },
23 + required: ['recipient', 'subject', 'body'],
24 + },
25 + output_parameters: {
26 + type: 'object',
27 + properties: {
28 + message_id: { type: 'string', description: 'Unique message identifier' },
29 + status: { type: 'string', description: 'Delivery status' },
30 + },
31 + },
32 + },
33 + {
34 + name: 'Create Draft',
35 + slug: 'GMAIL_CREATE_DRAFT',
36 + description: 'Creates a draft email in Gmail',
37 + tags: ['messaging', 'email'],
38 + available_versions: ['20260101_00'],
39 + input_parameters: { type: 'object', properties: {} },
40 + output_parameters: { type: 'object', properties: {} },
41 + },
42 +];
43 +
44 +const toolkitsData = {
45 + tools: testTools,
46 +} satisfies TestLiveInput['toolkitsData'];
47 +
48 +const testConfigProvider = ConfigProvider.fromMap(
49 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
50 +).pipe(extendConfigProvider);
51 +
52 +describe('CLI: composio tools info', () => {
53 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
54 + '[Given] valid slug [Then] displays tool info',
55 + it => {
56 + it.scoped('shows tool details with input/output schemas', () =>
57 + Effect.gen(function* () {
58 + yield* cli(['tools', 'info', 'GMAIL_SEND_EMAIL']);
59 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
60 + const output = lines.join('\n');
61 +
62 + expect(output).toContain('Send Email');
63 + expect(output).toContain('GMAIL_SEND_EMAIL');
64 + expect(output).toContain('Input Parameters');
65 + expect(output).toContain('recipient');
66 + expect(output).toContain('required');
67 + expect(output).toContain('Output Parameters');
68 + expect(output).toContain('message_id');
69 + })
70 + );
71 + }
72 + );
73 +
74 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
75 + '[Given] no slug [Then] warns missing argument',
76 + it => {
77 + it.scoped('shows missing argument warning', () =>
78 + Effect.gen(function* () {
79 + yield* cli(['tools', 'info']);
80 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
81 + const output = lines.join('\n');
82 +
83 + expect(output).toContain('Missing required argument');
84 + })
85 + );
86 + }
87 + );
88 +
89 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
90 + '[Given] invalid slug [Then] shows error and suggestions',
91 + it => {
92 + it.scoped('shows not found with suggestions', () =>
93 + Effect.gen(function* () {
94 + yield* cli(['tools', 'info', 'NONEXISTENT_TOOL']);
95 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
96 + const output = lines.join('\n');
97 +
98 + expect(output).toContain('not found');
99 + })
100 + );
101 + }
102 + );
103 +
104 + layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
105 + it.scoped('warns user to login', () =>
106 + Effect.gen(function* () {
107 + yield* cli(['tools', 'info', 'GMAIL_SEND_EMAIL']);
108 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
109 + const output = lines.join('\n');
110 +
111 + expect(output).toContain('not logged in');
112 + })
113 + );
114 + });
115 +});
ts/packages/cli/test/src/commands/tools/tools.list.cmd.test.ts new
+168
@@ -0,0 +1,168 @@
1 +import { describe, expect, layer } from '@effect/vitest';
2 +import { ConfigProvider, Effect } from 'effect';
3 +import { extendConfigProvider } from 'src/services/config';
4 +import { cli, TestLive, MockConsole } from 'test/__utils__';
5 +import type { TestLiveInput } from 'test/__utils__/services/test-layer';
6 +import type { Tools } from 'src/models/tools';
7 +
8 +const testTools: Tools = [
9 + {
10 + name: 'Send Email',
11 + slug: 'GMAIL_SEND_EMAIL',
12 + description: 'Sends an email to a recipient using Gmail',
13 + tags: ['messaging', 'email'],
14 + available_versions: ['20260101_00'],
15 + input_parameters: {
16 + type: 'object',
17 + properties: {
18 + recipient: { type: 'string', description: 'Email address' },
19 + body: { type: 'string', description: 'Email body' },
20 + },
21 + required: ['recipient', 'body'],
22 + },
23 + output_parameters: {
24 + type: 'object',
25 + properties: {
26 + message_id: { type: 'string', description: 'Message ID' },
27 + },
28 + },
29 + },
30 + {
31 + name: 'Create Draft',
32 + slug: 'GMAIL_CREATE_DRAFT',
33 + description: 'Creates a draft email in Gmail',
34 + tags: ['messaging', 'email'],
35 + available_versions: ['20260101_00'],
36 + input_parameters: { type: 'object', properties: {} },
37 + output_parameters: { type: 'object', properties: {} },
38 + },
39 + {
40 + name: 'Send Message',
41 + slug: 'SLACK_SEND_MESSAGE',
42 + description: 'Sends a message to a Slack channel',
43 + tags: ['messaging'],
44 + available_versions: ['20260101_00'],
45 + input_parameters: { type: 'object', properties: {} },
46 + output_parameters: { type: 'object', properties: {} },
47 + },
48 +];
49 +
50 +const toolkitsData = {
51 + tools: testTools,
52 +} satisfies TestLiveInput['toolkitsData'];
53 +
54 +const testConfigProvider = ConfigProvider.fromMap(
55 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
56 +).pipe(extendConfigProvider);
57 +
58 +describe('CLI: composio tools list', () => {
59 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
60 + '[Given] no flags [Then] lists all tools',
61 + it => {
62 + it.scoped('lists all tools', () =>
63 + Effect.gen(function* () {
64 + yield* cli(['tools', 'list']);
65 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
66 + const output = lines.join('\n');
67 +
68 + expect(output).toContain('GMAIL_SEND_EMAIL');
69 + expect(output).toContain('SLACK_SEND_MESSAGE');
70 + expect(output).toContain('Fetched 3 tools');
71 + })
72 + );
73 + }
74 + );
75 +
76 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
77 + '[Given] --toolkits "gmail" [Then] lists only gmail tools',
78 + it => {
79 + it.scoped('filters by toolkit', () =>
80 + Effect.gen(function* () {
81 + yield* cli(['tools', 'list', '--toolkits', 'gmail']);
82 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
83 + const output = lines.join('\n');
84 +
85 + expect(output).toContain('GMAIL_SEND_EMAIL');
86 + expect(output).toContain('GMAIL_CREATE_DRAFT');
87 + expect(output).not.toContain('SLACK_SEND_MESSAGE');
88 + expect(output).toContain('Fetched 2 tools');
89 + })
90 + );
91 + }
92 + );
93 +
94 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
95 + '[Given] --search "send" [Then] shows filtered results',
96 + it => {
97 + it.scoped('filters by search query', () =>
98 + Effect.gen(function* () {
99 + yield* cli(['tools', 'list', '--search', 'send']);
100 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
101 + const output = lines.join('\n');
102 +
103 + expect(output).toContain('GMAIL_SEND_EMAIL');
104 + expect(output).toContain('SLACK_SEND_MESSAGE');
105 + expect(output).not.toContain('GMAIL_CREATE_DRAFT');
106 + })
107 + );
108 + }
109 + );
110 +
111 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
112 + '[Given] --limit 2 [Then] respects limit',
113 + it => {
114 + it.scoped('respects limit', () =>
115 + Effect.gen(function* () {
116 + yield* cli(['tools', 'list', '--limit', '2']);
117 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
118 + const output = lines.join('\n');
119 +
120 + expect(output).toContain('Listing 2 tools');
121 + })
122 + );
123 + }
124 + );
125 +
126 + layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
127 + it.scoped('warns user to login', () =>
128 + Effect.gen(function* () {
129 + yield* cli(['tools', 'list']);
130 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
131 + const output = lines.join('\n');
132 +
133 + expect(output).toContain('not logged in');
134 + })
135 + );
136 + });
137 +
138 + layer(TestLive({ baseConfigProvider: testConfigProvider }))(
139 + '[Given] empty results [Then] shows no tools found',
140 + it => {
141 + it.scoped('shows no tools found', () =>
142 + Effect.gen(function* () {
143 + yield* cli(['tools', 'list']);
144 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
145 + const output = lines.join('\n');
146 +
147 + expect(output).toContain('No tools found');
148 + })
149 + );
150 + }
151 + );
152 +
153 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
154 + '[Given] --toolkits "nonexistent" [Then] shows no tools found with hint',
155 + it => {
156 + it.scoped('shows hint about verifying toolkit slug', () =>
157 + Effect.gen(function* () {
158 + yield* cli(['tools', 'list', '--toolkits', 'nonexistent']);
159 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
160 + const output = lines.join('\n');
161 +
162 + expect(output).toContain('No tools found');
163 + expect(output).toContain('composio toolkits list');
164 + })
165 + );
166 + }
167 + );
168 +});
ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts new
+108
@@ -0,0 +1,108 @@
1 +import { describe, expect, layer } from '@effect/vitest';
2 +import { ConfigProvider, Effect } from 'effect';
3 +import { extendConfigProvider } from 'src/services/config';
4 +import { cli, TestLive, MockConsole } from 'test/__utils__';
5 +import type { TestLiveInput } from 'test/__utils__/services/test-layer';
6 +import type { Tools } from 'src/models/tools';
7 +
8 +const testTools: Tools = [
9 + {
10 + name: 'Send Email',
11 + slug: 'GMAIL_SEND_EMAIL',
12 + description: 'Sends an email to a recipient using Gmail',
13 + tags: ['messaging', 'email'],
14 + available_versions: ['20260101_00'],
15 + input_parameters: { type: 'object', properties: {} },
16 + output_parameters: { type: 'object', properties: {} },
17 + },
18 + {
19 + name: 'Send Message',
20 + slug: 'SLACK_SEND_MESSAGE',
21 + description: 'Sends a message to a Slack channel',
22 + tags: ['messaging'],
23 + available_versions: ['20260101_00'],
24 + input_parameters: { type: 'object', properties: {} },
25 + output_parameters: { type: 'object', properties: {} },
26 + },
27 + {
28 + name: 'Create Issue',
29 + slug: 'GITHUB_CREATE_ISSUE',
30 + description: 'Creates a new issue in a GitHub repository',
31 + tags: ['development'],
32 + available_versions: ['20260101_00'],
33 + input_parameters: { type: 'object', properties: {} },
34 + output_parameters: { type: 'object', properties: {} },
35 + },
36 +];
37 +
38 +const toolkitsData = {
39 + tools: testTools,
40 +} satisfies TestLiveInput['toolkitsData'];
41 +
42 +const testConfigProvider = ConfigProvider.fromMap(
43 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
44 +).pipe(extendConfigProvider);
45 +
46 +describe('CLI: composio tools search', () => {
47 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
48 + '[Given] query "send" [Then] returns matching tools',
49 + it => {
50 + it.scoped('returns matching tools', () =>
51 + Effect.gen(function* () {
52 + yield* cli(['tools', 'search', 'send']);
53 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
54 + const output = lines.join('\n');
55 +
56 + expect(output).toContain('GMAIL_SEND_EMAIL');
57 + expect(output).toContain('SLACK_SEND_MESSAGE');
58 + expect(output).not.toContain('GITHUB_CREATE_ISSUE');
59 + expect(output).toContain('Found 2 tools');
60 + })
61 + );
62 + }
63 + );
64 +
65 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
66 + '[Given] query with no results [Then] shows not found message',
67 + it => {
68 + it.scoped('shows not found message', () =>
69 + Effect.gen(function* () {
70 + yield* cli(['tools', 'search', 'nonexistent_query']);
71 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
72 + const output = lines.join('\n');
73 +
74 + expect(output).toContain('No tools found');
75 + })
76 + );
77 + }
78 + );
79 +
80 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
81 + '[Given] query "send" --toolkits "gmail" [Then] scopes to toolkit',
82 + it => {
83 + it.scoped('scopes search to toolkit', () =>
84 + Effect.gen(function* () {
85 + yield* cli(['tools', 'search', 'send', '--toolkits', 'gmail']);
86 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
87 + const output = lines.join('\n');
88 +
89 + expect(output).toContain('GMAIL_SEND_EMAIL');
90 + expect(output).not.toContain('SLACK_SEND_MESSAGE');
91 + expect(output).toContain('Found 1 tools');
92 + })
93 + );
94 + }
95 + );
96 +
97 + layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
98 + it.scoped('warns user to login', () =>
99 + Effect.gen(function* () {
100 + yield* cli(['tools', 'search', 'send']);
101 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
102 + const output = lines.join('\n');
103 +
104 + expect(output).toContain('not logged in');
105 + })
106 + );
107 + });
108 +});