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.

feat(cli): add `composio connections list` command (#3206)

Rahul Tarak20cfa6cdaeb9
diff --git a/ts/packages/cli/README.md b/ts/packages/cli/README.md
index e37aacd61..fe2610772 100644
--- a/ts/packages/cli/README.md
+++ b/ts/packages/cli/README.md
@@ -38,6 +38,7 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]
- `composio proxy <url> --toolkit <toolkit> [-X method] [-H header]... [-d data]`: Call a toolkit API directly through Composio using a connected account.
- `composio tools list|info`: Inspect available tools and their cached schemas.
- `composio triggers list <toolkit>|info`: Inspect toolkit-scoped trigger types and their schemas.
+- `composio connections list [--toolkit <toolkit>]`: Print toolkit connection statuses as JSON.
- `composio artifacts cwd`: Print the cwd-scoped CLI session artifacts directory.
- `composio dev <subcommand>`: Developer workflows for init, playground execution, logs, toolkits, auth configs, accounts, triggers, orgs, and projects.
- `composio generate [-o, --output-dir <directory>] [--toolkits <toolkit>] [--type-tools]`: Auto-detect the project language (Python or TypeScript) and generate type stubs for toolkits, tools, and triggers.
diff --git a/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts b/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts
new file mode 100644
index 000000000..31e2b42f9
--- /dev/null
+++ b/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts
@@ -0,0 +1,61 @@
+import { Command, Options } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { requireAuth } from 'src/effects/require-auth';
+import type { ConnectedAccountItem } from 'src/models/connected-accounts';
+import { ComposioToolkitsRepository } from 'src/services/composio-clients';
+import { TerminalUI } from 'src/services/terminal-ui';
+
+const toolkit = Options.text('toolkit').pipe(
+ Options.withDescription('Filter by toolkit slug (e.g. "gmail")'),
+ Options.optional
+);
+
+const formatConnectionsJson = (items: ReadonlyArray<ConnectedAccountItem>): string => {
+ const toolkitCounts = items.reduce<Map<string, number>>((acc, item) => {
+ acc.set(item.toolkit.slug, (acc.get(item.toolkit.slug) ?? 0) + 1);
+ return acc;
+ }, new Map());
+
+ const grouped = items.reduce<Record<string, Array<{ status: string; alias?: string | null }>>>(
+ (acc, item) => {
+ const toolkit = item.toolkit.slug;
+ const entry = {
+ status: item.status,
+ ...(toolkitCounts.get(toolkit)! > 1 ? { alias: item.alias ?? null } : {}),
+ };
+
+ if (!acc[toolkit]) {
+ acc[toolkit] = [];
+ }
+ acc[toolkit].push(entry);
+ return acc;
+ },
+ {}
+ );
+
+ return JSON.stringify(grouped, null, 2);
+};
+
+export const connectionsCmd$List = Command.make('list', { toolkit }, ({ toolkit }) =>
+ Effect.gen(function* () {
+ if (!(yield* requireAuth)) return;
+
+ const ui = yield* TerminalUI;
+ const repo = yield* ComposioToolkitsRepository;
+ const toolkitSlug = Option.getOrUndefined(toolkit);
+
+ const result = yield* ui.withSpinner(
+ 'Fetching connections...',
+ repo.listConnectedAccounts({
+ toolkit_slugs: toolkitSlug ? [toolkitSlug] : undefined,
+ limit: 1000,
+ })
+ );
+
+ yield* ui.output(formatConnectionsJson(result.items));
+ })
+).pipe(
+ Command.withDescription(
+ 'List connection statuses as JSON. Includes aliases when a toolkit has multiple connections.'
+ )
+);
diff --git a/ts/packages/cli/src/commands/connections/connections.cmd.ts b/ts/packages/cli/src/commands/connections/connections.cmd.ts
new file mode 100644
index 000000000..d13e084af
--- /dev/null
+++ b/ts/packages/cli/src/commands/connections/connections.cmd.ts
@@ -0,0 +1,7 @@
+import { Command } from '@effect/cli';
+import { connectionsCmd$List } from './commands/connections.list.cmd';
+
+export const rootConnectionsCmd = Command.make('connections').pipe(
+ Command.withDescription('Inspect connected toolkit accounts in a script-friendly format.'),
+ Command.withSubcommands([connectionsCmd$List])
+);
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index 5969abda9..2a2fe4bda 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -27,6 +27,7 @@ import { rootTriggersCmd } from './triggers/root-triggers.cmd';
import { rootConnectedAccountsCmd$Link } from './connected-accounts/commands/connected-accounts.link.cmd';
import { orgsCmd } from './orgs/orgs.cmd';
import { configCmd } from './config/config.cmd';
+import { rootConnectionsCmd } from './connections/connections.cmd';
import { renderCommandHintGraph } from 'src/services/command-hints';
import { resetRuntimeDebugFlags, setRuntimeDebugFlags } from 'src/services/runtime-debug-flags';
import { ComposioCliUserConfig } from 'src/services/cli-user-config';
@@ -64,6 +65,7 @@ const ROOT_COMMANDS: ReadonlyArray<TaggedValue<Command.Command<any, any, any, an
tagged(rootToolsCmd$Search),
tagged(rootConnectedAccountsCmd$Link),
tagged(rootToolsCmd$Execute),
+ tagged(rootConnectionsCmd),
tagged(generateCmd),
tagged(orgsCmd),
tagged(configCmd),
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
index c3fa22147..b7518115a 100644
--- a/ts/packages/cli/src/commands/root-help.ts
+++ b/ts/packages/cli/src/commands/root-help.ts
@@ -143,6 +143,10 @@ const OTHER_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
name: 'composio triggers list <toolkit>',
description: 'List available trigger types in a toolkit',
}),
+ tagged({
+ name: 'composio connections list',
+ description: 'Print toolkit connection statuses as JSON',
+ }),
tagged({
name: 'composio artifacts cwd',
description: 'Print the cwd-scoped session artifact directory',
@@ -476,6 +480,17 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
'composio config experimental Manage experimental features',
],
},
+ 'connections list': {
+ usage: 'composio connections list [--toolkit <text>]',
+ description:
+ 'Print connected toolkit statuses as JSON. Adds aliases when a toolkit has multiple connections.',
+ options: [{ name: '--toolkit <text>', description: 'Filter to a single toolkit slug' }],
+ examples: ['composio connections list', 'composio connections list --toolkit gmail'],
+ seeAlso: [
+ 'composio link <toolkit> Connect a new account for a toolkit',
+ 'composio dev connected-accounts list Inspect the full connected-account table',
+ ],
+ },
run: {
usage: 'composio run <code> [-- ...args] | run -f <file> [-- ...args]',
description:
diff --git a/ts/packages/cli/test/src/commands/$default.cmd.test.ts b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
index d144425bf..84eea88f7 100644
--- a/ts/packages/cli/test/src/commands/$default.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
@@ -71,6 +71,7 @@ describe('CLI: composio', () => {
const output = lines.join('\n');
expect(output).toContain('Usage:');
expect(output).toContain('composio');
+ expect(output).toContain('composio connections list');
})
);
});
diff --git a/ts/packages/cli/test/src/commands/connections/connections.list.cmd.test.ts b/ts/packages/cli/test/src/commands/connections/connections.list.cmd.test.ts
new file mode 100644
index 000000000..8e7fb2b6b
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/connections/connections.list.cmd.test.ts
@@ -0,0 +1,126 @@
+import { describe, expect, layer } from '@effect/vitest';
+import { ConfigProvider, Effect } from 'effect';
+import type { ConnectedAccountItem } from 'src/models/connected-accounts';
+import { extendConfigProvider } from 'src/services/config';
+import { cli, TestLive, MockConsole } from 'test/__utils__';
+import type { TestLiveInput } from 'test/__utils__/services/test-layer';
+
+const parseJsonFromLines = (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 Record<string, Array<Record<string, string>>>;
+ } catch {
+ // continue
+ }
+ }
+ throw new Error('Expected JSON output but none found');
+};
+
+const testConnections: ConnectedAccountItem[] = [
+ {
+ id: 'con_gmail_active',
+ alias: null,
+ word_id: null,
+ status: 'ACTIVE',
+ status_reason: null,
+ is_disabled: false,
+ user_id: 'default',
+ toolkit: { slug: 'gmail' },
+ auth_config: {
+ id: 'ac_gmail_oauth',
+ auth_scheme: 'OAUTH2',
+ is_composio_managed: true,
+ is_disabled: false,
+ },
+ created_at: '2026-01-01T00:00:00Z',
+ updated_at: '2026-01-15T00:00:00Z',
+ test_request_endpoint: '',
+ },
+ {
+ id: 'con_github_work',
+ alias: 'work',
+ word_id: null,
+ status: 'ACTIVE',
+ status_reason: null,
+ is_disabled: false,
+ user_id: 'default',
+ toolkit: { slug: 'github' },
+ auth_config: {
+ id: 'ac_github_oauth',
+ auth_scheme: 'OAUTH2',
+ is_composio_managed: true,
+ is_disabled: false,
+ },
+ created_at: '2026-02-01T00:00:00Z',
+ updated_at: '2026-02-10T00:00:00Z',
+ test_request_endpoint: '',
+ },
+ {
+ id: 'con_github_personal',
+ alias: 'personal',
+ word_id: null,
+ status: 'FAILED',
+ status_reason: 'Token expired',
+ is_disabled: false,
+ user_id: 'default',
+ toolkit: { slug: 'github' },
+ auth_config: {
+ id: 'ac_github_oauth_2',
+ auth_scheme: 'OAUTH2',
+ is_composio_managed: true,
+ is_disabled: false,
+ },
+ created_at: '2026-02-03T00:00:00Z',
+ updated_at: '2026-02-12T00:00:00Z',
+ test_request_endpoint: '',
+ },
+];
+
+const connectedAccountsData = {
+ items: testConnections,
+} satisfies TestLiveInput['connectedAccountsData'];
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_USER_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio connections list', () => {
+ layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(it => {
+ it.scoped('[Given] no filter [Then] prints connection JSON with aliases for duplicates', () =>
+ Effect.gen(function* () {
+ yield* cli(['connections', 'list']);
+
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const parsed = parseJsonFromLines(lines);
+
+ expect(parsed).toEqual({
+ gmail: [{ status: 'ACTIVE' }],
+ github: [
+ { status: 'ACTIVE', alias: 'work' },
+ { status: 'FAILED', alias: 'personal' },
+ ],
+ });
+ })
+ );
+ });
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(it => {
+ it.scoped('[Given] --toolkit github [Then] filters the JSON output', () =>
+ Effect.gen(function* () {
+ yield* cli(['connections', 'list', '--toolkit', 'github']);
+
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const parsed = parseJsonFromLines(lines);
+
+ expect(parsed).toEqual({
+ github: [
+ { status: 'ACTIVE', alias: 'work' },
+ { status: 'FAILED', alias: 'personal' },
+ ],
+ });
+ })
+ );
+ });
+});