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.

fix(cli): unify toolkits list/search output into a single stable schema

jkomyno9d2f3fe5a203
diff --git a/ts/e2e-tests/cli/toolkits/list/e2e.test.ts b/ts/e2e-tests/cli/toolkits/list/e2e.test.ts
index 3bb155b49..972a00584 100644
--- a/ts/e2e-tests/cli/toolkits/list/e2e.test.ts
+++ b/ts/e2e-tests/cli/toolkits/list/e2e.test.ts
@@ -58,10 +58,12 @@ e2e(import.meta.url, {
expect(item).toHaveProperty('name');
expect(item).toHaveProperty('slug');
expect(item).toHaveProperty('description');
- // `toolkits list` without user-id uses legacy listing output.
expect(item).toHaveProperty('latest_version');
expect(item).toHaveProperty('tools_count');
expect(item).toHaveProperty('triggers_count');
+ expect(item).toHaveProperty('is_no_auth');
+ expect(item).toHaveProperty('enabled');
+ expect(item).toHaveProperty('connected');
});
});
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
index ab37f2d2a..1b03a6e64 100644
--- a/ts/packages/cli/src/commands/toolkits/commands/toolkits.list.cmd.ts
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.list.cmd.ts
@@ -8,12 +8,7 @@ import { ProjectContext } from 'src/services/project-context';
import { ComposioUserContext } from 'src/services/user-context';
import { clampLimit } from 'src/ui/clamp-limit';
import { extractMessage } from 'src/utils/api-error-extraction';
-import {
- formatLegacyToolkitsJson,
- formatLegacyToolkitsTable,
- formatToolkitsJson,
- formatToolkitsTable,
-} from '../format';
+import { mergeToolkitData, formatToolkitsJson, formatToolkitsTable } from '../format';
const query = Options.text('query').pipe(
Options.withDescription('Text search by name, slug, or description'),
@@ -40,6 +35,10 @@ const userId = Options.text('user-id').pipe(
/**
* List available toolkits with connection status.
*
+ * Always fetches catalog data (tools_count, triggers_count, latest_version).
+ * When a user ID is available (explicit --user-id, project, or global config),
+ * also fetches session data to enrich with connection status.
+ *
* @example
* ```bash
* composio toolkits list
@@ -80,78 +79,72 @@ export const toolkitsCmd$List = Command.make(
yield* ui.log.message('To show status for a specific user, use `--user-id`.');
}
- if (Option.isSome(resolvedUserId)) {
- const result = yield* ui.withSpinner(
- 'Fetching toolkits...',
- Effect.gen(function* () {
- const { client, sessionId } = yield* resolveToolRouterSession(resolvedUserId.value);
- return yield* Effect.tryPromise(() =>
- client.toolRouter.session.toolkits(sessionId, {
- search: Option.getOrUndefined(query),
- limit: clampedLimit,
- is_connected: Option.getOrUndefined(connected),
- })
- );
- })
- );
-
- const { items } = result;
- if (items.length === 0) {
- yield* ui.log.warn('No toolkits found. Try broadening your search.');
- yield* ui.output('[]');
- return;
- }
-
- const showing = items.length;
- const total = result.total_items;
- yield* ui.log.info(
- `Listing ${showing} of ${total} toolkits\n\n${formatToolkitsTable(items)}`
- );
-
- const firstSlug = items[0]?.slug;
- if (firstSlug) {
- yield* ui.log.step(
- `To view details of a toolkit:\n> composio toolkits info "${firstSlug}"`
- );
- }
- yield* ui.output(formatToolkitsJson(items));
- return;
- }
-
- if (Option.isSome(connected)) {
+ if (Option.isSome(connected) && Option.isNone(resolvedUserId)) {
yield* ui.log.warn(
'`--connected` requires a user id. Use `--user-id` or run `composio init`.'
);
}
- const result = yield* ui.withSpinner(
+ // Always fetch catalog data (has tools_count, triggers_count, versions).
+ const catalogResult = yield* ui.withSpinner(
'Fetching toolkits...',
repo.searchToolkits({
search: Option.getOrUndefined(query),
limit: clampedLimit,
})
);
- const items = result.items;
- if (items.length === 0) {
+
+ if (catalogResult.items.length === 0) {
yield* ui.log.warn('No toolkits found. Try broadening your search.');
yield* ui.output('[]');
return;
}
- const showing = items.length;
- const total = result.total_items;
+
+ // When a user ID is available, also fetch session data for connection status.
+ let sessionItems:
+ | ReadonlyArray<
+ import('@composio/client/resources/tool-router').SessionToolkitsResponse.Item
+ >
+ | undefined;
+ if (Option.isSome(resolvedUserId)) {
+ sessionItems = yield* resolveToolRouterSession(resolvedUserId.value).pipe(
+ Effect.flatMap(({ client, sessionId }) =>
+ Effect.tryPromise(() =>
+ client.toolRouter.session.toolkits(sessionId, {
+ search: Option.getOrUndefined(query),
+ limit: clampedLimit,
+ is_connected: Option.getOrUndefined(connected),
+ })
+ )
+ ),
+ Effect.map(r => r.items),
+ Effect.catchAll(error =>
+ Effect.gen(function* () {
+ yield* Effect.logDebug('Failed to fetch session data for connection status:', error);
+ return [] as ReadonlyArray<
+ import('@composio/client/resources/tool-router').SessionToolkitsResponse.Item
+ >;
+ })
+ )
+ );
+ if (sessionItems.length === 0) sessionItems = undefined;
+ }
+
+ const unified = mergeToolkitData(catalogResult.items, sessionItems);
+
+ const showing = unified.length;
+ const total = catalogResult.total_items;
yield* ui.log.info(
- `Listing ${showing} of ${total} toolkits\n\n${formatLegacyToolkitsTable(items)}`
+ `Listing ${showing} of ${total} toolkits\n\n${formatToolkitsTable(unified)}`
);
- // Next step hint
- const firstSlug = items[0]?.slug;
+ const firstSlug = unified[0]?.slug;
if (firstSlug) {
yield* ui.log.step(
`To view details of a toolkit:\n> composio toolkits info "${firstSlug}"`
);
}
-
- yield* ui.output(formatLegacyToolkitsJson(items));
+ yield* ui.output(formatToolkitsJson(unified));
}).pipe(
Effect.catchAll(error =>
Effect.gen(function* () {
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
index c008a515e..ea08ad1cc 100644
--- a/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts
@@ -5,7 +5,7 @@ import { TerminalUI } from 'src/services/terminal-ui';
import { requireAuth } from 'src/effects/require-auth';
import { clampLimit } from 'src/ui/clamp-limit';
import { extractMessage } from 'src/utils/api-error-extraction';
-import { formatLegacyToolkitsTable, formatLegacyToolkitsJson } from '../format';
+import { mergeToolkitData, formatToolkitsTable, formatToolkitsJson } from '../format';
const query = Args.text({ name: 'query' }).pipe(
Args.withDescription('Search query (e.g. "send emails")')
@@ -50,17 +50,17 @@ export const toolkitsCmd$Search = Command.make('search', { query, limit }, ({ qu
const showing = result.items.length;
const total = result.total_items;
- yield* ui.log.info(
- `Found ${showing} of ${total} toolkits\n\n${formatLegacyToolkitsTable(result.items)}`
- );
+ const unified = mergeToolkitData(result.items);
+
+ yield* ui.log.info(`Found ${showing} of ${total} toolkits\n\n${formatToolkitsTable(unified)}`);
// Next step hint
- const firstSlug = result.items[0]?.slug;
+ const firstSlug = unified[0]?.slug;
if (firstSlug) {
yield* ui.log.step(`To view details:\n> composio toolkits info "${firstSlug}"`);
}
- yield* ui.output(formatLegacyToolkitsJson(result.items));
+ yield* ui.output(formatToolkitsJson(unified));
}).pipe(
Effect.catchAll(error =>
Effect.gen(function* () {
diff --git a/ts/packages/cli/src/commands/toolkits/format.ts b/ts/packages/cli/src/commands/toolkits/format.ts
index 5e8751800..36602fdb1 100644
--- a/ts/packages/cli/src/commands/toolkits/format.ts
+++ b/ts/packages/cli/src/commands/toolkits/format.ts
@@ -21,65 +21,106 @@ const formatAuthConfigField = (field: {
` description: ${field.description || '-'}`,
].join('\n');
-// ---------- Tool Router format functions ----------
+// ---------- Unified toolkit list format ----------
/**
- * Derive connection status text and color from a session toolkit item.
- * Returns plain text + color function so callers can pad before coloring.
+ * Unified representation of a toolkit for list/search output.
+ * Catalog data is always present; connection data is optional (requires a user session).
*/
-function connectionStatusParts(item: SessionToolkitItem): {
+export interface UnifiedToolkit {
+ name: string;
+ slug: string;
+ description: string;
+ latest_version: string | null;
+ tools_count: number;
+ triggers_count: number;
+ is_no_auth: boolean;
+ enabled: boolean | null;
+ connected: {
+ status: string;
+ id: string;
+ auth_scheme: string | null;
+ is_composio_managed: boolean | null;
+ } | null;
+}
+
+/**
+ * Build unified toolkit items from catalog data, optionally enriched with
+ * session connection data (keyed by slug).
+ */
+export function mergeToolkitData(
+ catalogItems: ReadonlyArray<Toolkit>,
+ sessionItems?: ReadonlyArray<SessionToolkitItem>
+): UnifiedToolkit[] {
+ const sessionBySlug = new Map<string, SessionToolkitItem>();
+ if (sessionItems) {
+ for (const s of sessionItems) {
+ sessionBySlug.set(s.slug, s);
+ }
+ }
+
+ return catalogItems.map(t => {
+ const session = sessionBySlug.get(t.slug);
+ return {
+ name: t.name,
+ slug: t.slug,
+ description: t.meta.description,
+ latest_version: t.meta.available_versions.at(-1) ?? null,
+ tools_count: t.meta.tools_count,
+ triggers_count: t.meta.triggers_count,
+ is_no_auth: t.no_auth,
+ enabled: session?.enabled ?? null,
+ connected: session?.connected_account
+ ? {
+ status: session.connected_account.status,
+ id: session.connected_account.id,
+ auth_scheme: session.connected_account.auth_config?.auth_scheme ?? null,
+ is_composio_managed: session.connected_account.auth_config?.is_composio_managed ?? null,
+ }
+ : null,
+ };
+ });
+}
+
+/**
+ * Derive connection status text and color from a unified toolkit.
+ */
+function connectionStatusParts(item: UnifiedToolkit): {
text: string;
color: (s: string) => string;
} {
if (item.is_no_auth) return { text: 'no auth', color: dim };
- if (item.connected_account?.status === 'ACTIVE') return { text: 'active', color: green };
+ if (item.connected?.status === 'ACTIVE') return { text: 'active', color: green };
+ if (item.connected === null && item.enabled === null) return { text: '-', color: dim };
return { text: 'not connected', color: dim };
}
/**
- * Format a list of session toolkits as a human-readable table.
+ * Format a list of unified toolkits as a human-readable table.
*/
-export function formatToolkitsTable(toolkits: ReadonlyArray<SessionToolkitItem>): string {
- const header = `${bold('Name'.padEnd(20))} ${bold('Slug'.padEnd(20))} ${bold('Connected'.padEnd(16))} ${bold('Auth Scheme'.padEnd(14))} ${bold('Description')}`;
+export function formatToolkitsTable(toolkits: ReadonlyArray<UnifiedToolkit>): string {
+ const header = `${bold('Name'.padEnd(20))} ${bold('Slug'.padEnd(20))} ${bold('Version'.padEnd(12))} ${bold('Tools'.padEnd(7))} ${bold('Triggers'.padEnd(10))} ${bold('Connected'.padEnd(16))} ${bold('Description')}`;
const rows = toolkits.map(t => {
const name = t.name.padEnd(20);
const slug = t.slug.padEnd(20);
- // Pad plain text first, then apply color — ANSI escapes break padEnd.
+ const version = (t.latest_version ?? '-').padEnd(12);
+ const tools = String(t.tools_count).padEnd(7);
+ const triggers = String(t.triggers_count).padEnd(10);
const { text: statusText, color: statusColor } = connectionStatusParts(t);
const status = statusColor(statusText.padEnd(16));
- const authScheme = (t.connected_account?.auth_config?.auth_scheme ?? '-').padEnd(14);
- const desc = gray(truncate(t.meta.description, 50));
- return `${name} ${slug} ${status} ${authScheme} ${desc}`;
+ const desc = gray(truncate(t.description, 50));
+ return `${name} ${slug} ${version} ${tools} ${triggers} ${status} ${desc}`;
});
return [header, ...rows].join('\n');
}
/**
- * Format session toolkits as JSON for piped output.
+ * Format unified toolkits as JSON for piped output.
*/
-export function formatToolkitsJson(toolkits: ReadonlyArray<SessionToolkitItem>): string {
- return JSON.stringify(
- toolkits.map(t => ({
- name: t.name,
- slug: t.slug,
- description: t.meta.description,
- is_no_auth: t.is_no_auth,
- enabled: t.enabled,
- connected: t.connected_account
- ? {
- status: t.connected_account.status,
- id: t.connected_account.id,
- auth_scheme: t.connected_account.auth_config?.auth_scheme ?? null,
- is_composio_managed: t.connected_account.auth_config?.is_composio_managed ?? null,
- }
- : null,
- composio_managed_auth_schemes: t.composio_managed_auth_schemes,
- })),
- null,
- 2
- );
+export function formatToolkitsJson(toolkits: ReadonlyArray<UnifiedToolkit>): string {
+ return JSON.stringify(toolkits, null, 2);
}
/**
@@ -238,42 +279,3 @@ export function formatToolkitInfoJson(
2
);
}
-
-// ---------- Legacy format functions (used by non-migrated commands) ----------
-
-/**
- * Format a list of toolkits as a human-readable table (legacy format).
- */
-export function formatLegacyToolkitsTable(toolkits: ReadonlyArray<Toolkit>): string {
- const header = `${bold('Name'.padEnd(20))} ${bold('Slug'.padEnd(20))} ${bold('Version'.padEnd(12))} ${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 version = (t.meta.available_versions.at(-1) ?? '-').padEnd(12);
- 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} ${version} ${tools} ${triggers} ${desc}`;
- });
-
- return [header, ...rows].join('\n');
-}
-
-/**
- * Format toolkits as JSON for piped output (legacy format).
- */
-export function formatLegacyToolkitsJson(toolkits: ReadonlyArray<Toolkit>): string {
- return JSON.stringify(
- toolkits.map(t => ({
- name: t.name,
- slug: t.slug,
- latest_version: t.meta.available_versions.at(-1) ?? null,
- tools_count: t.meta.tools_count,
- triggers_count: t.meta.triggers_count,
- description: t.meta.description,
- })),
- null,
- 2
- );
-}