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 command aliases and restructure root help (#2842)

Musthaq Ahamadc35b38bfc79e
diff --git a/.changeset/fuzzy-phones-fold.md b/.changeset/fuzzy-phones-fold.md
new file mode 100644
index 000000000..22a83d0f3
--- /dev/null
+++ b/.changeset/fuzzy-phones-fold.md
@@ -0,0 +1,5 @@
+---
+'@composio/cli': minor
+---
+
+Add top-level command aliases, restructure root help with BASIC/ADVANCED sections, and show full usage/options for basic commands
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index 99b3e6926..ec0463ecf 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -100,6 +100,22 @@ const normalizeVersionShortFlag = (argv: ReadonlyArray<string>): ReadonlyArray<s
return argv;
};
+const ALIAS_TO_PARENT: Record<string, string> = {
+ search: 'tools',
+ execute: 'tools',
+ link: 'connected-accounts',
+ listen: 'triggers',
+};
+
+const normalizeAliases = (argv: ReadonlyArray<string>): ReadonlyArray<string> => {
+ const args = argv.slice(2);
+ if (args.length === 0) return argv;
+ const first = args[0];
+ const parent = first && ALIAS_TO_PARENT[first];
+ if (!parent) return argv;
+ return [...argv.slice(0, 2), parent, ...args];
+};
+
const isRootHelp = (argv: ReadonlyArray<string>): boolean => {
const args = argv.slice(2);
return args.length === 1 && (args[0] === '--help' || args[0] === '-h');
@@ -114,7 +130,7 @@ export const runWithConfig = Effect.gen(function* () {
});
return (argv: ReadonlyArray<string>) => {
- const normalizedArgv = normalizeVersionShortFlag(argv);
+ const normalizedArgv = normalizeAliases(normalizeVersionShortFlag(argv));
if (isRootHelp(normalizedArgv)) {
return printRootHelp();
}
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
index 812252cc6..0b15908a1 100644
--- a/ts/packages/cli/src/commands/root-help.ts
+++ b/ts/packages/cli/src/commands/root-help.ts
@@ -1,17 +1,109 @@
import { Console, Effect } from 'effect';
import { bold } from 'src/ui/colors';
-/**
- * Top-level commands for the root help output.
- * Order and descriptions must match the commands in index.ts.
- */
-const ROOT_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
- { name: 'version', description: 'Display the current Composio CLI version.' },
- { name: 'upgrade', description: 'Upgrade your Composio CLI to the latest available version.' },
- { name: 'whoami', description: 'Display your account information.' },
- { name: 'login', description: 'Log in to the Composio CLI session.' },
- { name: 'logout', description: 'Log out from the Composio CLI session.' },
- { name: 'init', description: 'Initialize a Composio project in the current directory.' },
+type BasicCommand = {
+ name: string;
+ description: string;
+ usage: string;
+ options?: ReadonlyArray<{ name: string; description: string }>;
+};
+
+const BASIC_COMMANDS: ReadonlyArray<BasicCommand> = [
+ {
+ name: 'version',
+ description: 'Display the current Composio CLI version.',
+ usage: 'version',
+ },
+ {
+ name: 'upgrade',
+ description: 'Upgrade your Composio CLI to the latest available version.',
+ usage: 'upgrade',
+ },
+ {
+ name: 'whoami',
+ description: 'Display your account information.',
+ usage: 'whoami',
+ },
+ {
+ name: 'login',
+ description: 'Log in to the Composio CLI session.',
+ usage: 'login [--no-browser] [--api-key text] [--org-id text] [--project-id text]',
+ options: [
+ { name: '--no-browser', description: 'Login without browser interaction' },
+ { name: '--api-key', description: 'API key for non-interactive login (agents/CI)' },
+ { name: '--org-id', description: 'Organization ID for non-interactive login' },
+ { name: '--project-id', description: 'Project ID for non-interactive login' },
+ ],
+ },
+ {
+ name: 'logout',
+ description: 'Log out from the Composio CLI session.',
+ usage: 'logout',
+ },
+ {
+ name: 'init',
+ description: 'Initialize a Composio project in the current directory.',
+ usage: 'init [--org-id text] [--project-id text] [--no-browser] [-y, --yes]',
+ options: [
+ { name: '--org-id', description: 'Organization ID (skip interactive picker)' },
+ { name: '--project-id', description: 'Project ID (skip interactive picker)' },
+ { name: '--no-browser', description: 'Skip opening browser for auth' },
+ { name: '-y, --yes', description: 'Auto-select default org/project' },
+ ],
+ },
+ {
+ name: 'search',
+ description: 'Search tools by use case across toolkits/apps.',
+ usage: 'search <query> [--toolkits text] [--limit integer]',
+ options: [
+ { name: '<query>', description: 'Semantic use-case query (e.g. "send emails")' },
+ { name: '--toolkits', description: 'Filter by toolkit slugs, comma-separated' },
+ { name: '--limit', description: 'Number of results per page (1-1000)' },
+ ],
+ },
+ {
+ name: 'execute',
+ description: 'Execute a tool.',
+ usage: 'execute <slug> [-d, --data text] [--user-id text]',
+ options: [
+ { name: '<slug>', description: 'Tool slug (e.g. "GITHUB_CREATE_ISSUE")' },
+ { name: '-d, --data', description: 'JSON arguments, @file, or - for stdin' },
+ { name: '--user-id', description: 'User ID (falls back to project test_user_id)' },
+ ],
+ },
+ {
+ name: 'link',
+ description: 'Connect a user account for a toolkit/app.',
+ usage: 'link [<toolkit>] [--auth-config text] [--user-id text] [--no-browser]',
+ options: [
+ { name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' },
+ { name: '--auth-config', description: 'Auth config ID (legacy flow)' },
+ { name: '--user-id', description: 'User ID for the connection' },
+ { name: '--no-browser', description: 'Skip auto-opening the browser' },
+ ],
+ },
+ {
+ name: 'listen',
+ description: 'Listen for trigger events.',
+ usage:
+ 'listen [--toolkits text] [--trigger-id text] [--user-id text] [--max-events integer] [--forward text] [--out text]',
+ options: [
+ { name: '--toolkits', description: 'Filter by toolkit slugs, comma-separated' },
+ { name: '--trigger-id', description: 'Filter by trigger id' },
+ { name: '--user-id', description: 'Filter by user id' },
+ { name: '--max-events', description: 'Stop after N matching events' },
+ {
+ name: '--forward',
+ description: 'Forward events to URL (signed with COMPOSIO_WEBHOOK_SECRET)',
+ },
+ { name: '--out', description: 'Append events to file' },
+ { name: '--json', description: 'Show raw event payload as JSON' },
+ { name: '--table', description: 'Show compact table rows' },
+ ],
+ },
+];
+
+const ADVANCED_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
{
name: 'generate',
description:
@@ -32,10 +124,29 @@ const ROOT_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
/**
* Prints the root-level help output in gh-style format.
* Shows only top-level commands, not nested subcommands.
+ * Basic commands include full usage and options.
*/
export function printRootHelp(): Effect.Effect<void> {
const name = 'composio';
- const maxNameLen = Math.max(...ROOT_COMMANDS.map(c => c.name.length), 10);
+ const allCommands = [
+ ...BASIC_COMMANDS.map(c => ({ name: c.name, description: c.description })),
+ ...ADVANCED_COMMANDS,
+ ];
+ const maxNameLen = Math.max(...allCommands.map(c => c.name.length), 10);
+
+ const basicLines: string[] = [];
+ for (const cmd of BASIC_COMMANDS) {
+ basicLines.push(` ${cmd.name}`);
+ basicLines.push(` ${cmd.description}`);
+ basicLines.push(` Usage: ${name} ${cmd.usage}`);
+ if (cmd.options && cmd.options.length > 0) {
+ basicLines.push(' Options:');
+ for (const opt of cmd.options) {
+ basicLines.push(` ${opt.name.padEnd(20)} ${opt.description}`);
+ }
+ }
+ basicLines.push('');
+ }
const lines: string[] = [
'',
@@ -44,8 +155,10 @@ export function printRootHelp(): Effect.Effect<void> {
bold('USAGE'),
` ${name} <command> [options]`,
'',
- bold('COMMANDS'),
- ...ROOT_COMMANDS.map(cmd => ` ${cmd.name.padEnd(maxNameLen)} ${cmd.description}`),
+ bold('BASIC COMMANDS'),
+ ...basicLines,
+ bold('ADVANCED COMMANDS'),
+ ...ADVANCED_COMMANDS.map(cmd => ` ${cmd.name.padEnd(maxNameLen)} ${cmd.description}`),
'',
bold('FLAGS'),
` -h, --help Show help for command`,
diff --git a/ts/packages/cli/test/src/commands/__snapshots__/$default.cmd.test.ts.snap b/ts/packages/cli/test/src/commands/__snapshots__/$default.cmd.test.ts.snap
index c15b58648..6f33e23cb 100644
--- a/ts/packages/cli/test/src/commands/__snapshots__/$default.cmd.test.ts.snap
+++ b/ts/packages/cli/test/src/commands/__snapshots__/$default.cmd.test.ts.snap
@@ -7,13 +7,80 @@ Connect AI agents to external tools. Link accounts, discover tools, and execute
USAGE
composio <command> [options]
-COMMANDS
- version Display the current Composio CLI version.
- upgrade Upgrade your Composio CLI to the latest available version.
- whoami Display your account information.
- login Log in to the Composio CLI session.
- logout Log out from the Composio CLI session.
- init Initialize a Composio project in the current directory.
+BASIC COMMANDS
+ version
+ Display the current Composio CLI version.
+ Usage: composio version
+
+ upgrade
+ Upgrade your Composio CLI to the latest available version.
+ Usage: composio upgrade
+
+ whoami
+ Display your account information.
+ Usage: composio whoami
+
+ login
+ Log in to the Composio CLI session.
+ Usage: composio login [--no-browser] [--api-key text] [--org-id text] [--project-id text]
+ Options:
+ --no-browser Login without browser interaction
+ --api-key API key for non-interactive login (agents/CI)
+ --org-id Organization ID for non-interactive login
+ --project-id Project ID for non-interactive login
+
+ logout
+ Log out from the Composio CLI session.
+ Usage: composio logout
+
+ init
+ Initialize a Composio project in the current directory.
+ Usage: composio init [--org-id text] [--project-id text] [--no-browser] [-y, --yes]
+ Options:
+ --org-id Organization ID (skip interactive picker)
+ --project-id Project ID (skip interactive picker)
+ --no-browser Skip opening browser for auth
+ -y, --yes Auto-select default org/project
+
+ search
+ Search tools by use case across toolkits/apps.
+ Usage: composio search <query> [--toolkits text] [--limit integer]
+ Options:
+ <query> Semantic use-case query (e.g. "send emails")
+ --toolkits Filter by toolkit slugs, comma-separated
+ --limit Number of results per page (1-1000)
+
+ execute
+ Execute a tool.
+ Usage: composio execute <slug> [-d, --data text] [--user-id text]
+ Options:
+ <slug> Tool slug (e.g. "GITHUB_CREATE_ISSUE")
+ -d, --data JSON arguments, @file, or - for stdin
+ --user-id User ID (falls back to project test_user_id)
+
+ link
+ Connect a user account for a toolkit/app.
+ Usage: composio link [<toolkit>] [--auth-config text] [--user-id text] [--no-browser]
+ Options:
+ <toolkit> Toolkit slug to link (e.g. "github", "gmail")
+ --auth-config Auth config ID (legacy flow)
+ --user-id User ID for the connection
+ --no-browser Skip auto-opening the browser
+
+ listen
+ Listen for trigger events.
+ Usage: composio listen [--toolkits text] [--trigger-id text] [--user-id text] [--max-events integer] [--forward text] [--out text]
+ Options:
+ --toolkits Filter by toolkit slugs, comma-separated
+ --trigger-id Filter by trigger id
+ --user-id Filter by user id
+ --max-events Stop after N matching events
+ --forward Forward events to URL (signed with COMPOSIO_WEBHOOK_SECRET)
+ --out Append events to file
+ --json Show raw event payload as JSON
+ --table Show compact table rows
+
+ADVANCED COMMANDS
generate Generate type stubs for toolkits, tools, and triggers, auto-detecting project language (TypeScript | Python)
py Handle Python projects.
ts Handle TypeScript projects.
diff --git a/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.link.cmd.test.ts b/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.link.cmd.test.ts
index 2e9b41582..9de32c402 100644
--- a/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.link.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.link.cmd.test.ts
@@ -120,4 +120,27 @@ describe('CLI: composio connected-accounts link', () => {
})
);
});
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, connectedAccountsData }))(
+ '[Given] composio link alias [Then] works like composio connected-accounts link',
+ it => {
+ it.scoped('alias expands to connected-accounts link', () =>
+ Effect.gen(function* () {
+ yield* cli([
+ 'link',
+ '--auth-config',
+ 'ac_gmail_oauth',
+ '--user-id',
+ 'default',
+ '--no-browser',
+ ]);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('https://app.composio.dev/link?token=lt_test_token');
+ expect(output).toContain('ACTIVE');
+ })
+ );
+ }
+ );
});
diff --git a/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts b/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts
index bc11583ec..c7f696dc6 100644
--- a/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts
@@ -71,6 +71,32 @@ describe('CLI: composio tools execute', () => {
);
});
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ stdin: { isTTY: true, data: '' },
+ })
+ )('[Given] composio execute alias [Then] works like composio tools execute', it => {
+ it.scoped('alias expands to tools execute', () =>
+ Effect.gen(function* () {
+ yield* cli([
+ 'execute',
+ 'GMAIL_SEND_EMAIL',
+ '--user-id',
+ 'default',
+ '-d',
+ '{"recipient":"a"}',
+ ]);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = parseLastJson(lines);
+
+ expect(output.successful).toBe(true);
+ expect(output.data.tool_slug).toBe('GMAIL_SEND_EMAIL');
+ expect(output.data.arguments).toEqual({ recipient: 'a' });
+ })
+ );
+ });
+
layer(
TestLive({
baseConfigProvider: testConfigProvider,
diff --git a/ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts b/ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts
index 15507eb7c..d9240361a 100644
--- a/ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/tools/tools.search.cmd.test.ts
@@ -280,4 +280,21 @@ describe('CLI: composio tools search', () => {
})
);
});
+
+ layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
+ '[Given] composio search alias [Then] works like composio tools search',
+ it => {
+ it.scoped('alias expands to tools search', () =>
+ Effect.gen(function* () {
+ yield* cli(['search', 'send']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('GMAIL_SEND_EMAIL');
+ expect(output).toContain('SLACK_SEND_MESSAGE');
+ expect(output).toContain('Found 2 tools');
+ })
+ );
+ }
+ );
});
diff --git a/ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts b/ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts
index f02f4678c..3407c9948 100644
--- a/ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/triggers/triggers.listen.cmd.test.ts
@@ -130,6 +130,27 @@ describe('CLI: composio triggers listen', () => {
);
});
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ realtimeData: {
+ events: [mockV3TriggerEvent],
+ },
+ })
+ )('[Given] composio listen alias [Then] works like composio triggers listen', it => {
+ it.scoped('alias expands to triggers listen', () =>
+ Effect.gen(function* () {
+ yield* cli(['listen', '--max-events', '1']);
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('Listening for realtime trigger events');
+ expect(output).toContain('GMAIL_NEW_GMAIL_MESSAGE');
+ expect(output).toContain('Stopped after receiving 1 matching events');
+ })
+ );
+ });
+
layer(
TestLive({
baseConfigProvider: testConfigProvider,