Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 04:30 UTC
feat(cli): Add command aliases and restructure root help (#2842)
Musthaq Ahamad committed
Mar 5, 2026 at 19:49 UTC
c35b38bfc79e8e0cb30ba35c955de018cb76f67d
8 files changed
+310
-22
.changeset/fuzzy-phones-fold.md
new
+5
@@ -0,0 +1,5 @@
1
+---
2
+'@composio/cli': minor
3
+---
4
+
5
+Add top-level command aliases, restructure root help with BASIC/ADVANCED sections, and show full usage/options for basic commands
ts/packages/cli/src/commands/index.ts
+17
-1
@@ -100,6 +100,22 @@ const normalizeVersionShortFlag = (argv: ReadonlyArray<string>): ReadonlyArray<s
100
return argv;
101
};
102
103
+const ALIAS_TO_PARENT: Record<string, string> = {
104
+ search: 'tools',
105
+ execute: 'tools',
106
+ link: 'connected-accounts',
107
+ listen: 'triggers',
108
+};
109
+
110
+const normalizeAliases = (argv: ReadonlyArray<string>): ReadonlyArray<string> => {
111
+ const args = argv.slice(2);
112
+ if (args.length === 0) return argv;
113
+ const first = args[0];
114
+ const parent = first && ALIAS_TO_PARENT[first];
115
+ if (!parent) return argv;
116
+ return [...argv.slice(0, 2), parent, ...args];
117
+};
118
+
119
const isRootHelp = (argv: ReadonlyArray<string>): boolean => {
120
const args = argv.slice(2);
121
return args.length === 1 && (args[0] === '--help' || args[0] === '-h');
@@ -114,7 +130,7 @@ export const runWithConfig = Effect.gen(function* () {
130
});
131
132
return (argv: ReadonlyArray<string>) => {
117
- const normalizedArgv = normalizeVersionShortFlag(argv);
133
+ const normalizedArgv = normalizeAliases(normalizeVersionShortFlag(argv));
134
if (isRootHelp(normalizedArgv)) {
135
return printRootHelp();
136
}
ts/packages/cli/src/commands/root-help.ts
+127
-14
@@ -1,17 +1,109 @@
1
import { Console, Effect } from 'effect';
2
import { bold } from 'src/ui/colors';
3
4
-/**
5
- * Top-level commands for the root help output.
6
- * Order and descriptions must match the commands in index.ts.
7
- */
8
-const ROOT_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
9
- { name: 'version', description: 'Display the current Composio CLI version.' },
10
- { name: 'upgrade', description: 'Upgrade your Composio CLI to the latest available version.' },
11
- { name: 'whoami', description: 'Display your account information.' },
12
- { name: 'login', description: 'Log in to the Composio CLI session.' },
13
- { name: 'logout', description: 'Log out from the Composio CLI session.' },
14
- { name: 'init', description: 'Initialize a Composio project in the current directory.' },
4
+type BasicCommand = {
5
+ name: string;
6
+ description: string;
7
+ usage: string;
8
+ options?: ReadonlyArray<{ name: string; description: string }>;
9
+};
10
+
11
+const BASIC_COMMANDS: ReadonlyArray<BasicCommand> = [
12
+ {
13
+ name: 'version',
14
+ description: 'Display the current Composio CLI version.',
15
+ usage: 'version',
16
+ },
17
+ {
18
+ name: 'upgrade',
19
+ description: 'Upgrade your Composio CLI to the latest available version.',
20
+ usage: 'upgrade',
21
+ },
22
+ {
23
+ name: 'whoami',
24
+ description: 'Display your account information.',
25
+ usage: 'whoami',
26
+ },
27
+ {
28
+ name: 'login',
29
+ description: 'Log in to the Composio CLI session.',
30
+ usage: 'login [--no-browser] [--api-key text] [--org-id text] [--project-id text]',
31
+ options: [
32
+ { name: '--no-browser', description: 'Login without browser interaction' },
33
+ { name: '--api-key', description: 'API key for non-interactive login (agents/CI)' },
34
+ { name: '--org-id', description: 'Organization ID for non-interactive login' },
35
+ { name: '--project-id', description: 'Project ID for non-interactive login' },
36
+ ],
37
+ },
38
+ {
39
+ name: 'logout',
40
+ description: 'Log out from the Composio CLI session.',
41
+ usage: 'logout',
42
+ },
43
+ {
44
+ name: 'init',
45
+ description: 'Initialize a Composio project in the current directory.',
46
+ usage: 'init [--org-id text] [--project-id text] [--no-browser] [-y, --yes]',
47
+ options: [
48
+ { name: '--org-id', description: 'Organization ID (skip interactive picker)' },
49
+ { name: '--project-id', description: 'Project ID (skip interactive picker)' },
50
+ { name: '--no-browser', description: 'Skip opening browser for auth' },
51
+ { name: '-y, --yes', description: 'Auto-select default org/project' },
52
+ ],
53
+ },
54
+ {
55
+ name: 'search',
56
+ description: 'Search tools by use case across toolkits/apps.',
57
+ usage: 'search <query> [--toolkits text] [--limit integer]',
58
+ options: [
59
+ { name: '<query>', description: 'Semantic use-case query (e.g. "send emails")' },
60
+ { name: '--toolkits', description: 'Filter by toolkit slugs, comma-separated' },
61
+ { name: '--limit', description: 'Number of results per page (1-1000)' },
62
+ ],
63
+ },
64
+ {
65
+ name: 'execute',
66
+ description: 'Execute a tool.',
67
+ usage: 'execute <slug> [-d, --data text] [--user-id text]',
68
+ options: [
69
+ { name: '<slug>', description: 'Tool slug (e.g. "GITHUB_CREATE_ISSUE")' },
70
+ { name: '-d, --data', description: 'JSON arguments, @file, or - for stdin' },
71
+ { name: '--user-id', description: 'User ID (falls back to project test_user_id)' },
72
+ ],
73
+ },
74
+ {
75
+ name: 'link',
76
+ description: 'Connect a user account for a toolkit/app.',
77
+ usage: 'link [<toolkit>] [--auth-config text] [--user-id text] [--no-browser]',
78
+ options: [
79
+ { name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' },
80
+ { name: '--auth-config', description: 'Auth config ID (legacy flow)' },
81
+ { name: '--user-id', description: 'User ID for the connection' },
82
+ { name: '--no-browser', description: 'Skip auto-opening the browser' },
83
+ ],
84
+ },
85
+ {
86
+ name: 'listen',
87
+ description: 'Listen for trigger events.',
88
+ usage:
89
+ 'listen [--toolkits text] [--trigger-id text] [--user-id text] [--max-events integer] [--forward text] [--out text]',
90
+ options: [
91
+ { name: '--toolkits', description: 'Filter by toolkit slugs, comma-separated' },
92
+ { name: '--trigger-id', description: 'Filter by trigger id' },
93
+ { name: '--user-id', description: 'Filter by user id' },
94
+ { name: '--max-events', description: 'Stop after N matching events' },
95
+ {
96
+ name: '--forward',
97
+ description: 'Forward events to URL (signed with COMPOSIO_WEBHOOK_SECRET)',
98
+ },
99
+ { name: '--out', description: 'Append events to file' },
100
+ { name: '--json', description: 'Show raw event payload as JSON' },
101
+ { name: '--table', description: 'Show compact table rows' },
102
+ ],
103
+ },
104
+];
105
+
106
+const ADVANCED_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
107
{
108
name: 'generate',
109
description:
@@ -32,10 +124,29 @@ const ROOT_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
124
/**
125
* Prints the root-level help output in gh-style format.
126
* Shows only top-level commands, not nested subcommands.
127
+ * Basic commands include full usage and options.
128
*/
129
export function printRootHelp(): Effect.Effect<void> {
130
const name = 'composio';
38
- const maxNameLen = Math.max(...ROOT_COMMANDS.map(c => c.name.length), 10);
131
+ const allCommands = [
132
+ ...BASIC_COMMANDS.map(c => ({ name: c.name, description: c.description })),
133
+ ...ADVANCED_COMMANDS,
134
+ ];
135
+ const maxNameLen = Math.max(...allCommands.map(c => c.name.length), 10);
136
+
137
+ const basicLines: string[] = [];
138
+ for (const cmd of BASIC_COMMANDS) {
139
+ basicLines.push(` ${cmd.name}`);
140
+ basicLines.push(` ${cmd.description}`);
141
+ basicLines.push(` Usage: ${name} ${cmd.usage}`);
142
+ if (cmd.options && cmd.options.length > 0) {
143
+ basicLines.push(' Options:');
144
+ for (const opt of cmd.options) {
145
+ basicLines.push(` ${opt.name.padEnd(20)} ${opt.description}`);
146
+ }
147
+ }
148
+ basicLines.push('');
149
+ }
150
151
const lines: string[] = [
152
'',
@@ -44,8 +155,10 @@ export function printRootHelp(): Effect.Effect<void> {
155
bold('USAGE'),
156
` ${name} <command> [options]`,
157
'',
47
- bold('COMMANDS'),
48
- ...ROOT_COMMANDS.map(cmd => ` ${cmd.name.padEnd(maxNameLen)} ${cmd.description}`),
158
+ bold('BASIC COMMANDS'),
159
+ ...basicLines,
160
+ bold('ADVANCED COMMANDS'),
161
+ ...ADVANCED_COMMANDS.map(cmd => ` ${cmd.name.padEnd(maxNameLen)} ${cmd.description}`),
162
'',
163
bold('FLAGS'),
164
` -h, --help Show help for command`,
ts/packages/cli/test/src/commands/__snapshots__/$default.cmd.test.ts.snap
+74
-7
@@ -7,13 +7,80 @@ Connect AI agents to external tools. Link accounts, discover tools, and execute
7
USAGE
8
composio <command> [options]
9
10
-COMMANDS
11
- version Display the current Composio CLI version.
12
- upgrade Upgrade your Composio CLI to the latest available version.
13
- whoami Display your account information.
14
- login Log in to the Composio CLI session.
15
- logout Log out from the Composio CLI session.
16
- init Initialize a Composio project in the current directory.
10
+BASIC COMMANDS
11
+ version
12
+ Display the current Composio CLI version.
13
+ Usage: composio version
14
+
15
+ upgrade
16
+ Upgrade your Composio CLI to the latest available version.
17
+ Usage: composio upgrade
18
+
19
+ whoami
20
+ Display your account information.
21
+ Usage: composio whoami
22
+
23
+ login
24
+ Log in to the Composio CLI session.
25
+ Usage: composio login [--no-browser] [--api-key text] [--org-id text] [--project-id text]
26
+ Options:
27
+ --no-browser Login without browser interaction
28
+ --api-key API key for non-interactive login (agents/CI)
29
+ --org-id Organization ID for non-interactive login
30
+ --project-id Project ID for non-interactive login
31
+
32
+ logout
33
+ Log out from the Composio CLI session.
34
+ Usage: composio logout
35
+
36
+ init
37
+ Initialize a Composio project in the current directory.
38
+ Usage: composio init [--org-id text] [--project-id text] [--no-browser] [-y, --yes]
39
+ Options:
40
+ --org-id Organization ID (skip interactive picker)
41
+ --project-id Project ID (skip interactive picker)
42
+ --no-browser Skip opening browser for auth
43
+ -y, --yes Auto-select default org/project
44
+
45
+ search
46
+ Search tools by use case across toolkits/apps.
47
+ Usage: composio search <query> [--toolkits text] [--limit integer]
48
+ Options:
49
+ <query> Semantic use-case query (e.g. "send emails")
50
+ --toolkits Filter by toolkit slugs, comma-separated
51
+ --limit Number of results per page (1-1000)
52
+
53
+ execute
54
+ Execute a tool.
55
+ Usage: composio execute <slug> [-d, --data text] [--user-id text]
56
+ Options:
57
+ <slug> Tool slug (e.g. "GITHUB_CREATE_ISSUE")
58
+ -d, --data JSON arguments, @file, or - for stdin
59
+ --user-id User ID (falls back to project test_user_id)
60
+
61
+ link
62
+ Connect a user account for a toolkit/app.
63
+ Usage: composio link [<toolkit>] [--auth-config text] [--user-id text] [--no-browser]
64
+ Options:
65
+ <toolkit> Toolkit slug to link (e.g. "github", "gmail")
66
+ --auth-config Auth config ID (legacy flow)
67
+ --user-id User ID for the connection
68
+ --no-browser Skip auto-opening the browser
69
+
70
+ listen
71
+ Listen for trigger events.
72
+ Usage: composio listen [--toolkits text] [--trigger-id text] [--user-id text] [--max-events integer] [--forward text] [--out text]
73
+ Options:
74
+ --toolkits Filter by toolkit slugs, comma-separated
75
+ --trigger-id Filter by trigger id
76
+ --user-id Filter by user id
77
+ --max-events Stop after N matching events
78
+ --forward Forward events to URL (signed with COMPOSIO_WEBHOOK_SECRET)
79
+ --out Append events to file
80
+ --json Show raw event payload as JSON
81
+ --table Show compact table rows
82
+
83
+ADVANCED COMMANDS
84
generate Generate type stubs for toolkits, tools, and triggers, auto-detecting project language (TypeScript | Python)
85
py Handle Python projects.
86
ts Handle TypeScript projects.
ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.link.cmd.test.ts
+23
@@ -120,4 +120,27 @@ describe('CLI: composio connected-accounts link', () => {
120
})
121
);
122
});
123
+
124
+ layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(
125
+ '[Given] composio link alias [Then] works like composio connected-accounts link',
126
+ it => {
127
+ it.scoped('alias expands to connected-accounts link', () =>
128
+ Effect.gen(function* () {
129
+ yield* cli([
130
+ 'link',
131
+ '--auth-config',
132
+ 'ac_gmail_oauth',
133
+ '--user-id',
134
+ 'default',
135
+ '--no-browser',
136
+ ]);
137
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
138
+ const output = lines.join('\n');
139
+
140
+ expect(output).toContain('https://app.composio.dev/link?token=lt_test_token');
141
+ expect(output).toContain('ACTIVE');
142
+ })
143
+ );
144
+ }
145
+ );
146
});
ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts
+26
@@ -71,6 +71,32 @@ describe('CLI: composio tools execute', () => {
71
);
72
});
73
74
+ layer(
75
+ TestLive({
76
+ baseConfigProvider: testConfigProvider,
77
+ stdin: { isTTY: true, data: '' },
78
+ })
79
+ )('[Given] composio execute alias [Then] works like composio tools execute', it => {
80
+ it.scoped('alias expands to tools execute', () =>
81
+ Effect.gen(function* () {
82
+ yield* cli([
83
+ 'execute',
84
+ 'GMAIL_SEND_EMAIL',
85
+ '--user-id',
86
+ 'default',
87
+ '-d',
88
+ '{"recipient":"a"}',
89
+ ]);
90
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
91
+ const output = parseLastJson(lines);
92
+
93
+ expect(output.successful).toBe(true);
94
+ expect(output.data.tool_slug).toBe('GMAIL_SEND_EMAIL');
95
+ expect(output.data.arguments).toEqual({ recipient: 'a' });
96
+ })
97
+ );
98
+ });
99
+
100
layer(
101
TestLive({
102
baseConfigProvider: testConfigProvider,
ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts
+17
@@ -280,4 +280,21 @@ describe('CLI: composio tools search', () => {
280
})
281
);
282
});
283
+
284
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
285
+ '[Given] composio search alias [Then] works like composio tools search',
286
+ it => {
287
+ it.scoped('alias expands to tools search', () =>
288
+ Effect.gen(function* () {
289
+ yield* cli(['search', 'send']);
290
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
291
+ const output = lines.join('\n');
292
+
293
+ expect(output).toContain('GMAIL_SEND_EMAIL');
294
+ expect(output).toContain('SLACK_SEND_MESSAGE');
295
+ expect(output).toContain('Found 2 tools');
296
+ })
297
+ );
298
+ }
299
+ );
300
});
ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts
+21
@@ -130,6 +130,27 @@ describe('CLI: composio triggers listen', () => {
130
);
131
});
132
133
+ layer(
134
+ TestLive({
135
+ baseConfigProvider: testConfigProvider,
136
+ realtimeData: {
137
+ events: [mockV3TriggerEvent],
138
+ },
139
+ })
140
+ )('[Given] composio listen alias [Then] works like composio triggers listen', it => {
141
+ it.scoped('alias expands to triggers listen', () =>
142
+ Effect.gen(function* () {
143
+ yield* cli(['listen', '--max-events', '1']);
144
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
145
+ const output = lines.join('\n');
146
+
147
+ expect(output).toContain('Listening for realtime trigger events');
148
+ expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
149
+ expect(output).toContain('Stopped after receiving 1 matching events');
150
+ })
151
+ );
152
+ });
153
+
154
layer(
155
TestLive({
156
baseConfigProvider: testConfigProvider,