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): add toolkit fallback and toolkit version command (#2784)

Musthaq Ahamad080572733742
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
index c465a9e0b..0d7589f8a 100644
--- a/ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts
@@ -5,6 +5,8 @@ import { TerminalUI } from 'src/services/terminal-ui';
import { requireAuth } from 'src/effects/require-auth';
import { resolveToolRouterSession } from 'src/effects/create-tool-router-session';
import { extractMessage } from 'src/utils/api-error-extraction';
+import { ProjectContext } from 'src/services/project-context';
+import { ComposioUserContext } from 'src/services/user-context';
import { formatToolkitInfo, formatToolkitInfoJson } from '../format';
const slug = Args.text({ name: 'slug' }).pipe(
@@ -13,8 +15,10 @@ const slug = Args.text({ name: 'slug' }).pipe(
);
const userId = Options.text('user-id').pipe(
- Options.withDefault('default'),
- Options.withDescription('User ID for connection status (default: "default")')
+ Options.optional,
+ Options.withDescription(
+ 'User ID for connection status (falls back to project/global test_user_id, then "default")'
+ )
);
const allDetails = Options.boolean('all').pipe(
@@ -40,6 +44,8 @@ export const toolkitsCmd$Info = Command.make(
if (!(yield* requireAuth)) return;
const ui = yield* TerminalUI;
+ const projectContext = yield* ProjectContext;
+ const userContext = yield* ComposioUserContext;
// Missing slug guard
if (Option.isNone(slug)) {
@@ -52,22 +58,56 @@ export const toolkitsCmd$Info = Command.make(
const slugValue = slug.value;
const repo = yield* ComposioToolkitsRepository;
+ const resolvedProjectContext = yield* projectContext.resolve;
+ const testUserId = Option.flatMap(resolvedProjectContext, keys => keys.testUserId);
+ const globalTestUserId = userContext.data.testUserId;
+ const resolvedUserId = Option.match(userId, {
+ onSome: value => Option.some(value),
+ onNone: () => Option.orElse(testUserId, () => globalTestUserId),
+ });
+
+ if (Option.isNone(userId) && Option.isSome(testUserId)) {
+ yield* ui.log.warn(`Using test user id "${testUserId.value}"`);
+ } else if (Option.isNone(userId) && Option.isSome(globalTestUserId)) {
+ yield* ui.log.warn(`Using global test user id "${globalTestUserId.value}"`);
+ } else if (Option.isNone(userId)) {
+ yield* ui.log.info(
+ 'No test user id found; showing toolkit details without connection status.'
+ );
+ }
const resultOpt = yield* ui
.withSpinner(
`Fetching toolkit "${slugValue}"...`,
Effect.gen(function* () {
- const [{ client, sessionId }, detailedToolkitOpt] = yield* Effect.all(
- [
- resolveToolRouterSession(userId),
- repo.getToolkitDetailed(slugValue).pipe(Effect.option),
- ],
- { concurrency: 'unbounded' }
- );
- const sessionToolkits = yield* Effect.tryPromise(() =>
- client.toolRouter.session.toolkits(sessionId, { toolkits: [slugValue] })
- );
- return { sessionToolkits, detailedToolkitOpt };
+ const detailedToolkitOpt = yield* repo
+ .getToolkitDetailed(slugValue)
+ .pipe(Effect.option);
+
+ if (Option.isSome(resolvedUserId)) {
+ const { client, sessionId } = yield* resolveToolRouterSession(resolvedUserId.value);
+ const sessionToolkits = yield* Effect.tryPromise(() =>
+ client.toolRouter.session.toolkits(sessionId, { toolkits: [slugValue] })
+ );
+ return { toolkit: sessionToolkits.items[0], detailedToolkitOpt };
+ }
+
+ const toolkit = Option.match(detailedToolkitOpt, {
+ onNone: () => undefined,
+ onSome: detailed => ({
+ slug: detailed.slug,
+ name: detailed.name,
+ meta: {
+ description: detailed.meta.description,
+ logo: '',
+ },
+ is_no_auth: detailed.no_auth,
+ enabled: true,
+ connected_account: null,
+ composio_managed_auth_schemes: [...detailed.composio_managed_auth_schemes],
+ }),
+ });
+ return { toolkit, detailedToolkitOpt };
})
)
.pipe(
@@ -88,7 +128,7 @@ export const toolkitsCmd$Info = Command.make(
}
const result = resultOpt.value;
- const toolkit = result.sessionToolkits.items[0];
+ const toolkit = result.toolkit;
const detailedToolkit = Option.getOrUndefined(result.detailedToolkitOpt);
if (!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
index 99742dd4e..af5a51b52 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
@@ -5,6 +5,7 @@ import { requireAuth } from 'src/effects/require-auth';
import { resolveToolRouterSession } from 'src/effects/create-tool-router-session';
import { ComposioToolkitsRepository } from 'src/services/composio-clients';
import { ProjectContext } from 'src/services/project-context';
+import { ComposioUserContext } from 'src/services/user-context';
import { clampLimit } from 'src/ui/clamp-limit';
import {
formatLegacyToolkitsJson,
@@ -30,7 +31,9 @@ const connected = Options.boolean('connected').pipe(
const userId = Options.text('user-id').pipe(
Options.optional,
- Options.withDescription('User ID for connection status (defaults to project test_user_id)')
+ Options.withDescription(
+ 'User ID for connection status (falls back to project/global test_user_id)'
+ )
);
/**
@@ -54,15 +57,25 @@ export const toolkitsCmd$List = Command.make(
const ui = yield* TerminalUI;
const repo = yield* ComposioToolkitsRepository;
const projectContext = yield* ProjectContext;
+ const userContext = yield* ComposioUserContext;
const clampedLimit = clampLimit(limit);
const resolvedProjectContext = yield* projectContext.resolve;
const testUserId = Option.flatMap(resolvedProjectContext, keys => keys.testUserId);
- const resolvedUserId = Option.orElse(userId, () => testUserId);
- const usingDefaultTestUserId = Option.isNone(userId) && Option.isSome(testUserId);
-
- if (usingDefaultTestUserId && Option.isSome(testUserId)) {
- yield* ui.log.info(`Showing connection status for user id "${testUserId.value}"`);
+ const globalTestUserId = userContext.data.testUserId;
+ const resolvedUserId = Option.match(userId, {
+ onSome: value => Option.some(value),
+ onNone: () => Option.orElse(testUserId, () => globalTestUserId),
+ });
+ const usingProjectTestUserId = Option.isNone(userId) && Option.isSome(testUserId);
+ const usingGlobalTestUserId =
+ Option.isNone(userId) && Option.isNone(testUserId) && Option.isSome(globalTestUserId);
+
+ if (usingProjectTestUserId && Option.isSome(testUserId)) {
+ yield* ui.log.warn(`Using test user id "${testUserId.value}"`);
+ yield* ui.log.message('To show status for a specific user, use `--user-id`.');
+ } else if (usingGlobalTestUserId && Option.isSome(globalTestUserId)) {
+ yield* ui.log.warn(`Using global test user id "${globalTestUserId.value}"`);
yield* ui.log.message('To show status for a specific user, use `--user-id`.');
}
diff --git a/ts/packages/cli/src/commands/toolkits/commands/toolkits.version.cmd.ts b/ts/packages/cli/src/commands/toolkits/commands/toolkits.version.cmd.ts
new file mode 100644
index 000000000..da371b8cd
--- /dev/null
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.version.cmd.ts
@@ -0,0 +1,84 @@
+import { Args, Command } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { requireAuth } from 'src/effects/require-auth';
+import { ComposioClientSingleton } from 'src/services/composio-clients';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { extractMessage } from 'src/utils/api-error-extraction';
+
+const slug = Args.text({ name: 'slug' }).pipe(Args.withDescription('Toolkit slug (e.g. "gmail")'));
+
+/**
+ * Show toolkit version information.
+ *
+ * Fetches toolkit data via `client.toolkits.retrieve(slug)` and prints:
+ * - latest available version
+ * - last 20 available versions
+ */
+export const toolkitsCmd$Version = Command.make('version', { slug }, ({ slug }) =>
+ Effect.gen(function* () {
+ if (!(yield* requireAuth)) return;
+
+ const ui = yield* TerminalUI;
+ const clientSingleton = yield* ComposioClientSingleton;
+ const client = yield* clientSingleton.get();
+
+ const toolkitOpt = yield* ui
+ .withSpinner(
+ `Fetching versions for toolkit "${slug}"...`,
+ Effect.tryPromise({
+ try: () => client.toolkits.retrieve(slug),
+ catch: error => (error instanceof Error ? error : new Error(String(error))),
+ })
+ )
+ .pipe(
+ Effect.asSome,
+ Effect.catchAll(error =>
+ Effect.gen(function* () {
+ const message =
+ extractMessage(error) ?? `Failed to fetch version info for toolkit "${slug}".`;
+ yield* ui.log.error(message);
+ yield* Effect.logDebug('Toolkit version error:', error);
+ yield* ui.log.step('Browse available toolkits:\n> composio toolkits list');
+ return Option.none();
+ })
+ )
+ );
+
+ if (Option.isNone(toolkitOpt)) return;
+
+ const toolkit = toolkitOpt.value as {
+ slug: string;
+ name: string;
+ meta?: { available_versions?: ReadonlyArray<string> };
+ };
+ const availableVersions = toolkit.meta?.available_versions ?? [];
+ const latestVersion = availableVersions.at(-1) ?? null;
+ const recentVersions = availableVersions.slice(-20);
+
+ const recentVersionLines =
+ recentVersions.length > 0
+ ? recentVersions.map(version => `- ${version}`).join('\n')
+ : '- none';
+
+ yield* ui.log.message(
+ [
+ `Toolkit: ${toolkit.name} (${toolkit.slug})`,
+ `Latest Version: ${latestVersion ?? 'none'}`,
+ `Last ${Math.min(20, recentVersions.length)} Available Versions:`,
+ recentVersionLines,
+ ].join('\n')
+ );
+
+ yield* ui.output(
+ JSON.stringify(
+ {
+ slug: toolkit.slug,
+ latest_version: latestVersion,
+ available_versions_last_20: recentVersions,
+ },
+ null,
+ 2
+ )
+ );
+ })
+).pipe(Command.withDescription('Show latest and recent versions for a toolkit.'));
diff --git a/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts b/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts
index de89ac625..a3a3ab02c 100644
--- a/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts
+++ b/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts
@@ -2,6 +2,7 @@ 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';
+import { toolkitsCmd$Version } from './commands/toolkits.version.cmd';
/**
* CLI entry point for toolkit discovery commands.
@@ -13,5 +14,10 @@ import { toolkitsCmd$Search } from './commands/toolkits.search.cmd';
*/
export const toolkitsCmd = Command.make('toolkits').pipe(
Command.withDescription('Discover and inspect Composio toolkits.'),
- Command.withSubcommands([toolkitsCmd$List, toolkitsCmd$Info, toolkitsCmd$Search])
+ Command.withSubcommands([
+ toolkitsCmd$List,
+ toolkitsCmd$Info,
+ toolkitsCmd$Search,
+ toolkitsCmd$Version,
+ ])
);
diff --git a/ts/packages/cli/test/__utils__/services/test-layer.ts b/ts/packages/cli/test/__utils__/services/test-layer.ts
index f178fc608..64720d00e 100644
--- a/ts/packages/cli/test/__utils__/services/test-layer.ts
+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts
@@ -866,6 +866,38 @@ export const TestLayer = (input?: TestLiveInput) =>
};
const mockComposioClient = {
+ toolkits: {
+ retrieve: async (slug: string) => {
+ const detailed = toolkitsData.detailedToolkits.find(
+ t => t.slug.toLowerCase() === slug.toLowerCase()
+ );
+ if (detailed) {
+ return {
+ name: detailed.name,
+ slug: detailed.slug,
+ is_local_toolkit: detailed.is_local_toolkit,
+ composio_managed_auth_schemes: [...detailed.composio_managed_auth_schemes],
+ no_auth: detailed.no_auth,
+ meta: detailed.meta,
+ };
+ }
+
+ const found = toolkitsData.toolkits.find(
+ t => t.slug.toLowerCase() === slug.toLowerCase()
+ );
+ if (!found) {
+ throw new Error(`Toolkit "${slug}" not found`);
+ }
+ return {
+ name: found.name,
+ slug: found.slug,
+ is_local_toolkit: found.is_local_toolkit,
+ composio_managed_auth_schemes: [...found.composio_managed_auth_schemes],
+ no_auth: found.no_auth,
+ meta: found.meta,
+ };
+ },
+ },
toolRouter: {
session: {
create:
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
index 72373e5a3..624853fe0 100644
--- 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
@@ -154,6 +154,28 @@ describe('CLI: composio toolkits info', () => {
}
);
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ toolkitsData,
+ fixture: 'global-test-user-id',
+ })
+ )(
+ '[Given] no --user-id and no project test_user_id [Then] falls back to global test_user_id',
+ it => {
+ it.scoped('uses global test user id for toolkit info', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'info', 'gmail']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Using global test user id "global-default"');
+ expect(output).toContain('Gmail');
+ })
+ );
+ }
+ );
+
layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
'[Given] toolkit with no_auth=true',
it => {
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
index b4e62eaec..a4953285a 100644
--- 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
@@ -90,6 +90,28 @@ describe('CLI: composio toolkits list', () => {
}
);
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ toolkitsData,
+ fixture: 'global-test-user-id',
+ })
+ )(
+ '[Given] no --user-id and no project test_user_id [Then] falls back to global test_user_id',
+ it => {
+ it.scoped('shows connected column with global test user id', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'list']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Connected');
+ expect(output).toContain('Using global test user id "global-default"');
+ })
+ );
+ }
+ );
+
layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
'[Given] explicit --user-id [Then] shows connected status column',
it => {
diff --git a/ts/packages/cli/test/src/commands/toolkits/toolkits.version.cmd.test.ts b/ts/packages/cli/test/src/commands/toolkits/toolkits.version.cmd.test.ts
new file mode 100644
index 000000000..af3b55454
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/toolkits/toolkits.version.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, ToolkitDetailed } from 'src/models/toolkits';
+
+const versionHistory = Array.from({ length: 25 }, (_, index) => {
+ const suffix = String(index + 1).padStart(2, '0');
+ return `20260101_${suffix}`;
+});
+
+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: versionHistory,
+ 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: versionHistory,
+ tools_count: 36,
+ triggers_count: 2,
+ },
+ auth_config_details: [],
+ },
+];
+
+const toolkitsData = {
+ toolkits: testToolkits,
+ detailedToolkits,
+} satisfies TestLiveInput['toolkitsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_USER_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+const parseLastJson = (lines: ReadonlyArray<string>) => {
+ for (let i = lines.length - 1; i >= 0; i -= 1) {
+ const line = lines[i];
+ if (!line) continue;
+ try {
+ return JSON.parse(line) as {
+ slug: string;
+ latest_version: string | null;
+ available_versions_last_20: string[];
+ };
+ } catch {
+ // keep searching for the last JSON line
+ }
+ }
+ throw new Error('Expected JSON output but none found');
+};
+
+describe('CLI: composio toolkits version', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] valid slug [Then] shows latest and last 20 versions',
+ it => {
+ it.scoped('prints latest version and truncates to last 20', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'version', 'gmail']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+ const json = parseLastJson(lines);
+
+ expect(output).toContain('Toolkit: Gmail (gmail)');
+ expect(output).toContain('Latest Version: 20260101_25');
+ expect(output).toContain('Last 20 Available Versions:');
+ expect(json.slug).toBe('gmail');
+ expect(json.latest_version).toBe('20260101_25');
+ expect(json.available_versions_last_20).toHaveLength(20);
+ expect(json.available_versions_last_20[0]).toBe('20260101_06');
+ expect(json.available_versions_last_20[19]).toBe('20260101_25');
+ })
+ );
+ }
+ );
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] invalid slug [Then] shows error and hint',
+ it => {
+ it.scoped('prints fetch failure and browse hint', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'version', 'unknown']).pipe(Effect.either);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Toolkit "unknown" not found');
+ expect(output).toContain('composio toolkits list');
+ })
+ );
+ }
+ );
+
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
+ it.scoped('warns user to login', () =>
+ Effect.gen(function* () {
+ yield* cli(['toolkits', 'version', 'gmail']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('not logged in');
+ })
+ );
+ });
+});