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

Add experimental feature config support to the CLI (#3126)

## Summary - Adds a persisted CLI user config file for experimental feature flags, artifact directory overrides, and experimental subagent target selection. - Wires config-aware command visibility into root command construction, help text, and validation error handling so experimental commands only appear when enabled. - Updates runtime helpers and session artifact resolution to honor the new CLI config values. - Expands installation workflow checks and adds tests for the new CLI config service. ## Testing - `pnpm test ts/packages/cli/test/src/services/cli-user-config.test.ts` - `pnpm test ts/packages/cli/test/src/commands/$default.cmd.test.ts` - Not run: full repo test suite - Not run: install workflow end-to-end in this environment --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Rahul Tarak committed Apr 7, 2026 at 00:34 UTC 7d2ccf8c480b06aa5dfddb243d418ef9d6f2cacf
15 files changed +565 -134
.github/workflows/cli.test-installation.yml
+20 -26
@@ -316,33 +316,27 @@ jobs:
316 echo "Checking shell configuration updates..."
317
318 if [[ "${{ matrix.shell }}" == "zsh" ]]; then
319 - if grep -q "COMPOSIO_INSTALL_DIR" ~/.zshrc; then
320 - echo "✅ .zshrc updated with COMPOSIO_INSTALL"
321 - else
322 - echo "❌ .zshrc not updated"
323 - exit 1
324 - fi
325 -
326 - if grep -q 'export PATH="\\$COMPOSIO_INSTALL_DIR:\\$PATH"' ~/.zshrc; then
327 - echo "✅ .zshrc updated with PATH"
328 - else
329 - echo "❌ .zshrc PATH not updated"
330 - exit 1
331 - fi
319 + config_file=~/.zshrc
320 else
333 - if grep -q "COMPOSIO_INSTALL_DIR" ~/.bashrc; then
334 - echo "✅ .bashrc updated with COMPOSIO_INSTALL"
335 - else
336 - echo "❌ .bashrc not updated"
337 - exit 1
338 - fi
339 -
340 - if grep -q 'export PATH="\\$COMPOSIO_INSTALL_DIR:\\$PATH"' ~/.bashrc; then
341 - echo "✅ .bashrc updated with PATH"
342 - else
343 - echo "❌ .bashrc PATH not updated"
344 - exit 1
345 - fi
321 + config_file=~/.bashrc
322 + fi
323 +
324 + if grep -q "COMPOSIO_INSTALL_DIR" "$config_file"; then
325 + echo "✅ $config_file updated with COMPOSIO_INSTALL_DIR"
326 + else
327 + echo "❌ $config_file not updated with COMPOSIO_INSTALL_DIR"
328 + echo "=== $config_file contents ==="
329 + cat "$config_file"
330 + exit 1
331 + fi
332 +
333 + if grep -q 'export PATH=.*COMPOSIO_INSTALL_DIR.*PATH' "$config_file"; then
334 + echo "✅ $config_file updated with PATH"
335 + else
336 + echo "❌ $config_file PATH not updated"
337 + echo "=== $config_file contents ==="
338 + cat "$config_file"
339 + exit 1
340 fi
341
342 - name: Test custom install directory
ts/packages/cli/src/cli-main.ts
+42 -22
@@ -5,7 +5,7 @@ import { CliConfig, CommandDescriptor, HelpDoc, Usage, ValidationError } from '@
5 import { FetchHttpClient } from '@effect/platform';
6 import { BunContext, BunRuntime, BunFileSystem } from '@effect/platform-bun';
7 import type { Teardown } from '@effect/platform/Runtime';
8 -import { rootCommand, runWithConfig } from 'src/commands';
8 +import { buildRootCommand, runWithConfig } from 'src/commands';
9 import { matchCommandFromArgv, getCommandHelpText } from 'src/commands/root-help';
10 import * as constants from 'src/constants';
11 import { ComposioCliConfig } from 'src/cli-config';
@@ -19,6 +19,7 @@ import { ComposioToolkitsRepositoryCached } from 'src/services/composio-clients-
19 import { NodeOs } from 'src/services/node-os';
20 import { NodeProcess } from 'src/services/node-process';
21 import { JsPackageManagerDetector } from 'src/services/js-package-manager-detector';
22 +import { ComposioCliUserConfigLive, ComposioCliUserConfig } from 'src/services/cli-user-config';
23 import { ComposioUserContextLive as _ComposioUserContextLive } from 'src/services/user-context';
24 import { UpgradeBinary } from 'src/services/upgrade-binary';
25 import { TerminalUILive } from 'src/services/terminal-ui';
@@ -48,6 +49,11 @@ export const ComposioUserContextLive = Layer.provide(
49 Layer.mergeAll(BunFileSystem.layer, NodeOs.Default)
50 ) satisfies RequiredLayer;
51
52 +export const ComposioCliUserConfigLayer = Layer.provide(
53 + ComposioCliUserConfigLive,
54 + Layer.mergeAll(BunFileSystem.layer, NodeOs.Default)
55 +);
56 +
57 export const ComposioSessionRepositoryLive = Layer.provide(
58 ComposioSessionRepository.Default,
59 Layer.mergeAll(BunFileSystem.layer, NodeOs.Default)
@@ -93,6 +99,7 @@ const layers = Layer.mergeAll(
99 NodeOs.Default,
100 NodeProcess.Default,
101 UpgradeBinaryLive,
102 + ComposioCliUserConfigLayer,
103 ComposioUserContextLive,
104 ComposioSessionRepositoryLive,
105 ComposioClientSingletonLive,
@@ -161,7 +168,7 @@ const collectValueOptionNamesFromUsage = (usage: Usage.Usage, acc: Set<string>)
168 }
169 };
170
164 -const valueOptionNames = (() => {
171 +const collectValueOptionNames = (rootCommand: ReturnType<typeof buildRootCommand>) => {
172 const names = new Set<string>();
173 const visited = new Set<CommandDescriptor.Command<unknown>>();
174 const visit = (command: CommandDescriptor.Command<unknown>) => {
@@ -176,7 +183,7 @@ const valueOptionNames = (() => {
183 };
184 visit(rootCommand.descriptor);
185 return names;
179 -})();
186 +};
187
188 showUpdateNotice();
189 checkForUpdateInBackground();
@@ -194,23 +201,31 @@ runWithArgs.pipe(
201 )
202 ),
203 Effect.catchIf(ValidationError.isValidationError, error => {
197 - const text = HelpDoc.toAnsiText(error.error).trim();
198 - const errorEffect = text.length > 0 ? Console.error(text) : Effect.void;
199 - const flagMatch = text.match(/Received unknown argument: '(-{1,2}[\w-]+)'/);
200 - const tipEffect =
201 - flagMatch && valueOptionNames.has(flagMatch[1])
202 - ? Console.error(`Tip: ${flagMatch[1]} requires a value, e.g. ${flagMatch[1]} "value"`)
203 - : Effect.void;
204 - const cmdName = matchCommandFromArgv(process.argv);
205 - const helpText = cmdName ? getCommandHelpText(cmdName) : undefined;
206 - const helpEffect = helpText ? Console.error(helpText) : Effect.void;
207 - return Effect.all([errorEffect, tipEffect, helpEffect], { discard: true }).pipe(
208 - Effect.tap(() =>
209 - Effect.sync(() => {
210 - process.exitCode = 1;
211 - })
212 - )
213 - );
204 + return Effect.gen(function* () {
205 + const cliUserConfig = yield* ComposioCliUserConfig;
206 + const visibility = {
207 + isExperimentalFeatureEnabled: (feature: string) =>
208 + cliUserConfig.isExperimentalFeatureEnabled(feature),
209 + };
210 + const valueOptionNames = collectValueOptionNames(buildRootCommand(visibility));
211 + const text = HelpDoc.toAnsiText(error.error).trim();
212 + const errorEffect = text.length > 0 ? Console.error(text) : Effect.void;
213 + const flagMatch = text.match(/Received unknown argument: '(-{1,2}[\w-]+)'/);
214 + const tipEffect =
215 + flagMatch && valueOptionNames.has(flagMatch[1])
216 + ? Console.error(`Tip: ${flagMatch[1]} requires a value, e.g. ${flagMatch[1]} "value"`)
217 + : Effect.void;
218 + const cmdName = matchCommandFromArgv(process.argv, visibility);
219 + const helpText = cmdName ? getCommandHelpText(cmdName, visibility) : undefined;
220 + const helpEffect = helpText ? Console.error(helpText) : Effect.void;
221 + return yield* Effect.all([errorEffect, tipEffect, helpEffect], { discard: true }).pipe(
222 + Effect.tap(() =>
223 + Effect.sync(() => {
224 + process.exitCode = 1;
225 + })
226 + )
227 + );
228 + });
229 }),
230 Effect.withSpan('composio-cli', {
231 attributes: {
@@ -238,8 +253,13 @@ runWithArgs.pipe(
253 ).trim();
254 if (message.length > 0) {
255 yield* Console.error(message);
241 - const cmdName = matchCommandFromArgv(process.argv);
242 - const helpText = cmdName ? getCommandHelpText(cmdName) : undefined;
256 + const cliUserConfig = yield* ComposioCliUserConfig;
257 + const visibility = {
258 + isExperimentalFeatureEnabled: (feature: string) =>
259 + cliUserConfig.isExperimentalFeatureEnabled(feature),
260 + };
261 + const cmdName = matchCommandFromArgv(process.argv, visibility);
262 + const helpText = cmdName ? getCommandHelpText(cmdName, visibility) : undefined;
263 if (helpText) {
264 yield* Console.error(helpText);
265 }
ts/packages/cli/src/commands/feature-tags.ts new
+37
@@ -0,0 +1,37 @@
1 +export type CliFeatureTag = string;
2 +
3 +export type TaggedValue<T> = {
4 + readonly value: T;
5 + readonly tags?: ReadonlyArray<CliFeatureTag>;
6 +};
7 +
8 +export type CommandVisibility = {
9 + readonly isExperimentalFeatureEnabled: (feature: string) => boolean;
10 +};
11 +
12 +export const tagged = <T>(value: T, tags?: ReadonlyArray<CliFeatureTag>): TaggedValue<T> => ({
13 + value,
14 + tags,
15 +});
16 +
17 +export const experimental = <T>(feature: string, value: T): TaggedValue<T> => ({
18 + value,
19 + tags: [feature],
20 +});
21 +
22 +export const isTaggedValueVisible = <T>(
23 + entry: TaggedValue<T>,
24 + visibility: CommandVisibility
25 +): boolean => {
26 + if (!entry.tags || entry.tags.length === 0) {
27 + return true;
28 + }
29 +
30 + return entry.tags.every(tag => visibility.isExperimentalFeatureEnabled(tag));
31 +};
32 +
33 +export const visibleValues = <T>(
34 + entries: ReadonlyArray<TaggedValue<T>>,
35 + visibility: CommandVisibility
36 +): Array<T> =>
37 + entries.filter(entry => isTaggedValueVisible(entry, visibility)).map(entry => entry.value);
ts/packages/cli/src/commands/index.ts
+44 -33
@@ -29,6 +29,7 @@ import { rootConnectedAccountsCmd$Link } from './connected-accounts/commands/con
29 import { orgsCmd } from './orgs/orgs.cmd';
30 import { renderCommandHintGraph } from 'src/services/command-hints';
31 import { resetRuntimeDebugFlags, setRuntimeDebugFlags } from 'src/services/runtime-debug-flags';
32 +import { ComposioCliUserConfig } from 'src/services/cli-user-config';
33 import { ComposioUserContext } from 'src/services/user-context';
34 import { TerminalUI } from 'src/services/terminal-ui';
35 import { detectMaster } from 'src/services/master-detector';
@@ -36,30 +37,41 @@ import {
37 formatResolveCommandProjectError,
38 resolveCommandProject,
39 } from 'src/services/command-project';
40 +import {
41 + type CommandVisibility,
42 + experimental,
43 + type TaggedValue,
44 + tagged,
45 + visibleValues,
46 +} from './feature-tags';
47 +
48 +// eslint-disable-next-line @typescript-eslint/no-explicit-any
49 +const ROOT_COMMANDS: ReadonlyArray<TaggedValue<Command.Command<any, any, any, any>>> = [
50 + tagged(versionCmd),
51 + tagged(upgradeCmd),
52 + tagged(whoamiCmd),
53 + tagged(loginCmd),
54 + experimental('listen', listenCmd),
55 + tagged(logoutCmd),
56 + tagged(runCmd),
57 + tagged(proxyCmd),
58 + tagged(artifactsCmd),
59 + tagged(installCmd),
60 + tagged(devCmd),
61 + tagged(rootToolsCmd),
62 + tagged(rootTriggersCmd),
63 + tagged(rootToolsCmd$Search),
64 + tagged(rootConnectedAccountsCmd$Link),
65 + tagged(rootToolsCmd$Execute),
66 + tagged(generateCmd),
67 + tagged(orgsCmd),
68 +];
69
40 -const $cmd = $defaultCmd.pipe(
41 - Command.withSubcommands([
42 - versionCmd,
43 - upgradeCmd,
44 - whoamiCmd,
45 - loginCmd,
46 - listenCmd,
47 - logoutCmd,
48 - runCmd,
49 - proxyCmd,
50 - artifactsCmd,
51 - installCmd,
52 - devCmd,
53 - rootToolsCmd,
54 - rootTriggersCmd,
55 - rootToolsCmd$Search,
56 - rootConnectedAccountsCmd$Link,
57 - rootToolsCmd$Execute,
58 - generateCmd,
59 - orgsCmd,
60 - ])
61 -);
62 -export const rootCommand = $cmd;
70 +export const buildRootCommand = (visibility: CommandVisibility) => {
71 + const subcommands = visibleValues(ROOT_COMMANDS, visibility);
72 + // eslint-disable-next-line @typescript-eslint/no-explicit-any
73 + return $defaultCmd.pipe(Command.withSubcommands(subcommands as any));
74 +};
75
76 const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefined => {
77 const args = argv.slice(2);
@@ -239,8 +251,13 @@ const isDebugWhoIsMyMaster = (argv: ReadonlyArray<string>): boolean => {
251 };
252
253 export const runWithConfig = Effect.gen(function* () {
254 + const cliUserConfig = yield* ComposioCliUserConfig;
255 + const visibility: CommandVisibility = {
256 + isExperimentalFeatureEnabled: feature => cliUserConfig.isExperimentalFeatureEnabled(feature),
257 + };
258 const version = yield* getVersion;
243 - const run = Command.run($cmd, {
259 + const rootCommand = buildRootCommand(visibility);
260 + const run = Command.run(rootCommand, {
261 name: 'composio',
262 executable: 'composio',
263 version,
@@ -251,11 +268,11 @@ export const runWithConfig = Effect.gen(function* () {
268 normalizeListenStreamFlag(normalizeVersionShortFlag(argv))
269 );
270 if (isRootHelp(normalizedArgv)) {
254 - return printRootHelp();
271 + return printRootHelp(visibility);
272 }
256 - const subHelp = matchSubcommandHelp(normalizedArgv);
273 + const subHelp = matchSubcommandHelp(normalizedArgv, visibility);
274 if (subHelp) {
258 - return printSubcommandHelp(subHelp);
275 + return printSubcommandHelp(subHelp, visibility);
276 }
277 const parallelExecute = runParallelToolsExecuteFromArgv(normalizedArgv);
278 if (parallelExecute) {
@@ -316,9 +333,3 @@ export const runWithConfig = Effect.gen(function* () {
333 return run(normalizedArgv);
334 };
335 });
319 -
320 -export const run = Command.run($cmd, {
321 - name: 'composio',
322 - version: constants.APP_VERSION,
323 - executable: 'composio',
324 -});
ts/packages/cli/src/commands/install.cmd.ts
+14 -2
@@ -4,6 +4,7 @@ import { Command, Options } from '@effect/cli';
4 import { FileSystem } from '@effect/platform';
5 import type { PlatformError } from '@effect/platform/Error';
6 import { Array as Arr, Effect } from 'effect';
7 +import { ComposioCliUserConfig } from 'src/services/cli-user-config';
8 import { NodeOs } from 'src/services/node-os';
9 import { TerminalUI } from 'src/services/terminal-ui';
10 import { getCompletionScript } from 'src/effects/shell-completions';
@@ -128,7 +129,11 @@ const tildify = (p: string, homedir: string): string =>
129
130 export const installShellIntegration = (params: {
131 readonly completions: boolean;
131 -}): Effect.Effect<void, PlatformError, TerminalUI | NodeOs | FileSystem.FileSystem> =>
132 +}): Effect.Effect<
133 + void,
134 + PlatformError,
135 + TerminalUI | NodeOs | FileSystem.FileSystem | ComposioCliUserConfig
136 +> =>
137 Effect.gen(function* () {
138 const ui = yield* TerminalUI;
139 const os = yield* NodeOs;
@@ -168,8 +173,15 @@ export const installShellIntegration = (params: {
173 // (index.ts → install.cmd.ts → index.ts).
174 let completionScript: string | undefined;
175 if (params.completions && shell !== 'zsh') {
176 + const cliUserConfig = yield* ComposioCliUserConfig;
177 const mod = yield* Effect.promise(() => import('src/commands'));
172 - const lines = yield* getCompletionScript(mod.rootCommand, shell);
178 + const lines = yield* getCompletionScript(
179 + mod.buildRootCommand({
180 + isExperimentalFeatureEnabled: feature =>
181 + cliUserConfig.isExperimentalFeatureEnabled(feature),
182 + }),
183 + shell
184 + );
185 completionScript = lines.length > 0 ? Arr.join(lines, '\n') : undefined;
186 }
187
ts/packages/cli/src/commands/root-help.ts
+70 -44
@@ -1,5 +1,12 @@
1 import { Console, Effect } from 'effect';
2 import { bold, dim, gray } from 'src/ui/colors';
3 +import {
4 + type CommandVisibility,
5 + experimental,
6 + tagged,
7 + visibleValues,
8 + type TaggedValue,
9 +} from './feature-tags';
10
11 type DetailedCommand = {
12 name: string;
@@ -15,8 +22,8 @@ type CompactCommand = {
22
23 // ── Core workflow commands ──────────────────────────────────────────────
24
18 -const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
19 - {
25 +const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
26 + tagged({
27 name: 'search',
28 description: 'Find tools by use case across all toolkits/apps.',
29 usage: 'search <query...> [--toolkits text] [--limit integer] [--human]',
@@ -29,8 +36,8 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
36 { name: '--limit', description: 'Maximum number of results (1-1000)' },
37 { name: '--human', description: 'Show formatted output instead of default JSON' },
38 ],
32 - },
33 - {
39 + }),
40 + tagged({
41 name: 'execute',
42 description:
43 'Execute a tool. Validates inputs and connections automatically; use it aggressively.',
@@ -54,14 +61,14 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
61 { name: '--dry-run', description: 'Validate and preview the tool call without executing it' },
62 { name: '--get-schema', description: 'Fetch and print the CLI-facing input schema' },
63 ],
57 - },
58 - {
64 + }),
65 + tagged({
66 name: 'link',
67 description: 'Connect your account for a toolkit/app.',
68 usage: 'link [<toolkit>]',
69 options: [{ name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' }],
63 - },
64 - {
70 + }),
71 + tagged({
72 name: 'run',
73 description:
74 'Run inline TS/JS code with shimmed CLI commands; injected execute(), search(), proxy(), experimental_subAgent(), and z (zod).',
@@ -71,8 +78,8 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
78 { name: '-f, --file', description: 'Run a TS/JS file instead of inline code' },
79 { name: '--dry-run', description: 'Preview execute() calls without running remote actions' },
80 ],
74 - },
75 - {
81 + }),
82 + experimental('listen', {
83 name: 'listen',
84 description:
85 'Create a temporary subscription for consumer-project events and persist each payload into the session artifact folder.',
@@ -100,8 +107,8 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
107 'Also print each payload inline as a single-line stream value. Optionally pass a jq-like path such as ".thread.id".',
108 },
109 ],
103 - },
104 - {
110 + }),
111 + tagged({
112 name: 'proxy',
113 description:
114 'curl-like access to any toolkit API through Composio using your connected account.',
@@ -113,49 +120,55 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
120 { name: '-H, --header', description: 'Header in "Name: value" format. Repeat for multiple.' },
121 { name: '-d, --data', description: 'Request body as raw text, JSON, @file, or - for stdin' },
122 ],
116 - },
123 + }),
124 ];
125
126 // ── Developer commands ─────────────────────────────────────────────────
127
121 -const OTHER_COMMANDS: ReadonlyArray<CompactCommand> = [
122 - { name: 'composio tools info <slug>', description: 'Print tool summary and cache its schema' },
123 - { name: 'composio tools list <toolkit>', description: 'List tools available in a toolkit' },
124 - {
128 +const OTHER_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
129 + tagged({
130 + name: 'composio tools info <slug>',
131 + description: 'Print tool summary and cache its schema',
132 + }),
133 + tagged({
134 + name: 'composio tools list <toolkit>',
135 + description: 'List tools available in a toolkit',
136 + }),
137 + tagged({
138 name: 'composio triggers info <slug>',
139 description: 'Print trigger type details and schema summaries',
127 - },
128 - {
140 + }),
141 + tagged({
142 name: 'composio triggers list <toolkit>',
143 description: 'List available trigger types in a toolkit',
131 - },
132 - {
144 + }),
145 + tagged({
146 name: 'composio artifacts cwd',
147 description: 'Print the cwd-scoped session artifact directory',
135 - },
148 + }),
149 ];
150
138 -const DEVELOPER_COMMANDS: ReadonlyArray<CompactCommand> = [
139 - {
151 +const DEVELOPER_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
152 + tagged({
153 name: 'dev',
154 description:
155 'Developer workflows and management: init, logs, projects, toolkits, accounts, and triggers.',
143 - },
144 - {
156 + }),
157 + tagged({
158 name: 'generate',
159 description: 'Generate type stubs for toolkits, tools, and triggers (TypeScript | Python).',
147 - },
160 + }),
161 ];
162
163 // ── Account commands ───────────────────────────────────────────────────
164
152 -const ACCOUNT_COMMANDS: ReadonlyArray<CompactCommand> = [
153 - { name: 'login', description: 'Log in to Composio' },
154 - { name: 'logout', description: 'Log out from Composio' },
155 - { name: 'whoami', description: 'Show current account info' },
156 - { name: 'orgs', description: 'Manage default organization context (list, switch)' },
157 - { name: 'version', description: 'Display CLI version' },
158 - { name: 'upgrade', description: 'Upgrade CLI to the latest version' },
165 +const ACCOUNT_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
166 + tagged({ name: 'login', description: 'Log in to Composio' }),
167 + tagged({ name: 'logout', description: 'Log out from Composio' }),
168 + tagged({ name: 'whoami', description: 'Show current account info' }),
169 + tagged({ name: 'orgs', description: 'Manage default organization context (list, switch)' }),
170 + tagged({ name: 'version', description: 'Display CLI version' }),
171 + tagged({ name: 'upgrade', description: 'Upgrade CLI to the latest version' }),
172 ];
173
174 // ── Render helpers ─────────────────────────────────────────────────────
@@ -990,7 +1003,10 @@ function renderSubcommandHelp(cmd: SubcommandHelp): string {
1003 * Check if argv is `composio <subcommand> --help` for a command we have custom help for.
1004 * Returns the command name if matched, undefined otherwise.
1005 */
993 -export function matchSubcommandHelp(argv: ReadonlyArray<string>): string | undefined {
1006 +export function matchSubcommandHelp(
1007 + argv: ReadonlyArray<string>,
1008 + _visibility: CommandVisibility
1009 +): string | undefined {
1010 const args = argv.slice(2);
1011 if (args.length < 2) return undefined;
1012 const last = args[args.length - 1];
@@ -1005,7 +1021,10 @@ export function matchSubcommandHelp(argv: ReadonlyArray<string>): string | undef
1021 return undefined;
1022 }
1023
1008 -export function printSubcommandHelp(cmd: string): Effect.Effect<void> {
1024 +export function printSubcommandHelp(
1025 + cmd: string,
1026 + _visibility: CommandVisibility
1027 +): Effect.Effect<void> {
1028 const help = SUBCOMMAND_HELP[cmd];
1029 if (!help) return Console.log(`Unknown command: ${cmd}`);
1030 return Console.log(renderSubcommandHelp(help));
@@ -1015,7 +1034,10 @@ export function printSubcommandHelp(cmd: string): Effect.Effect<void> {
1034 * Match the command name from argv without requiring --help at the end.
1035 * Used to print contextual help alongside error messages.
1036 */
1018 -export function matchCommandFromArgv(argv: ReadonlyArray<string>): string | undefined {
1037 +export function matchCommandFromArgv(
1038 + argv: ReadonlyArray<string>,
1039 + _visibility: CommandVisibility
1040 +): string | undefined {
1041 const args = argv.slice(2).filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));
1042 // Try longest match first: "dev toolkits list" → "dev toolkits" → "dev"
1043 for (let len = Math.min(args.length, 3); len > 0; len--) {
@@ -1028,7 +1050,10 @@ export function matchCommandFromArgv(argv: ReadonlyArray<string>): string | unde
1050 /**
1051 * Get rendered help text for a command, or undefined if not found.
1052 */
1031 -export function getCommandHelpText(cmd: string): string | undefined {
1053 +export function getCommandHelpText(
1054 + cmd: string,
1055 + _visibility: CommandVisibility
1056 +): string | undefined {
1057 const help = SUBCOMMAND_HELP[cmd];
1058 if (!help) return undefined;
1059 return renderSubcommandHelp(help);
@@ -1041,7 +1066,7 @@ export function getCommandHelpText(cmd: string): string | undefined {
1066 * Core workflow commands are shown first with full usage/options.
1067 * Housekeeping and developer commands are shown compactly at the bottom.
1068 */
1044 -export function printRootHelp(): Effect.Effect<void> {
1069 +export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void> {
1070 const name = 'composio';
1071
1072 const lines: string[] = [
@@ -1058,11 +1083,11 @@ export function printRootHelp(): Effect.Effect<void> {
1083 ` ${name} <command> [options]`,
1084 '',
1085 bold('CORE COMMANDS'),
1061 - ...renderDetailedCommands(name, CORE_COMMANDS),
1086 + ...renderDetailedCommands(name, visibleValues(CORE_COMMANDS, visibility)),
1087 gray(' Typical flow: search → execute (link and tools when needed)'),
1088 '',
1089 bold('TOOLS'),
1065 - ...renderCompactCommands(OTHER_COMMANDS),
1090 + ...renderCompactCommands(visibleValues(OTHER_COMMANDS, visibility)),
1091 '',
1092 bold('EXAMPLES'),
1093 ` ${dim('# Find tools — supports multiple queries at once')}`,
@@ -1096,15 +1121,16 @@ export function printRootHelp(): Effect.Effect<void> {
1121 ` '`,
1122 '',
1123 bold('DEVELOPER COMMANDS'),
1099 - ...renderCompactCommands(DEVELOPER_COMMANDS),
1124 + ...renderCompactCommands(visibleValues(DEVELOPER_COMMANDS, visibility)),
1125 '',
1126 bold('ACCOUNT'),
1102 - ...renderCompactCommands(ACCOUNT_COMMANDS),
1127 + ...renderCompactCommands(visibleValues(ACCOUNT_COMMANDS, visibility)),
1128 '',
1129 bold('FILES') + dim(' (composio files --help)'),
1130 ` ${bold('~/.composio/')}`,
1131 ` CLI configuration and cache directory. Contains your auth state`,
1107 - ` (user_data.json), cached tool definitions (tools.json, toolkits.json),`,
1132 + ` (user_data.json), runtime settings (config.json), cached tool definitions`,
1133 + ` (tools.json, toolkits.json),`,
1134 ` trigger types, and per-org consumer caches. These caches speed up`,
1135 ` repeated commands — safe to delete, they will be re-fetched on next use.`,
1136 '',
ts/packages/cli/src/constants.ts
+5
@@ -32,6 +32,11 @@ export const DEBUG_OVERRIDE_ENV_CONFIG_KEY_PREFIX = 'DEBUG_OVERRIDE_';
32 */
33 export const USER_CONFIG_FILE_NAME = constants.USER_DATA_FILE_NAME;
34
35 +/**
36 + * Name of the general CLI config file used by the Composio CLI.
37 + */
38 +export const CLI_CONFIG_FILE_NAME = 'config.json';
39 +
40 /**
41 * Name of the directory used to store the Composio CLI config.
42 */
ts/packages/cli/src/models/cli-user-config.ts new
+42
@@ -0,0 +1,42 @@
1 +import { Schema } from 'effect';
2 +import { OptionFromNullishOr } from 'effect/Schema';
3 +import { JSONTransformSchema } from './utils/json-transform-schema';
4 +
5 +export const ExperimentalSubagentTarget = Schema.Literal('auto', 'claude', 'codex');
6 +export type ExperimentalSubagentTarget = Schema.Schema.Type<typeof ExperimentalSubagentTarget>;
7 +
8 +export const ExperimentalFeatures = Schema.Record({
9 + key: Schema.String,
10 + value: Schema.Boolean,
11 +});
12 +export type ExperimentalFeatures = Schema.Schema.Type<typeof ExperimentalFeatures>;
13 +
14 +export const CliUserConfig = Schema.Struct({
15 + experimentalFeatures: Schema.optionalWith(ExperimentalFeatures, {
16 + default: () => ({}),
17 + }).pipe(Schema.fromKey('experimental_features')),
18 + artifactDirectory: Schema.propertySignature(OptionFromNullishOr(Schema.String, null)).pipe(
19 + Schema.fromKey('artifact_directory')
20 + ),
21 + experimentalSubagent: Schema.propertySignature(
22 + OptionFromNullishOr(
23 + Schema.Struct({
24 + target: ExperimentalSubagentTarget,
25 + }),
26 + null
27 + )
28 + ).pipe(Schema.fromKey('experimental_subagent')),
29 +}).annotations({
30 + identifier: 'CliUserConfig',
31 + description: 'Named user configuration storage for the Composio CLI',
32 +});
33 +
34 +export type CliUserConfig = Schema.Schema.Type<typeof CliUserConfig>;
35 +
36 +export const CliUserConfigJSON = JSONTransformSchema(CliUserConfig);
37 +export const cliUserConfigFromJSON = Schema.decode(CliUserConfigJSON, {
38 + propertyOrder: 'original',
39 + onExcessProperty: 'preserve',
40 + exact: false,
41 +});
42 +export const cliUserConfigToJSON = Schema.encode(CliUserConfigJSON);
ts/packages/cli/src/services/cli-session-artifacts.ts
+15
@@ -3,10 +3,25 @@ import os from 'node:os';
3 import path from 'node:path';
4 import { Effect, Option } from 'effect';
5 import { getOrCreateProbablyMyCliSessionIdForCurrentCwd } from 'src/services/consumer-short-term-cache';
6 +import { resolveCliConfigPathSync } from 'src/services/cli-user-config';
7 +
8 +const readConfiguredArtifactDirectory = (): string | undefined => {
9 + try {
10 + const raw = fs.readFileSync(resolveCliConfigPathSync(), 'utf8');
11 + const parsed = JSON.parse(raw) as { artifact_directory?: unknown };
12 + return typeof parsed.artifact_directory === 'string' &&
13 + parsed.artifact_directory.trim().length > 0
14 + ? parsed.artifact_directory.trim()
15 + : undefined;
16 + } catch {
17 + return undefined;
18 + }
19 +};
20
21 export const resolveArtifactsRoot = (): string =>
22 process.env.COMPOSIO_SESSION_DIR?.trim() ||
23 process.env.COMPOSIO_CACHE_DIR?.trim() ||
24 + readConfiguredArtifactDirectory() ||
25 path.join(os.tmpdir(), 'composio');
26
27 const SESSION_HISTORY_FILE = 'session-history.jsonl';
ts/packages/cli/src/services/cli-user-config.ts new
+128
@@ -0,0 +1,128 @@
1 +import { FileSystem } from '@effect/platform';
2 +import type { PlatformError } from '@effect/platform/Error';
3 +import { Context, Effect, Layer, Option } from 'effect';
4 +import type { ParseError } from 'effect/ParseResult';
5 +import os from 'node:os';
6 +import path from 'node:path';
7 +import { setupCacheDir } from 'src/effects/setup-cache-dir';
8 +import { getVersion } from 'src/effects/version';
9 +import {
10 + CliUserConfig,
11 + cliUserConfigFromJSON,
12 + cliUserConfigToJSON,
13 +} from 'src/models/cli-user-config';
14 +import * as constants from 'src/constants';
15 +
16 +export type CliReleaseChannel = 'stable' | 'beta';
17 +
18 +export type CliUserConfigResolved = {
19 + readonly channel: CliReleaseChannel;
20 + readonly experimentalFeatures: Readonly<Record<string, boolean>>;
21 + readonly artifactDirectory: string | undefined;
22 + readonly experimentalSubagentTarget: 'auto' | 'claude' | 'codex';
23 +};
24 +
25 +const detectReleaseChannel = (version: string): CliReleaseChannel =>
26 + /-[0-9A-Za-z.-]+$/.test(version) ? 'beta' : 'stable';
27 +
28 +export const resolveCliConfigDirectorySync = (): string =>
29 + process.env.COMPOSIO_CACHE_DIR?.trim() || path.join(os.homedir(), constants.USER_COMPOSIO_DIR);
30 +
31 +export const resolveCliConfigPathSync = (): string =>
32 + path.join(resolveCliConfigDirectorySync(), constants.CLI_CONFIG_FILE_NAME);
33 +
34 +export class ComposioCliUserConfig extends Context.Tag('ComposioCliUserConfig')<
35 + ComposioCliUserConfig,
36 + {
37 + readonly data: CliUserConfigResolved;
38 + readonly raw: CliUserConfig;
39 + readonly channel: CliReleaseChannel;
40 + readonly isExperimentalFeatureEnabled: (feature: string) => boolean;
41 + readonly update: (
42 + next: Partial<CliUserConfig>
43 + ) => Effect.Effect<void, ParseError | PlatformError, never>;
44 + }
45 +>() {}
46 +
47 +const resolveConfig = (raw: CliUserConfig, channel: CliReleaseChannel): CliUserConfigResolved => ({
48 + channel,
49 + experimentalFeatures: raw.experimentalFeatures,
50 + artifactDirectory: Option.getOrUndefined(raw.artifactDirectory),
51 + experimentalSubagentTarget: Option.match(raw.experimentalSubagent, {
52 + onNone: () => 'auto',
53 + onSome: value => value.target,
54 + }),
55 +});
56 +
57 +export const ComposioCliUserConfigLive = Layer.effect(
58 + ComposioCliUserConfig,
59 + Effect.gen(function* () {
60 + const fs = yield* FileSystem.FileSystem;
61 + const version = yield* getVersion;
62 + const channel = detectReleaseChannel(version);
63 + const configDir = yield* setupCacheDir;
64 + const jsonConfigPath = path.join(configDir, constants.CLI_CONFIG_FILE_NAME);
65 +
66 + let rawConfig = CliUserConfig.make({
67 + experimentalFeatures: {},
68 + artifactDirectory: Option.none(),
69 + experimentalSubagent: Option.none(),
70 + });
71 +
72 + const persist = (next: CliUserConfig) =>
73 + Effect.gen(function* () {
74 + const encoded = yield* cliUserConfigToJSON(next);
75 + yield* fs.writeFileString(jsonConfigPath, encoded);
76 + rawConfig = next;
77 + });
78 +
79 + const update = (
80 + next: Partial<CliUserConfig>
81 + ): Effect.Effect<void, ParseError | PlatformError, never> =>
82 + persist(
83 + CliUserConfig.make({
84 + ...rawConfig,
85 + ...next,
86 + })
87 + );
88 +
89 + const load = Effect.gen(function* () {
90 + const configJson = yield* fs.readFileString(jsonConfigPath, 'utf8');
91 + rawConfig = yield* cliUserConfigFromJSON(configJson);
92 + return rawConfig;
93 + });
94 +
95 + if (yield* fs.exists(jsonConfigPath)) {
96 + yield* load.pipe(
97 + Effect.catchAll(() =>
98 + persist(
99 + CliUserConfig.make({
100 + experimentalFeatures: {},
101 + artifactDirectory: Option.none(),
102 + experimentalSubagent: Option.none(),
103 + })
104 + )
105 + )
106 + );
107 + } else {
108 + yield* persist(rawConfig);
109 + }
110 +
111 + const isExperimentalFeatureEnabled = (feature: string) => {
112 + const configured = resolveConfig(rawConfig, channel).experimentalFeatures[feature];
113 + return configured ?? channel === 'beta';
114 + };
115 +
116 + return ComposioCliUserConfig.of({
117 + get data() {
118 + return resolveConfig(rawConfig, channel);
119 + },
120 + get raw() {
121 + return rawConfig;
122 + },
123 + channel,
124 + isExperimentalFeatureEnabled,
125 + update,
126 + });
127 + })
128 +);
ts/packages/cli/src/services/run-helpers-runtime.ts
+16
@@ -3,6 +3,7 @@ import * as os from 'node:os';
3 import * as path from 'node:path';
4 import process from 'node:process';
5 import { z } from 'zod';
6 +import { resolveCliConfigPathSync } from 'src/services/cli-user-config';
7 import type { MasterKind } from 'src/services/master-detector';
8 import { isAcpInvokeError } from 'src/services/run-subagent-shared';
9 import { invokeAcpSubAgent } from 'src/services/run-subagent-acp';
@@ -490,8 +491,23 @@ export const installRunHelpers = async ({
491 return 'user';
492 };
493
494 + const readConfiguredExperimentalSubagentTarget = (): 'auto' | 'claude' | 'codex' => {
495 + try {
496 + const raw = fs.readFileSync(resolveCliConfigPathSync(), 'utf8');
497 + const parsed = JSON.parse(raw) as {
498 + experimental_subagent?: { target?: unknown };
499 + };
500 + const target = parsed.experimental_subagent?.target;
501 + return target === 'claude' || target === 'codex' || target === 'auto' ? target : 'auto';
502 + } catch {
503 + return 'auto';
504 + }
505 + };
506 +
507 const resolveInvokeAgentTarget = (requestedTarget?: string): 'claude' | 'codex' => {
508 if (requestedTarget === 'claude' || requestedTarget === 'codex') return requestedTarget;
509 + const configuredTarget = readConfiguredExperimentalSubagentTarget();
510 + if (configuredTarget === 'claude' || configuredTarget === 'codex') return configuredTarget;
511 const detected = requestedTarget === 'user' ? 'user' : detectInvokeAgentMaster();
512 if (detected === 'codex' || detected === 'claude') return detected;
513 if (typeof Bun.which === 'function' && Bun.which('codex')) return 'codex';
ts/packages/cli/test/__utils__/cli.ts
+2 -6
@@ -2,9 +2,5 @@ import { Effect } from 'effect';
2 import * as Cli from 'src/commands';
3
4 // Run CLI in test environment
5 -export const cli = (args: ReadonlyArray<string>) =>
6 - Effect.flatMap(Cli.runWithConfig, run => run(['node', '<CMD>', ...args])) satisfies Effect.Effect<
7 - void,
8 - any,
9 - any
10 - >;
5 +export const cli = (args: ReadonlyArray<string>): Effect.Effect<void, unknown, any> =>
6 + Effect.flatMap(Cli.runWithConfig, run => run(['node', '<CMD>', ...args]));
ts/packages/cli/test/__utils__/services/test-layer.ts
+7
@@ -39,6 +39,7 @@ import type { TriggerInstanceItem } from 'src/models/triggers';
39 import type { AuthConfigCreateResponse, LinkCreateResponse } from 'src/services/composio-clients';
40 import type { ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
41 import { ComposioUserContextLive } from 'src/services/user-context';
42 +import { ComposioCliUserConfigLive } from 'src/services/cli-user-config';
43 import { UpgradeBinary } from 'src/services/upgrade-binary';
44 import { NodeOs } from 'src/services/node-os';
45 import { TriggersRealtime } from 'src/services/triggers-realtime';
@@ -798,6 +799,11 @@ export const TestLayer = (input?: TestLiveInput) =>
799 Layer.merge(BunFileSystem.layer, NodeOsTest)
800 );
801
802 + const ComposioCliUserConfigTest = Layer.provideMerge(
803 + ComposioCliUserConfigLive,
804 + Layer.mergeAll(BunFileSystem.layer, NodeOsTest)
805 + );
806 +
807 const UpgradeBinaryTest = Layer.provide(
808 UpgradeBinary.Default,
809 Layer.mergeAll(BunFileSystem.layer, FetchHttpClient.layer)
@@ -1147,6 +1153,7 @@ export const TestLayer = (input?: TestLiveInput) =>
1153 CliConfigLive,
1154 NodeProcessTest,
1155 UpgradeBinaryTest,
1156 + ComposioCliUserConfigTest,
1157 ComposioUserContextTest,
1158 ComposioClientSingletonTest,
1159 ComposioSessionRepositoryTest,
ts/packages/cli/test/src/commands/$default.cmd.test.ts
+3 -1
@@ -59,7 +59,9 @@ describe('CLI: composio', () => {
59 const args = ['--help'];
60 yield* cli(args);
61 const lines = yield* MockConsole.getLines({ stripAnsi: true });
62 - expect(lines.join('\n').trim().length).toBeGreaterThan(0);
62 + const output = lines.join('\n');
63 + expect(output.trim().length).toBeGreaterThan(0);
64 + expect(output).toContain('config.json');
65 })
66 );
67 });
ts/packages/cli/test/src/services/cli-user-config.test.ts new
+120
@@ -0,0 +1,120 @@
1 +import path from 'node:path';
2 +import * as tempy from 'tempy';
3 +import fs from 'node:fs';
4 +import { describe, it } from '@effect/vitest';
5 +import { assertEquals } from '@effect/vitest/utils';
6 +import { FileSystem } from '@effect/platform';
7 +import { BunFileSystem } from '@effect/platform-bun';
8 +import { ConfigProvider, Effect, Layer } from 'effect';
9 +import { extendConfigProvider } from 'src/services/config';
10 +import { defaultNodeOs, NodeOs } from 'src/services/node-os';
11 +import {
12 + ComposioCliUserConfig,
13 + ComposioCliUserConfigLive,
14 + resolveCliConfigPathSync,
15 +} from 'src/services/cli-user-config';
16 +
17 +describe('ComposioCliUserConfig', () => {
18 + const withMapConfigProvider = (map: Map<string, string>) =>
19 + Layer.setConfigProvider(extendConfigProvider(ConfigProvider.fromMap(map)));
20 +
21 + it.scoped('defaults experimental features off in stable releases', () => {
22 + const cwd = tempy.temporaryDirectory();
23 + const map = new Map([['DEBUG_OVERRIDE_VERSION', '1.2.3']]) satisfies Map<string, string>;
24 + const NodeOsTest = Layer.succeed(NodeOs, defaultNodeOs({ homedir: cwd }));
25 + const CliUserConfigTest = Layer.provideMerge(
26 + ComposioCliUserConfigLive,
27 + Layer.mergeAll(BunFileSystem.layer, NodeOsTest, withMapConfigProvider(map))
28 + );
29 +
30 + return Effect.gen(function* () {
31 + const config = yield* ComposioCliUserConfig;
32 + assertEquals(config.channel, 'stable');
33 + assertEquals(config.data.experimentalFeatures.listen, undefined);
34 + assertEquals(config.isExperimentalFeatureEnabled('listen'), false);
35 + assertEquals(config.data.experimentalSubagentTarget, 'auto');
36 + assertEquals(config.data.artifactDirectory, undefined);
37 +
38 + const fs = yield* FileSystem.FileSystem;
39 + assertEquals(yield* fs.exists(path.join(cwd, '.composio', 'config.json')), true);
40 + }).pipe(Effect.provide(CliUserConfigTest));
41 + });
42 +
43 + it.scoped('defaults experimental features on in beta releases', () => {
44 + const cwd = tempy.temporaryDirectory();
45 + const map = new Map([['DEBUG_OVERRIDE_VERSION', '1.2.3-beta.4']]) satisfies Map<string, string>;
46 + const NodeOsTest = Layer.succeed(NodeOs, defaultNodeOs({ homedir: cwd }));
47 + const CliUserConfigTest = Layer.provideMerge(
48 + ComposioCliUserConfigLive,
49 + Layer.mergeAll(BunFileSystem.layer, NodeOsTest, withMapConfigProvider(map))
50 + );
51 +
52 + return Effect.gen(function* () {
53 + const config = yield* ComposioCliUserConfig;
54 + assertEquals(config.channel, 'beta');
55 + assertEquals(config.data.experimentalFeatures.listen, undefined);
56 + assertEquals(config.isExperimentalFeatureEnabled('listen'), true);
57 + assertEquals(config.data.experimentalSubagentTarget, 'auto');
58 + }).pipe(Effect.provide(CliUserConfigTest));
59 + });
60 +
61 + it.scoped('respects explicit persisted cli settings from config.json', () => {
62 + const cwd = tempy.temporaryDirectory();
63 + const map = new Map([['DEBUG_OVERRIDE_VERSION', '1.2.3-beta.4']]) satisfies Map<string, string>;
64 + fs.mkdirSync(path.join(cwd, '.composio'), { recursive: true });
65 + fs.writeFileSync(
66 + path.join(cwd, '.composio', 'config.json'),
67 + JSON.stringify({
68 + experimental_features: {
69 + listen: false,
70 + },
71 + artifact_directory: '/tmp/composio-artifacts',
72 + experimental_subagent: {
73 + target: 'claude',
74 + },
75 + })
76 + );
77 +
78 + const NodeOsTest = Layer.succeed(NodeOs, defaultNodeOs({ homedir: cwd }));
79 + const CliUserConfigTest = Layer.provideMerge(
80 + ComposioCliUserConfigLive,
81 + Layer.mergeAll(BunFileSystem.layer, NodeOsTest, withMapConfigProvider(map))
82 + );
83 +
84 + return Effect.gen(function* () {
85 + const fileSystem = yield* FileSystem.FileSystem;
86 + const config = yield* ComposioCliUserConfig;
87 + assertEquals(config.data.experimentalFeatures.listen, false);
88 + assertEquals(config.isExperimentalFeatureEnabled('listen'), false);
89 + assertEquals(config.data.artifactDirectory, '/tmp/composio-artifacts');
90 + assertEquals(config.data.experimentalSubagentTarget, 'claude');
91 +
92 + const persisted = yield* fileSystem.readFileString(
93 + path.join(cwd, '.composio', 'config.json'),
94 + 'utf8'
95 + );
96 + const parsed = JSON.parse(persisted) as {
97 + experimental_features: { listen: boolean };
98 + artifact_directory: string;
99 + experimental_subagent: { target: string };
100 + };
101 +
102 + assertEquals(parsed.experimental_features.listen, false);
103 + assertEquals(parsed.artifact_directory, '/tmp/composio-artifacts');
104 + assertEquals(parsed.experimental_subagent.target, 'claude');
105 + }).pipe(Effect.provide(CliUserConfigTest));
106 + });
107 +
108 + it.effect('resolves sync config path from COMPOSIO_CACHE_DIR when provided', () => {
109 + const cacheDir = tempy.temporaryDirectory();
110 + process.env.COMPOSIO_CACHE_DIR = cacheDir;
111 +
112 + return Effect.sync(() => {
113 + try {
114 + assertEquals(resolveCliConfigPathSync(), path.join(cacheDir, 'config.json'));
115 + } finally {
116 + delete process.env.COMPOSIO_CACHE_DIR;
117 + }
118 + });
119 + });
120 +});