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 toolkits` command with list, info, and search subcommands

jkomyno350e7ffc868e
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index d5a1b73be..1f198384d 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -11,6 +11,7 @@ import { logoutCmd } from './logout.cmd';
import { pyCmd } from './py/py.cmd';
import { tsCmd } from './ts/ts.cmd';
import { generateCmd } from './generate.cmd';
+import { toolkitsCmd } from './toolkits/toolkits.cmd';
const $cmd = $defaultCmd.pipe(
Command.withSubcommands([
@@ -22,6 +23,7 @@ const $cmd = $defaultCmd.pipe(
generateCmd,
pyCmd,
tsCmd,
+ toolkitsCmd,
])
);
diff --git a/ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts b/ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts
new file mode 100644
index 000000000..7118f4c05
--- /dev/null
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts
@@ -0,0 +1,139 @@
+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 type { ToolkitDetailed, AuthConfigDetail } from 'src/models/toolkits';
+import { bold, gray } from 'src/ui/colors';
+
+const slug = Args.text({ name: 'slug' }).pipe(Args.withDescription('Toolkit slug (e.g. "gmail")'));
+
+/**
+ * Format auth config fields for display.
+ */
+function formatFields(fields: ReadonlyArray<AuthConfigDetail['fields']['auth_config_creation']>) {
+ const lines: string[] = [];
+
+ for (const group of fields) {
+ const allFields = [
+ ...group.required.map(f => ({ ...f, label: 'required' })),
+ ...group.optional.map(f => ({ ...f, label: 'optional' })),
+ ];
+
+ if (allFields.length === 0) {
+ lines.push(' (none)');
+ } else {
+ for (const field of allFields) {
+ const desc = field.description ? ` ${gray(`"${field.description}"`)}` : '';
+ lines.push(` ${field.name.padEnd(16)} ${field.label.padEnd(10)} ${field.type}${desc}`);
+ }
+ }
+ }
+
+ return lines.join('\n');
+}
+
+/**
+ * Format a detailed toolkit for interactive display.
+ */
+function formatToolkitInfo(toolkit: ToolkitDetailed): string {
+ const lines: string[] = [];
+
+ lines.push(`${bold('Name:')} ${toolkit.name}`);
+ lines.push(`${bold('Slug:')} ${toolkit.slug}`);
+ lines.push(`${bold('Description:')} ${toolkit.meta.description || '(none)'}`);
+
+ // Derive auth schemes from auth_config_details
+ const authSchemes = toolkit.auth_config_details.map(d => d.mode);
+ if (toolkit.no_auth) {
+ lines.push(`${bold('Auth:')} No authentication required`);
+ } else if (authSchemes.length > 0) {
+ lines.push(`${bold('Auth Schemes:')} ${authSchemes.join(', ')}`);
+ if (toolkit.composio_managed_auth_schemes.length > 0) {
+ lines.push(
+ `${bold('Composio Managed Auth Schemes:')} ${toolkit.composio_managed_auth_schemes.join(', ')}`
+ );
+ }
+ }
+
+ // Auth config creation fields
+ if (toolkit.auth_config_details.length > 0) {
+ lines.push('');
+ lines.push(bold('Fields Required for AuthConfig creation:'));
+ for (const detail of toolkit.auth_config_details) {
+ lines.push(` ${detail.name} (${detail.mode}):`);
+ lines.push(formatFields([detail.fields.auth_config_creation]));
+ }
+
+ lines.push('');
+ lines.push(bold('Fields Required for Connected Account creation:'));
+ for (const detail of toolkit.auth_config_details) {
+ lines.push(` ${detail.name} (${detail.mode}):`);
+ lines.push(formatFields([detail.fields.connected_account_initiation]));
+ }
+ }
+
+ return lines.join('\n');
+}
+
+/**
+ * View details of a specific toolkit including auth schemes and required fields.
+ *
+ * @example
+ * ```bash
+ * composio toolkits info "gmail"
+ * ```
+ */
+export const toolkitsCmd$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;
+ }
+
+ const toolkit = yield* ui
+ .withSpinner(`Fetching toolkit "${slug}"...`, repo.getToolkitDetailed(slug))
+ .pipe(
+ Effect.catchTag('services/HttpServerError', (e: HttpServerError) =>
+ Effect.gen(function* () {
+ if (e.status === 404) {
+ // Try to suggest similar toolkits
+ const suggestions = yield* repo.searchToolkits({ search: slug, limit: 3 }).pipe(
+ Effect.map(r => r.items),
+ Effect.catchAll(() => Effect.succeed([]))
+ );
+
+ if (suggestions.length > 0) {
+ const suggestionLines = suggestions
+ .map(s => ` ${s.slug} — ${s.meta.description}`)
+ .join('\n');
+ yield* ui.log.error(
+ `Toolkit "${slug}" not found.\n\nDid you mean?\n${suggestionLines}\n\n> composio toolkits info "${suggestions[0]!.slug}"`
+ );
+ } else {
+ yield* ui.log.error(`Toolkit "${slug}" not found.`);
+ }
+
+ return yield* Effect.fail(e);
+ }
+
+ return yield* Effect.fail(e);
+ })
+ )
+ );
+
+ yield* ui.note(formatToolkitInfo(toolkit), `Toolkit: ${toolkit.name}`);
+
+ // Next step hint
+ yield* ui.log.step(
+ `To list tools in this toolkit:\n> composio tools list --toolkit "${toolkit.slug}"`
+ );
+
+ yield* ui.output(JSON.stringify(toolkit, null, 2));
+ })
+).pipe(Command.withDescription('View details of a specific toolkit.'));
diff --git a/ts/packages/cli/src/commands/toolkits/commands/toolkits.list.cmd.ts b/ts/packages/cli/src/commands/toolkits/commands/toolkits.list.cmd.ts
new file mode 100644
index 000000000..65dbae989
--- /dev/null
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.list.cmd.ts
@@ -0,0 +1,82 @@
+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 { formatToolkitsTable, formatToolkitsJson } from '../format';
+
+const query = Options.text('query').pipe(
+ Options.withDescription('Text search by name, slug, or description'),
+ Options.optional
+);
+
+const category = Options.text('category').pipe(
+ Options.withDescription('Filter by category ID'),
+ Options.optional
+);
+
+const limit = Options.integer('limit').pipe(
+ Options.withDefault(30),
+ Options.withDescription('Number of results per page (1-1000)')
+);
+
+/**
+ * List available toolkits with optional filters.
+ *
+ * @example
+ * ```bash
+ * composio toolkits list
+ * composio toolkits list --query "email"
+ * composio toolkits list --category "messaging" --limit 10
+ * ```
+ */
+export const toolkitsCmd$List = Command.make(
+ 'list',
+ { query, category, limit },
+ ({ query, category, 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 toolkits...',
+ repo.searchToolkits({
+ search: Option.getOrUndefined(query),
+ category: Option.getOrUndefined(category),
+ limit: clampedLimit,
+ })
+ );
+
+ if (result.items.length === 0) {
+ yield* ui.log.warn('No toolkits found. Try broadening your search.');
+ return;
+ }
+
+ const showing = result.items.length;
+ const total = result.total_items;
+
+ yield* ui.log.info(`Listing ${showing} of ${total} toolkits`);
+ yield* ui.log.message('');
+ yield* ui.log.message(formatToolkitsTable(result.items));
+
+ // Next step hint
+ const firstSlug = result.items[0]?.slug;
+ if (firstSlug) {
+ yield* ui.log.message('');
+ yield* ui.log.step(
+ `To view details of a toolkit:\n> composio toolkits info "${firstSlug}"`
+ );
+ }
+
+ yield* ui.output(formatToolkitsJson(result.items));
+ })
+).pipe(Command.withDescription('List available toolkits.'));
diff --git a/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts b/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts
new file mode 100644
index 000000000..61ea9e76c
--- /dev/null
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts
@@ -0,0 +1,63 @@
+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 { formatToolkitsTable, formatToolkitsJson } from '../format';
+
+const query = Args.text({ name: 'query' }).pipe(
+ Args.withDescription('Search query (e.g. "send emails")')
+);
+
+const limit = Options.integer('limit').pipe(
+ Options.withDefault(10),
+ Options.withDescription('Number of results per page (1-1000)')
+);
+
+/**
+ * Search toolkits by use case.
+ *
+ * @example
+ * ```bash
+ * composio toolkits search "send emails"
+ * composio toolkits search "messaging" --limit 5
+ * ```
+ */
+export const toolkitsCmd$Search = Command.make('search', { query, limit }, ({ query, 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 toolkits for "${query}"...`,
+ repo.searchToolkits({ search: query, limit: clampedLimit })
+ );
+
+ if (result.items.length === 0) {
+ yield* ui.log.warn(`No toolkits found matching "${query}". Try broadening your search.`);
+ return;
+ }
+
+ yield* ui.log.info(`Found ${result.items.length} toolkits`);
+ yield* ui.log.message('');
+ yield* ui.log.message(formatToolkitsTable(result.items));
+
+ // Next step hint
+ const firstSlug = result.items[0]?.slug;
+ if (firstSlug) {
+ yield* ui.log.message('');
+ yield* ui.log.step(`To view details:\n> composio toolkits info "${firstSlug}"`);
+ }
+
+ yield* ui.output(formatToolkitsJson(result.items));
+ })
+).pipe(Command.withDescription('Search toolkits by use case.'));
diff --git a/ts/packages/cli/src/commands/toolkits/format.ts b/ts/packages/cli/src/commands/toolkits/format.ts
new file mode 100644
index 000000000..f1d4709f4
--- /dev/null
+++ b/ts/packages/cli/src/commands/toolkits/format.ts
@@ -0,0 +1,45 @@
+import type { Toolkit } from 'src/models/toolkits';
+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 toolkits as a human-readable table.
+ */
+export function formatToolkitsTable(toolkits: ReadonlyArray<Toolkit>): string {
+ const header = `${bold('Name'.padEnd(20))} ${bold('Slug'.padEnd(20))} ${bold('Tools'.padEnd(7))} ${bold('Triggers'.padEnd(10))} ${bold('Description')}`;
+
+ const rows = toolkits.map(t => {
+ const name = t.name.padEnd(20);
+ const slug = t.slug.padEnd(20);
+ const tools = String(t.meta.tools_count).padEnd(7);
+ const triggers = String(t.meta.triggers_count).padEnd(10);
+ const desc = gray(truncate(t.meta.description, 50));
+ return `${name} ${slug} ${tools} ${triggers} ${desc}`;
+ });
+
+ return [header, ...rows].join('\n');
+}
+
+/**
+ * Format toolkits as JSON for piped output.
+ */
+export function formatToolkitsJson(toolkits: ReadonlyArray<Toolkit>): string {
+ return JSON.stringify(
+ toolkits.map(t => ({
+ name: t.name,
+ slug: t.slug,
+ tools_count: t.meta.tools_count,
+ triggers_count: t.meta.triggers_count,
+ description: t.meta.description,
+ })),
+ null,
+ 2
+ );
+}
diff --git a/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts b/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts
new file mode 100644
index 000000000..de89ac625
--- /dev/null
+++ b/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts
@@ -0,0 +1,17 @@
+import { Command } from '@effect/cli';
+import { toolkitsCmd$List } from './commands/toolkits.list.cmd';
+import { toolkitsCmd$Info } from './commands/toolkits.info.cmd';
+import { toolkitsCmd$Search } from './commands/toolkits.search.cmd';
+
+/**
+ * CLI entry point for toolkit discovery commands.
+ *
+ * @example
+ * ```bash
+ * composio toolkits <command>
+ * ```
+ */
+export const toolkitsCmd = Command.make('toolkits').pipe(
+ Command.withDescription('Discover and inspect Composio toolkits.'),
+ Command.withSubcommands([toolkitsCmd$List, toolkitsCmd$Info, toolkitsCmd$Search])
+);
diff --git a/ts/packages/cli/src/models/toolkits.ts b/ts/packages/cli/src/models/toolkits.ts
index 3df5b7328..c7dcc6968 100644
--- a/ts/packages/cli/src/models/toolkits.ts
+++ b/ts/packages/cli/src/models/toolkits.ts
@@ -13,6 +13,8 @@ export const Toolkit = Schema.Struct({
created_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
updated_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+ tools_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
+ triggers_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
}),
no_auth: Schema.Boolean,
}).annotations({ identifier: 'Toolkit' });
@@ -27,3 +29,79 @@ export const toolkitsToJSON = Schema.encode(ToolkitsJSON);
export type ToolkitName = string & Brand.Brand<'ToolkitName'>;
export const ToolkitName = Brand.nominal<ToolkitName>();
+
+/**
+ * Field definition for auth config creation / connected account initiation.
+ */
+export const AuthConfigField = Schema.Struct({
+ name: Schema.String,
+ displayName: Schema.String,
+ description: Schema.String,
+ type: Schema.String,
+ required: Schema.Boolean,
+ default: Schema.optionalWith(Schema.NullOr(Schema.String), { default: () => null }),
+}).annotations({ identifier: 'AuthConfigField' });
+export type AuthConfigField = Schema.Schema.Type<typeof AuthConfigField>;
+
+/**
+ * Auth config detail for a specific auth scheme (e.g. OAUTH2, API_KEY).
+ */
+export const AuthConfigDetail = Schema.Struct({
+ mode: Schema.String,
+ name: Schema.String,
+ fields: Schema.Struct({
+ auth_config_creation: Schema.Struct({
+ required: Schema.Array(AuthConfigField),
+ optional: Schema.Array(AuthConfigField),
+ }),
+ connected_account_initiation: Schema.Struct({
+ required: Schema.Array(AuthConfigField),
+ optional: Schema.Array(AuthConfigField),
+ }),
+ }),
+}).annotations({ identifier: 'AuthConfigDetail' });
+export type AuthConfigDetail = Schema.Schema.Type<typeof AuthConfigDetail>;
+
+/**
+ * Detailed toolkit info from the retrieve endpoint, includes auth_config_details.
+ */
+export const ToolkitDetailed = Schema.Struct({
+ name: Schema.String,
+ slug: Schema.Trim.pipe(Schema.nonEmptyString()),
+ is_local_toolkit: Schema.Boolean,
+ composio_managed_auth_schemes: Schema.optionalWith(Schema.Array(Schema.String), {
+ default: () => [],
+ }),
+ no_auth: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+ meta: Schema.Struct({
+ description: Schema.optionalWith(Schema.String, { default: () => '' }),
+ categories: Schema.optionalWith(Schema.Array(Schema.Unknown), { default: () => [] }),
+ created_at: Schema.DateTimeUtc,
+ updated_at: Schema.DateTimeUtc,
+ available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+ tools_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
+ triggers_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
+ }),
+ auth_config_details: Schema.optionalWith(Schema.Array(AuthConfigDetail), { default: () => [] }),
+}).annotations({ identifier: 'ToolkitDetailed' });
+export type ToolkitDetailed = Schema.Schema.Type<typeof ToolkitDetailed>;
+
+/**
+ * Toolkit category.
+ */
+export const ToolkitCategory = Schema.Struct({
+ id: Schema.String,
+ name: Schema.String,
+}).annotations({ identifier: 'ToolkitCategory' });
+export type ToolkitCategory = Schema.Schema.Type<typeof ToolkitCategory>;
+
+/**
+ * Search result for a single page of toolkits.
+ */
+export const ToolkitSearchResult = Schema.Struct({
+ items: Toolkits,
+ total_items: Schema.Int,
+ total_pages: Schema.Int,
+ next_cursor: Schema.NullOr(Schema.String),
+}).annotations({ identifier: 'ToolkitSearchResult' });
+export type ToolkitSearchResult = Schema.Schema.Type<typeof ToolkitSearchResult>;
diff --git a/ts/packages/cli/src/services/composio-clients-cached.ts b/ts/packages/cli/src/services/composio-clients-cached.ts
index 583d6b937..a9f80446a 100644
--- a/ts/packages/cli/src/services/composio-clients-cached.ts
+++ b/ts/packages/cli/src/services/composio-clients-cached.ts
@@ -238,6 +238,13 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
// 3. Caching validation results could cause false positives/negatives
validateToolkitVersions: (overrides, relevantToolkits) =>
underlyingRepository.validateToolkitVersions(overrides, relevantToolkits),
+ // These methods should NOT be cached:
+ // - searchToolkits: results depend on query params, caching would be misleading
+ // - getToolkitDetailed: detailed info should be fresh (auth config fields change)
+ // - getCategories: categories change infrequently but are cheap to fetch
+ searchToolkits: params => underlyingRepository.searchToolkits(params),
+ getToolkitDetailed: slug => underlyingRepository.getToolkitDetailed(slug),
+ getCategories: () => underlyingRepository.getCategories(),
});
})
).pipe(
diff --git a/ts/packages/cli/src/services/composio-clients.ts b/ts/packages/cli/src/services/composio-clients.ts
index 598e617c2..3e62c30cd 100644
--- a/ts/packages/cli/src/services/composio-clients.ts
+++ b/ts/packages/cli/src/services/composio-clients.ts
@@ -13,7 +13,13 @@ import {
SynchronizedRef,
} from 'effect';
import { Composio as _RawComposioClient, APIPromise } from '@composio/client';
-import { Toolkit, Toolkits } from 'src/models/toolkits';
+import {
+ Toolkit,
+ Toolkits,
+ ToolkitDetailed,
+ ToolkitCategory,
+ type ToolkitSearchResult,
+} from 'src/models/toolkits';
import { ToolsAsEnums, Tools, Tool } from 'src/models/tools';
import {
groupByVersion,
@@ -253,6 +259,27 @@ export const TriggerTypesResponse = Schema.Struct({
next_cursor: Schema.NullOr(Schema.String),
}).annotations({ identifier: 'TriggerTypesResponse' });
+// Single-page search response (includes total_items for "Listing X of Y" display)
+export const ToolkitSearchResponse = Schema.Struct({
+ items: Toolkits,
+ total_items: Schema.Int,
+ total_pages: Schema.Int,
+ current_page: Schema.Int,
+ next_cursor: Schema.NullOr(Schema.String),
+}).annotations({ identifier: 'ToolkitSearchResponse' });
+
+// Detailed retrieve response (includes auth_config_details)
+export const ToolkitDetailedResponse = ToolkitDetailed.annotations({
+ identifier: 'ToolkitDetailedResponse',
+});
+
+// Categories response
+export const ToolkitCategoriesResponse = Schema.Struct({
+ items: Schema.Array(ToolkitCategory),
+ total_items: Schema.Int,
+ next_cursor: Schema.NullOr(Schema.String),
+}).annotations({ identifier: 'ToolkitCategoriesResponse' });
+
/**
* Error response schemas
*/
@@ -640,10 +667,70 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
composio_managed_auth_schemes: retrieved.composio_managed_auth_schemes,
is_local_toolkit: retrieved.is_local_toolkit,
no_auth: retrieved.no_auth,
- meta: retrieved.meta,
+ meta: {
+ ...retrieved.meta,
+ tools_count: 0,
+ triggers_count: 0,
+ },
}) satisfies Toolkit
)
),
+ /**
+ * Searches toolkits with optional filters. Returns a single page of results (no auto-pagination).
+ * @param params - Search/filter parameters
+ */
+ search: (params: {
+ search?: string;
+ category?: string;
+ limit?: number;
+ cursor?: string;
+ }) =>
+ withMetrics(
+ callClient(
+ clientSingleton,
+ client =>
+ client.toolkits.list({
+ search: params.search,
+ category: params.category,
+ limit: params.limit,
+ cursor: params.cursor,
+ }),
+ ToolkitSearchResponse
+ )
+ ).pipe(
+ Effect.map(
+ response =>
+ ({
+ items: response.items,
+ total_items: response.total_items,
+ total_pages: response.total_pages,
+ next_cursor: response.next_cursor,
+ }) satisfies ToolkitSearchResult
+ )
+ ),
+ /**
+ * Retrieves detailed toolkit info including auth_config_details.
+ * @param slug - Toolkit slug
+ */
+ retrieveDetailed: (slug: string) =>
+ withMetrics(
+ callClient(
+ clientSingleton,
+ client => client.toolkits.retrieve(slug),
+ ToolkitDetailedResponse
+ )
+ ),
+ /**
+ * Retrieves all available toolkit categories.
+ */
+ retrieveCategories: () =>
+ withMetrics(
+ callClient(
+ clientSingleton,
+ client => client.toolkits.retrieveCategories(),
+ ToolkitCategoriesResponse
+ )
+ ).pipe(Effect.map(response => response.items)),
},
tools: {
/**
@@ -951,6 +1038,25 @@ export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsR
},
InvalidToolkitVersionsError | InvalidToolkitsError | HttpError | NoSuchElementException
> => validateToolkitVersionsImpl(client, overrides, relevantToolkits),
+ /**
+ * Searches toolkits with optional filters. Returns a single page of results.
+ * @param params - Search/filter parameters
+ */
+ searchToolkits: (params: {
+ search?: string;
+ category?: string;
+ limit?: number;
+ cursor?: string;
+ }) => client.toolkits.search(params),
+ /**
+ * Retrieves detailed toolkit info including auth_config_details.
+ * @param slug - Toolkit slug
+ */
+ getToolkitDetailed: (slug: string) => client.toolkits.retrieveDetailed(slug),
+ /**
+ * Retrieves all available toolkit categories.
+ */
+ getCategories: () => client.toolkits.retrieveCategories(),
};
}),
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 aa7199a9a..0a4ebaa94 100644
--- a/ts/packages/cli/test/__utils__/services/test-layer.ts
+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts
@@ -18,11 +18,12 @@ import { ComposioCliConfig } from 'src/cli-config';
import * as MockConsole from './mock-console';
import * as MockTerminal from './mock-terminal';
import { TerminalUITest } from './terminal-ui-test';
-import type { Toolkits } from 'src/models/toolkits';
+import type { Toolkits, ToolkitDetailed, ToolkitCategory } from 'src/models/toolkits';
import { NodeProcess } from 'src/services/node-process';
import {
ComposioSessionRepository,
ComposioToolkitsRepository,
+ HttpServerError,
InvalidToolkitsError,
InvalidToolkitVersionsError,
type InvalidVersionDetail,
@@ -55,6 +56,8 @@ export interface TestLiveInput {
*/
toolkitsData?: {
toolkits?: Toolkits;
+ detailedToolkits?: ToolkitDetailed[];
+ categories?: ToolkitCategory[];
tools?: Tools;
triggerTypesAsEnums?: TriggerTypesAsEnums;
triggerTypes?: TriggerTypes;
@@ -81,6 +84,8 @@ export const TestLayer = (input?: TestLiveInput) =>
Effect.gen(function* () {
const defaultAppClientData = {
toolkits: [] as Toolkits,
+ detailedToolkits: [] as ToolkitDetailed[],
+ categories: [] as ToolkitCategory[],
tools: [] as Tools,
triggerTypesAsEnums: [] as TriggerTypesAsEnums,
triggerTypes: [] as TriggerTypes,
@@ -213,6 +218,45 @@ export const TestLayer = (input?: TestLiveInput) =>
warnings: warnings as ReadonlyArray<string>,
});
},
+ searchToolkits: (params: {
+ search?: string;
+ category?: string;
+ limit?: number;
+ cursor?: string;
+ }) => {
+ let results = [...toolkitsData.toolkits];
+
+ if (params.search) {
+ const q = params.search.toLowerCase();
+ results = results.filter(
+ t =>
+ t.name.toLowerCase().includes(q) ||
+ t.slug.toLowerCase().includes(q) ||
+ t.meta.description.toLowerCase().includes(q)
+ );
+ }
+
+ const limit = params.limit ?? 30;
+ const items = results.slice(0, limit);
+ return Effect.succeed({
+ items,
+ total_items: results.length,
+ total_pages: Math.ceil(results.length / limit),
+ next_cursor: null,
+ });
+ },
+ getToolkitDetailed: (slug: string) => {
+ const found = toolkitsData.detailedToolkits.find(
+ t => t.slug.toLowerCase() === slug.toLowerCase()
+ );
+ if (!found) {
+ return Effect.fail(
+ new HttpServerError({ cause: `Toolkit "${slug}" not found`, status: 404 })
+ );
+ }
+ return Effect.succeed(found);
+ },
+ getCategories: () => Effect.succeed(toolkitsData.categories),
})
);
const ComposioSessionRepositoryTest = yield* setupComposioSessionRepository();
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 274b51a84..1eb9b1115 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'"
+ "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits'"
)
)
);
@@ -83,6 +83,14 @@ describe('CLI: composio', () => {
Environment Variables:
COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
Use "latest" or unset to use the latest version.
+
+ - toolkits Discover and inspect Composio toolkits.
+
+ - toolkits list [--query text] [--category text] [--limit integer] List available toolkits.
+
+ - toolkits info <slug> View details of a specific toolkit.
+
+ - toolkits search [--limit integer] <query> Search toolkits by use case.
"
`);
})
diff --git a/ts/packages/cli/test/src/commands/toolkits/toolkits.info.cmd.test.ts b/ts/packages/cli/test/src/commands/toolkits/toolkits.info.cmd.test.ts
new file mode 100644
index 000000000..e260a9497
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/toolkits/toolkits.info.cmd.test.ts
@@ -0,0 +1,180 @@
+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 { Toolkits, ToolkitDetailed } from 'src/models/toolkits';
+
+const testToolkits: Toolkits = [
+ {
+ name: 'Gmail',
+ slug: 'gmail',
+ auth_schemes: ['OAUTH2', 'BEARER_TOKEN'],
+ composio_managed_auth_schemes: ['OAUTH2'],
+ is_local_toolkit: false,
+ no_auth: false,
+ meta: {
+ description: 'Email service to send and receive emails',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 36,
+ triggers_count: 2,
+ },
+ },
+];
+
+const detailedToolkits: ToolkitDetailed[] = [
+ {
+ name: 'Gmail',
+ slug: 'gmail',
+ is_local_toolkit: false,
+ composio_managed_auth_schemes: ['OAUTH2'],
+ no_auth: false,
+ meta: {
+ description: 'Email service to send and receive emails',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 36,
+ triggers_count: 2,
+ },
+ auth_config_details: [
+ {
+ mode: 'OAUTH2',
+ name: 'OAuth 2.0',
+ fields: {
+ auth_config_creation: { required: [], optional: [] },
+ connected_account_initiation: { required: [], optional: [] },
+ },
+ },
+ {
+ mode: 'BEARER_TOKEN',
+ name: 'Bearer Token',
+ fields: {
+ auth_config_creation: {
+ required: [
+ {
+ name: 'apiKey',
+ displayName: 'API Key',
+ description: 'Your API key',
+ type: 'string',
+ required: true,
+ default: null,
+ },
+ ],
+ optional: [],
+ },
+ connected_account_initiation: {
+ required: [
+ {
+ name: 'apiKey',
+ displayName: 'API Key',
+ description: 'Your API key',
+ type: 'string',
+ required: true,
+ default: null,
+ },
+ ],
+ optional: [],
+ },
+ },
+ },
+ ],
+ },
+ {
+ name: 'Code Interpreter',
+ slug: 'codeinterpreter',
+ is_local_toolkit: false,
+ composio_managed_auth_schemes: [],
+ no_auth: true,
+ meta: {
+ description: 'Execute code snippets',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 5,
+ triggers_count: 0,
+ },
+ auth_config_details: [],
+ },
+];
+
+const toolkitsData = {
+ toolkits: testToolkits,
+ detailedToolkits,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio toolkits info', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] valid slug "gmail"',
+ it => {
+ it.scoped('shows detailed info with auth schemes', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'info', 'gmail']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Gmail');
+ expect(output).toContain('gmail');
+ expect(output).toContain('Email service to send and receive emails');
+ expect(output).toContain('OAUTH2');
+ expect(output).toContain('BEARER_TOKEN');
+ expect(output).toContain('apiKey');
+ expect(output).toContain('AuthConfig creation');
+ expect(output).toContain('Connected Account creation');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] toolkit with no_auth=true',
+ it => {
+ it.scoped('shows "No authentication required"', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'info', 'codeinterpreter']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Code Interpreter');
+ expect(output).toContain('No authentication required');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] invalid slug',
+ it => {
+ it.scoped('shows error', () =>
+ Effect.gen(function* () {
+ const result = yield* cli(['toolkits', 'info', 'gmal']).pipe(Effect.either);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not found');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'info', 'gmail']);
+ 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/toolkits/toolkits.list.cmd.test.ts b/ts/packages/cli/test/src/commands/toolkits/toolkits.list.cmd.test.ts
new file mode 100644
index 000000000..f9d052ee0
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/toolkits/toolkits.list.cmd.test.ts
@@ -0,0 +1,145 @@
+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 { Toolkits } from 'src/models/toolkits';
+
+const testToolkits: Toolkits = [
+ {
+ name: 'Gmail',
+ slug: 'gmail',
+ auth_schemes: ['OAUTH2'],
+ composio_managed_auth_schemes: ['OAUTH2'],
+ is_local_toolkit: false,
+ no_auth: false,
+ meta: {
+ description: 'Email service to send and receive emails',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 36,
+ triggers_count: 2,
+ },
+ },
+ {
+ name: 'Slack',
+ slug: 'slack',
+ auth_schemes: ['OAUTH2'],
+ composio_managed_auth_schemes: ['OAUTH2'],
+ is_local_toolkit: false,
+ no_auth: false,
+ meta: {
+ description: 'Messaging platform for teams',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 42,
+ triggers_count: 5,
+ },
+ },
+ {
+ name: 'GitHub',
+ slug: 'github',
+ auth_schemes: ['OAUTH2'],
+ composio_managed_auth_schemes: ['OAUTH2'],
+ is_local_toolkit: false,
+ no_auth: false,
+ meta: {
+ description: 'Code hosting and collaboration platform',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 50,
+ triggers_count: 10,
+ },
+ },
+];
+
+const toolkitsData = {
+ toolkits: testToolkits,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio toolkits list', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] no flags [Then] lists all toolkits',
+ it => {
+ it.scoped('lists all toolkits', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Gmail');
+ expect(output).toContain('gmail');
+ expect(output).toContain('Slack');
+ expect(output).toContain('GitHub');
+ expect(output).toContain('Listing 3 of 3 toolkits');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --query "email"',
+ it => {
+ it.scoped('shows filtered results', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'list', '--query', 'email']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Gmail');
+ expect(output).not.toContain('GitHub');
+ expect(output).toContain('Listing 1 of 1 toolkits');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --limit 2',
+ it => {
+ it.scoped('respects limit', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'list', '--limit', '2']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Listing 2 of 3 toolkits');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', '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', it => {
+ it.scoped('shows no toolkits found', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('No toolkits found');
+ })
+ );
+ });
+});
diff --git a/ts/packages/cli/test/src/commands/toolkits/toolkits.search.cmd.test.ts b/ts/packages/cli/test/src/commands/toolkits/toolkits.search.cmd.test.ts
new file mode 100644
index 000000000..243bf2381
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/toolkits/toolkits.search.cmd.test.ts
@@ -0,0 +1,130 @@
+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 { Toolkits } from 'src/models/toolkits';
+
+const testToolkits: Toolkits = [
+ {
+ name: 'Gmail',
+ slug: 'gmail',
+ auth_schemes: ['OAUTH2'],
+ composio_managed_auth_schemes: ['OAUTH2'],
+ is_local_toolkit: false,
+ no_auth: false,
+ meta: {
+ description: 'Email service to send and receive emails',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 36,
+ triggers_count: 2,
+ },
+ },
+ {
+ name: 'Outlook',
+ slug: 'outlook',
+ auth_schemes: ['OAUTH2'],
+ composio_managed_auth_schemes: ['OAUTH2'],
+ is_local_toolkit: false,
+ no_auth: false,
+ meta: {
+ description: 'Microsoft email service',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 28,
+ triggers_count: 1,
+ },
+ },
+ {
+ name: 'Slack',
+ slug: 'slack',
+ auth_schemes: ['OAUTH2'],
+ composio_managed_auth_schemes: ['OAUTH2'],
+ is_local_toolkit: false,
+ no_auth: false,
+ meta: {
+ description: 'Messaging platform for teams',
+ categories: [],
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
+ available_versions: [],
+ tools_count: 42,
+ triggers_count: 5,
+ },
+ },
+];
+
+const toolkitsData = {
+ toolkits: testToolkits,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio toolkits search', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] query "email"',
+ it => {
+ it.scoped('shows matching toolkits', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'search', 'email']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Gmail');
+ expect(output).toContain('Outlook');
+ expect(output).not.toContain('Slack');
+ expect(output).toContain('Found 2 toolkits');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] query with no results',
+ it => {
+ it.scoped('shows "No toolkits found"', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'search', 'xyzzy']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('No toolkits found');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] --limit 1',
+ it => {
+ it.scoped('respects limit', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'search', 'email', '--limit', '1']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Found 1 toolkits');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'search', 'email']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+});