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.

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

jkomyno0a8557d6cb34
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index 1f198384d..1c4c8959d 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -12,6 +12,7 @@ import { pyCmd } from './py/py.cmd';
import { tsCmd } from './ts/ts.cmd';
import { generateCmd } from './generate.cmd';
import { toolkitsCmd } from './toolkits/toolkits.cmd';
+import { toolsCmd } from './tools/tools.cmd';
const $cmd = $defaultCmd.pipe(
Command.withSubcommands([
@@ -24,6 +25,7 @@ const $cmd = $defaultCmd.pipe(
pyCmd,
tsCmd,
toolkitsCmd,
+ toolsCmd,
])
);
diff --git a/ts/packages/cli/src/commands/tools/commands/tools.info.cmd.ts b/ts/packages/cli/src/commands/tools/commands/tools.info.cmd.ts
new file mode 100644
index 000000000..8b77a4e7e
--- /dev/null
+++ b/ts/packages/cli/src/commands/tools/commands/tools.info.cmd.ts
@@ -0,0 +1,98 @@
+import { Args, Command } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { ComposioToolkitsRepository, HttpServerError } from 'src/services/composio-clients';
+import { ComposioUserContext } from 'src/services/user-context';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { formatToolInfo } from '../format';
+
+const slug = Args.text({ name: 'slug' }).pipe(
+ Args.withDescription('Tool slug (e.g. "GMAIL_SEND_EMAIL")'),
+ Args.optional
+);
+
+/**
+ * View details of a specific tool including input/output schemas.
+ *
+ * @example
+ * ```bash
+ * composio tools info "GMAIL_SEND_EMAIL"
+ * ```
+ */
+export const toolsCmd$Info = Command.make('info', { slug }, ({ slug }) =>
+ Effect.gen(function* () {
+ const ui = yield* TerminalUI;
+ const ctx = yield* ComposioUserContext;
+ const repo = yield* ComposioToolkitsRepository;
+
+ // Auth guard
+ if (Option.isNone(ctx.data.apiKey)) {
+ yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
+ return;
+ }
+
+ // Missing slug guard
+ if (Option.isNone(slug)) {
+ yield* ui.log.warn('Missing required argument: <slug>');
+ yield* ui.log.step(
+ 'Try specifying a tool slug, e.g.:\n> composio tools info "GMAIL_SEND_EMAIL"'
+ );
+ return;
+ }
+
+ const slugValue = slug.value;
+
+ const toolOpt = yield* ui
+ .withSpinner(`Fetching tool "${slugValue}"...`, repo.getToolDetailed(slugValue))
+ .pipe(
+ Effect.asSome,
+ Effect.catchTag('services/HttpServerError', (e: HttpServerError) =>
+ Effect.gen(function* () {
+ // Show structured error message and suggested fix from the API
+ if (e.details) {
+ yield* ui.log.error(e.details.message);
+ yield* ui.log.step(e.details.suggestedFix);
+ } else {
+ yield* ui.log.error(`Tool "${slugValue}" not found.`);
+ }
+
+ // Try to suggest similar tools
+ const suggestions = yield* repo.searchTools({ search: slugValue, limit: 3 }).pipe(
+ Effect.map(r => r.items),
+ Effect.catchAll(() => Effect.succeed([]))
+ );
+
+ if (suggestions.length > 0) {
+ const suggestionLines = suggestions
+ .map(s => ` ${s.slug} — ${s.description}`)
+ .join('\n');
+ yield* ui.log.step(
+ `Did you mean?\n${suggestionLines}\n\n> composio tools info "${suggestions[0]!.slug}"`
+ );
+ } else {
+ yield* ui.log.step('Browse available tools:\n> composio tools list');
+ }
+
+ return Option.none();
+ })
+ )
+ );
+
+ if (Option.isNone(toolOpt)) {
+ return;
+ }
+
+ const tool = toolOpt.value;
+
+ yield* ui.note(formatToolInfo(tool), `Tool: ${tool.name}`);
+
+ // Next step hint
+ const toolkitSlug = tool.toolkit.slug;
+ if (toolkitSlug) {
+ yield* ui.log.step(
+ `To list more tools in this toolkit:\n> composio tools list --toolkits "${toolkitSlug}"`
+ );
+ }
+
+ yield* ui.output(JSON.stringify(tool, null, 2));
+ })
+).pipe(Command.withDescription('View details of a specific tool.'));
diff --git a/ts/packages/cli/src/commands/tools/commands/tools.list.cmd.ts b/ts/packages/cli/src/commands/tools/commands/tools.list.cmd.ts
new file mode 100644
index 000000000..822a3ed99
--- /dev/null
+++ b/ts/packages/cli/src/commands/tools/commands/tools.list.cmd.ts
@@ -0,0 +1,92 @@
+import { Command, Options } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { ComposioToolkitsRepository } from 'src/services/composio-clients';
+import { ComposioUserContext } from 'src/services/user-context';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { formatToolsTable, formatToolsJson } from '../format';
+
+const search = Options.text('search').pipe(
+ Options.withDescription('Text search by name, slug, or description'),
+ Options.optional
+);
+
+const toolkits = Options.text('toolkits').pipe(
+ Options.withDescription(
+ 'Filter by toolkit slugs, comma-separated (e.g. "gmail" or "gmail,slack")'
+ ),
+ Options.optional
+);
+
+const tags = Options.text('tags').pipe(
+ Options.withDescription('Filter by tags (e.g. "important")'),
+ Options.optional
+);
+
+const limit = Options.integer('limit').pipe(
+ Options.withDefault(30),
+ Options.withDescription('Number of results per page (1-1000)')
+);
+
+/**
+ * List available tools with optional filters.
+ *
+ * @example
+ * ```bash
+ * composio tools list --toolkits "gmail"
+ * composio tools list --search "send email" --toolkits "gmail"
+ * composio tools list --tags "important" --limit 10
+ * ```
+ */
+export const toolsCmd$List = Command.make(
+ 'list',
+ { search, toolkits, tags, limit },
+ ({ search, toolkits, tags, limit }) =>
+ Effect.gen(function* () {
+ const ui = yield* TerminalUI;
+ const ctx = yield* ComposioUserContext;
+ const repo = yield* ComposioToolkitsRepository;
+
+ // Auth guard
+ if (Option.isNone(ctx.data.apiKey)) {
+ yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
+ return;
+ }
+
+ const clampedLimit = Math.max(1, Math.min(1000, limit));
+
+ const result = yield* ui.withSpinner(
+ 'Fetching tools...',
+ repo.searchTools({
+ search: Option.getOrUndefined(search),
+ toolkit_slug: Option.getOrUndefined(toolkits),
+ tags: Option.getOrUndefined(tags),
+ limit: clampedLimit,
+ })
+ );
+
+ if (result.items.length === 0) {
+ const hint = Option.isSome(toolkits)
+ ? `No tools found in toolkit "${toolkits.value}". Verify the toolkit slug with:\n> composio toolkits list`
+ : 'No tools found. Try broadening your search.';
+ yield* ui.log.warn(hint);
+ return;
+ }
+
+ const showing = result.items.length;
+ const totalPages = result.total_pages;
+
+ yield* ui.log.info(
+ totalPages > 1
+ ? `Listing ${showing} tools (page 1 of ${totalPages})\n\n${formatToolsTable(result.items)}`
+ : `Fetched ${showing} tools\n\n${formatToolsTable(result.items)}`
+ );
+
+ // Next step hint
+ const firstSlug = result.items[0]?.slug;
+ if (firstSlug) {
+ yield* ui.log.step(`To view details of a tool:\n> composio tools info "${firstSlug}"`);
+ }
+
+ yield* ui.output(formatToolsJson(result.items));
+ })
+).pipe(Command.withDescription('List available tools.'));
diff --git a/ts/packages/cli/src/commands/tools/commands/tools.search.cmd.ts b/ts/packages/cli/src/commands/tools/commands/tools.search.cmd.ts
new file mode 100644
index 000000000..c138e6763
--- /dev/null
+++ b/ts/packages/cli/src/commands/tools/commands/tools.search.cmd.ts
@@ -0,0 +1,73 @@
+import { Args, Command, Options } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { ComposioToolkitsRepository } from 'src/services/composio-clients';
+import { ComposioUserContext } from 'src/services/user-context';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { formatToolsTable, formatToolsJson } from '../format';
+
+const query = Args.text({ name: 'query' }).pipe(
+ Args.withDescription('Search query (e.g. "send emails")')
+);
+
+const toolkits = Options.text('toolkits').pipe(
+ Options.withDescription('Filter by toolkit slugs, comma-separated (e.g. "gmail,outlook")'),
+ Options.optional
+);
+
+const limit = Options.integer('limit').pipe(
+ Options.withDefault(10),
+ Options.withDescription('Number of results per page (1-1000)')
+);
+
+/**
+ * Search tools by use case.
+ *
+ * @example
+ * ```bash
+ * composio tools search "send emails"
+ * composio tools search "send emails" --toolkits "gmail,outlook"
+ * composio tools search "messaging" --limit 5
+ * ```
+ */
+export const toolsCmd$Search = Command.make(
+ 'search',
+ { query, toolkits, limit },
+ ({ query, toolkits, limit }) =>
+ Effect.gen(function* () {
+ const ui = yield* TerminalUI;
+ const ctx = yield* ComposioUserContext;
+ const repo = yield* ComposioToolkitsRepository;
+
+ // Auth guard
+ if (Option.isNone(ctx.data.apiKey)) {
+ yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
+ return;
+ }
+
+ const clampedLimit = Math.max(1, Math.min(1000, limit));
+
+ const result = yield* ui.withSpinner(
+ `Searching tools for "${query}"...`,
+ repo.searchTools({
+ search: query,
+ toolkit_slug: Option.getOrUndefined(toolkits),
+ limit: clampedLimit,
+ })
+ );
+
+ if (result.items.length === 0) {
+ yield* ui.log.warn(`No tools found matching "${query}". Try broadening your search.`);
+ return;
+ }
+
+ yield* ui.log.info(`Found ${result.items.length} tools\n\n${formatToolsTable(result.items)}`);
+
+ // Next step hint
+ const firstSlug = result.items[0]?.slug;
+ if (firstSlug) {
+ yield* ui.log.step(`To view details:\n> composio tools info "${firstSlug}"`);
+ }
+
+ yield* ui.output(formatToolsJson(result.items));
+ })
+).pipe(Command.withDescription('Search tools by use case.'));
diff --git a/ts/packages/cli/src/commands/tools/format.ts b/ts/packages/cli/src/commands/tools/format.ts
new file mode 100644
index 000000000..c15e3b8f5
--- /dev/null
+++ b/ts/packages/cli/src/commands/tools/format.ts
@@ -0,0 +1,115 @@
+import type { Tool } from 'src/models/tools';
+import type { ToolDetailedResponse } from 'src/services/composio-clients';
+import { bold, gray } from 'src/ui/colors';
+
+/**
+ * Truncate a string to the given max length, appending "..." if truncated.
+ */
+function truncate(str: string, max: number): string {
+ if (str.length <= max) return str;
+ return str.slice(0, max - 3) + '...';
+}
+
+/**
+ * Format a list of tools as a human-readable table.
+ */
+export function formatToolsTable(tools: ReadonlyArray<Tool>): string {
+ const header = `${bold('Slug'.padEnd(35))} ${bold('Name'.padEnd(20))} ${bold('Description')}`;
+
+ const rows = tools.map(t => {
+ const slug = truncate(t.slug, 35).padEnd(35);
+ const name = truncate(t.name, 20).padEnd(20);
+ const desc = gray(truncate(t.description, 50));
+ return `${slug} ${name} ${desc}`;
+ });
+
+ return [header, ...rows].join('\n');
+}
+
+/**
+ * Format tools as JSON for piped output.
+ */
+export function formatToolsJson(tools: ReadonlyArray<Tool>): string {
+ return JSON.stringify(
+ tools.map(t => ({
+ slug: t.slug,
+ name: t.name,
+ description: t.description,
+ tags: t.tags,
+ })),
+ null,
+ 2
+ );
+}
+
+/**
+ * Format JSON Schema properties as a human-readable parameter table.
+ * Extracts `properties` entries, cross-references `required` array.
+ */
+function formatSchemaProperties(schema: Record<string, unknown>): string {
+ const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
+ if (!properties || Object.keys(properties).length === 0) {
+ return ' (none)';
+ }
+
+ const requiredArr = (schema['required'] as string[] | undefined) ?? [];
+ const requiredSet = new Set(requiredArr);
+
+ const entries = Object.entries(properties).map(([name, prop]) => {
+ const type = (prop['type'] as string) ?? 'unknown';
+ const label = requiredSet.has(name) ? 'required' : 'optional';
+ const description = prop['description'] as string | undefined;
+ return { name, type, label, description };
+ });
+
+ if (entries.length === 0) {
+ return ' (none)';
+ }
+
+ const nameWidth = Math.max(...entries.map(e => e.name.length));
+ const typeWidth = Math.max(...entries.map(e => e.type.length));
+ const labelWidth = Math.max(...entries.map(e => e.label.length));
+
+ return entries
+ .map(e => {
+ const desc = e.description ? ` ${gray(`"${truncate(e.description, 50)}"`)}` : '';
+ return ` ${e.name.padEnd(nameWidth)} ${e.type.padEnd(typeWidth)} ${e.label.padEnd(labelWidth)}${desc}`;
+ })
+ .join('\n');
+}
+
+/**
+ * Format a detailed tool for interactive display.
+ */
+export function formatToolInfo(tool: ToolDetailedResponse): string {
+ const lines: string[] = [];
+
+ lines.push(`${bold('Name:')} ${tool.name}`);
+ lines.push(`${bold('Slug:')} ${tool.slug}`);
+ lines.push(`${bold('Description:')} ${tool.description}`);
+ lines.push(`${bold('Tags:')} ${tool.tags.length > 0 ? tool.tags.join(', ') : '(none)'}`);
+
+ if (tool.toolkit.slug) {
+ lines.push(`${bold('Toolkit:')} ${tool.toolkit.name} (${tool.toolkit.slug})`);
+ }
+
+ if (tool.no_auth) {
+ lines.push(`${bold('Auth:')} No authentication required`);
+ }
+
+ if (tool.available_versions.length > 0) {
+ lines.push(`${bold('Versions:')} ${tool.available_versions.join(', ')}`);
+ }
+
+ // Input parameters
+ lines.push('');
+ lines.push(bold('Input Parameters:'));
+ lines.push(formatSchemaProperties(tool.input_parameters as Record<string, unknown>));
+
+ // Output parameters
+ lines.push('');
+ lines.push(bold('Output Parameters:'));
+ lines.push(formatSchemaProperties(tool.output_parameters as Record<string, unknown>));
+
+ return lines.join('\n');
+}
diff --git a/ts/packages/cli/src/commands/tools/tools.cmd.ts b/ts/packages/cli/src/commands/tools/tools.cmd.ts
new file mode 100644
index 000000000..d5602080e
--- /dev/null
+++ b/ts/packages/cli/src/commands/tools/tools.cmd.ts
@@ -0,0 +1,17 @@
+import { Command } from '@effect/cli';
+import { toolsCmd$List } from './commands/tools.list.cmd';
+import { toolsCmd$Info } from './commands/tools.info.cmd';
+import { toolsCmd$Search } from './commands/tools.search.cmd';
+
+/**
+ * CLI entry point for tool discovery commands.
+ *
+ * @example
+ * ```bash
+ * composio tools <command>
+ * ```
+ */
+export const toolsCmd = Command.make('tools').pipe(
+ Command.withDescription('Discover and inspect Composio tools.'),
+ Command.withSubcommands([toolsCmd$List, toolsCmd$Info, toolsCmd$Search])
+);
diff --git a/ts/packages/cli/src/services/composio-clients-cached.ts b/ts/packages/cli/src/services/composio-clients-cached.ts
index a9f80446a..53abf214c 100644
--- a/ts/packages/cli/src/services/composio-clients-cached.ts
+++ b/ts/packages/cli/src/services/composio-clients-cached.ts
@@ -245,6 +245,9 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
searchToolkits: params => underlyingRepository.searchToolkits(params),
getToolkitDetailed: slug => underlyingRepository.getToolkitDetailed(slug),
getCategories: () => underlyingRepository.getCategories(),
+ // Tool search/detail should NOT be cached (query-dependent, should be fresh)
+ searchTools: params => underlyingRepository.searchTools(params),
+ getToolDetailed: slug => underlyingRepository.getToolDetailed(slug),
});
})
).pipe(
diff --git a/ts/packages/cli/src/services/composio-clients.ts b/ts/packages/cli/src/services/composio-clients.ts
index 03eaa49b9..80e8bdb91 100644
--- a/ts/packages/cli/src/services/composio-clients.ts
+++ b/ts/packages/cli/src/services/composio-clients.ts
@@ -262,6 +262,25 @@ export const ToolsResponse = Schema.Struct({
}).annotations({ identifier: 'ToolsResponse' });
export type ToolsResponse = Schema.Schema.Type<typeof ToolsResponse>;
+export const ToolDetailedResponse = Schema.Struct({
+ name: Schema.String,
+ slug: Schema.String,
+ description: Schema.String,
+ tags: Schema.Array(Schema.String),
+ available_versions: Schema.Array(Schema.String),
+ input_parameters: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+ output_parameters: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+ no_auth: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+ toolkit: Schema.optionalWith(
+ Schema.Struct({
+ name: Schema.String,
+ slug: Schema.String,
+ }),
+ { default: () => ({ name: '', slug: '' }) }
+ ),
+}).annotations({ identifier: 'ToolDetailedResponse' });
+export type ToolDetailedResponse = Schema.Schema.Type<typeof ToolDetailedResponse>;
+
export const TriggerTypesAsEnumsResponse = TriggerTypesAsEnums;
export type TriggerTypesAsEnumsResponse = Schema.Schema.Type<typeof TriggerTypesAsEnumsResponse>;
@@ -621,6 +640,119 @@ class ComposioClientSingleton extends Effect.Service<ComposioClientSingleton>()(
}
) {}
+/**
+ * Build the `tools` namespace for ComposioClientLive.
+ * Extracted to keep the main generator under the max-lines-per-function limit.
+ */
+function buildToolsNamespace(
+ clientSingleton: ComposioClientSingleton,
+ withMetrics: <A, E, R>(
+ effect: Effect.Effect<{ data: A; metrics: Metrics }, E, R>
+ ) => Effect.Effect<A, E, R>
+) {
+ return {
+ /**
+ * Retrieve a list of all available tool enumeration values (tool slugs) for the project.
+ */
+ retrieveEnum: () =>
+ withMetrics(
+ callClient(clientSingleton, client => client.tools.retrieveEnum(), ToolsAsEnumsResponse)
+ ),
+ /**
+ * Retrieve a list of tools, automatically handling pagination.
+ * It always fetches the latest version of tools for each toolkit.
+ * For more granular toolkit version control, use `listByVersionSpecs`.
+ * @param toolkitSlugs - Array of toolkit slugs to filter by
+ */
+ list: (toolkitSlugs: ReadonlyArray<string>) =>
+ withMetrics(
+ callClientWithPagination(
+ clientSingleton,
+ (client, cursor, limit) =>
+ client.tools.list({
+ cursor,
+ toolkit_slug: toolkitSlugs.length > 0 ? toolkitSlugs.join(',') : undefined,
+ toolkit_versions: 'latest',
+ limit,
+ }),
+ ToolsResponse
+ )
+ ),
+ /**
+ * Retrieve tools for multiple toolkits, grouped by version.
+ * Makes parallel API calls for each version group, then merges results.
+ * @param specs - Array of toolkit version specifications
+ */
+ listByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
+ Effect.gen(function* () {
+ const grouped = groupByVersion(specs);
+ const versionGroups = [...grouped.entries()];
+
+ // Fetch all version groups in parallel with bounded concurrency
+ const responses = yield* Effect.all(
+ versionGroups.map(([version, slugs]) =>
+ withMetrics(
+ callClientWithPagination(
+ clientSingleton,
+ (client, cursor, limit) =>
+ client.tools.list({
+ cursor,
+ toolkit_slug: slugs.join(','),
+ toolkit_versions: version,
+ limit,
+ }),
+ ToolsResponse
+ )
+ )
+ ),
+ { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
+ );
+
+ // Merge all tools from all version groups
+ const allTools = responses.flatMap(response => response.items);
+ return { items: allTools };
+ }),
+ /**
+ * Search tools with optional filters. Returns a single page of results (no auto-pagination).
+ * @param params - Search/filter parameters
+ */
+ search: (params: {
+ search?: string;
+ toolkit_slug?: string;
+ tags?: string;
+ limit?: number;
+ cursor?: string;
+ }) =>
+ withMetrics(
+ callClient(
+ clientSingleton,
+ client =>
+ client.tools.list({
+ search: params.search,
+ toolkit_slug: params.toolkit_slug,
+ tags: params.tags ? params.tags.split(',').map(t => t.trim()) : undefined,
+ limit: params.limit,
+ cursor: params.cursor,
+ toolkit_versions: 'latest',
+ }),
+ ToolsResponse
+ )
+ ),
+ /**
+ * Retrieves detailed info about a single tool by slug.
+ * @param slug - Tool slug (e.g. "GMAIL_SEND_EMAIL")
+ */
+ retrieve: (slug: string) =>
+ withMetrics(
+ callClient(
+ clientSingleton,
+ client => client.tools.retrieve(slug, { toolkit_versions: 'latest' }),
+ ToolDetailedResponse
+ )
+ ),
+ };
+}
+
// Service that wraps the raw Composio client, which is shared by all client services.
export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
'services/ComposioClientLive',
@@ -745,73 +877,7 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
)
).pipe(Effect.map(response => response.items)),
},
- tools: {
- /**
- * Retrieve a list of all available tool enumeration values (tool slugs) for the project.
- */
- retrieveEnum: () =>
- withMetrics(
- callClient(
- clientSingleton,
- client => client.tools.retrieveEnum(),
- ToolsAsEnumsResponse
- )
- ),
- /**
- * Retrieve a list of tools, automatically handling pagination.
- * It always fetches the latest version of tools for each toolkit.
- * For more granular toolkit version control, use `listByVersionSpecs`.
- * @param toolkitSlugs - Array of toolkit slugs to filter by
- */
- list: (toolkitSlugs: ReadonlyArray<string>) =>
- withMetrics(
- callClientWithPagination(
- clientSingleton,
- (client, cursor, limit) =>
- client.tools.list({
- cursor,
- toolkit_slug: toolkitSlugs.length > 0 ? toolkitSlugs.join(',') : undefined,
- toolkit_versions: 'latest',
- limit,
- }),
- ToolsResponse
- )
- ),
- /**
- * Retrieve tools for multiple toolkits, grouped by version.
- * Makes parallel API calls for each version group, then merges results.
- * @param specs - Array of toolkit version specifications
- */
- listByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
- Effect.gen(function* () {
- const grouped = groupByVersion(specs);
- const versionGroups = [...grouped.entries()];
-
- // Fetch all version groups in parallel with bounded concurrency
- const responses = yield* Effect.all(
- versionGroups.map(([version, slugs]) =>
- withMetrics(
- callClientWithPagination(
- clientSingleton,
- (client, cursor, limit) =>
- client.tools.list({
- cursor,
- toolkit_slug: slugs.join(','),
- toolkit_versions: version,
- limit,
- }),
- ToolsResponse
- )
- )
- ),
- { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
- );
-
- // Merge all tools from all version groups
- const allTools = responses.flatMap(response => response.items);
- return { items: allTools };
- }),
- },
+ tools: buildToolsNamespace(clientSingleton, withMetrics),
triggersTypes: {
/**
* 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
* Retrieves all available toolkit categories.
*/
getCategories: () => client.toolkits.retrieveCategories(),
+ /**
+ * Searches tools with optional filters. Returns a single page of results.
+ * @param params - Search/filter parameters
+ */
+ searchTools: (params: {
+ search?: string;
+ toolkit_slug?: string;
+ tags?: string;
+ limit?: number;
+ cursor?: string;
+ }) => client.tools.search(params),
+ /**
+ * Retrieves detailed info about a single tool by slug.
+ * @param slug - Tool slug (e.g. "GMAIL_SEND_EMAIL")
+ */
+ getToolDetailed: (slug: string) => client.tools.retrieve(slug),
};
}),
dependencies: [ComposioClientLive.Default],
diff --git a/ts/packages/cli/test/__utils__/services/test-layer.ts b/ts/packages/cli/test/__utils__/services/test-layer.ts
index 94731e60b..115d077f1 100644
--- a/ts/packages/cli/test/__utils__/services/test-layer.ts
+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts
@@ -246,6 +246,51 @@ export const TestLayer = (input?: TestLiveInput) =>
next_cursor: null,
});
},
+ searchTools: (params: {
+ search?: string;
+ toolkit_slug?: string;
+ tags?: string;
+ limit?: number;
+ cursor?: string;
+ }) => {
+ let results = [...toolkitsData.tools];
+
+ if (params.toolkit_slug) {
+ const slugs = params.toolkit_slug.split(',').map(s => s.trim().toUpperCase() + '_');
+ results = results.filter(t => slugs.some(p => t.slug.toUpperCase().startsWith(p)));
+ }
+
+ if (params.search) {
+ const q = params.search.toLowerCase();
+ results = results.filter(
+ t =>
+ t.name.toLowerCase().includes(q) ||
+ t.slug.toLowerCase().includes(q) ||
+ t.description.toLowerCase().includes(q)
+ );
+ }
+
+ const limit = params.limit ?? 30;
+ const items = results.slice(0, limit);
+ return Effect.succeed({
+ items,
+ total_pages: Math.ceil(results.length / limit),
+ next_cursor: null,
+ });
+ },
+ getToolDetailed: (slug: string) => {
+ const found = toolkitsData.tools.find(t => t.slug.toUpperCase() === slug.toUpperCase());
+ if (!found) {
+ return Effect.fail(
+ new HttpServerError({ cause: `Tool "${slug}" not found`, status: 404 })
+ );
+ }
+ return Effect.succeed({
+ ...found,
+ no_auth: false,
+ toolkit: { name: '', slug: '' },
+ });
+ },
getToolkitDetailed: (slug: string) => {
const found = toolkitsData.detailedToolkits.find(
t => t.slug.toLowerCase() === slug.toLowerCase()
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 a8f76925f..b0419f739 100644
--- a/ts/packages/cli/test/src/commands/$default.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
@@ -15,7 +15,7 @@ describe('CLI: composio', () => {
expect(result).toEqual(
ValidationError.commandMismatch(
HelpDoc.p(
- "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits'"
+ "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits', 'tools'"
)
)
);
@@ -91,6 +91,14 @@ describe('CLI: composio', () => {
- toolkits info [<slug>] View details of a specific toolkit.
- toolkits search [--limit integer] <query> Search toolkits by use case.
+
+ - tools Discover and inspect Composio tools.
+
+ - tools list [--search text] [--toolkits text] [--tags text] [--limit integer] List available tools.
+
+ - tools info [<slug>] View details of a specific tool.
+
+ - tools search [--toolkits text] [--limit integer] <query> Search tools by use case.
"
`);
})
diff --git a/ts/packages/cli/test/src/commands/tools/tools.info.cmd.test.ts b/ts/packages/cli/test/src/commands/tools/tools.info.cmd.test.ts
new file mode 100644
index 000000000..989c2e0b8
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/tools/tools.info.cmd.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, layer } from '@effect/vitest';
+import { ConfigProvider, Effect } from 'effect';
+import { extendConfigProvider } from 'src/services/config';
+import { cli, TestLive, MockConsole } from 'test/__utils__';
+import type { TestLiveInput } from 'test/__utils__/services/test-layer';
+import type { Tools } from 'src/models/tools';
+
+const testTools: Tools = [
+ {
+ name: 'Send Email',
+ slug: 'GMAIL_SEND_EMAIL',
+ description: 'Sends an email to a recipient using Gmail',
+ tags: ['messaging', 'email'],
+ available_versions: ['20260101_00'],
+ input_parameters: {
+ type: 'object',
+ properties: {
+ recipient: { type: 'string', description: 'Email address of recipient' },
+ subject: { type: 'string', description: 'Email subject line' },
+ body: { type: 'string', description: 'Email body content' },
+ cc: { type: 'string', description: 'CC recipients' },
+ },
+ required: ['recipient', 'subject', 'body'],
+ },
+ output_parameters: {
+ type: 'object',
+ properties: {
+ message_id: { type: 'string', description: 'Unique message identifier' },
+ status: { type: 'string', description: 'Delivery status' },
+ },
+ },
+ },
+ {
+ name: 'Create Draft',
+ slug: 'GMAIL_CREATE_DRAFT',
+ description: 'Creates a draft email in Gmail',
+ tags: ['messaging', 'email'],
+ available_versions: ['20260101_00'],
+ input_parameters: { type: 'object', properties: {} },
+ output_parameters: { type: 'object', properties: {} },
+ },
+];
+
+const toolkitsData = {
+ tools: testTools,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio tools info', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] valid slug [Then] displays tool info',
+ it => {
+ it.scoped('shows tool details with input/output schemas', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'info', 'GMAIL_SEND_EMAIL']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Send Email');
+ expect(output).toContain('GMAIL_SEND_EMAIL');
+ expect(output).toContain('Input Parameters');
+ expect(output).toContain('recipient');
+ expect(output).toContain('required');
+ expect(output).toContain('Output Parameters');
+ expect(output).toContain('message_id');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] no slug [Then] warns missing argument',
+ it => {
+ it.scoped('shows missing argument warning', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'info']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Missing required argument');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] invalid slug [Then] shows error and suggestions',
+ it => {
+ it.scoped('shows not found with suggestions', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'info', 'NONEXISTENT_TOOL']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not found');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'info', 'GMAIL_SEND_EMAIL']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+});
diff --git a/ts/packages/cli/test/src/commands/tools/tools.list.cmd.test.ts b/ts/packages/cli/test/src/commands/tools/tools.list.cmd.test.ts
new file mode 100644
index 000000000..ccbf4756c
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/tools/tools.list.cmd.test.ts
@@ -0,0 +1,168 @@
+import { describe, expect, layer } from '@effect/vitest';
+import { ConfigProvider, Effect } from 'effect';
+import { extendConfigProvider } from 'src/services/config';
+import { cli, TestLive, MockConsole } from 'test/__utils__';
+import type { TestLiveInput } from 'test/__utils__/services/test-layer';
+import type { Tools } from 'src/models/tools';
+
+const testTools: Tools = [
+ {
+ name: 'Send Email',
+ slug: 'GMAIL_SEND_EMAIL',
+ description: 'Sends an email to a recipient using Gmail',
+ tags: ['messaging', 'email'],
+ available_versions: ['20260101_00'],
+ input_parameters: {
+ type: 'object',
+ properties: {
+ recipient: { type: 'string', description: 'Email address' },
+ body: { type: 'string', description: 'Email body' },
+ },
+ required: ['recipient', 'body'],
+ },
+ output_parameters: {
+ type: 'object',
+ properties: {
+ message_id: { type: 'string', description: 'Message ID' },
+ },
+ },
+ },
+ {
+ name: 'Create Draft',
+ slug: 'GMAIL_CREATE_DRAFT',
+ description: 'Creates a draft email in Gmail',
+ tags: ['messaging', 'email'],
+ available_versions: ['20260101_00'],
+ input_parameters: { type: 'object', properties: {} },
+ output_parameters: { type: 'object', properties: {} },
+ },
+ {
+ name: 'Send Message',
+ slug: 'SLACK_SEND_MESSAGE',
+ description: 'Sends a message to a Slack channel',
+ tags: ['messaging'],
+ available_versions: ['20260101_00'],
+ input_parameters: { type: 'object', properties: {} },
+ output_parameters: { type: 'object', properties: {} },
+ },
+];
+
+const toolkitsData = {
+ tools: testTools,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio tools list', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] no flags [Then] lists all tools',
+ it => {
+ it.scoped('lists all tools', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_SEND_EMAIL');
+ expect(output).toContain('SLACK_SEND_MESSAGE');
+ expect(output).toContain('Fetched 3 tools');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --toolkits "gmail" [Then] lists only gmail tools',
+ it => {
+ it.scoped('filters by toolkit', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'list', '--toolkits', 'gmail']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_SEND_EMAIL');
+ expect(output).toContain('GMAIL_CREATE_DRAFT');
+ expect(output).not.toContain('SLACK_SEND_MESSAGE');
+ expect(output).toContain('Fetched 2 tools');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --search "send" [Then] shows filtered results',
+ it => {
+ it.scoped('filters by search query', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'list', '--search', 'send']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_SEND_EMAIL');
+ expect(output).toContain('SLACK_SEND_MESSAGE');
+ expect(output).not.toContain('GMAIL_CREATE_DRAFT');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --limit 2 [Then] respects limit',
+ it => {
+ it.scoped('respects limit', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'list', '--limit', '2']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Listing 2 tools');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider }))(
+ '[Given] empty results [Then] shows no tools found',
+ it => {
+ it.scoped('shows no tools found', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('No tools found');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --toolkits "nonexistent" [Then] shows no tools found with hint',
+ it => {
+ it.scoped('shows hint about verifying toolkit slug', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'list', '--toolkits', 'nonexistent']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('No tools found');
+ expect(output).toContain('composio toolkits list');
+ })
+ );
+ }
+ );
+});
diff --git a/ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts b/ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts
new file mode 100644
index 000000000..82f3bc44e
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, layer } from '@effect/vitest';
+import { ConfigProvider, Effect } from 'effect';
+import { extendConfigProvider } from 'src/services/config';
+import { cli, TestLive, MockConsole } from 'test/__utils__';
+import type { TestLiveInput } from 'test/__utils__/services/test-layer';
+import type { Tools } from 'src/models/tools';
+
+const testTools: Tools = [
+ {
+ name: 'Send Email',
+ slug: 'GMAIL_SEND_EMAIL',
+ description: 'Sends an email to a recipient using Gmail',
+ tags: ['messaging', 'email'],
+ available_versions: ['20260101_00'],
+ input_parameters: { type: 'object', properties: {} },
+ output_parameters: { type: 'object', properties: {} },
+ },
+ {
+ name: 'Send Message',
+ slug: 'SLACK_SEND_MESSAGE',
+ description: 'Sends a message to a Slack channel',
+ tags: ['messaging'],
+ available_versions: ['20260101_00'],
+ input_parameters: { type: 'object', properties: {} },
+ output_parameters: { type: 'object', properties: {} },
+ },
+ {
+ name: 'Create Issue',
+ slug: 'GITHUB_CREATE_ISSUE',
+ description: 'Creates a new issue in a GitHub repository',
+ tags: ['development'],
+ available_versions: ['20260101_00'],
+ input_parameters: { type: 'object', properties: {} },
+ output_parameters: { type: 'object', properties: {} },
+ },
+];
+
+const toolkitsData = {
+ tools: testTools,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio tools search', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] query "send" [Then] returns matching tools',
+ it => {
+ it.scoped('returns matching tools', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'search', 'send']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_SEND_EMAIL');
+ expect(output).toContain('SLACK_SEND_MESSAGE');
+ expect(output).not.toContain('GITHUB_CREATE_ISSUE');
+ expect(output).toContain('Found 2 tools');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] query with no results [Then] shows not found message',
+ it => {
+ it.scoped('shows not found message', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'search', 'nonexistent_query']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('No tools found');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] query "send" --toolkits "gmail" [Then] scopes to toolkit',
+ it => {
+ it.scoped('scopes search to toolkit', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'search', 'send', '--toolkits', 'gmail']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_SEND_EMAIL');
+ expect(output).not.toContain('SLACK_SEND_MESSAGE');
+ expect(output).toContain('Found 1 tools');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['tools', 'search', 'send']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+});