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

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,