Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdnew file mode 100644index 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 commandsdiff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.tsindex 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<sreturn 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.tsindex 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.snapindex 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 executeUSAGEcomposio <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 COMMANDSgenerate 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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,