@devries-cameron20 / composio-1 / commits / a987c0da1
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.

fix(cli): stabilize multi-account selection (#3897)

## Summary - promote CLI multi-account selection out of the experimental feature system so stale `multi_account: false` config can no longer disable `execute --account`, `listen --account`, or `link --alias` - add `proxy --account <alias|word_id|connected-account-id>` and pin the resolved connected account into the Tool Router session - expose account selection consistently in command help and the generated `composio-cli` skill - make duplicate-alias link errors explain how to select and inspect the existing account ## Root cause Multi-account selection was introduced behind `multi_account` in #3129. #3163 enabled it by default for stable builds, but the command implementations still consulted the experimental setting and the custom help surface still omitted the selector. That left stale or explicit `multi_account: false` config able to disable selection even though the feature was intended to be stable. `proxy` never received equivalent account-selection wiring. This is an incomplete graduation of the feature rather than a recent code regression. Existing implicit/default account selection behavior remains unchanged; this PR does **not** require explicit selection. Closes #3894. ## Tests - `vitest run` in `ts/packages/cli`: **84 files passed, 785 tests passed, 1 skipped** - focused proxy/link/help regression suite: **26 tests passed** - CLI source and test typechecks via `tsgo --noEmit`: passed - `tsx ./scripts/validate-skills.ts`: passed for stable and beta builds - Prettier and `git diff --check`: passed ## Notes - No changeset: `@composio/cli` is excluded from Changesets; the CLI changelog is updated directly. - No VHS recording: this is a narrow selector-wiring/help regression covered by command-level tests and requires a real multi-account fixture to demo safely. - The root Turbo typecheck entrypoint could not run in this worktree because the local environment does not have `mise` on `PATH`; the directly equivalent CLI source/test `tsgo` checks passed. - GitHub CI: queued/pending at PR creation; no background CI watch started per workspace policy.

Rahul Tarak committed Jul 21, 2026 at 01:34 UTC a987c0da1b871b7ae93d83f211bcf99f76bb84dd
16 files changed +297 -133
ts/packages/cli/CHANGELOG.md
+1
@@ -15,6 +15,7 @@
15
16 ### Patch Changes
17
18 +- Make multi-account selection a stable CLI feature: `execute`, `listen`, and `link --alias` no longer honor the old experimental toggle; `proxy` now accepts `--account <alias|word_id|connected-account-id>`; and duplicate-alias link errors explain how to select the existing account.
19 - 8467efd: Fix `composio whoami` reporting the API key's home organization after `composio orgs switch`. Session info requests now forward the selected global organization.
20 - 5f004ff: Drop `COMPOSIO_UPSERT_RECIPE` and `COMPOSIO_GET_RECIPE` from the CLI meta-tool list. These slugs were removed from `@composio/client` (alpha.74), so listing them broke the type-checked CLI build.
21 - 23f9053: Remove the unused `ansis` dependency from the CLI. Colored output is already handled by `picocolors`, so `ansis` was a dead production dependency that shipped with the package.
ts/packages/cli/skills-src/composio-cli/index.ts
+7 -4
@@ -76,7 +76,6 @@ const commands: SkillCommand[] = [
76 name: '`--account`',
77 description:
78 'Select which connected account to use by alias, word_id, or account id when multiple accounts exist for the same toolkit.',
79 - features: [CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT],
79 },
80 ],
81 examples: [
@@ -136,7 +135,6 @@ const commands: SkillCommand[] = [
135 name: '`--alias`',
136 description:
137 'Assign an alias to the connected account. Required when creating an additional account for the same toolkit.',
139 - features: [CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT],
138 },
139 ],
140 notes: ['Retry the original `execute` command after linking succeeds.'],
@@ -169,7 +167,6 @@ const commands: SkillCommand[] = [
167 {
168 name: '`--account`',
169 description: 'Select which connected account to use by alias, word_id, or account id.',
172 - features: [CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT],
170 },
171 ],
172 notes: [
@@ -183,7 +180,13 @@ const commands: SkillCommand[] = [
180 'Use `proxy` when a toolkit supports a raw API operation that is easier than finding a dedicated tool slug.',
181 examples: [
182 {
186 - code: 'composio proxy https://api.github.com/user --toolkit github --method GET </dev/null',
183 + code: 'composio proxy https://api.github.com/user --toolkit github --account work --method GET </dev/null',
184 + },
185 + ],
186 + flags: [
187 + {
188 + name: '`--account`',
189 + description: 'Select which connected account to use by alias, word_id, or account id.',
190 },
191 ],
192 },
ts/packages/cli/skills-src/composio-cli/reference-schema.ts
-4
@@ -67,10 +67,6 @@ export const resolveSkillBuildContext = (
67 CLI_EXPERIMENTAL_FEATURES.LOCAL_TOOLS,
68 channel
69 ),
70 - [CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT]: isExperimentalFeatureEnabledByDefault(
71 - CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT,
72 - channel
73 - ),
70 ...overrides,
71 },
72 });
ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.link.cmd.ts
+64 -10
@@ -23,8 +23,6 @@ import {
23 groupCachedConnectedAccountsByToolkit,
24 resolveDefaultConnectedAccountsByToolkit,
25 } from 'src/services/connected-account-selection';
26 -import { ComposioCliUserConfig } from 'src/services/cli-user-config';
27 -import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
26 import { decodeConnectedAccountItemsWithFallback } from 'src/effects/decode-connected-account-list';
27
28 class ConnectionPollingError extends Data.TaggedError('commands/ConnectionPollingError')<{
@@ -339,6 +337,51 @@ const formatExistingAccountLabels = (
337 })
338 .join(', ');
339
340 +const showAliasConflictGuidance = (params: {
341 + readonly ui: TerminalUI;
342 + readonly alias: string;
343 + readonly executeCommand: string;
344 + readonly listCommand: string;
345 +}) =>
346 + params.ui.note(
347 + [
348 + `Use the existing alias: ${params.executeCommand} <TOOL_SLUG> --account ${params.alias} -d '{ ... }'`,
349 + `List connected accounts: ${params.listCommand}`,
350 + ].join('\n'),
351 + 'Tips'
352 + );
353 +
354 +const ensureAliasIsAvailable = (params: {
355 + readonly ui: TerminalUI;
356 + readonly alias: Option.Option<string>;
357 + readonly existingAccounts: ReadonlyArray<{
358 + readonly id: string;
359 + readonly alias?: string | null;
360 + }>;
361 + readonly executeCommand: string;
362 + readonly listCommand: string;
363 +}) =>
364 + Effect.gen(function* () {
365 + if (Option.isNone(params.alias)) return true as const;
366 +
367 + const normalizedAlias = params.alias.value.toLowerCase();
368 + const existing = params.existingAccounts.find(
369 + item => item.alias?.trim().toLowerCase() === normalizedAlias
370 + );
371 + if (!existing) return true as const;
372 +
373 + yield* params.ui.log.error(
374 + `Alias "${params.alias.value}" is already in use by connected account "${existing.id}".`
375 + );
376 + yield* showAliasConflictGuidance({
377 + ui: params.ui,
378 + alias: params.alias.value,
379 + executeCommand: params.executeCommand,
380 + listCommand: params.listCommand,
381 + });
382 + return false as const;
383 + });
384 +
385 const ensureAliasForAdditionalAccount = (params: {
386 readonly ui: TerminalUI;
387 readonly alias: Option.Option<string>;
@@ -612,6 +655,15 @@ const handleLegacyAuthConfigLink = (params: {
655 // failure must not abort the link flow.
656 Effect.catchAll(() => Effect.succeed({ items: [] }))
657 );
658 + const aliasAvailable = yield* ensureAliasIsAvailable({
659 + ui: params.ui,
660 + alias: normalizedAlias,
661 + existingAccounts: existingAccounts.items,
662 + executeCommand: 'composio dev playground-execute',
663 + listCommand: 'composio dev connected-accounts list',
664 + });
665 + if (!aliasAvailable) return;
666 +
667 const linkOpt = yield* params.ui
668 .withSpinner(
669 'Creating link session...',
@@ -702,13 +754,7 @@ const runConnectedAccountsLink = (params: {
754 Effect.gen(function* () {
755 if (!(yield* requireAuth)) return;
756
705 - const cliConfig = yield* ComposioCliUserConfig;
706 - const aliasOption = cliConfig.isExperimentalFeatureEnabled(
707 - CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT
708 - )
709 - ? params.alias
710 - : Option.none<string>();
711 - const normalizedAliasOption = yield* resolveNormalizedAliasOption(aliasOption);
757 + const normalizedAliasOption = yield* resolveNormalizedAliasOption(params.alias);
758
759 const ui = yield* TerminalUI;
760 const clientSingleton = yield* ComposioClientSingleton;
@@ -767,7 +813,7 @@ const runConnectedAccountsLink = (params: {
813 projectName: params.projectName,
814 noWait: params.noWait,
815 noBrowser: params.noBrowser,
770 - alias: aliasOption,
816 + alias: params.alias,
817 ui,
818 clientSingleton,
819 projectContext,
@@ -809,6 +855,14 @@ const runConnectedAccountsLink = (params: {
855 // failure must not abort the link flow.
856 Effect.catchAll(() => Effect.succeed({ items: [] }))
857 );
858 + const aliasAvailable = yield* ensureAliasIsAvailable({
859 + ui,
860 + alias: normalizedAliasOption,
861 + existingAccounts: existingAccounts.items,
862 + executeCommand: 'composio execute',
863 + listCommand: `composio connections list --toolkit ${toolkitSlug}`,
864 + });
865 + if (!aliasAvailable) return;
866
867 const linkOpt = yield* ui
868 .withSpinner(
ts/packages/cli/src/commands/listen.cmd.ts
+1 -9
@@ -21,8 +21,6 @@ import {
21 } from 'src/services/connected-account-selection';
22 import { parseJsonRecord } from 'src/utils/parse-json';
23 import { toolkitFromToolSlug } from 'src/utils/toolkit-from-tool-slug';
24 -import { ComposioCliUserConfig } from 'src/services/cli-user-config';
25 -import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
24 import { matchesTriggerListenFilters } from './triggers/filter';
25 import { parseTriggerListenEvent } from './triggers/parse';
26 import { decodeConnectedAccountItemsWithFallback } from 'src/effects/decode-connected-account-list';
@@ -462,12 +460,6 @@ export const listenCmd = Command.make(
460 orgId: resolvedProject.orgId,
461 projectId: resolvedProject.projectId,
462 });
465 - const cliConfig = yield* ComposioCliUserConfig;
466 - const accountSelector = cliConfig.isExperimentalFeatureEnabled(
467 - CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT
468 - )
469 - ? account
470 - : Option.none<string>();
463 const {
464 listeningToProjectEvent,
465 createParams,
@@ -482,7 +474,7 @@ export const listenCmd = Command.make(
474 timeout,
475 stream,
476 maxEvents,
485 - account: accountSelector,
477 + account,
478 client,
479 resolvedProject,
480 });
ts/packages/cli/src/commands/proxy.cmd.ts
+23 -1
@@ -22,6 +22,7 @@ import {
22 mapComposioError,
23 } from 'src/services/composio-error-overrides';
24 import { parseJsonRecord } from 'src/utils/parse-json';
25 +import { resolveConnectedAccountForToolkit } from 'src/services/connected-account-selection';
26
27 const endpoint = Args.text({ name: 'url' }).pipe(
28 Args.withDescription('Absolute or relative API endpoint to call through proxy execute.')
@@ -32,6 +33,13 @@ const toolkit = Options.text('toolkit').pipe(
33 Options.withDescription('Toolkit slug whose connected account should be used')
34 );
35
36 +const account = Options.text('account').pipe(
37 + Options.withDescription(
38 + 'Connected account selector. Matches alias, word_id, or connected account id for the toolkit.'
39 + ),
40 + Options.optional
41 +);
42 +
43 const method = Options.text('method').pipe(
44 Options.withAlias('X'),
45 Options.withDefault('GET'),
@@ -251,6 +259,7 @@ const runProxyConnectedToolkitFailFast = (params: {
259 export const proxyCmd = Command.make('proxy', {
260 endpoint,
261 toolkit,
262 + account,
263 method,
264 headers,
265 data,
@@ -263,6 +272,7 @@ export const proxyCmd = Command.make('proxy', {
272 '',
273 'Examples:',
274 ' composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail',
275 + ' composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail --account work',
276 ` composio proxy https://gmail.googleapis.com/gmail/v1/users/me/drafts --toolkit gmail \\`,
277 ` -X POST -H 'content-type: application/json' -d '{"message":{"raw":"..."}}'`,
278 '',
@@ -271,8 +281,9 @@ export const proxyCmd = Command.make('proxy', {
281 ' composio run \'const f = await proxy("gmail"); ...\' Use proxy in a script',
282 ].join('\n')
283 ),
274 - Command.withHandler(({ endpoint, toolkit, method, headers, data, skipConnectionCheck }) =>
284 + Command.withHandler(options =>
285 Effect.gen(function* () {
286 + const { endpoint, toolkit, account, method, headers, data, skipConnectionCheck } = options;
287 if (!(yield* requireAuth)) return;
288
289 const ui = yield* TerminalUI;
@@ -320,8 +331,19 @@ export const proxyCmd = Command.make('proxy', {
331 orgId: resolvedProject.orgId,
332 projectId: resolvedProject.projectId,
333 });
334 + const selectedConnectedAccountId = Option.isSome(account)
335 + ? yield* resolveConnectedAccountForToolkit({
336 + client,
337 + toolkitSlug: normalizedToolkit,
338 + userId: consumerUserId,
339 + selector: account,
340 + })
341 + : undefined;
342 const { sessionId } = yield* resolveToolRouterSession(client, consumerUserId, {
343 toolkits: [normalizedToolkit],
344 + connectedAccounts: selectedConnectedAccountId
345 + ? { [normalizedToolkit]: selectedConnectedAccountId }
346 + : undefined,
347 cacheScope: {
348 orgId: resolvedProject.orgId,
349 projectId: resolvedProject.projectId,
ts/packages/cli/src/commands/root-help.ts
+41 -17
@@ -49,7 +49,7 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
49 description:
50 'Execute a tool. Validates inputs and connections automatically; use it aggressively.',
51 usage:
52 - 'execute <slug> [-d, --data text] [--file path] [--dry-run] [--get-schema] | execute -p <slug> -d <text> <slug> -d <text> ...',
52 + 'execute <slug> [-d, --data text] [--account selector] [--file path] [--dry-run] [--get-schema] | execute -p <slug> -d <text> <slug> -d <text> ...',
53 options: [
54 { name: '<slug>', description: 'Tool slug (e.g. "GITHUB_CREATE_ISSUE")' },
55 {
@@ -61,6 +61,10 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
61 name: '-p, --parallel',
62 description: 'Execute repeated <slug> -d <text> pairs concurrently',
63 },
64 + {
65 + name: '--account',
66 + description: 'Select a connected account by alias, word_id, or account ID',
67 + },
68 {
69 name: '--file',
70 description: 'Inject a local file path into the single file_uploadable input',
@@ -72,8 +76,11 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
76 simple({
77 name: 'link',
78 description: 'Connect your account for a toolkit/app.',
75 - usage: 'link [<toolkit>]',
76 - options: [{ name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' }],
79 + usage: 'link [<toolkit>] [--alias text]',
80 + options: [
81 + { name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' },
82 + { name: '--alias', description: 'Alias for this connected account' },
83 + ],
84 }),
85 tagged({
86 name: 'run',
@@ -91,7 +98,7 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
98 description:
99 'Create a temporary subscription for consumer-project events and persist each payload into the session artifact folder.',
100 usage:
94 - 'listen <slug> [-p, --params text] [--max-events integer] [--timeout text] [--stream [text]]',
101 + 'listen <slug> [-p, --params text] [--account selector] [--max-events integer] [--timeout text] [--stream [text]]',
102 options: [
103 { name: '<slug>', description: 'Trigger slug (e.g. "GMAIL_NEW_GMAIL_MESSAGE")' },
104 {
@@ -99,6 +106,10 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
106 description:
107 "Trigger create params as JSON or JS-style object, e.g. -p '{ trigger_config: { ... } }'.",
108 },
109 + {
110 + name: '--account',
111 + description: 'Select a connected account by alias, word_id, or account ID',
112 + },
113 {
114 name: '--max-events',
115 description: 'Stop after receiving N events, then disable the temporary trigger',
@@ -119,10 +130,11 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
130 name: 'proxy',
131 description:
132 'curl-like access to any toolkit API through Composio using your connected account.',
122 - usage: 'proxy <url> --toolkit text [-X method] [-H header]... [-d data]',
133 + usage: 'proxy <url> --toolkit text [--account selector] [-X method] [-H header]... [-d data]',
134 options: [
135 { name: '<url>', description: 'Full API endpoint URL' },
136 { name: '--toolkit', description: 'Toolkit slug whose connected account should be used' },
137 + { name: '--account', description: 'Connected account alias, word_id, or account ID' },
138 { name: '-X, --method', description: 'HTTP method (GET, POST, PUT, DELETE, PATCH)' },
139 { name: '-H, --header', description: 'Header in "Name: value" format. Repeat for multiple.' },
140 { name: '-d, --data', description: 'Request body as raw text, JSON, @file, or - for stdin' },
@@ -421,7 +433,7 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
433 },
434 execute: {
435 usage:
424 - 'composio execute <slug> [-d, --data text] [--file path] [--dry-run] [--get-schema] [--parallel]',
436 + 'composio execute <slug> [-d, --data text] [--account selector] [--file path] [--dry-run] [--get-schema] [--parallel]',
437 description:
438 'Execute a tool by slug. Validates inputs against cached schemas and checks connections automatically — just try it and it will tell you what to fix.',
439 args: [
@@ -441,6 +453,10 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
453 name: '-p, --parallel',
454 description: 'Execute repeated TOOL_SLUG -d <text> groups concurrently',
455 },
456 + {
457 + name: '--account <selector>',
458 + description: 'Select a connected account by alias, word_id, or connected account ID',
459 + },
460 {
461 name: '--file <path>',
462 description: 'Inject a local file path into the single file_uploadable input',
@@ -466,8 +482,8 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
482 '# Send an email',
483 `composio execute GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hello", body: "World" }'`,
484 '',
469 - '# Create a GitHub issue',
470 - `composio execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'`,
485 + '# Create a GitHub issue with a named account',
486 + `composio execute GITHUB_CREATE_ISSUE --account work -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'`,
487 '',
488 '# Preview what a tool call would send without executing',
489 `composio execute SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL --dry-run -d '{ channel: "general", text: "Hello team" }'`,
@@ -490,7 +506,7 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
506 },
507 listen: experimental(CLI_EXPERIMENTAL_FEATURES.LISTEN, {
508 usage:
493 - 'composio listen <slug> [-p, --params text] [--max-events integer] [--timeout text] [--stream [text]]',
509 + 'composio listen <slug> [-p, --params text] [--account selector] [--max-events integer] [--timeout text] [--stream [text]]',
510 description:
511 'Create a temporary subscription for consumer-project events so background agents can easily consume new emails, Slack messages, and other trigger payloads from artifacts.',
512 args: [{ name: '<slug>', description: 'Trigger slug to create and listen to' }],
@@ -500,6 +516,10 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
516 description:
517 'Trigger create params as JSON/JS object, @file, or - for stdin. Pass optional trigger config fields only.',
518 },
519 + {
520 + name: '--account <selector>',
521 + description: 'Select a connected account by alias, word_id, or connected account ID',
522 + },
523 {
524 name: '--max-events <integer>',
525 description: 'Stop after N events for this temporary trigger and disable it',
@@ -517,7 +537,7 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
537 examples: [
538 'composio listen GMAIL_NEW_GMAIL_MESSAGE',
539 'composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --max-events 5',
520 - 'composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 5m',
540 + 'composio listen GMAIL_NEW_GMAIL_MESSAGE --account work --timeout 5m',
541 "composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 1hr --stream '.data.threadId'",
542 'composio listen SLACK_RECEIVE_MESSAGE -p \'{ trigger_config: { channel: "C123" } }\'',
543 'composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream',
@@ -538,7 +558,7 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
558 {
559 name: '--alias <text>',
560 description:
541 - 'Alias for the connected account. Required when creating an additional account for the same toolkit (requires multi_account experimental feature)',
561 + 'Alias for the connected account. Required when creating an additional account for the same toolkit',
562 },
563 ],
564 flags: [
@@ -563,8 +583,8 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
583 ],
584 seeAlso: [
585 'composio search "<query>" Find tools to use after linking',
566 - "composio execute <slug> -d '{ ... }' Execute a tool with your connected account",
567 - 'composio config experimental Manage experimental features',
586 + "composio execute <slug> --account <alias> -d '{ ... }' Use a named account",
587 + 'composio connections list --toolkit <toolkit> List account selectors',
588 ],
589 },
590 'connections list': {
@@ -800,7 +820,8 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
820 ],
821 },
822 proxy: {
803 - usage: 'composio proxy <url> --toolkit <text> [-X method] [-H header]... [-d data]',
823 + usage:
824 + 'composio proxy <url> --toolkit <text> [--account <selector>] [-X method] [-H header]... [-d data]',
825 description:
826 'curl-like access to any toolkit API through Composio using your connected account. Composio handles authentication — just provide the full URL and toolkit.',
827 args: [{ name: '<url>', description: 'Full API endpoint URL' }],
@@ -809,6 +830,10 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
830 name: '-t, --toolkit <text>',
831 description: 'Toolkit slug whose connected account should be used',
832 },
833 + {
834 + name: '--account <selector>',
835 + description: 'Select a connected account by alias, word_id, or connected account ID',
836 + },
837 { name: '-X, --method <text>', description: 'HTTP method (GET, POST, PUT, DELETE, PATCH)' },
838 {
839 name: '-H, --header <text>',
@@ -821,7 +846,7 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
846 ],
847 flags: [{ name: '--skip-connection-check', description: 'Skip the connected-account check' }],
848 examples: [
824 - 'composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail',
849 + 'composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail --account work',
850 `composio proxy https://gmail.googleapis.com/gmail/v1/users/me/drafts --toolkit gmail \\`,
851 ` -X POST -H 'content-type: application/json' -d '{"message":{"raw":"..."}}'`,
852 ],
@@ -1259,14 +1284,13 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
1284 usage: 'composio config experimental [<feature>] [on|off]',
1285 description: 'View or toggle experimental feature flags.',
1286 args: [
1262 - { name: '<feature>', description: 'Feature name (e.g., listen, local_tools, multi_account)' },
1287 + { name: '<feature>', description: 'Feature name (e.g., listen, local_tools)' },
1288 { name: 'on|off', description: 'Enable or disable the feature' },
1289 ],
1290 examples: [
1291 'composio config experimental # List all features',
1292 'composio config experimental listen # Show current state',
1293 'composio config experimental local_tools on # Enable local toolkits',
1269 - 'composio config experimental multi_account on # Enable multi_account',
1294 ],
1295 },
1296 'dev logs triggers': {
ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts
+3 -76
@@ -1,5 +1,4 @@
1 import { Args, Command, HelpDoc, Options, ValidationError } from '@effect/cli';
2 -import type { Composio } from '@composio/client';
2 import { isLocalToolSlug } from '@composio/cli-local-tools';
3 import util from 'node:util';
4 import { Cause, Data, Effect, Either, Exit, Fiber, HashSet, Option, Predicate } from 'effect';
@@ -49,10 +48,7 @@ import {
48 getFreshConsumerConnectedToolkitsFromCache,
49 refreshConsumerConnectedToolkitsCache,
50 } from 'src/services/consumer-short-term-cache';
52 -import {
53 - formatConnectedAccountChoices,
54 - resolveConnectedAccountSelection,
55 -} from 'src/services/connected-account-selection';
51 +import { resolveConnectedAccountForToolkit } from 'src/services/connected-account-selection';
52 import {
53 appendCliSessionHistory,
54 resolveCliSessionArtifacts,
@@ -67,7 +63,6 @@ import {
63 import * as constants from 'src/constants';
64 import { ComposioCliUserConfig } from 'src/services/cli-user-config';
65 import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
70 -import { decodeConnectedAccountItemsWithFallback } from 'src/effects/decode-connected-account-list';
66
67 const slug = Args.text({ name: 'slug' }).pipe(
68 Args.withDescription('Tool slug (e.g. "GITHUB_CREATE_ISSUE")')
@@ -968,69 +963,6 @@ const emitCachedSchema = (
963 );
964 });
965
971 -const resolveExplicitConnectedAccount = (params: {
972 - readonly client: Composio;
973 - readonly toolkitSlug?: string;
974 - readonly userId: string;
975 - readonly selector: Option.Option<string>;
976 -}) =>
977 - Effect.gen(function* () {
978 - if (!params.toolkitSlug) return undefined;
979 - const toolkitSlug = params.toolkitSlug;
980 -
981 - const accounts = yield* Effect.tryPromise({
982 - try: () =>
983 - params.client.connectedAccounts.list({
984 - toolkit_slugs: [toolkitSlug],
985 - user_ids: [params.userId],
986 - statuses: ['ACTIVE'],
987 - limit: 100,
988 - }),
989 - catch: cause =>
990 - new ToolExecutionError({
991 - reason: 'connected_account',
992 - toolSlug: params.toolkitSlug,
993 - message: `Failed to load connected accounts for toolkit "${toolkitSlug}": ${String(cause)}`,
994 - cause,
995 - }),
996 - });
997 - const selectableAccounts = yield* decodeConnectedAccountItemsWithFallback(accounts.items).pipe(
998 - Effect.mapError(
999 - cause =>
1000 - new ToolExecutionError({
1001 - reason: 'connected_account',
1002 - toolSlug: toolkitSlug,
1003 - message: `Connected accounts for toolkit "${toolkitSlug}" did not match the expected response shape.`,
1004 - cause,
1005 - })
1006 - )
1007 - );
1008 -
1009 - const selected = resolveConnectedAccountSelection(
1010 - selectableAccounts,
1011 - Option.getOrUndefined(params.selector)
1012 - );
1013 -
1014 - if (selected) {
1015 - return selected.id;
1016 - }
1017 -
1018 - if (Option.isNone(params.selector)) {
1019 - return undefined;
1020 - }
1021 -
1022 - const choices = formatConnectedAccountChoices(selectableAccounts);
1023 - const hint =
1024 - choices.length > 0
1025 - ? ` Available accounts: ${choices.join(', ')}.`
1026 - : ' No active connected accounts were found for that toolkit.';
1027 - return yield* new ToolExecutionError({
1028 - reason: 'connected_account',
1029 - toolSlug: toolkitSlug,
1030 - message: `No connected account matched "${params.selector.value}" for toolkit "${toolkitSlug}".${hint}`,
1031 - });
1032 - });
1033 -
966 const resolveExecuteContext = (params: RunToolsExecuteParams) =>
967 Effect.gen(function* () {
968 const ui = yield* TerminalUI;
@@ -1114,17 +1046,12 @@ const resolveExecuteContext = (params: RunToolsExecuteParams) =>
1046 orgId: resolvedProject.orgId,
1047 projectId: resolvedProject.projectId,
1048 });
1117 - const accountSelector = cliConfig.isExperimentalFeatureEnabled(
1118 - CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT
1119 - )
1120 - ? params.account
1121 - : Option.none<string>();
1049 const toolkitSlug = isLocalToolSlug(params.slug) ? undefined : toolkitFromToolSlug(params.slug);
1123 - const selectedConnectedAccountId = yield* resolveExplicitConnectedAccount({
1050 + const selectedConnectedAccountId = yield* resolveConnectedAccountForToolkit({
1051 client,
1052 toolkitSlug,
1053 userId: resolvedUserId.value,
1127 - selector: accountSelector,
1054 + selector: params.account,
1055 });
1056 const args = Option.isSome(params.file)
1057 ? yield* getOrFetchToolInputDefinition(params.slug, {
ts/packages/cli/src/experimental-features.ts
-3
@@ -8,7 +8,6 @@
8 export const CLI_EXPERIMENTAL_FEATURES = {
9 LISTEN: 'listen',
10 LOCAL_TOOLS: 'local_tools',
11 - MULTI_ACCOUNT: 'multi_account',
11 } as const;
12
13 export const CLI_RELEASE_CHANNELS = ['stable', 'beta'] as const;
@@ -23,8 +22,6 @@ export const isExperimentalFeatureEnabledByDefault = (
22 channel: CliReleaseChannel
23 ) => {
24 switch (feature) {
26 - case CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT:
27 - return true;
25 case CLI_EXPERIMENTAL_FEATURES.LISTEN:
26 case CLI_EXPERIMENTAL_FEATURES.LOCAL_TOOLS:
27 return channel === 'beta';
ts/packages/cli/src/services/connected-account-selection.ts
+66 -1
@@ -1,5 +1,8 @@
1 +import type { Composio } from '@composio/client';
2 +import { Data, Effect, Option, Schema } from 'effect';
3 import type { ConnectedAccountItem } from 'src/models/connected-accounts';
2 -import { Schema } from 'effect';
4 +import { decodeConnectedAccountItemsWithFallback } from 'src/effects/decode-connected-account-list';
5 +import type { TerminalUI } from 'src/services/terminal-ui';
6
7 // `ConnectedAccountItem` widened with an `'UNKNOWN'` sentinel for statuses
8 // the closed schema doesn't yet know about. Selection only picks `'ACTIVE'`,
@@ -134,3 +137,65 @@ export const formatConnectedAccountChoices = (
137 items: ReadonlyArray<ConnectedAccountItem>
138 ): ReadonlyArray<string> =>
139 items.filter(isUsableConnectedAccount).sort(compareNewestFirst).map(formatConnectedAccountChoice);
140 +
141 +export class ConnectedAccountResolutionError extends Data.TaggedError(
142 + 'services/ConnectedAccountResolutionError'
143 +)<{
144 + readonly message: string;
145 + readonly toolkitSlug: string;
146 + readonly cause?: unknown;
147 +}> {}
148 +
149 +export const resolveConnectedAccountForToolkit = (params: {
150 + readonly client: Composio;
151 + readonly toolkitSlug?: string;
152 + readonly userId: string;
153 + readonly selector: Option.Option<string>;
154 +}): Effect.Effect<string | undefined, ConnectedAccountResolutionError, TerminalUI> =>
155 + Effect.gen(function* () {
156 + if (!params.toolkitSlug) return undefined;
157 + const toolkitSlug = params.toolkitSlug;
158 +
159 + const accounts = yield* Effect.tryPromise({
160 + try: () =>
161 + params.client.connectedAccounts.list({
162 + toolkit_slugs: [toolkitSlug],
163 + user_ids: [params.userId],
164 + statuses: ['ACTIVE'],
165 + limit: 100,
166 + }),
167 + catch: cause =>
168 + new ConnectedAccountResolutionError({
169 + message: `Failed to load connected accounts for toolkit "${toolkitSlug}": ${String(cause)}`,
170 + toolkitSlug,
171 + cause,
172 + }),
173 + });
174 + const selectableAccounts = yield* decodeConnectedAccountItemsWithFallback(accounts.items).pipe(
175 + Effect.mapError(
176 + cause =>
177 + new ConnectedAccountResolutionError({
178 + message: `Connected accounts for toolkit "${toolkitSlug}" did not match the expected response shape.`,
179 + toolkitSlug,
180 + cause,
181 + })
182 + )
183 + );
184 +
185 + const selected = resolveConnectedAccountSelection(
186 + selectableAccounts,
187 + Option.getOrUndefined(params.selector)
188 + );
189 + if (selected) return selected.id;
190 + if (Option.isNone(params.selector)) return undefined;
191 +
192 + const choices = formatConnectedAccountChoices(selectableAccounts);
193 + const hint =
194 + choices.length > 0
195 + ? ` Available accounts: ${choices.join(', ')}.`
196 + : ' No active connected accounts were found for that toolkit.';
197 + return yield* new ConnectedAccountResolutionError({
198 + message: `No connected account matched "${params.selector.value}" for toolkit "${toolkitSlug}".${hint}`,
199 + toolkitSlug,
200 + });
201 + });
ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.link.cmd.test.ts
+26
@@ -424,6 +424,7 @@ describe('CLI: composio dev connected-accounts link', () => {
424 connectedAccountsData: makeConnectedAccountsData({
425 items: [makeConnectedAccount({ status: 'INITIATED' })],
426 }),
427 + cliUserConfig: { experimentalFeatures: { multi_account: false } },
428 toolRouter: {
429 create: toolRouterCreateSpy,
430 link: toolRouterLinkSpy,
@@ -483,4 +484,29 @@ describe('CLI: composio dev connected-accounts link', () => {
484 );
485 }
486 );
487 +
488 + layer(
489 + TestLive({
490 + baseConfigProvider: testConfigProvider,
491 + connectedAccountsData: makeConnectedAccountsData({
492 + items: [makeConnectedAccount({ alias: 'work' })],
493 + }),
494 + toolRouter: { create: toolRouterCreateSpy, link: toolRouterLinkSpy },
495 + fixture: 'global-test-user-id',
496 + })
497 + )('[Given] a duplicate alias [Then] link explains how to use the existing account', it => {
498 + it.scoped('detects the exact existing alias before creating a link', () =>
499 + Effect.gen(function* () {
500 + yield* cli(['link', 'gmail', '--alias', 'work']);
501 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
502 + const output = lines.join('\n');
503 +
504 + expect(output).toContain('Alias "work" is already in use');
505 + expect(output).toContain('composio execute <TOOL_SLUG> --account work');
506 + expect(output).toContain('composio connections list --toolkit gmail');
507 + expect(toolRouterCreateSpy).not.toHaveBeenCalled();
508 + expect(toolRouterLinkSpy).not.toHaveBeenCalled();
509 + })
510 + );
511 + });
512 });
ts/packages/cli/test/src/commands/feature-visibility.test.ts
+8
@@ -59,6 +59,14 @@ describe('CLI experimental feature visibility', () => {
59 expect(getCommandHelpText('local-tools', betaVisibility)).toContain('composio local-tools');
60 });
61
62 + it('shows stable account selection for execute and proxy', () => {
63 + expect(getCommandHelpText('execute', stableVisibility)).toContain('--account <selector>');
64 + expect(getCommandHelpText('proxy', stableVisibility)).toContain('--account <selector>');
65 + expect(getCommandHelpText('link', stableVisibility)).not.toContain(
66 + 'multi_account experimental feature'
67 + );
68 + });
69 +
70 it('accepts help mode suffixes when matching subcommand help', () => {
71 expect(
72 matchSubcommandHelp(['bun', 'composio', 'search', '--help', 'simple'], stableVisibility)
ts/packages/cli/test/src/commands/proxy.cmd.test.ts
+46
@@ -56,6 +56,49 @@ describe('CLI: composio proxy', () => {
56 const live = TestLive({
57 baseConfigProvider: testConfigProvider,
58 fixture: 'global-test-user-id',
59 + cliUserConfig: { experimentalFeatures: { multi_account: false } },
60 + connectedAccountsData: {
61 + items: [
62 + {
63 + id: 'con_gmail_work',
64 + alias: 'work',
65 + word_id: 'gmail-work',
66 + status: 'ACTIVE',
67 + status_reason: null,
68 + is_disabled: false,
69 + user_id: 'consumer-user-org_test',
70 + toolkit: { slug: 'gmail' },
71 + auth_config: {
72 + id: 'ac_gmail_oauth',
73 + auth_scheme: 'OAUTH2',
74 + is_composio_managed: true,
75 + is_disabled: false,
76 + },
77 + created_at: '2026-01-01T00:00:00.000Z',
78 + updated_at: '2026-01-01T00:00:00.000Z',
79 + test_request_endpoint: '',
80 + },
81 + {
82 + id: 'con_gmail_personal',
83 + alias: 'personal',
84 + word_id: 'gmail-personal',
85 + status: 'ACTIVE',
86 + status_reason: null,
87 + is_disabled: false,
88 + user_id: 'consumer-user-org_test',
89 + toolkit: { slug: 'gmail' },
90 + auth_config: {
91 + id: 'ac_gmail_oauth',
92 + auth_scheme: 'OAUTH2',
93 + is_composio_managed: true,
94 + is_disabled: false,
95 + },
96 + created_at: '2026-01-02T00:00:00.000Z',
97 + updated_at: '2026-01-02T00:00:00.000Z',
98 + test_request_endpoint: '',
99 + },
100 + ],
101 + },
102 toolRouter: {
103 create: async (params: SessionCreateParams) => {
104 createParams = params;
@@ -92,6 +135,8 @@ describe('CLI: composio proxy', () => {
135 'https://gmail.googleapis.com/gmail/v1/users/me/drafts',
136 '--toolkit',
137 'gmail',
138 + '--account',
139 + 'work',
140 '-X',
141 'post',
142 '-H',
@@ -102,6 +147,7 @@ describe('CLI: composio proxy', () => {
147
148 expect(createParams).toEqual({
149 user_id: 'consumer-user-org_test',
150 + connected_accounts: { gmail: 'con_gmail_work' },
151 manage_connections: { enable: false },
152 toolkits: { enable: ['gmail'] },
153 });
ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts
+9 -2
@@ -18,6 +18,7 @@ import {
18 parseParallelExecuteArgs,
19 showToolsExecuteInputHelp,
20 } from 'src/commands/tools/commands/tools.execute.cmd';
21 +import { ComposioCliUserConfig } from 'src/services/cli-user-config';
22 import type { ToolkitDetailed } from 'src/models/toolkits';
23
24 const testConfigProvider = ConfigProvider.fromMap(
@@ -389,8 +390,13 @@ describe('CLI: composio execute', () => {
390 },
391 })
392 )('[Given] --account selector [Then] execute pins the matched connected account', it => {
392 - it.scoped('matches by alias, word_id, or id', () =>
393 + it.scoped('matches even when a stale config disables the former experiment', () =>
394 Effect.gen(function* () {
395 + const cliConfig = yield* ComposioCliUserConfig;
396 + yield* cliConfig.update({
397 + experimentalFeatures: { multi_account: false },
398 + });
399 +
400 yield* cli([
401 'execute',
402 'GMAIL_SEND_EMAIL',
@@ -1964,10 +1970,11 @@ describe('CLI: composio execute', () => {
1970
1971 expect(output).toContain('USAGE');
1972 expect(output).toContain(
1967 - 'composio execute <slug> [-d, --data text] [--file path] [--dry-run] [--get-schema] [--parallel]'
1973 + 'composio execute <slug> [-d, --data text] [--account selector] [--file path] [--dry-run] [--get-schema] [--parallel]'
1974 );
1975 expect(output).toContain('composio execute GMAIL_SEND_EMAIL --get-schema');
1976 expect(output).toContain('--parallel');
1977 + expect(output).toContain('--account <selector>');
1978 expect(output).toContain('GITHUB_CREATE_AN_ISSUE');
1979 })
1980 );
ts/packages/cli/test/src/services/cli-user-config.test.ts
-4
@@ -34,8 +34,6 @@ describe('ComposioCliUserConfig', () => {
34 assertEquals(config.data.developerDangerousCommandsEnabled, false);
35 assertEquals(config.data.experimentalFeatures.listen, undefined);
36 assertEquals(config.isExperimentalFeatureEnabled('listen'), false);
37 - assertEquals(config.data.experimentalFeatures.multi_account, undefined);
38 - assertEquals(config.isExperimentalFeatureEnabled('multi_account'), true);
37 assertEquals(config.data.experimentalSubagentTarget, 'auto');
38 assertEquals(config.data.artifactDirectory, undefined);
39
@@ -86,8 +84,6 @@ describe('ComposioCliUserConfig', () => {
84 assertEquals(config.data.developerDangerousCommandsEnabled, false);
85 assertEquals(config.data.experimentalFeatures.listen, undefined);
86 assertEquals(config.isExperimentalFeatureEnabled('listen'), true);
89 - assertEquals(config.data.experimentalFeatures.multi_account, undefined);
90 - assertEquals(config.isExperimentalFeatureEnabled('multi_account'), true);
87 assertEquals(config.data.experimentalSubagentTarget, 'auto');
88 }).pipe(Effect.provide(CliUserConfigTest));
89 });
ts/packages/cli/test/src/skills/composio-cli/reference-schema.test.ts
+2 -2
@@ -3,10 +3,10 @@ import { CLI_EXPERIMENTAL_FEATURES } from 'src/experimental-features';
3 import { resolveSkillBuildContext } from '../../../../skills-src/composio-cli/reference-schema';
4
5 describe('composio-cli skill build context', () => {
6 - it('enables multi-account guidance in stable builds', () => {
6 + it('keeps only genuinely experimental guidance disabled in stable builds', () => {
7 const build = resolveSkillBuildContext('stable');
8
9 - expect(build.experimentalFeatures[CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT]).toBe(true);
9 expect(build.experimentalFeatures[CLI_EXPERIMENTAL_FEATURES.LISTEN]).toBe(false);
10 + expect(build.experimentalFeatures[CLI_EXPERIMENTAL_FEATURES.LOCAL_TOOLS]).toBe(false);
11 });
12 });