@devries-cameron20 / composio Mirror · read-only / commits / 9d2cd9dce
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 13:30 UTC

fix(cli): curated help for every command family and a help command

Audit finding: the curated `--help` pages (USAGE/DESCRIPTION/SEE ALSO via root-help.ts's SUBCOMMAND_HELP registry) silently missed whole command families. `composio orgs --help`, `signup --help`, and the group pages for `connections`, `triggers`, `tools`, `artifacts`, `install`, and `agent` fell through to the framework's raw parser rendering — unstyled headers, a different section layout, and the root-level `--log-level` flag exposed on subcommand pages. - Add the missing SUBCOMMAND_HELP entries; orgs pages also gain options/examples matching their actual flags. - Add `composio help [command] [level]`: the framework has no builtin help command, so `composio help orgs` now routes to the same curated page as `composio orgs --help` (bare `composio help` keeps printing the root help). - Fix the stale orgs description in the contextual-error help registry (said 'Manage current organization context'; the command manages the default global org/project context). - Lock the class shut: a consistency test walks every visible root command and fails when any lacks a curated help entry. It caught signup and agent during development. Validation: typecheck + full suite (1330 passed, incl. 6 new tests), oxlint/prettier clean, binary rebuilt and smoke-tested — orgs/signup/ connections/triggers/tools/artifacts/install help pages, help command paths, and whoami against staging all behave.

jkomyno committed Sep 10, 2026 at 17:47 UTC 9d2cd9dce8ca1d30e8d6f550ab5c1caf1ecad84d
4 files changed +172 -2
ts/packages/cli/CHANGELOG.md
+7
@@ -41,6 +41,13 @@
41 `https://staging-dashboard.composio.dev/`.
42 - `composio dev auth-configs create` now sends custom OAuth credentials and scopes
43 in the API's expected shape instead of failing validation.
44 +- `composio orgs --help`, `composio signup --help`, and the group help pages for
45 + `connections`, `triggers`, `tools`, `artifacts`, and `install` now render the same
46 + curated, styled help page as every other command family, instead of falling back to
47 + the framework's raw flag dump. `composio help <command>` is now a supported spelling
48 + of command help (`composio help orgs` shows the same page as `composio orgs --help`),
49 + and the `orgs` description in contextual error help matches the command's actual
50 + description.
51
52 ## 0.3.3
53
ts/packages/cli/src/commands/index.ts
+12
@@ -563,6 +563,18 @@ export const runWithConfig = Effect.gen(function* () {
563 if (isRootHelp(normalizedArgv)) {
564 return printRootHelp(visibility, parseHelpLevel(normalizedArgv[3]) ?? 'default');
565 }
566 + // `composio help [command] [level]` — the framework has no builtin help command, so
567 + // route it through the same curated pages as `composio <command> --help`.
568 + if (args[0] === 'help') {
569 + const rest = args.slice(1);
570 + const last = rest[rest.length - 1];
571 + const helpLevel = parseHelpLevel(last) ?? 'default';
572 + const cmdParts = parseHelpLevel(last) !== undefined ? rest.slice(0, -1) : rest;
573 + if (cmdParts.length === 0) {
574 + return printRootHelp(visibility, helpLevel);
575 + }
576 + return printSubcommandHelp(cmdParts.join(' '), visibility, helpLevel);
577 + }
578 const subHelp = matchSubcommandHelp(normalizedArgv, visibility);
579 if (subHelp) {
580 const helpLevel = parseHelpLevel(normalizedArgv[normalizedArgv.length - 1]) ?? 'default';
ts/packages/cli/src/commands/root-help.ts
+82 -2
@@ -179,7 +179,7 @@ const ACCOUNT_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
179 tagged({ name: 'login', description: 'Log in to Composio' }),
180 tagged({ name: 'logout', description: 'Log out from Composio' }),
181 tagged({ name: 'whoami', description: 'Show current account info' }),
182 - tagged({ name: 'orgs', description: 'Manage current organization context (list, switch)' }),
182 + tagged({ name: 'orgs', description: 'Manage default global organization/project context.' }),
183 tagged({ name: 'version', description: 'Display CLI version' }),
184 tagged({ name: 'upgrade', description: 'Upgrade CLI to the latest version' }),
185 tagged({ name: 'config', description: 'View and manage CLI configuration' }),
@@ -587,6 +587,11 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
587 'composio connections list --toolkit <toolkit> List account selectors',
588 ],
589 },
590 + connections: {
591 + usage: 'composio connections <subcommand>',
592 + description: 'View and manage Composio connected accounts.',
593 + seeAlso: ['composio connections list', 'composio connections remove'],
594 + },
595 'connections list': {
596 usage: 'composio connections list [--toolkit <text>]',
597 description:
@@ -858,6 +863,35 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
863
864 // ── Account commands ──────────────────────────────────────────────────
865
866 + agent: {
867 + usage: 'composio agent <subcommand>',
868 + description: 'Manage Composio agent identity, inbox, and handoff.',
869 + seeAlso: [
870 + 'composio agent signup',
871 + 'composio agent login',
872 + 'composio agent whoami',
873 + 'composio agent inbox',
874 + 'composio agent claim',
875 + ],
876 + },
877 + signup: {
878 + usage: 'composio signup [-f, --force] [--no-wait] [--no-login]',
879 + description: 'Sign up and optionally log in as a Composio agent.',
880 + options: [
881 + {
882 + name: '-f, --force',
883 + description: 'Create a new agent identity even if ~/.composio/agent.json already exists',
884 + },
885 + {
886 + name: '--no-wait',
887 + description: 'Start agent signup and exit without waiting for credentials',
888 + },
889 + {
890 + name: '--no-login',
891 + description: 'Create or verify the agent identity without logging the CLI in',
892 + },
893 + ],
894 + },
895 login: {
896 usage:
897 'composio login [--no-browser] [--poll] [--no-wait] [--key text] [--user-api-key text] [--org text] [-y, --yes] [--no-skill-install]',
@@ -899,6 +933,32 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
933 usage: 'composio whoami',
934 description: 'Display your account information.',
935 },
936 + orgs: {
937 + usage: 'composio orgs <subcommand>',
938 + description: 'Manage default global organization/project context.',
939 + seeAlso: ['composio orgs list', 'composio orgs switch'],
940 + },
941 + 'orgs list': {
942 + usage: 'composio orgs list [--limit integer]',
943 + description: 'List organizations and show current global selection.',
944 + options: [
945 + {
946 + name: '--limit <integer>',
947 + description: 'Max organizations to fetch from API (default: 50)',
948 + },
949 + ],
950 + },
951 + 'orgs switch': {
952 + usage: 'composio orgs switch [--org-id text] [--limit integer]',
953 + description: 'Switch current organization context.',
954 + options: [
955 + { name: '--org-id <text>', description: 'Organization ID to use as global default' },
956 + {
957 + name: '--limit <integer>',
958 + description: 'Max orgs to fetch from API (default: 50)',
959 + },
960 + ],
961 + },
962 setup: {
963 usage: 'composio setup [--target auto|claude|codex|all] [--uninstall] [--yes] [--if-present]',
964 description: 'Install or uninstall plugins for supported agent hosts.',
@@ -963,7 +1023,22 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
1023 ],
1024 },
1025
966 - // ── Tools commands ────────────────────────────────────────────────────
1026 + artifacts: {
1027 + usage: 'composio artifacts <subcommand>',
1028 + description: 'Inspect session artifact directories.',
1029 + seeAlso: ['composio artifacts cwd'],
1030 + },
1031 + 'artifacts cwd': {
1032 + usage: 'composio artifacts cwd',
1033 + description: 'Print the cwd-scoped session artifact directory.',
1034 + },
1035 + install: {
1036 + usage: 'composio install [--completions] [--no-completions] [--shell text]',
1037 + description:
1038 + 'Set up shell integration (PATH and completions). Set COMPOSIO_BIN_DIR to choose the directory added to PATH; it otherwise defaults to ~/.local/bin when that holds this executable, and to the directory of the running binary.',
1039 + },
1040 +
1041 + // ── Tools commands ──────────────────────────────────────────────────────
1042
1043 tools: {
1044 usage: 'composio tools <command>',
@@ -990,6 +1065,11 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
1065 'View a brief summary of a tool and show the CLI-facing schema used by `composio execute --get-schema`.',
1066 args: [{ name: '<slug>', description: 'Tool slug (e.g. "GMAIL_SEND_EMAIL")' }],
1067 },
1068 + triggers: {
1069 + usage: 'composio triggers <subcommand>',
1070 + description: 'Inspect and subscribe to trigger events.',
1071 + seeAlso: ['composio triggers list', 'composio triggers info'],
1072 + },
1073 'triggers list': {
1074 usage: 'composio triggers list <toolkit> [--limit integer]',
1075 description: 'List available trigger types for a toolkit.',
ts/packages/cli/test/src/commands/root-help-consistency.test.ts new
+71
@@ -0,0 +1,71 @@
1 +import { layer } from '@effect/vitest';
2 +import { Effect } from 'effect';
3 +import { describe, expect, it } from 'vitest';
4 +import { buildRootCommand } from 'src/commands';
5 +import {
6 + getCommandHelpText,
7 + matchSubcommandHelp,
8 + printSubcommandHelp,
9 +} from 'src/commands/root-help';
10 +import { MockConsole, TestLive } from 'test/__utils__';
11 +
12 +const stableVisibility = {
13 + isDevModeEnabled: true,
14 + isExperimentalFeatureEnabled: () => false,
15 +};
16 +
17 +const getVisibleRootCommandNames = () =>
18 + buildRootCommand(stableVisibility).subcommands.flatMap(group =>
19 + group.commands.map(cmd => cmd.name)
20 + );
21 +
22 +describe('subcommand help registry consistency', () => {
23 + it('has a curated help entry for every visible root command', () => {
24 + for (const name of getVisibleRootCommandNames()) {
25 + const matched = matchSubcommandHelp(['bun', 'composio', name, '--help'], stableVisibility);
26 + expect(matched, `missing curated help for \`composio ${name}\``).toBe(name);
27 + }
28 + });
29 +
30 + it('matches every orgs family invocation', () => {
31 + expect(matchSubcommandHelp(['bun', 'composio', 'orgs', '--help'], stableVisibility)).toBe(
32 + 'orgs'
33 + );
34 + expect(
35 + matchSubcommandHelp(['bun', 'composio', 'orgs', 'list', '--help'], stableVisibility)
36 + ).toBe('orgs list');
37 + expect(
38 + matchSubcommandHelp(['bun', 'composio', 'orgs', 'switch', '--help'], stableVisibility)
39 + ).toBe('orgs switch');
40 + expect(
41 + matchSubcommandHelp(['bun', 'composio', 'orgs', '--help', 'full'], stableVisibility)
42 + ).toBe('orgs');
43 + });
44 +
45 + it('renders the curated orgs page', () =>
46 + Effect.gen(function* () {
47 + yield* printSubcommandHelp('orgs', stableVisibility);
48 + const output = (yield* MockConsole.getLines({ stripAnsi: true })).join('\n');
49 +
50 + expect(output).toContain('USAGE');
51 + expect(output).toContain('composio orgs <subcommand>');
52 + expect(output).toContain('SEE ALSO');
53 + expect(output).toContain('composio orgs list');
54 + expect(output).toContain('composio orgs switch');
55 + }));
56 +
57 + it('renders curated pages for formerly raw-fallback groups', () =>
58 + Effect.gen(function* () {
59 + for (const cmd of ['connections', 'triggers', 'tools', 'artifacts', 'install']) {
60 + yield* printSubcommandHelp(cmd, stableVisibility);
61 + const output = (yield* MockConsole.getLines({ stripAnsi: true })).join('\n');
62 + expect(output, `\`composio ${cmd}\` help page`).toContain('USAGE');
63 + }
64 + }));
65 +
66 + it('uses the current orgs description in contextual help', () => {
67 + expect(getCommandHelpText('orgs', stableVisibility)).toContain(
68 + 'Manage default global organization/project context.'
69 + );
70 + });
71 +});