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 Ahamad committed
Feb 26, 2026 at 16:48 UTC
08057273374221d2d6621b7f3e9de685e7616e45
8 files changed
+370
-21
ts/packages/cli/src/commands/toolkits/commands/toolkits.info.cmd.ts
+54
-14
@@ -5,6 +5,8 @@ import { TerminalUI } from 'src/services/terminal-ui';
5
import { requireAuth } from 'src/effects/require-auth';
6
import { resolveToolRouterSession } from 'src/effects/create-tool-router-session';
7
import { extractMessage } from 'src/utils/api-error-extraction';
8
+import { ProjectContext } from 'src/services/project-context';
9
+import { ComposioUserContext } from 'src/services/user-context';
10
import { formatToolkitInfo, formatToolkitInfoJson } from '../format';
11
12
const slug = Args.text({ name: 'slug' }).pipe(
@@ -13,8 +15,10 @@ const slug = Args.text({ name: 'slug' }).pipe(
15
);
16
17
const userId = Options.text('user-id').pipe(
16
- Options.withDefault('default'),
17
- Options.withDescription('User ID for connection status (default: "default")')
18
+ Options.optional,
19
+ Options.withDescription(
20
+ 'User ID for connection status (falls back to project/global test_user_id, then "default")'
21
+ )
22
);
23
24
const allDetails = Options.boolean('all').pipe(
@@ -40,6 +44,8 @@ export const toolkitsCmd$Info = Command.make(
44
if (!(yield* requireAuth)) return;
45
46
const ui = yield* TerminalUI;
47
+ const projectContext = yield* ProjectContext;
48
+ const userContext = yield* ComposioUserContext;
49
50
// Missing slug guard
51
if (Option.isNone(slug)) {
@@ -52,22 +58,56 @@ export const toolkitsCmd$Info = Command.make(
58
59
const slugValue = slug.value;
60
const repo = yield* ComposioToolkitsRepository;
61
+ const resolvedProjectContext = yield* projectContext.resolve;
62
+ const testUserId = Option.flatMap(resolvedProjectContext, keys => keys.testUserId);
63
+ const globalTestUserId = userContext.data.testUserId;
64
+ const resolvedUserId = Option.match(userId, {
65
+ onSome: value => Option.some(value),
66
+ onNone: () => Option.orElse(testUserId, () => globalTestUserId),
67
+ });
68
+
69
+ if (Option.isNone(userId) && Option.isSome(testUserId)) {
70
+ yield* ui.log.warn(`Using test user id "${testUserId.value}"`);
71
+ } else if (Option.isNone(userId) && Option.isSome(globalTestUserId)) {
72
+ yield* ui.log.warn(`Using global test user id "${globalTestUserId.value}"`);
73
+ } else if (Option.isNone(userId)) {
74
+ yield* ui.log.info(
75
+ 'No test user id found; showing toolkit details without connection status.'
76
+ );
77
+ }
78
79
const resultOpt = yield* ui
80
.withSpinner(
81
`Fetching toolkit "${slugValue}"...`,
82
Effect.gen(function* () {
60
- const [{ client, sessionId }, detailedToolkitOpt] = yield* Effect.all(
61
- [
62
- resolveToolRouterSession(userId),
63
- repo.getToolkitDetailed(slugValue).pipe(Effect.option),
64
- ],
65
- { concurrency: 'unbounded' }
66
- );
67
- const sessionToolkits = yield* Effect.tryPromise(() =>
68
- client.toolRouter.session.toolkits(sessionId, { toolkits: [slugValue] })
69
- );
70
- return { sessionToolkits, detailedToolkitOpt };
83
+ const detailedToolkitOpt = yield* repo
84
+ .getToolkitDetailed(slugValue)
85
+ .pipe(Effect.option);
86
+
87
+ if (Option.isSome(resolvedUserId)) {
88
+ const { client, sessionId } = yield* resolveToolRouterSession(resolvedUserId.value);
89
+ const sessionToolkits = yield* Effect.tryPromise(() =>
90
+ client.toolRouter.session.toolkits(sessionId, { toolkits: [slugValue] })
91
+ );
92
+ return { toolkit: sessionToolkits.items[0], detailedToolkitOpt };
93
+ }
94
+
95
+ const toolkit = Option.match(detailedToolkitOpt, {
96
+ onNone: () => undefined,
97
+ onSome: detailed => ({
98
+ slug: detailed.slug,
99
+ name: detailed.name,
100
+ meta: {
101
+ description: detailed.meta.description,
102
+ logo: '',
103
+ },
104
+ is_no_auth: detailed.no_auth,
105
+ enabled: true,
106
+ connected_account: null,
107
+ composio_managed_auth_schemes: [...detailed.composio_managed_auth_schemes],
108
+ }),
109
+ });
110
+ return { toolkit, detailedToolkitOpt };
111
})
112
)
113
.pipe(
@@ -88,7 +128,7 @@ export const toolkitsCmd$Info = Command.make(
128
}
129
130
const result = resultOpt.value;
91
- const toolkit = result.sessionToolkits.items[0];
131
+ const toolkit = result.toolkit;
132
const detailedToolkit = Option.getOrUndefined(result.detailedToolkitOpt);
133
134
if (!toolkit) {
ts/packages/cli/src/commands/toolkits/commands/toolkits.list.cmd.ts
+19
-6
@@ -5,6 +5,7 @@ import { requireAuth } from 'src/effects/require-auth';
5
import { resolveToolRouterSession } from 'src/effects/create-tool-router-session';
6
import { ComposioToolkitsRepository } from 'src/services/composio-clients';
7
import { ProjectContext } from 'src/services/project-context';
8
+import { ComposioUserContext } from 'src/services/user-context';
9
import { clampLimit } from 'src/ui/clamp-limit';
10
import {
11
formatLegacyToolkitsJson,
@@ -30,7 +31,9 @@ const connected = Options.boolean('connected').pipe(
31
32
const userId = Options.text('user-id').pipe(
33
Options.optional,
33
- Options.withDescription('User ID for connection status (defaults to project test_user_id)')
34
+ Options.withDescription(
35
+ 'User ID for connection status (falls back to project/global test_user_id)'
36
+ )
37
);
38
39
/**
@@ -54,15 +57,25 @@ export const toolkitsCmd$List = Command.make(
57
const ui = yield* TerminalUI;
58
const repo = yield* ComposioToolkitsRepository;
59
const projectContext = yield* ProjectContext;
60
+ const userContext = yield* ComposioUserContext;
61
62
const clampedLimit = clampLimit(limit);
63
const resolvedProjectContext = yield* projectContext.resolve;
64
const testUserId = Option.flatMap(resolvedProjectContext, keys => keys.testUserId);
61
- const resolvedUserId = Option.orElse(userId, () => testUserId);
62
- const usingDefaultTestUserId = Option.isNone(userId) && Option.isSome(testUserId);
63
-
64
- if (usingDefaultTestUserId && Option.isSome(testUserId)) {
65
- yield* ui.log.info(`Showing connection status for user id "${testUserId.value}"`);
65
+ const globalTestUserId = userContext.data.testUserId;
66
+ const resolvedUserId = Option.match(userId, {
67
+ onSome: value => Option.some(value),
68
+ onNone: () => Option.orElse(testUserId, () => globalTestUserId),
69
+ });
70
+ const usingProjectTestUserId = Option.isNone(userId) && Option.isSome(testUserId);
71
+ const usingGlobalTestUserId =
72
+ Option.isNone(userId) && Option.isNone(testUserId) && Option.isSome(globalTestUserId);
73
+
74
+ if (usingProjectTestUserId && Option.isSome(testUserId)) {
75
+ yield* ui.log.warn(`Using test user id "${testUserId.value}"`);
76
+ yield* ui.log.message('To show status for a specific user, use `--user-id`.');
77
+ } else if (usingGlobalTestUserId && Option.isSome(globalTestUserId)) {
78
+ yield* ui.log.warn(`Using global test user id "${globalTestUserId.value}"`);
79
yield* ui.log.message('To show status for a specific user, use `--user-id`.');
80
}
81
ts/packages/cli/src/commands/toolkits/commands/toolkits.version.cmd.ts
new
+84
@@ -0,0 +1,84 @@
1
+import { Args, Command } from '@effect/cli';
2
+import { Effect, Option } from 'effect';
3
+import { requireAuth } from 'src/effects/require-auth';
4
+import { ComposioClientSingleton } from 'src/services/composio-clients';
5
+import { TerminalUI } from 'src/services/terminal-ui';
6
+import { extractMessage } from 'src/utils/api-error-extraction';
7
+
8
+const slug = Args.text({ name: 'slug' }).pipe(Args.withDescription('Toolkit slug (e.g. "gmail")'));
9
+
10
+/**
11
+ * Show toolkit version information.
12
+ *
13
+ * Fetches toolkit data via `client.toolkits.retrieve(slug)` and prints:
14
+ * - latest available version
15
+ * - last 20 available versions
16
+ */
17
+export const toolkitsCmd$Version = Command.make('version', { slug }, ({ slug }) =>
18
+ Effect.gen(function* () {
19
+ if (!(yield* requireAuth)) return;
20
+
21
+ const ui = yield* TerminalUI;
22
+ const clientSingleton = yield* ComposioClientSingleton;
23
+ const client = yield* clientSingleton.get();
24
+
25
+ const toolkitOpt = yield* ui
26
+ .withSpinner(
27
+ `Fetching versions for toolkit "${slug}"...`,
28
+ Effect.tryPromise({
29
+ try: () => client.toolkits.retrieve(slug),
30
+ catch: error => (error instanceof Error ? error : new Error(String(error))),
31
+ })
32
+ )
33
+ .pipe(
34
+ Effect.asSome,
35
+ Effect.catchAll(error =>
36
+ Effect.gen(function* () {
37
+ const message =
38
+ extractMessage(error) ?? `Failed to fetch version info for toolkit "${slug}".`;
39
+ yield* ui.log.error(message);
40
+ yield* Effect.logDebug('Toolkit version error:', error);
41
+ yield* ui.log.step('Browse available toolkits:\n> composio toolkits list');
42
+ return Option.none();
43
+ })
44
+ )
45
+ );
46
+
47
+ if (Option.isNone(toolkitOpt)) return;
48
+
49
+ const toolkit = toolkitOpt.value as {
50
+ slug: string;
51
+ name: string;
52
+ meta?: { available_versions?: ReadonlyArray<string> };
53
+ };
54
+ const availableVersions = toolkit.meta?.available_versions ?? [];
55
+ const latestVersion = availableVersions.at(-1) ?? null;
56
+ const recentVersions = availableVersions.slice(-20);
57
+
58
+ const recentVersionLines =
59
+ recentVersions.length > 0
60
+ ? recentVersions.map(version => `- ${version}`).join('\n')
61
+ : '- none';
62
+
63
+ yield* ui.log.message(
64
+ [
65
+ `Toolkit: ${toolkit.name} (${toolkit.slug})`,
66
+ `Latest Version: ${latestVersion ?? 'none'}`,
67
+ `Last ${Math.min(20, recentVersions.length)} Available Versions:`,
68
+ recentVersionLines,
69
+ ].join('\n')
70
+ );
71
+
72
+ yield* ui.output(
73
+ JSON.stringify(
74
+ {
75
+ slug: toolkit.slug,
76
+ latest_version: latestVersion,
77
+ available_versions_last_20: recentVersions,
78
+ },
79
+ null,
80
+ 2
81
+ )
82
+ );
83
+ })
84
+).pipe(Command.withDescription('Show latest and recent versions for a toolkit.'));
ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts
+7
-1
@@ -2,6 +2,7 @@ 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
+import { toolkitsCmd$Version } from './commands/toolkits.version.cmd';
6
7
/**
8
* CLI entry point for toolkit discovery commands.
@@ -13,5 +14,10 @@ import { toolkitsCmd$Search } from './commands/toolkits.search.cmd';
14
*/
15
export const toolkitsCmd = Command.make('toolkits').pipe(
16
Command.withDescription('Discover and inspect Composio toolkits.'),
16
- Command.withSubcommands([toolkitsCmd$List, toolkitsCmd$Info, toolkitsCmd$Search])
17
+ Command.withSubcommands([
18
+ toolkitsCmd$List,
19
+ toolkitsCmd$Info,
20
+ toolkitsCmd$Search,
21
+ toolkitsCmd$Version,
22
+ ])
23
);
ts/packages/cli/test/__utils__/services/test-layer.ts
+32
@@ -866,6 +866,38 @@ export const TestLayer = (input?: TestLiveInput) =>
866
};
867
868
const mockComposioClient = {
869
+ toolkits: {
870
+ retrieve: async (slug: string) => {
871
+ const detailed = toolkitsData.detailedToolkits.find(
872
+ t => t.slug.toLowerCase() === slug.toLowerCase()
873
+ );
874
+ if (detailed) {
875
+ return {
876
+ name: detailed.name,
877
+ slug: detailed.slug,
878
+ is_local_toolkit: detailed.is_local_toolkit,
879
+ composio_managed_auth_schemes: [...detailed.composio_managed_auth_schemes],
880
+ no_auth: detailed.no_auth,
881
+ meta: detailed.meta,
882
+ };
883
+ }
884
+
885
+ const found = toolkitsData.toolkits.find(
886
+ t => t.slug.toLowerCase() === slug.toLowerCase()
887
+ );
888
+ if (!found) {
889
+ throw new Error(`Toolkit "${slug}" not found`);
890
+ }
891
+ return {
892
+ name: found.name,
893
+ slug: found.slug,
894
+ is_local_toolkit: found.is_local_toolkit,
895
+ composio_managed_auth_schemes: [...found.composio_managed_auth_schemes],
896
+ no_auth: found.no_auth,
897
+ meta: found.meta,
898
+ };
899
+ },
900
+ },
901
toolRouter: {
902
session: {
903
create:
ts/packages/cli/test/src/commands/toolkits/toolkits.info.cmd.test.ts
+22
@@ -154,6 +154,28 @@ describe('CLI: composio toolkits info', () => {
154
}
155
);
156
157
+ layer(
158
+ TestLive({
159
+ baseConfigProvider: testConfigProvider,
160
+ toolkitsData,
161
+ fixture: 'global-test-user-id',
162
+ })
163
+ )(
164
+ '[Given] no --user-id and no project test_user_id [Then] falls back to global test_user_id',
165
+ it => {
166
+ it.scoped('uses global test user id for toolkit info', () =>
167
+ Effect.gen(function* () {
168
+ yield* cli(['toolkits', 'info', 'gmail']);
169
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
170
+ const output = lines.join('\n');
171
+
172
+ expect(output).toContain('Using global test user id "global-default"');
173
+ expect(output).toContain('Gmail');
174
+ })
175
+ );
176
+ }
177
+ );
178
+
179
layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
180
'[Given] toolkit with no_auth=true',
181
it => {
ts/packages/cli/test/src/commands/toolkits/toolkits.list.cmd.test.ts
+22
@@ -90,6 +90,28 @@ describe('CLI: composio toolkits list', () => {
90
}
91
);
92
93
+ layer(
94
+ TestLive({
95
+ baseConfigProvider: testConfigProvider,
96
+ toolkitsData,
97
+ fixture: 'global-test-user-id',
98
+ })
99
+ )(
100
+ '[Given] no --user-id and no project test_user_id [Then] falls back to global test_user_id',
101
+ it => {
102
+ it.scoped('shows connected column with global test user id', () =>
103
+ Effect.gen(function* () {
104
+ yield* cli(['toolkits', 'list']);
105
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
106
+ const output = lines.join('\n');
107
+
108
+ expect(output).toContain('Connected');
109
+ expect(output).toContain('Using global test user id "global-default"');
110
+ })
111
+ );
112
+ }
113
+ );
114
+
115
layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
116
'[Given] explicit --user-id [Then] shows connected status column',
117
it => {
ts/packages/cli/test/src/commands/toolkits/toolkits.version.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, ToolkitDetailed } from 'src/models/toolkits';
7
+
8
+const versionHistory = Array.from({ length: 25 }, (_, index) => {
9
+ const suffix = String(index + 1).padStart(2, '0');
10
+ return `20260101_${suffix}`;
11
+});
12
+
13
+const testToolkits: Toolkits = [
14
+ {
15
+ name: 'Gmail',
16
+ slug: 'gmail',
17
+ auth_schemes: ['OAUTH2'],
18
+ composio_managed_auth_schemes: ['OAUTH2'],
19
+ is_local_toolkit: false,
20
+ no_auth: false,
21
+ meta: {
22
+ description: 'Email service to send and receive emails',
23
+ categories: [],
24
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
25
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
26
+ available_versions: versionHistory,
27
+ tools_count: 36,
28
+ triggers_count: 2,
29
+ },
30
+ },
31
+];
32
+
33
+const detailedToolkits: ToolkitDetailed[] = [
34
+ {
35
+ name: 'Gmail',
36
+ slug: 'gmail',
37
+ is_local_toolkit: false,
38
+ composio_managed_auth_schemes: ['OAUTH2'],
39
+ no_auth: false,
40
+ meta: {
41
+ description: 'Email service to send and receive emails',
42
+ categories: [],
43
+ created_at: new Date('2024-05-03T11:44:32.061Z') as any,
44
+ updated_at: new Date('2024-05-03T11:44:32.061Z') as any,
45
+ available_versions: versionHistory,
46
+ tools_count: 36,
47
+ triggers_count: 2,
48
+ },
49
+ auth_config_details: [],
50
+ },
51
+];
52
+
53
+const toolkitsData = {
54
+ toolkits: testToolkits,
55
+ detailedToolkits,
56
+} satisfies TestLiveInput['toolkitsData'];
57
+
58
+const testConfigProvider = ConfigProvider.fromMap(
59
+ new Map([['COMPOSIO_USER_API_KEY', 'test_api_key']])
60
+).pipe(extendConfigProvider);
61
+
62
+const parseLastJson = (lines: ReadonlyArray<string>) => {
63
+ for (let i = lines.length - 1; i >= 0; i -= 1) {
64
+ const line = lines[i];
65
+ if (!line) continue;
66
+ try {
67
+ return JSON.parse(line) as {
68
+ slug: string;
69
+ latest_version: string | null;
70
+ available_versions_last_20: string[];
71
+ };
72
+ } catch {
73
+ // keep searching for the last JSON line
74
+ }
75
+ }
76
+ throw new Error('Expected JSON output but none found');
77
+};
78
+
79
+describe('CLI: composio toolkits version', () => {
80
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
81
+ '[Given] valid slug [Then] shows latest and last 20 versions',
82
+ it => {
83
+ it.scoped('prints latest version and truncates to last 20', () =>
84
+ Effect.gen(function* () {
85
+ yield* cli(['toolkits', 'version', 'gmail']);
86
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
87
+ const output = lines.join('\n');
88
+ const json = parseLastJson(lines);
89
+
90
+ expect(output).toContain('Toolkit: Gmail (gmail)');
91
+ expect(output).toContain('Latest Version: 20260101_25');
92
+ expect(output).toContain('Last 20 Available Versions:');
93
+ expect(json.slug).toBe('gmail');
94
+ expect(json.latest_version).toBe('20260101_25');
95
+ expect(json.available_versions_last_20).toHaveLength(20);
96
+ expect(json.available_versions_last_20[0]).toBe('20260101_06');
97
+ expect(json.available_versions_last_20[19]).toBe('20260101_25');
98
+ })
99
+ );
100
+ }
101
+ );
102
+
103
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
104
+ '[Given] invalid slug [Then] shows error and hint',
105
+ it => {
106
+ it.scoped('prints fetch failure and browse hint', () =>
107
+ Effect.gen(function* () {
108
+ yield* cli(['toolkits', 'version', 'unknown']).pipe(Effect.either);
109
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
110
+ const output = lines.join('\n');
111
+
112
+ expect(output).toContain('Toolkit "unknown" not found');
113
+ expect(output).toContain('composio toolkits list');
114
+ })
115
+ );
116
+ }
117
+ );
118
+
119
+ layer(TestLive())('[Given] no API key [Then] warns user to login', it => {
120
+ it.scoped('warns user to login', () =>
121
+ Effect.gen(function* () {
122
+ yield* cli(['toolkits', 'version', 'gmail']);
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
+});