@devries-cameron20 / composio-1 / commits / 350e7ffc8
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 toolkits` command with list, info, and search subcommands

Implement toolkit discovery via CLI to help agents and developers find and inspect Composio toolkits without the dashboard. - `composio toolkits list [--query] [--category] [--limit]` — browse toolkits - `composio toolkits info <slug>` — view auth schemes and required fields - `composio toolkits search <query>` — search by use case Extends the API layer with search, retrieveDetailed, and retrieveCategories methods. All subcommands follow the stdout/stderr output convention and include auth guards, "next step" hints, and JSON piped output. Ref: PLEN-1584

jkomyno committed Feb 18, 2026 at 19:18 UTC 350e7ffc868e8163505c4336793ebfea8d32a94f
14 files changed +1050 -4
ts/packages/cli/src/commands/index.ts
+2
@@ -11,6 +11,7 @@ import { logoutCmd } from './logout.cmd';
11 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
16 const $cmd = $defaultCmd.pipe(
17 Command.withSubcommands([
@@ -22,6 +23,7 @@ const $cmd = $defaultCmd.pipe(
23 generateCmd,
24 pyCmd,
25 tsCmd,
26 + toolkitsCmd,
27 ])
28 );
29
ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts new
+139
@@ -0,0 +1,139 @@
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 type { ToolkitDetailed, AuthConfigDetail } from 'src/models/toolkits';
7 +import { bold, gray } from 'src/ui/colors';
8 +
9 +const slug = Args.text({ name: 'slug' }).pipe(Args.withDescription('Toolkit slug (e.g. "gmail")'));
10 +
11 +/**
12 + * Format auth config fields for display.
13 + */
14 +function formatFields(fields: ReadonlyArray<AuthConfigDetail['fields']['auth_config_creation']>) {
15 + const lines: string[] = [];
16 +
17 + for (const group of fields) {
18 + const allFields = [
19 + ...group.required.map(f => ({ ...f, label: 'required' })),
20 + ...group.optional.map(f => ({ ...f, label: 'optional' })),
21 + ];
22 +
23 + if (allFields.length === 0) {
24 + lines.push(' (none)');
25 + } else {
26 + for (const field of allFields) {
27 + const desc = field.description ? ` ${gray(`"${field.description}"`)}` : '';
28 + lines.push(` ${field.name.padEnd(16)} ${field.label.padEnd(10)} ${field.type}${desc}`);
29 + }
30 + }
31 + }
32 +
33 + return lines.join('\n');
34 +}
35 +
36 +/**
37 + * Format a detailed toolkit for interactive display.
38 + */
39 +function formatToolkitInfo(toolkit: ToolkitDetailed): string {
40 + const lines: string[] = [];
41 +
42 + lines.push(`${bold('Name:')} ${toolkit.name}`);
43 + lines.push(`${bold('Slug:')} ${toolkit.slug}`);
44 + lines.push(`${bold('Description:')} ${toolkit.meta.description || '(none)'}`);
45 +
46 + // Derive auth schemes from auth_config_details
47 + const authSchemes = toolkit.auth_config_details.map(d => d.mode);
48 + if (toolkit.no_auth) {
49 + lines.push(`${bold('Auth:')} No authentication required`);
50 + } else if (authSchemes.length > 0) {
51 + lines.push(`${bold('Auth Schemes:')} ${authSchemes.join(', ')}`);
52 + if (toolkit.composio_managed_auth_schemes.length > 0) {
53 + lines.push(
54 + `${bold('Composio Managed Auth Schemes:')} ${toolkit.composio_managed_auth_schemes.join(', ')}`
55 + );
56 + }
57 + }
58 +
59 + // Auth config creation fields
60 + if (toolkit.auth_config_details.length > 0) {
61 + lines.push('');
62 + lines.push(bold('Fields Required for AuthConfig creation:'));
63 + for (const detail of toolkit.auth_config_details) {
64 + lines.push(` ${detail.name} (${detail.mode}):`);
65 + lines.push(formatFields([detail.fields.auth_config_creation]));
66 + }
67 +
68 + lines.push('');
69 + lines.push(bold('Fields Required for Connected Account creation:'));
70 + for (const detail of toolkit.auth_config_details) {
71 + lines.push(` ${detail.name} (${detail.mode}):`);
72 + lines.push(formatFields([detail.fields.connected_account_initiation]));
73 + }
74 + }
75 +
76 + return lines.join('\n');
77 +}
78 +
79 +/**
80 + * View details of a specific toolkit including auth schemes and required fields.
81 + *
82 + * @example
83 + * ```bash
84 + * composio toolkits info "gmail"
85 + * ```
86 + */
87 +export const toolkitsCmd$Info = Command.make('info', { slug }, ({ slug }) =>
88 + Effect.gen(function* () {
89 + const ui = yield* TerminalUI;
90 + const ctx = yield* ComposioUserContext;
91 + const repo = yield* ComposioToolkitsRepository;
92 +
93 + // Auth guard
94 + if (Option.isNone(ctx.data.apiKey)) {
95 + yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
96 + return;
97 + }
98 +
99 + const toolkit = yield* ui
100 + .withSpinner(`Fetching toolkit "${slug}"...`, repo.getToolkitDetailed(slug))
101 + .pipe(
102 + Effect.catchTag('services/HttpServerError', (e: HttpServerError) =>
103 + Effect.gen(function* () {
104 + if (e.status === 404) {
105 + // Try to suggest similar toolkits
106 + const suggestions = yield* repo.searchToolkits({ search: slug, limit: 3 }).pipe(
107 + Effect.map(r => r.items),
108 + Effect.catchAll(() => Effect.succeed([]))
109 + );
110 +
111 + if (suggestions.length > 0) {
112 + const suggestionLines = suggestions
113 + .map(s => ` ${s.slug} — ${s.meta.description}`)
114 + .join('\n');
115 + yield* ui.log.error(
116 + `Toolkit "${slug}" not found.\n\nDid you mean?\n${suggestionLines}\n\n> composio toolkits info "${suggestions[0]!.slug}"`
117 + );
118 + } else {
119 + yield* ui.log.error(`Toolkit "${slug}" not found.`);
120 + }
121 +
122 + return yield* Effect.fail(e);
123 + }
124 +
125 + return yield* Effect.fail(e);
126 + })
127 + )
128 + );
129 +
130 + yield* ui.note(formatToolkitInfo(toolkit), `Toolkit: ${toolkit.name}`);
131 +
132 + // Next step hint
133 + yield* ui.log.step(
134 + `To list tools in this toolkit:\n> composio tools list --toolkit "${toolkit.slug}"`
135 + );
136 +
137 + yield* ui.output(JSON.stringify(toolkit, null, 2));
138 + })
139 +).pipe(Command.withDescription('View details of a specific toolkit.'));
ts/packages/cli/src/commands/toolkits/commands/toolkits.list.cmd.ts new
+82
@@ -0,0 +1,82 @@
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 { formatToolkitsTable, formatToolkitsJson } from '../format';
7 +
8 +const query = Options.text('query').pipe(
9 + Options.withDescription('Text search by name, slug, or description'),
10 + Options.optional
11 +);
12 +
13 +const category = Options.text('category').pipe(
14 + Options.withDescription('Filter by category ID'),
15 + Options.optional
16 +);
17 +
18 +const limit = Options.integer('limit').pipe(
19 + Options.withDefault(30),
20 + Options.withDescription('Number of results per page (1-1000)')
21 +);
22 +
23 +/**
24 + * List available toolkits with optional filters.
25 + *
26 + * @example
27 + * ```bash
28 + * composio toolkits list
29 + * composio toolkits list --query "email"
30 + * composio toolkits list --category "messaging" --limit 10
31 + * ```
32 + */
33 +export const toolkitsCmd$List = Command.make(
34 + 'list',
35 + { query, category, limit },
36 + ({ query, category, limit }) =>
37 + Effect.gen(function* () {
38 + const ui = yield* TerminalUI;
39 + const ctx = yield* ComposioUserContext;
40 + const repo = yield* ComposioToolkitsRepository;
41 +
42 + // Auth guard
43 + if (Option.isNone(ctx.data.apiKey)) {
44 + yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
45 + return;
46 + }
47 +
48 + const clampedLimit = Math.max(1, Math.min(1000, limit));
49 +
50 + const result = yield* ui.withSpinner(
51 + 'Fetching toolkits...',
52 + repo.searchToolkits({
53 + search: Option.getOrUndefined(query),
54 + category: Option.getOrUndefined(category),
55 + limit: clampedLimit,
56 + })
57 + );
58 +
59 + if (result.items.length === 0) {
60 + yield* ui.log.warn('No toolkits found. Try broadening your search.');
61 + return;
62 + }
63 +
64 + const showing = result.items.length;
65 + const total = result.total_items;
66 +
67 + yield* ui.log.info(`Listing ${showing} of ${total} toolkits`);
68 + yield* ui.log.message('');
69 + yield* ui.log.message(formatToolkitsTable(result.items));
70 +
71 + // Next step hint
72 + const firstSlug = result.items[0]?.slug;
73 + if (firstSlug) {
74 + yield* ui.log.message('');
75 + yield* ui.log.step(
76 + `To view details of a toolkit:\n> composio toolkits info "${firstSlug}"`
77 + );
78 + }
79 +
80 + yield* ui.output(formatToolkitsJson(result.items));
81 + })
82 +).pipe(Command.withDescription('List available toolkits.'));
ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts new
+63
@@ -0,0 +1,63 @@
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 { formatToolkitsTable, formatToolkitsJson } from '../format';
7 +
8 +const query = Args.text({ name: 'query' }).pipe(
9 + Args.withDescription('Search query (e.g. "send emails")')
10 +);
11 +
12 +const limit = Options.integer('limit').pipe(
13 + Options.withDefault(10),
14 + Options.withDescription('Number of results per page (1-1000)')
15 +);
16 +
17 +/**
18 + * Search toolkits by use case.
19 + *
20 + * @example
21 + * ```bash
22 + * composio toolkits search "send emails"
23 + * composio toolkits search "messaging" --limit 5
24 + * ```
25 + */
26 +export const toolkitsCmd$Search = Command.make('search', { query, limit }, ({ query, limit }) =>
27 + Effect.gen(function* () {
28 + const ui = yield* TerminalUI;
29 + const ctx = yield* ComposioUserContext;
30 + const repo = yield* ComposioToolkitsRepository;
31 +
32 + // Auth guard
33 + if (Option.isNone(ctx.data.apiKey)) {
34 + yield* ui.log.warn('You are not logged in yet. Please run `composio login`.');
35 + return;
36 + }
37 +
38 + const clampedLimit = Math.max(1, Math.min(1000, limit));
39 +
40 + const result = yield* ui.withSpinner(
41 + `Searching toolkits for "${query}"...`,
42 + repo.searchToolkits({ search: query, limit: clampedLimit })
43 + );
44 +
45 + if (result.items.length === 0) {
46 + yield* ui.log.warn(`No toolkits found matching "${query}". Try broadening your search.`);
47 + return;
48 + }
49 +
50 + yield* ui.log.info(`Found ${result.items.length} toolkits`);
51 + yield* ui.log.message('');
52 + yield* ui.log.message(formatToolkitsTable(result.items));
53 +
54 + // Next step hint
55 + const firstSlug = result.items[0]?.slug;
56 + if (firstSlug) {
57 + yield* ui.log.message('');
58 + yield* ui.log.step(`To view details:\n> composio toolkits info "${firstSlug}"`);
59 + }
60 +
61 + yield* ui.output(formatToolkitsJson(result.items));
62 + })
63 +).pipe(Command.withDescription('Search toolkits by use case.'));
ts/packages/cli/src/commands/toolkits/format.ts new
+45
@@ -0,0 +1,45 @@
1 +import type { Toolkit } from 'src/models/toolkits';
2 +import { bold, gray } from 'src/ui/colors';
3 +
4 +/**
5 + * Truncate a string to the given max length, appending "..." if truncated.
6 + */
7 +function truncate(str: string, max: number): string {
8 + if (str.length <= max) return str;
9 + return str.slice(0, max - 3) + '...';
10 +}
11 +
12 +/**
13 + * Format a list of toolkits as a human-readable table.
14 + */
15 +export function formatToolkitsTable(toolkits: ReadonlyArray<Toolkit>): string {
16 + const header = `${bold('Name'.padEnd(20))} ${bold('Slug'.padEnd(20))} ${bold('Tools'.padEnd(7))} ${bold('Triggers'.padEnd(10))} ${bold('Description')}`;
17 +
18 + const rows = toolkits.map(t => {
19 + const name = t.name.padEnd(20);
20 + const slug = t.slug.padEnd(20);
21 + const tools = String(t.meta.tools_count).padEnd(7);
22 + const triggers = String(t.meta.triggers_count).padEnd(10);
23 + const desc = gray(truncate(t.meta.description, 50));
24 + return `${name} ${slug} ${tools} ${triggers} ${desc}`;
25 + });
26 +
27 + return [header, ...rows].join('\n');
28 +}
29 +
30 +/**
31 + * Format toolkits as JSON for piped output.
32 + */
33 +export function formatToolkitsJson(toolkits: ReadonlyArray<Toolkit>): string {
34 + return JSON.stringify(
35 + toolkits.map(t => ({
36 + name: t.name,
37 + slug: t.slug,
38 + tools_count: t.meta.tools_count,
39 + triggers_count: t.meta.triggers_count,
40 + description: t.meta.description,
41 + })),
42 + null,
43 + 2
44 + );
45 +}
ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts new
+17
@@ -0,0 +1,17 @@
1 +import { Command } from '@effect/cli';
2 +import { toolkitsCmd$List } from './commands/toolkits.list.cmd';
3 +import { toolkitsCmd$Info } from './commands/toolkits.info.cmd';
4 +import { toolkitsCmd$Search } from './commands/toolkits.search.cmd';
5 +
6 +/**
7 + * CLI entry point for toolkit discovery commands.
8 + *
9 + * @example
10 + * ```bash
11 + * composio toolkits <command>
12 + * ```
13 + */
14 +export const toolkitsCmd = Command.make('toolkits').pipe(
15 + Command.withDescription('Discover and inspect Composio toolkits.'),
16 + Command.withSubcommands([toolkitsCmd$List, toolkitsCmd$Info, toolkitsCmd$Search])
17 +);
ts/packages/cli/src/models/toolkits.ts
+78
@@ -13,6 +13,8 @@ export const Toolkit = Schema.Struct({
13 created_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
14 updated_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
15 available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
16 + tools_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
17 + triggers_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
18 }),
19 no_auth: Schema.Boolean,
20 }).annotations({ identifier: 'Toolkit' });
@@ -27,3 +29,79 @@ export const toolkitsToJSON = Schema.encode(ToolkitsJSON);
29
30 export type ToolkitName = string & Brand.Brand<'ToolkitName'>;
31 export const ToolkitName = Brand.nominal<ToolkitName>();
32 +
33 +/**
34 + * Field definition for auth config creation / connected account initiation.
35 + */
36 +export const AuthConfigField = Schema.Struct({
37 + name: Schema.String,
38 + displayName: Schema.String,
39 + description: Schema.String,
40 + type: Schema.String,
41 + required: Schema.Boolean,
42 + default: Schema.optionalWith(Schema.NullOr(Schema.String), { default: () => null }),
43 +}).annotations({ identifier: 'AuthConfigField' });
44 +export type AuthConfigField = Schema.Schema.Type<typeof AuthConfigField>;
45 +
46 +/**
47 + * Auth config detail for a specific auth scheme (e.g. OAUTH2, API_KEY).
48 + */
49 +export const AuthConfigDetail = Schema.Struct({
50 + mode: Schema.String,
51 + name: Schema.String,
52 + fields: Schema.Struct({
53 + auth_config_creation: Schema.Struct({
54 + required: Schema.Array(AuthConfigField),
55 + optional: Schema.Array(AuthConfigField),
56 + }),
57 + connected_account_initiation: Schema.Struct({
58 + required: Schema.Array(AuthConfigField),
59 + optional: Schema.Array(AuthConfigField),
60 + }),
61 + }),
62 +}).annotations({ identifier: 'AuthConfigDetail' });
63 +export type AuthConfigDetail = Schema.Schema.Type<typeof AuthConfigDetail>;
64 +
65 +/**
66 + * Detailed toolkit info from the retrieve endpoint, includes auth_config_details.
67 + */
68 +export const ToolkitDetailed = Schema.Struct({
69 + name: Schema.String,
70 + slug: Schema.Trim.pipe(Schema.nonEmptyString()),
71 + is_local_toolkit: Schema.Boolean,
72 + composio_managed_auth_schemes: Schema.optionalWith(Schema.Array(Schema.String), {
73 + default: () => [],
74 + }),
75 + no_auth: Schema.optionalWith(Schema.Boolean, { default: () => false }),
76 + meta: Schema.Struct({
77 + description: Schema.optionalWith(Schema.String, { default: () => '' }),
78 + categories: Schema.optionalWith(Schema.Array(Schema.Unknown), { default: () => [] }),
79 + created_at: Schema.DateTimeUtc,
80 + updated_at: Schema.DateTimeUtc,
81 + available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
82 + tools_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
83 + triggers_count: Schema.optionalWith(Schema.Int, { default: () => 0 }),
84 + }),
85 + auth_config_details: Schema.optionalWith(Schema.Array(AuthConfigDetail), { default: () => [] }),
86 +}).annotations({ identifier: 'ToolkitDetailed' });
87 +export type ToolkitDetailed = Schema.Schema.Type<typeof ToolkitDetailed>;
88 +
89 +/**
90 + * Toolkit category.
91 + */
92 +export const ToolkitCategory = Schema.Struct({
93 + id: Schema.String,
94 + name: Schema.String,
95 +}).annotations({ identifier: 'ToolkitCategory' });
96 +export type ToolkitCategory = Schema.Schema.Type<typeof ToolkitCategory>;
97 +
98 +/**
99 + * Search result for a single page of toolkits.
100 + */
101 +export const ToolkitSearchResult = Schema.Struct({
102 + items: Toolkits,
103 + total_items: Schema.Int,
104 + total_pages: Schema.Int,
105 + next_cursor: Schema.NullOr(Schema.String),
106 +}).annotations({ identifier: 'ToolkitSearchResult' });
107 +export type ToolkitSearchResult = Schema.Schema.Type<typeof ToolkitSearchResult>;
ts/packages/cli/src/services/composio-clients-cached.ts
+7
@@ -238,6 +238,13 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
238 // 3. Caching validation results could cause false positives/negatives
239 validateToolkitVersions: (overrides, relevantToolkits) =>
240 underlyingRepository.validateToolkitVersions(overrides, relevantToolkits),
241 + // These methods should NOT be cached:
242 + // - searchToolkits: results depend on query params, caching would be misleading
243 + // - getToolkitDetailed: detailed info should be fresh (auth config fields change)
244 + // - getCategories: categories change infrequently but are cheap to fetch
245 + searchToolkits: params => underlyingRepository.searchToolkits(params),
246 + getToolkitDetailed: slug => underlyingRepository.getToolkitDetailed(slug),
247 + getCategories: () => underlyingRepository.getCategories(),
248 });
249 })
250 ).pipe(
ts/packages/cli/src/services/composio-clients.ts
+108 -2
@@ -13,7 +13,13 @@ import {
13 SynchronizedRef,
14 } from 'effect';
15 import { Composio as _RawComposioClient, APIPromise } from '@composio/client';
16 -import { Toolkit, Toolkits } from 'src/models/toolkits';
16 +import {
17 + Toolkit,
18 + Toolkits,
19 + ToolkitDetailed,
20 + ToolkitCategory,
21 + type ToolkitSearchResult,
22 +} from 'src/models/toolkits';
23 import { ToolsAsEnums, Tools, Tool } from 'src/models/tools';
24 import {
25 groupByVersion,
@@ -253,6 +259,27 @@ export const TriggerTypesResponse = Schema.Struct({
259 next_cursor: Schema.NullOr(Schema.String),
260 }).annotations({ identifier: 'TriggerTypesResponse' });
261
262 +// Single-page search response (includes total_items for "Listing X of Y" display)
263 +export const ToolkitSearchResponse = Schema.Struct({
264 + items: Toolkits,
265 + total_items: Schema.Int,
266 + total_pages: Schema.Int,
267 + current_page: Schema.Int,
268 + next_cursor: Schema.NullOr(Schema.String),
269 +}).annotations({ identifier: 'ToolkitSearchResponse' });
270 +
271 +// Detailed retrieve response (includes auth_config_details)
272 +export const ToolkitDetailedResponse = ToolkitDetailed.annotations({
273 + identifier: 'ToolkitDetailedResponse',
274 +});
275 +
276 +// Categories response
277 +export const ToolkitCategoriesResponse = Schema.Struct({
278 + items: Schema.Array(ToolkitCategory),
279 + total_items: Schema.Int,
280 + next_cursor: Schema.NullOr(Schema.String),
281 +}).annotations({ identifier: 'ToolkitCategoriesResponse' });
282 +
283 /**
284 * Error response schemas
285 */
@@ -640,10 +667,70 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
667 composio_managed_auth_schemes: retrieved.composio_managed_auth_schemes,
668 is_local_toolkit: retrieved.is_local_toolkit,
669 no_auth: retrieved.no_auth,
643 - meta: retrieved.meta,
670 + meta: {
671 + ...retrieved.meta,
672 + tools_count: 0,
673 + triggers_count: 0,
674 + },
675 }) satisfies Toolkit
676 )
677 ),
678 + /**
679 + * Searches toolkits with optional filters. Returns a single page of results (no auto-pagination).
680 + * @param params - Search/filter parameters
681 + */
682 + search: (params: {
683 + search?: string;
684 + category?: string;
685 + limit?: number;
686 + cursor?: string;
687 + }) =>
688 + withMetrics(
689 + callClient(
690 + clientSingleton,
691 + client =>
692 + client.toolkits.list({
693 + search: params.search,
694 + category: params.category,
695 + limit: params.limit,
696 + cursor: params.cursor,
697 + }),
698 + ToolkitSearchResponse
699 + )
700 + ).pipe(
701 + Effect.map(
702 + response =>
703 + ({
704 + items: response.items,
705 + total_items: response.total_items,
706 + total_pages: response.total_pages,
707 + next_cursor: response.next_cursor,
708 + }) satisfies ToolkitSearchResult
709 + )
710 + ),
711 + /**
712 + * Retrieves detailed toolkit info including auth_config_details.
713 + * @param slug - Toolkit slug
714 + */
715 + retrieveDetailed: (slug: string) =>
716 + withMetrics(
717 + callClient(
718 + clientSingleton,
719 + client => client.toolkits.retrieve(slug),
720 + ToolkitDetailedResponse
721 + )
722 + ),
723 + /**
724 + * Retrieves all available toolkit categories.
725 + */
726 + retrieveCategories: () =>
727 + withMetrics(
728 + callClient(
729 + clientSingleton,
730 + client => client.toolkits.retrieveCategories(),
731 + ToolkitCategoriesResponse
732 + )
733 + ).pipe(Effect.map(response => response.items)),
734 },
735 tools: {
736 /**
@@ -951,6 +1038,25 @@ export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsR
1038 },
1039 InvalidToolkitVersionsError | InvalidToolkitsError | HttpError | NoSuchElementException
1040 > => validateToolkitVersionsImpl(client, overrides, relevantToolkits),
1041 + /**
1042 + * Searches toolkits with optional filters. Returns a single page of results.
1043 + * @param params - Search/filter parameters
1044 + */
1045 + searchToolkits: (params: {
1046 + search?: string;
1047 + category?: string;
1048 + limit?: number;
1049 + cursor?: string;
1050 + }) => client.toolkits.search(params),
1051 + /**
1052 + * Retrieves detailed toolkit info including auth_config_details.
1053 + * @param slug - Toolkit slug
1054 + */
1055 + getToolkitDetailed: (slug: string) => client.toolkits.retrieveDetailed(slug),
1056 + /**
1057 + * Retrieves all available toolkit categories.
1058 + */
1059 + getCategories: () => client.toolkits.retrieveCategories(),
1060 };
1061 }),
1062 dependencies: [ComposioClientLive.Default],
ts/packages/cli/test/__utils__/services/test-layer.ts
+45 -1
@@ -18,11 +18,12 @@ import { ComposioCliConfig } from 'src/cli-config';
18 import * as MockConsole from './mock-console';
19 import * as MockTerminal from './mock-terminal';
20 import { TerminalUITest } from './terminal-ui-test';
21 -import type { Toolkits } from 'src/models/toolkits';
21 +import type { Toolkits, ToolkitDetailed, ToolkitCategory } from 'src/models/toolkits';
22 import { NodeProcess } from 'src/services/node-process';
23 import {
24 ComposioSessionRepository,
25 ComposioToolkitsRepository,
26 + HttpServerError,
27 InvalidToolkitsError,
28 InvalidToolkitVersionsError,
29 type InvalidVersionDetail,
@@ -55,6 +56,8 @@ export interface TestLiveInput {
56 */
57 toolkitsData?: {
58 toolkits?: Toolkits;
59 + detailedToolkits?: ToolkitDetailed[];
60 + categories?: ToolkitCategory[];
61 tools?: Tools;
62 triggerTypesAsEnums?: TriggerTypesAsEnums;
63 triggerTypes?: TriggerTypes;
@@ -81,6 +84,8 @@ export const TestLayer = (input?: TestLiveInput) =>
84 Effect.gen(function* () {
85 const defaultAppClientData = {
86 toolkits: [] as Toolkits,
87 + detailedToolkits: [] as ToolkitDetailed[],
88 + categories: [] as ToolkitCategory[],
89 tools: [] as Tools,
90 triggerTypesAsEnums: [] as TriggerTypesAsEnums,
91 triggerTypes: [] as TriggerTypes,
@@ -213,6 +218,45 @@ export const TestLayer = (input?: TestLiveInput) =>
218 warnings: warnings as ReadonlyArray<string>,
219 });
220 },
221 + searchToolkits: (params: {
222 + search?: string;
223 + category?: string;
224 + limit?: number;
225 + cursor?: string;
226 + }) => {
227 + let results = [...toolkitsData.toolkits];
228 +
229 + if (params.search) {
230 + const q = params.search.toLowerCase();
231 + results = results.filter(
232 + t =>
233 + t.name.toLowerCase().includes(q) ||
234 + t.slug.toLowerCase().includes(q) ||
235 + t.meta.description.toLowerCase().includes(q)
236 + );
237 + }
238 +
239 + const limit = params.limit ?? 30;
240 + const items = results.slice(0, limit);
241 + return Effect.succeed({
242 + items,
243 + total_items: results.length,
244 + total_pages: Math.ceil(results.length / limit),
245 + next_cursor: null,
246 + });
247 + },
248 + getToolkitDetailed: (slug: string) => {
249 + const found = toolkitsData.detailedToolkits.find(
250 + t => t.slug.toLowerCase() === slug.toLowerCase()
251 + );
252 + if (!found) {
253 + return Effect.fail(
254 + new HttpServerError({ cause: `Toolkit "${slug}" not found`, status: 404 })
255 + );
256 + }
257 + return Effect.succeed(found);
258 + },
259 + getCategories: () => Effect.succeed(toolkitsData.categories),
260 })
261 );
262 const ComposioSessionRepositoryTest = yield* setupComposioSessionRepository();
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'"
18 + "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts', 'toolkits'"
19 )
20 )
21 );
@@ -83,6 +83,14 @@ describe('CLI: composio', () => {
83 Environment Variables:
84 COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
85 Use "latest" or unset to use the latest version.
86 +
87 + - toolkits Discover and inspect Composio toolkits.
88 +
89 + - toolkits list [--query text] [--category text] [--limit integer] List available toolkits.
90 +
91 + - toolkits info <slug> View details of a specific toolkit.
92 +
93 + - toolkits search [--limit integer] <query> Search toolkits by use case.
94 "
95 `);
96 })
ts/packages/cli/test/src/commands/toolkits/toolkits.info.cmd.test.ts new
+180
@@ -0,0 +1,180 @@
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 { Toolkits, ToolkitDetailed } from 'src/models/toolkits';
7 +
8 +const testToolkits: Toolkits = [
9 + {
10 + name: 'Gmail',
11 + slug: 'gmail',
12 + auth_schemes: ['OAUTH2', 'BEARER_TOKEN'],
13 + composio_managed_auth_schemes: ['OAUTH2'],
14 + is_local_toolkit: false,
15 + no_auth: false,
16 + meta: {
17 + description: 'Email service to send and receive emails',
18 + categories: [],
19 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
20 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
21 + available_versions: [],
22 + tools_count: 36,
23 + triggers_count: 2,
24 + },
25 + },
26 +];
27 +
28 +const detailedToolkits: ToolkitDetailed[] = [
29 + {
30 + name: 'Gmail',
31 + slug: 'gmail',
32 + is_local_toolkit: false,
33 + composio_managed_auth_schemes: ['OAUTH2'],
34 + no_auth: false,
35 + meta: {
36 + description: 'Email service to send and receive emails',
37 + categories: [],
38 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
39 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
40 + available_versions: [],
41 + tools_count: 36,
42 + triggers_count: 2,
43 + },
44 + auth_config_details: [
45 + {
46 + mode: 'OAUTH2',
47 + name: 'OAuth 2.0',
48 + fields: {
49 + auth_config_creation: { required: [], optional: [] },
50 + connected_account_initiation: { required: [], optional: [] },
51 + },
52 + },
53 + {
54 + mode: 'BEARER_TOKEN',
55 + name: 'Bearer Token',
56 + fields: {
57 + auth_config_creation: {
58 + required: [
59 + {
60 + name: 'apiKey',
61 + displayName: 'API Key',
62 + description: 'Your API key',
63 + type: 'string',
64 + required: true,
65 + default: null,
66 + },
67 + ],
68 + optional: [],
69 + },
70 + connected_account_initiation: {
71 + required: [
72 + {
73 + name: 'apiKey',
74 + displayName: 'API Key',
75 + description: 'Your API key',
76 + type: 'string',
77 + required: true,
78 + default: null,
79 + },
80 + ],
81 + optional: [],
82 + },
83 + },
84 + },
85 + ],
86 + },
87 + {
88 + name: 'Code Interpreter',
89 + slug: 'codeinterpreter',
90 + is_local_toolkit: false,
91 + composio_managed_auth_schemes: [],
92 + no_auth: true,
93 + meta: {
94 + description: 'Execute code snippets',
95 + categories: [],
96 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
97 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
98 + available_versions: [],
99 + tools_count: 5,
100 + triggers_count: 0,
101 + },
102 + auth_config_details: [],
103 + },
104 +];
105 +
106 +const toolkitsData = {
107 + toolkits: testToolkits,
108 + detailedToolkits,
109 +} satisfies TestLiveInput['toolkitsData'];
110 +
111 +const testConfigProvider = ConfigProvider.fromMap(
112 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
113 +).pipe(extendConfigProvider);
114 +
115 +describe('CLI: composio toolkits info', () => {
116 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
117 + '[Given] valid slug "gmail"',
118 + it => {
119 + it.scoped('shows detailed info with auth schemes', () =>
120 + Effect.gen(function* () {
121 + yield* cli(['toolkits', 'info', 'gmail']);
122 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
123 + const output = lines.join('\n');
124 +
125 + expect(output).toContain('Gmail');
126 + expect(output).toContain('gmail');
127 + expect(output).toContain('Email service to send and receive emails');
128 + expect(output).toContain('OAUTH2');
129 + expect(output).toContain('BEARER_TOKEN');
130 + expect(output).toContain('apiKey');
131 + expect(output).toContain('AuthConfig creation');
132 + expect(output).toContain('Connected Account creation');
133 + })
134 + );
135 + }
136 + );
137 +
138 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
139 + '[Given] toolkit with no_auth=true',
140 + it => {
141 + it.scoped('shows "No authentication required"', () =>
142 + Effect.gen(function* () {
143 + yield* cli(['toolkits', 'info', 'codeinterpreter']);
144 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
145 + const output = lines.join('\n');
146 +
147 + expect(output).toContain('Code Interpreter');
148 + expect(output).toContain('No authentication required');
149 + })
150 + );
151 + }
152 + );
153 +
154 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
155 + '[Given] invalid slug',
156 + it => {
157 + it.scoped('shows error', () =>
158 + Effect.gen(function* () {
159 + const result = yield* cli(['toolkits', 'info', 'gmal']).pipe(Effect.either);
160 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
161 + const output = lines.join('\n');
162 +
163 + expect(output).toContain('not found');
164 + })
165 + );
166 + }
167 + );
168 +
169 + layer(TestLive())('[Given] no API key', it => {
170 + it.scoped('warns user to login', () =>
171 + Effect.gen(function* () {
172 + yield* cli(['toolkits', 'info', 'gmail']);
173 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
174 + const output = lines.join('\n');
175 +
176 + expect(output).toContain('not logged in');
177 + })
178 + );
179 + });
180 +});
ts/packages/cli/test/src/commands/toolkits/toolkits.list.cmd.test.ts new
+145
@@ -0,0 +1,145 @@
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 { Toolkits } from 'src/models/toolkits';
7 +
8 +const testToolkits: Toolkits = [
9 + {
10 + name: 'Gmail',
11 + slug: 'gmail',
12 + auth_schemes: ['OAUTH2'],
13 + composio_managed_auth_schemes: ['OAUTH2'],
14 + is_local_toolkit: false,
15 + no_auth: false,
16 + meta: {
17 + description: 'Email service to send and receive emails',
18 + categories: [],
19 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
20 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
21 + available_versions: [],
22 + tools_count: 36,
23 + triggers_count: 2,
24 + },
25 + },
26 + {
27 + name: 'Slack',
28 + slug: 'slack',
29 + auth_schemes: ['OAUTH2'],
30 + composio_managed_auth_schemes: ['OAUTH2'],
31 + is_local_toolkit: false,
32 + no_auth: false,
33 + meta: {
34 + description: 'Messaging platform for teams',
35 + categories: [],
36 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
37 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
38 + available_versions: [],
39 + tools_count: 42,
40 + triggers_count: 5,
41 + },
42 + },
43 + {
44 + name: 'GitHub',
45 + slug: 'github',
46 + auth_schemes: ['OAUTH2'],
47 + composio_managed_auth_schemes: ['OAUTH2'],
48 + is_local_toolkit: false,
49 + no_auth: false,
50 + meta: {
51 + description: 'Code hosting and collaboration platform',
52 + categories: [],
53 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
54 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
55 + available_versions: [],
56 + tools_count: 50,
57 + triggers_count: 10,
58 + },
59 + },
60 +];
61 +
62 +const toolkitsData = {
63 + toolkits: testToolkits,
64 +} satisfies TestLiveInput['toolkitsData'];
65 +
66 +const testConfigProvider = ConfigProvider.fromMap(
67 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
68 +).pipe(extendConfigProvider);
69 +
70 +describe('CLI: composio toolkits list', () => {
71 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
72 + '[Given] no flags [Then] lists all toolkits',
73 + it => {
74 + it.scoped('lists all toolkits', () =>
75 + Effect.gen(function* () {
76 + yield* cli(['toolkits', 'list']);
77 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
78 + const output = lines.join('\n');
79 +
80 + expect(output).toContain('Gmail');
81 + expect(output).toContain('gmail');
82 + expect(output).toContain('Slack');
83 + expect(output).toContain('GitHub');
84 + expect(output).toContain('Listing 3 of 3 toolkits');
85 + })
86 + );
87 + }
88 + );
89 +
90 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
91 + '[Given] --query "email"',
92 + it => {
93 + it.scoped('shows filtered results', () =>
94 + Effect.gen(function* () {
95 + yield* cli(['toolkits', 'list', '--query', 'email']);
96 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
97 + const output = lines.join('\n');
98 +
99 + expect(output).toContain('Gmail');
100 + expect(output).not.toContain('GitHub');
101 + expect(output).toContain('Listing 1 of 1 toolkits');
102 + })
103 + );
104 + }
105 + );
106 +
107 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
108 + '[Given] --limit 2',
109 + it => {
110 + it.scoped('respects limit', () =>
111 + Effect.gen(function* () {
112 + yield* cli(['toolkits', 'list', '--limit', '2']);
113 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
114 + const output = lines.join('\n');
115 +
116 + expect(output).toContain('Listing 2 of 3 toolkits');
117 + })
118 + );
119 + }
120 + );
121 +
122 + layer(TestLive())('[Given] no API key', it => {
123 + it.scoped('warns user to login', () =>
124 + Effect.gen(function* () {
125 + yield* cli(['toolkits', 'list']);
126 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
127 + const output = lines.join('\n');
128 +
129 + expect(output).toContain('not logged in');
130 + })
131 + );
132 + });
133 +
134 + layer(TestLive({ baseConfigProvider: testConfigProvider }))('[Given] empty results', it => {
135 + it.scoped('shows no toolkits found', () =>
136 + Effect.gen(function* () {
137 + yield* cli(['toolkits', 'list']);
138 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
139 + const output = lines.join('\n');
140 +
141 + expect(output).toContain('No toolkits found');
142 + })
143 + );
144 + });
145 +});
ts/packages/cli/test/src/commands/toolkits/toolkits.search.cmd.test.ts new
+130
@@ -0,0 +1,130 @@
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 { Toolkits } from 'src/models/toolkits';
7 +
8 +const testToolkits: Toolkits = [
9 + {
10 + name: 'Gmail',
11 + slug: 'gmail',
12 + auth_schemes: ['OAUTH2'],
13 + composio_managed_auth_schemes: ['OAUTH2'],
14 + is_local_toolkit: false,
15 + no_auth: false,
16 + meta: {
17 + description: 'Email service to send and receive emails',
18 + categories: [],
19 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
20 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
21 + available_versions: [],
22 + tools_count: 36,
23 + triggers_count: 2,
24 + },
25 + },
26 + {
27 + name: 'Outlook',
28 + slug: 'outlook',
29 + auth_schemes: ['OAUTH2'],
30 + composio_managed_auth_schemes: ['OAUTH2'],
31 + is_local_toolkit: false,
32 + no_auth: false,
33 + meta: {
34 + description: 'Microsoft email service',
35 + categories: [],
36 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
37 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
38 + available_versions: [],
39 + tools_count: 28,
40 + triggers_count: 1,
41 + },
42 + },
43 + {
44 + name: 'Slack',
45 + slug: 'slack',
46 + auth_schemes: ['OAUTH2'],
47 + composio_managed_auth_schemes: ['OAUTH2'],
48 + is_local_toolkit: false,
49 + no_auth: false,
50 + meta: {
51 + description: 'Messaging platform for teams',
52 + categories: [],
53 + created_at: new Date('2024-05-03T11:44:32.061Z') as any,
54 + updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
55 + available_versions: [],
56 + tools_count: 42,
57 + triggers_count: 5,
58 + },
59 + },
60 +];
61 +
62 +const toolkitsData = {
63 + toolkits: testToolkits,
64 +} satisfies TestLiveInput['toolkitsData'];
65 +
66 +const testConfigProvider = ConfigProvider.fromMap(
67 + new Map([['COMPOSIO_API_KEY', 'test_api_key']])
68 +).pipe(extendConfigProvider);
69 +
70 +describe('CLI: composio toolkits search', () => {
71 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
72 + '[Given] query "email"',
73 + it => {
74 + it.scoped('shows matching toolkits', () =>
75 + Effect.gen(function* () {
76 + yield* cli(['toolkits', 'search', 'email']);
77 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
78 + const output = lines.join('\n');
79 +
80 + expect(output).toContain('Gmail');
81 + expect(output).toContain('Outlook');
82 + expect(output).not.toContain('Slack');
83 + expect(output).toContain('Found 2 toolkits');
84 + })
85 + );
86 + }
87 + );
88 +
89 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
90 + '[Given] query with no results',
91 + it => {
92 + it.scoped('shows "No toolkits found"', () =>
93 + Effect.gen(function* () {
94 + yield* cli(['toolkits', 'search', 'xyzzy']);
95 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
96 + const output = lines.join('\n');
97 +
98 + expect(output).toContain('No toolkits found');
99 + })
100 + );
101 + }
102 + );
103 +
104 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
105 + '[Given] --limit 1',
106 + it => {
107 + it.scoped('respects limit', () =>
108 + Effect.gen(function* () {
109 + yield* cli(['toolkits', 'search', 'email', '--limit', '1']);
110 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
111 + const output = lines.join('\n');
112 +
113 + expect(output).toContain('Found 1 toolkits');
114 + })
115 + );
116 + }
117 + );
118 +
119 + layer(TestLive())('[Given] no API key', it => {
120 + it.scoped('warns user to login', () =>
121 + Effect.gen(function* () {
122 + yield* cli(['toolkits', 'search', 'email']);
123 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
124 + const output = lines.join('\n');
125 +
126 + expect(output).toContain('not logged in');
127 + })
128 + );
129 + });
130 +});