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>

Author: CryogenicPlanet

.github/workflows/cli.test-installation.yml

@@ -316,33 +316,27 @@ jobs:
           echo "Checking shell configuration updates..."
 
           if [[ "${{ matrix.shell }}" == "zsh" ]]; then
-            if grep -q "COMPOSIO_INSTALL_DIR" ~/.zshrc; then
-              echo "✅ .zshrc updated with COMPOSIO_INSTALL"
-            else
-              echo "❌ .zshrc not updated"
-              exit 1
-            fi
-            
-            if grep -q 'export PATH="\\$COMPOSIO_INSTALL_DIR:\\$PATH"' ~/.zshrc; then
-              echo "✅ .zshrc updated with PATH"
-            else
-              echo "❌ .zshrc PATH not updated"
-              exit 1
-            fi
+            config_file=~/.zshrc
           else
-            if grep -q "COMPOSIO_INSTALL_DIR" ~/.bashrc; then
-              echo "✅ .bashrc updated with COMPOSIO_INSTALL"
-            else
-              echo "❌ .bashrc not updated"
-              exit 1
-            fi
-            
-            if grep -q 'export PATH="\\$COMPOSIO_INSTALL_DIR:\\$PATH"' ~/.bashrc; then
-              echo "✅ .bashrc updated with PATH"
-            else
-              echo "❌ .bashrc PATH not updated"
-              exit 1
-            fi
+            config_file=~/.bashrc
+          fi
+
+          if grep -q "COMPOSIO_INSTALL_DIR" "$config_file"; then
+            echo "✅ $config_file updated with COMPOSIO_INSTALL_DIR"
+          else
+            echo "❌ $config_file not updated with COMPOSIO_INSTALL_DIR"
+            echo "=== $config_file contents ==="
+            cat "$config_file"
+            exit 1
+          fi
+
+          if grep -q 'export PATH=.*COMPOSIO_INSTALL_DIR.*PATH' "$config_file"; then
+            echo "✅ $config_file updated with PATH"
+          else
+            echo "❌ $config_file PATH not updated"
+            echo "=== $config_file contents ==="
+            cat "$config_file"
+            exit 1
           fi
 
       - name: Test custom install directory

ts/packages/cli/src/cli-main.ts

@@ -5,7 +5,7 @@ import { CliConfig, CommandDescriptor, HelpDoc, Usage, ValidationError } from '@
 import { FetchHttpClient } from '@effect/platform';
 import { BunContext, BunRuntime, BunFileSystem } from '@effect/platform-bun';
 import type { Teardown } from '@effect/platform/Runtime';
-import { rootCommand, runWithConfig } from 'src/commands';
+import { buildRootCommand, runWithConfig } from 'src/commands';
 import { matchCommandFromArgv, getCommandHelpText } from 'src/commands/root-help';
 import * as constants from 'src/constants';
 import { ComposioCliConfig } from 'src/cli-config';
@@ -19,6 +19,7 @@ import { ComposioToolkitsRepositoryCached } from 'src/services/composio-clients-
 import { NodeOs } from 'src/services/node-os';
 import { NodeProcess } from 'src/services/node-process';
 import { JsPackageManagerDetector } from 'src/services/js-package-manager-detector';
+import { ComposioCliUserConfigLive, ComposioCliUserConfig } from 'src/services/cli-user-config';
 import { ComposioUserContextLive as _ComposioUserContextLive } from 'src/services/user-context';
 import { UpgradeBinary } from 'src/services/upgrade-binary';
 import { TerminalUILive } from 'src/services/terminal-ui';
@@ -48,6 +49,11 @@ export const ComposioUserContextLive = Layer.provide(
   Layer.mergeAll(BunFileSystem.layer, NodeOs.Default)
 ) satisfies RequiredLayer;
 
+export const ComposioCliUserConfigLayer = Layer.provide(
+  ComposioCliUserConfigLive,
+  Layer.mergeAll(BunFileSystem.layer, NodeOs.Default)
+);
+
 export const ComposioSessionRepositoryLive = Layer.provide(
   ComposioSessionRepository.Default,
   Layer.mergeAll(BunFileSystem.layer, NodeOs.Default)
@@ -93,6 +99,7 @@ const layers = Layer.mergeAll(
   NodeOs.Default,
   NodeProcess.Default,
   UpgradeBinaryLive,
+  ComposioCliUserConfigLayer,
   ComposioUserContextLive,
   ComposioSessionRepositoryLive,
   ComposioClientSingletonLive,
@@ -161,7 +168,7 @@ const collectValueOptionNamesFromUsage = (usage: Usage.Usage, acc: Set<string>)
   }
 };
 
-const valueOptionNames = (() => {
+const collectValueOptionNames = (rootCommand: ReturnType<typeof buildRootCommand>) => {
   const names = new Set<string>();
   const visited = new Set<CommandDescriptor.Command<unknown>>();
   const visit = (command: CommandDescriptor.Command<unknown>) => {
@@ -176,7 +183,7 @@ const valueOptionNames = (() => {
   };
   visit(rootCommand.descriptor);
   return names;
-})();
+};
 
 showUpdateNotice();
 checkForUpdateInBackground();
@@ -194,23 +201,31 @@ runWithArgs.pipe(
     )
   ),
   Effect.catchIf(ValidationError.isValidationError, error => {
-    const text = HelpDoc.toAnsiText(error.error).trim();
-    const errorEffect = text.length > 0 ? Console.error(text) : Effect.void;
-    const flagMatch = text.match(/Received unknown argument: '(-{1,2}[\w-]+)'/);
-    const tipEffect =
-      flagMatch && valueOptionNames.has(flagMatch[1])
-        ? Console.error(`Tip: ${flagMatch[1]} requires a value, e.g. ${flagMatch[1]} "value"`)
-        : Effect.void;
-    const cmdName = matchCommandFromArgv(process.argv);
-    const helpText = cmdName ? getCommandHelpText(cmdName) : undefined;
-    const helpEffect = helpText ? Console.error(helpText) : Effect.void;
-    return Effect.all([errorEffect, tipEffect, helpEffect], { discard: true }).pipe(
-      Effect.tap(() =>
-        Effect.sync(() => {
-          process.exitCode = 1;
-        })
-      )
-    );
+    return Effect.gen(function* () {
+      const cliUserConfig = yield* ComposioCliUserConfig;
+      const visibility = {
+        isExperimentalFeatureEnabled: (feature: string) =>
+          cliUserConfig.isExperimentalFeatureEnabled(feature),
+      };
+      const valueOptionNames = collectValueOptionNames(buildRootCommand(visibility));
+      const text = HelpDoc.toAnsiText(error.error).trim();
+      const errorEffect = text.length > 0 ? Console.error(text) : Effect.void;
+      const flagMatch = text.match(/Received unknown argument: '(-{1,2}[\w-]+)'/);
+      const tipEffect =
+        flagMatch && valueOptionNames.has(flagMatch[1])
+          ? Console.error(`Tip: ${flagMatch[1]} requires a value, e.g. ${flagMatch[1]} "value"`)
+          : Effect.void;
+      const cmdName = matchCommandFromArgv(process.argv, visibility);
+      const helpText = cmdName ? getCommandHelpText(cmdName, visibility) : undefined;
+      const helpEffect = helpText ? Console.error(helpText) : Effect.void;
+      return yield* Effect.all([errorEffect, tipEffect, helpEffect], { discard: true }).pipe(
+        Effect.tap(() =>
+          Effect.sync(() => {
+            process.exitCode = 1;
+          })
+        )
+      );
+    });
   }),
   Effect.withSpan('composio-cli', {
     attributes: {
@@ -238,8 +253,13 @@ runWithArgs.pipe(
         ).trim();
         if (message.length > 0) {
           yield* Console.error(message);
-          const cmdName = matchCommandFromArgv(process.argv);
-          const helpText = cmdName ? getCommandHelpText(cmdName) : undefined;
+          const cliUserConfig = yield* ComposioCliUserConfig;
+          const visibility = {
+            isExperimentalFeatureEnabled: (feature: string) =>
+              cliUserConfig.isExperimentalFeatureEnabled(feature),
+          };
+          const cmdName = matchCommandFromArgv(process.argv, visibility);
+          const helpText = cmdName ? getCommandHelpText(cmdName, visibility) : undefined;
           if (helpText) {
             yield* Console.error(helpText);
           }

ts/packages/cli/src/commands/feature-tags.ts

@@ -0,0 +1,37 @@
+export type CliFeatureTag = string;
+
+export type TaggedValue<T> = {
+  readonly value: T;
+  readonly tags?: ReadonlyArray<CliFeatureTag>;
+};
+
+export type CommandVisibility = {
+  readonly isExperimentalFeatureEnabled: (feature: string) => boolean;
+};
+
+export const tagged = <T>(value: T, tags?: ReadonlyArray<CliFeatureTag>): TaggedValue<T> => ({
+  value,
+  tags,
+});
+
+export const experimental = <T>(feature: string, value: T): TaggedValue<T> => ({
+  value,
+  tags: [feature],
+});
+
+export const isTaggedValueVisible = <T>(
+  entry: TaggedValue<T>,
+  visibility: CommandVisibility
+): boolean => {
+  if (!entry.tags || entry.tags.length === 0) {
+    return true;
+  }
+
+  return entry.tags.every(tag => visibility.isExperimentalFeatureEnabled(tag));
+};
+
+export const visibleValues = <T>(
+  entries: ReadonlyArray<TaggedValue<T>>,
+  visibility: CommandVisibility
+): Array<T> =>
+  entries.filter(entry => isTaggedValueVisible(entry, visibility)).map(entry => entry.value);

ts/packages/cli/src/commands/index.ts

@@ -29,37 +29,49 @@ import { rootConnectedAccountsCmd$Link } from './connected-accounts/commands/con
 import { orgsCmd } from './orgs/orgs.cmd';
 import { renderCommandHintGraph } from 'src/services/command-hints';
 import { resetRuntimeDebugFlags, setRuntimeDebugFlags } from 'src/services/runtime-debug-flags';
+import { ComposioCliUserConfig } from 'src/services/cli-user-config';
 import { ComposioUserContext } from 'src/services/user-context';
 import { TerminalUI } from 'src/services/terminal-ui';
 import { detectMaster } from 'src/services/master-detector';
 import {
   formatResolveCommandProjectError,
   resolveCommandProject,
 } from 'src/services/command-project';
+import {
+  type CommandVisibility,
+  experimental,
+  type TaggedValue,
+  tagged,
+  visibleValues,
+} from './feature-tags';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ROOT_COMMANDS: ReadonlyArray<TaggedValue<Command.Command<any, any, any, any>>> = [
+  tagged(versionCmd),
+  tagged(upgradeCmd),
+  tagged(whoamiCmd),
+  tagged(loginCmd),
+  experimental('listen', listenCmd),
+  tagged(logoutCmd),
+  tagged(runCmd),
+  tagged(proxyCmd),
+  tagged(artifactsCmd),
+  tagged(installCmd),
+  tagged(devCmd),
+  tagged(rootToolsCmd),
+  tagged(rootTriggersCmd),
+  tagged(rootToolsCmd$Search),
+  tagged(rootConnectedAccountsCmd$Link),
+  tagged(rootToolsCmd$Execute),
+  tagged(generateCmd),
+  tagged(orgsCmd),
+];
 
-const $cmd = $defaultCmd.pipe(
-  Command.withSubcommands([
-    versionCmd,
-    upgradeCmd,
-    whoamiCmd,
-    loginCmd,
-    listenCmd,
-    logoutCmd,
-    runCmd,
-    proxyCmd,
-    artifactsCmd,
-    installCmd,
-    devCmd,
-    rootToolsCmd,
-    rootTriggersCmd,
-    rootToolsCmd$Search,
-    rootConnectedAccountsCmd$Link,
-    rootToolsCmd$Execute,
-    generateCmd,
-    orgsCmd,
-  ])
-);
-export const rootCommand = $cmd;
+export const buildRootCommand = (visibility: CommandVisibility) => {
+  const subcommands = visibleValues(ROOT_COMMANDS, visibility);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return $defaultCmd.pipe(Command.withSubcommands(subcommands as any));
+};
 
 const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefined => {
   const args = argv.slice(2);
@@ -239,8 +251,13 @@ const isDebugWhoIsMyMaster = (argv: ReadonlyArray<string>): boolean => {
 };
 
 export const runWithConfig = Effect.gen(function* () {
+  const cliUserConfig = yield* ComposioCliUserConfig;
+  const visibility: CommandVisibility = {
+    isExperimentalFeatureEnabled: feature => cliUserConfig.isExperimentalFeatureEnabled(feature),
+  };
   const version = yield* getVersion;
-  const run = Command.run($cmd, {
+  const rootCommand = buildRootCommand(visibility);
+  const run = Command.run(rootCommand, {
     name: 'composio',
     executable: 'composio',
     version,
@@ -251,11 +268,11 @@ export const runWithConfig = Effect.gen(function* () {
       normalizeListenStreamFlag(normalizeVersionShortFlag(argv))
     );
     if (isRootHelp(normalizedArgv)) {
-      return printRootHelp();
+      return printRootHelp(visibility);
     }
-    const subHelp = matchSubcommandHelp(normalizedArgv);
+    const subHelp = matchSubcommandHelp(normalizedArgv, visibility);
     if (subHelp) {
-      return printSubcommandHelp(subHelp);
+      return printSubcommandHelp(subHelp, visibility);
     }
     const parallelExecute = runParallelToolsExecuteFromArgv(normalizedArgv);
     if (parallelExecute) {
@@ -316,9 +333,3 @@ export const runWithConfig = Effect.gen(function* () {
     return run(normalizedArgv);
   };
 });
-
-export const run = Command.run($cmd, {
-  name: 'composio',
-  version: constants.APP_VERSION,
-  executable: 'composio',
-});

ts/packages/cli/src/commands/install.cmd.ts

@@ -4,6 +4,7 @@ import { Command, Options } from '@effect/cli';
 import { FileSystem } from '@effect/platform';
 import type { PlatformError } from '@effect/platform/Error';
 import { Array as Arr, Effect } from 'effect';
+import { ComposioCliUserConfig } from 'src/services/cli-user-config';
 import { NodeOs } from 'src/services/node-os';
 import { TerminalUI } from 'src/services/terminal-ui';
 import { getCompletionScript } from 'src/effects/shell-completions';
@@ -128,7 +129,11 @@ const tildify = (p: string, homedir: string): string =>
 
 export const installShellIntegration = (params: {
   readonly completions: boolean;
-}): Effect.Effect<void, PlatformError, TerminalUI | NodeOs | FileSystem.FileSystem> =>
+}): Effect.Effect<
+  void,
+  PlatformError,
+  TerminalUI | NodeOs | FileSystem.FileSystem | ComposioCliUserConfig
+> =>
   Effect.gen(function* () {
     const ui = yield* TerminalUI;
     const os = yield* NodeOs;
@@ -168,8 +173,15 @@ export const installShellIntegration = (params: {
     // (index.ts → install.cmd.ts → index.ts).
     let completionScript: string | undefined;
     if (params.completions && shell !== 'zsh') {
+      const cliUserConfig = yield* ComposioCliUserConfig;
       const mod = yield* Effect.promise(() => import('src/commands'));
-      const lines = yield* getCompletionScript(mod.rootCommand, shell);
+      const lines = yield* getCompletionScript(
+        mod.buildRootCommand({
+          isExperimentalFeatureEnabled: feature =>
+            cliUserConfig.isExperimentalFeatureEnabled(feature),
+        }),
+        shell
+      );
       completionScript = lines.length > 0 ? Arr.join(lines, '\n') : undefined;
     }