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.

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

Rahul Tarak7d2ccf8c480b
diff --git a/.github/workflows/cli.test-installation.yml b/.github/workflows/cli.test-installation.yml
index 4fbfa023d..f45ede0f0 100644
--- a/.github/workflows/cli.test-installation.yml
+++ b/.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
diff --git a/ts/packages/cli/src/cli-main.ts b/ts/packages/cli/src/cli-main.ts
index 92ef413ef..73de4725a 100644
--- a/ts/packages/cli/src/cli-main.ts
+++ b/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);
}
diff --git a/ts/packages/cli/src/commands/feature-tags.ts b/ts/packages/cli/src/commands/feature-tags.ts
new file mode 100644
index 000000000..7415507b7
--- /dev/null
+++ b/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);
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index 28ffcf3ed..b6960e665 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -29,6 +29,7 @@ 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';
@@ -36,30 +37,41 @@ 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',
-});
diff --git a/ts/packages/cli/src/commands/install.cmd.ts b/ts/packages/cli/src/commands/install.cmd.ts
index 424ed8072..4fa4a122a 100644
--- a/ts/packages/cli/src/commands/install.cmd.ts
+++ b/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;
}
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
index f9f95fb89..74523622e 100644
--- a/ts/packages/cli/src/commands/root-help.ts
+++ b/ts/packages/cli/src/commands/root-help.ts
@@ -1,5 +1,12 @@
import { Console, Effect } from 'effect';
import { bold, dim, gray } from 'src/ui/colors';
+import {
+ type CommandVisibility,
+ experimental,
+ tagged,
+ visibleValues,
+ type TaggedValue,
+} from './feature-tags';
type DetailedCommand = {
name: string;
@@ -15,8 +22,8 @@ type CompactCommand = {
// ── Core workflow commands ──────────────────────────────────────────────
-const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
- {
+const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
+ tagged({
name: 'search',
description: 'Find tools by use case across all toolkits/apps.',
usage: 'search <query...> [--toolkits text] [--limit integer] [--human]',
@@ -29,8 +36,8 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
{ name: '--limit', description: 'Maximum number of results (1-1000)' },
{ name: '--human', description: 'Show formatted output instead of default JSON' },
],
- },
- {
+ }),
+ tagged({
name: 'execute',
description:
'Execute a tool. Validates inputs and connections automatically; use it aggressively.',
@@ -54,14 +61,14 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
{ name: '--dry-run', description: 'Validate and preview the tool call without executing it' },
{ name: '--get-schema', description: 'Fetch and print the CLI-facing input schema' },
],
- },
- {
+ }),
+ tagged({
name: 'link',
description: 'Connect your account for a toolkit/app.',
usage: 'link [<toolkit>]',
options: [{ name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' }],
- },
- {
+ }),
+ tagged({
name: 'run',
description:
'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> = [
{ name: '-f, --file', description: 'Run a TS/JS file instead of inline code' },
{ name: '--dry-run', description: 'Preview execute() calls without running remote actions' },
],
- },
- {
+ }),
+ experimental('listen', {
name: 'listen',
description:
'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> = [
'Also print each payload inline as a single-line stream value. Optionally pass a jq-like path such as ".thread.id".',
},
],
- },
- {
+ }),
+ tagged({
name: 'proxy',
description:
'curl-like access to any toolkit API through Composio using your connected account.',
@@ -113,49 +120,55 @@ const CORE_COMMANDS: ReadonlyArray<DetailedCommand> = [
{ name: '-H, --header', description: 'Header in "Name: value" format. Repeat for multiple.' },
{ name: '-d, --data', description: 'Request body as raw text, JSON, @file, or - for stdin' },
],
- },
+ }),
];
// ── Developer commands ─────────────────────────────────────────────────
-const OTHER_COMMANDS: ReadonlyArray<CompactCommand> = [
- { name: 'composio tools info <slug>', description: 'Print tool summary and cache its schema' },
- { name: 'composio tools list <toolkit>', description: 'List tools available in a toolkit' },
- {
+const OTHER_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
+ tagged({
+ name: 'composio tools info <slug>',
+ description: 'Print tool summary and cache its schema',
+ }),
+ tagged({
+ name: 'composio tools list <toolkit>',
+ description: 'List tools available in a toolkit',
+ }),
+ tagged({
name: 'composio triggers info <slug>',
description: 'Print trigger type details and schema summaries',
- },
- {
+ }),
+ tagged({
name: 'composio triggers list <toolkit>',
description: 'List available trigger types in a toolkit',
- },
- {
+ }),
+ tagged({
name: 'composio artifacts cwd',
description: 'Print the cwd-scoped session artifact directory',
- },
+ }),
];
-const DEVELOPER_COMMANDS: ReadonlyArray<CompactCommand> = [
- {
+const DEVELOPER_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
+ tagged({
name: 'dev',
description:
'Developer workflows and management: init, logs, projects, toolkits, accounts, and triggers.',
- },
- {
+ }),
+ tagged({
name: 'generate',
description: 'Generate type stubs for toolkits, tools, and triggers (TypeScript | Python).',
- },
+ }),
];
// ── Account commands ───────────────────────────────────────────────────
-const ACCOUNT_COMMANDS: ReadonlyArray<CompactCommand> = [
- { name: 'login', description: 'Log in to Composio' },
- { name: 'logout', description: 'Log out from Composio' },
- { name: 'whoami', description: 'Show current account info' },
- { name: 'orgs', description: 'Manage default organization context (list, switch)' },
- { name: 'version', description: 'Display CLI version' },
- { name: 'upgrade', description: 'Upgrade CLI to the latest version' },
+const ACCOUNT_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
+ tagged({ name: 'login', description: 'Log in to Composio' }),
+ tagged({ name: 'logout', description: 'Log out from Composio' }),
+ tagged({ name: 'whoami', description: 'Show current account info' }),
+ tagged({ name: 'orgs', description: 'Manage default organization context (list, switch)' }),
+ tagged({ name: 'version', description: 'Display CLI version' }),
+ tagged({ name: 'upgrade', description: 'Upgrade CLI to the latest version' }),
];
// ── Render helpers ─────────────────────────────────────────────────────
@@ -990,7 +1003,10 @@ function renderSubcommandHelp(cmd: SubcommandHelp): string {
* Check if argv is `composio <subcommand> --help` for a command we have custom help for.
* Returns the command name if matched, undefined otherwise.
*/
-export function matchSubcommandHelp(argv: ReadonlyArray<string>): string | undefined {
+export function matchSubcommandHelp(
+ argv: ReadonlyArray<string>,
+ _visibility: CommandVisibility
+): string | undefined {
const args = argv.slice(2);
if (args.length < 2) return undefined;
const last = args[args.length - 1];
@@ -1005,7 +1021,10 @@ export function matchSubcommandHelp(argv: ReadonlyArray<string>): string | undef
return undefined;
}
-export function printSubcommandHelp(cmd: string): Effect.Effect<void> {
+export function printSubcommandHelp(
+ cmd: string,
+ _visibility: CommandVisibility
+): Effect.Effect<void> {
const help = SUBCOMMAND_HELP[cmd];
if (!help) return Console.log(`Unknown command: ${cmd}`);
return Console.log(renderSubcommandHelp(help));
@@ -1015,7 +1034,10 @@ export function printSubcommandHelp(cmd: string): Effect.Effect<void> {
* Match the command name from argv without requiring --help at the end.
* Used to print contextual help alongside error messages.
*/
-export function matchCommandFromArgv(argv: ReadonlyArray<string>): string | undefined {
+export function matchCommandFromArgv(
+ argv: ReadonlyArray<string>,
+ _visibility: CommandVisibility
+): string | undefined {
const args = argv.slice(2).filter(a => a !== '--help' && a !== '-h' && !a.startsWith('--'));
// Try longest match first: "dev toolkits list" → "dev toolkits" → "dev"
for (let len = Math.min(args.length, 3); len > 0; len--) {
@@ -1028,7 +1050,10 @@ export function matchCommandFromArgv(argv: ReadonlyArray<string>): string | unde
/**
* Get rendered help text for a command, or undefined if not found.
*/
-export function getCommandHelpText(cmd: string): string | undefined {
+export function getCommandHelpText(
+ cmd: string,
+ _visibility: CommandVisibility
+): string | undefined {
const help = SUBCOMMAND_HELP[cmd];
if (!help) return undefined;
return renderSubcommandHelp(help);
@@ -1041,7 +1066,7 @@ export function getCommandHelpText(cmd: string): string | undefined {
* Core workflow commands are shown first with full usage/options.
* Housekeeping and developer commands are shown compactly at the bottom.
*/
-export function printRootHelp(): Effect.Effect<void> {
+export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void> {
const name = 'composio';
const lines: string[] = [
@@ -1058,11 +1083,11 @@ export function printRootHelp(): Effect.Effect<void> {
` ${name} <command> [options]`,
'',
bold('CORE COMMANDS'),
- ...renderDetailedCommands(name, CORE_COMMANDS),
+ ...renderDetailedCommands(name, visibleValues(CORE_COMMANDS, visibility)),
gray(' Typical flow: search → execute (link and tools when needed)'),
'',
bold('TOOLS'),
- ...renderCompactCommands(OTHER_COMMANDS),
+ ...renderCompactCommands(visibleValues(OTHER_COMMANDS, visibility)),
'',
bold('EXAMPLES'),
` ${dim('# Find tools — supports multiple queries at once')}`,
@@ -1096,15 +1121,16 @@ export function printRootHelp(): Effect.Effect<void> {
` '`,
'',
bold('DEVELOPER COMMANDS'),
- ...renderCompactCommands(DEVELOPER_COMMANDS),
+ ...renderCompactCommands(visibleValues(DEVELOPER_COMMANDS, visibility)),
'',
bold('ACCOUNT'),
- ...renderCompactCommands(ACCOUNT_COMMANDS),
+ ...renderCompactCommands(visibleValues(ACCOUNT_COMMANDS, visibility)),
'',
bold('FILES') + dim(' (composio files --help)'),
` ${bold('~/.composio/')}`,
` CLI configuration and cache directory. Contains your auth state`,
- ` (user_data.json), cached tool definitions (tools.json, toolkits.json),`,
+ ` (user_data.json), runtime settings (config.json), cached tool definitions`,
+ ` (tools.json, toolkits.json),`,
` trigger types, and per-org consumer caches. These caches speed up`,
` repeated commands — safe to delete, they will be re-fetched on next use.`,
'',
diff --git a/ts/packages/cli/src/constants.ts b/ts/packages/cli/src/constants.ts
index eb18723c6..c3a29bc39 100644
--- a/ts/packages/cli/src/constants.ts
+++ b/ts/packages/cli/src/constants.ts
@@ -32,6 +32,11 @@ export const DEBUG_OVERRIDE_ENV_CONFIG_KEY_PREFIX = 'DEBUG_OVERRIDE_';
*/
export const USER_CONFIG_FILE_NAME = constants.USER_DATA_FILE_NAME;
+/**
+ * Name of the general CLI config file used by the Composio CLI.
+ */
+export const CLI_CONFIG_FILE_NAME = 'config.json';
+
/**
* Name of the directory used to store the Composio CLI config.
*/
diff --git a/ts/packages/cli/src/models/cli-user-config.ts b/ts/packages/cli/src/models/cli-user-config.ts
new file mode 100644
index 000000000..26647b212
--- /dev/null
+++ b/ts/packages/cli/src/models/cli-user-config.ts
@@ -0,0 +1,42 @@
+import { Schema } from 'effect';
+import { OptionFromNullishOr } from 'effect/Schema';
+import { JSONTransformSchema } from './utils/json-transform-schema';
+
+export const ExperimentalSubagentTarget = Schema.Literal('auto', 'claude', 'codex');
+export type ExperimentalSubagentTarget = Schema.Schema.Type<typeof ExperimentalSubagentTarget>;
+
+export const ExperimentalFeatures = Schema.Record({
+ key: Schema.String,
+ value: Schema.Boolean,
+});
+export type ExperimentalFeatures = Schema.Schema.Type<typeof ExperimentalFeatures>;
+
+export const CliUserConfig = Schema.Struct({
+ experimentalFeatures: Schema.optionalWith(ExperimentalFeatures, {
+ default: () => ({}),
+ }).pipe(Schema.fromKey('experimental_features')),
+ artifactDirectory: Schema.propertySignature(OptionFromNullishOr(Schema.String, null)).pipe(
+ Schema.fromKey('artifact_directory')
+ ),
+ experimentalSubagent: Schema.propertySignature(
+ OptionFromNullishOr(
+ Schema.Struct({
+ target: ExperimentalSubagentTarget,
+ }),
+ null
+ )
+ ).pipe(Schema.fromKey('experimental_subagent')),
+}).annotations({
+ identifier: 'CliUserConfig',
+ description: 'Named user configuration storage for the Composio CLI',
+});
+
+export type CliUserConfig = Schema.Schema.Type<typeof CliUserConfig>;
+
+export const CliUserConfigJSON = JSONTransformSchema(CliUserConfig);
+export const cliUserConfigFromJSON = Schema.decode(CliUserConfigJSON, {
+ propertyOrder: 'original',
+ onExcessProperty: 'preserve',
+ exact: false,
+});
+export const cliUserConfigToJSON = Schema.encode(CliUserConfigJSON);
diff --git a/ts/packages/cli/src/services/cli-session-artifacts.ts b/ts/packages/cli/src/services/cli-session-artifacts.ts
index 921c7b55f..fb3070187 100644
--- a/ts/packages/cli/src/services/cli-session-artifacts.ts
+++ b/ts/packages/cli/src/services/cli-session-artifacts.ts
@@ -3,10 +3,25 @@ import os from 'node:os';
import path from 'node:path';
import { Effect, Option } from 'effect';
import { getOrCreateProbablyMyCliSessionIdForCurrentCwd } from 'src/services/consumer-short-term-cache';
+import { resolveCliConfigPathSync } from 'src/services/cli-user-config';
+
+const readConfiguredArtifactDirectory = (): string | undefined => {
+ try {
+ const raw = fs.readFileSync(resolveCliConfigPathSync(), 'utf8');
+ const parsed = JSON.parse(raw) as { artifact_directory?: unknown };
+ return typeof parsed.artifact_directory === 'string' &&
+ parsed.artifact_directory.trim().length > 0
+ ? parsed.artifact_directory.trim()
+ : undefined;
+ } catch {
+ return undefined;
+ }
+};
export const resolveArtifactsRoot = (): string =>
process.env.COMPOSIO_SESSION_DIR?.trim() ||
process.env.COMPOSIO_CACHE_DIR?.trim() ||
+ readConfiguredArtifactDirectory() ||
path.join(os.tmpdir(), 'composio');
const SESSION_HISTORY_FILE = 'session-history.jsonl';
diff --git a/ts/packages/cli/src/services/cli-user-config.ts b/ts/packages/cli/src/services/cli-user-config.ts
new file mode 100644
index 000000000..af4ea0104
--- /dev/null
+++ b/ts/packages/cli/src/services/cli-user-config.ts
@@ -0,0 +1,128 @@
+import { FileSystem } from '@effect/platform';
+import type { PlatformError } from '@effect/platform/Error';
+import { Context, Effect, Layer, Option } from 'effect';
+import type { ParseError } from 'effect/ParseResult';
+import os from 'node:os';
+import path from 'node:path';
+import { setupCacheDir } from 'src/effects/setup-cache-dir';
+import { getVersion } from 'src/effects/version';
+import {
+ CliUserConfig,
+ cliUserConfigFromJSON,
+ cliUserConfigToJSON,
+} from 'src/models/cli-user-config';
+import * as constants from 'src/constants';
+
+export type CliReleaseChannel = 'stable' | 'beta';
+
+export type CliUserConfigResolved = {
+ readonly channel: CliReleaseChannel;
+ readonly experimentalFeatures: Readonly<Record<string, boolean>>;
+ readonly artifactDirectory: string | undefined;
+ readonly experimentalSubagentTarget: 'auto' | 'claude' | 'codex';
+};
+
+const detectReleaseChannel = (version: string): CliReleaseChannel =>
+ /-[0-9A-Za-z.-]+$/.test(version) ? 'beta' : 'stable';
+
+export const resolveCliConfigDirectorySync = (): string =>
+ process.env.COMPOSIO_CACHE_DIR?.trim() || path.join(os.homedir(), constants.USER_COMPOSIO_DIR);
+
+export const resolveCliConfigPathSync = (): string =>
+ path.join(resolveCliConfigDirectorySync(), constants.CLI_CONFIG_FILE_NAME);
+
+export class ComposioCliUserConfig extends Context.Tag('ComposioCliUserConfig')<
+ ComposioCliUserConfig,
+ {
+ readonly data: CliUserConfigResolved;
+ readonly raw: CliUserConfig;
+ readonly channel: CliReleaseChannel;
+ readonly isExperimentalFeatureEnabled: (feature: string) => boolean;
+ readonly update: (
+ next: Partial<CliUserConfig>
+ ) => Effect.Effect<void, ParseError | PlatformError, never>;
+ }
+>() {}
+
+const resolveConfig = (raw: CliUserConfig, channel: CliReleaseChannel): CliUserConfigResolved => ({
+ channel,
+ experimentalFeatures: raw.experimentalFeatures,
+ artifactDirectory: Option.getOrUndefined(raw.artifactDirectory),
+ experimentalSubagentTarget: Option.match(raw.experimentalSubagent, {
+ onNone: () => 'auto',
+ onSome: value => value.target,
+ }),
+});
+
+export const ComposioCliUserConfigLive = Layer.effect(
+ ComposioCliUserConfig,
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const version = yield* getVersion;
+ const channel = detectReleaseChannel(version);
+ const configDir = yield* setupCacheDir;
+ const jsonConfigPath = path.join(configDir, constants.CLI_CONFIG_FILE_NAME);
+
+ let rawConfig = CliUserConfig.make({
+ experimentalFeatures: {},
+ artifactDirectory: Option.none(),
+ experimentalSubagent: Option.none(),
+ });
+
+ const persist = (next: CliUserConfig) =>
+ Effect.gen(function* () {
+ const encoded = yield* cliUserConfigToJSON(next);
+ yield* fs.writeFileString(jsonConfigPath, encoded);
+ rawConfig = next;
+ });
+
+ const update = (
+ next: Partial<CliUserConfig>
+ ): Effect.Effect<void, ParseError | PlatformError, never> =>
+ persist(
+ CliUserConfig.make({
+ ...rawConfig,
+ ...next,
+ })
+ );
+
+ const load = Effect.gen(function* () {
+ const configJson = yield* fs.readFileString(jsonConfigPath, 'utf8');
+ rawConfig = yield* cliUserConfigFromJSON(configJson);
+ return rawConfig;
+ });
+
+ if (yield* fs.exists(jsonConfigPath)) {
+ yield* load.pipe(
+ Effect.catchAll(() =>
+ persist(
+ CliUserConfig.make({
+ experimentalFeatures: {},
+ artifactDirectory: Option.none(),
+ experimentalSubagent: Option.none(),
+ })
+ )
+ )
+ );
+ } else {
+ yield* persist(rawConfig);
+ }
+
+ const isExperimentalFeatureEnabled = (feature: string) => {
+ const configured = resolveConfig(rawConfig, channel).experimentalFeatures[feature];
+ return configured ?? channel === 'beta';
+ };
+
+ return ComposioCliUserConfig.of({
+ get data() {
+ return resolveConfig(rawConfig, channel);
+ },
+ get raw() {
+ return rawConfig;
+ },
+ channel,
+ isExperimentalFeatureEnabled,
+ update,
+ });
+ })
+);
diff --git a/ts/packages/cli/src/services/run-helpers-runtime.ts b/ts/packages/cli/src/services/run-helpers-runtime.ts
index b79516791..0fa61f910 100644
--- a/ts/packages/cli/src/services/run-helpers-runtime.ts
+++ b/ts/packages/cli/src/services/run-helpers-runtime.ts
@@ -3,6 +3,7 @@ import * as os from 'node:os';
import * as path from 'node:path';
import process from 'node:process';
import { z } from 'zod';
+import { resolveCliConfigPathSync } from 'src/services/cli-user-config';
import type { MasterKind } from 'src/services/master-detector';
import { isAcpInvokeError } from 'src/services/run-subagent-shared';
import { invokeAcpSubAgent } from 'src/services/run-subagent-acp';
@@ -490,8 +491,23 @@ export const installRunHelpers = async ({
return 'user';
};
+ const readConfiguredExperimentalSubagentTarget = (): 'auto' | 'claude' | 'codex' => {
+ try {
+ const raw = fs.readFileSync(resolveCliConfigPathSync(), 'utf8');
+ const parsed = JSON.parse(raw) as {
+ experimental_subagent?: { target?: unknown };
+ };
+ const target = parsed.experimental_subagent?.target;
+ return target === 'claude' || target === 'codex' || target === 'auto' ? target : 'auto';
+ } catch {
+ return 'auto';
+ }
+ };
+
const resolveInvokeAgentTarget = (requestedTarget?: string): 'claude' | 'codex' => {
if (requestedTarget === 'claude' || requestedTarget === 'codex') return requestedTarget;
+ const configuredTarget = readConfiguredExperimentalSubagentTarget();
+ if (configuredTarget === 'claude' || configuredTarget === 'codex') return configuredTarget;
const detected = requestedTarget === 'user' ? 'user' : detectInvokeAgentMaster();
if (detected === 'codex' || detected === 'claude') return detected;
if (typeof Bun.which === 'function' && Bun.which('codex')) return 'codex';
diff --git a/ts/packages/cli/test/__utils__/cli.ts b/ts/packages/cli/test/__utils__/cli.ts
index a66d0a289..22cc586ec 100644
--- a/ts/packages/cli/test/__utils__/cli.ts
+++ b/ts/packages/cli/test/__utils__/cli.ts
@@ -2,9 +2,5 @@ import { Effect } from 'effect';
import * as Cli from 'src/commands';
// Run CLI in test environment
-export const cli = (args: ReadonlyArray<string>) =>
- Effect.flatMap(Cli.runWithConfig, run => run(['node', '<CMD>', ...args])) satisfies Effect.Effect<
- void,
- any,
- any
- >;
+export const cli = (args: ReadonlyArray<string>): Effect.Effect<void, unknown, any> =>
+ Effect.flatMap(Cli.runWithConfig, run => run(['node', '<CMD>', ...args]));
diff --git a/ts/packages/cli/test/__utils__/services/test-layer.ts b/ts/packages/cli/test/__utils__/services/test-layer.ts
index 725ee9fa4..2c6726a41 100644
--- a/ts/packages/cli/test/__utils__/services/test-layer.ts
+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts
@@ -39,6 +39,7 @@ import type { TriggerInstanceItem } from 'src/models/triggers';
import type { AuthConfigCreateResponse, LinkCreateResponse } from 'src/services/composio-clients';
import type { ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
import { ComposioUserContextLive } from 'src/services/user-context';
+import { ComposioCliUserConfigLive } from 'src/services/cli-user-config';
import { UpgradeBinary } from 'src/services/upgrade-binary';
import { NodeOs } from 'src/services/node-os';
import { TriggersRealtime } from 'src/services/triggers-realtime';
@@ -798,6 +799,11 @@ export const TestLayer = (input?: TestLiveInput) =>
Layer.merge(BunFileSystem.layer, NodeOsTest)
);
+ const ComposioCliUserConfigTest = Layer.provideMerge(
+ ComposioCliUserConfigLive,
+ Layer.mergeAll(BunFileSystem.layer, NodeOsTest)
+ );
+
const UpgradeBinaryTest = Layer.provide(
UpgradeBinary.Default,
Layer.mergeAll(BunFileSystem.layer, FetchHttpClient.layer)
@@ -1147,6 +1153,7 @@ export const TestLayer = (input?: TestLiveInput) =>
CliConfigLive,
NodeProcessTest,
UpgradeBinaryTest,
+ ComposioCliUserConfigTest,
ComposioUserContextTest,
ComposioClientSingletonTest,
ComposioSessionRepositoryTest,
diff --git a/ts/packages/cli/test/src/commands/$default.cmd.test.ts b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
index b5de659a3..3ecf46f42 100644
--- a/ts/packages/cli/test/src/commands/$default.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
@@ -59,7 +59,9 @@ describe('CLI: composio', () => {
const args = ['--help'];
yield* cli(args);
const lines = yield* MockConsole.getLines({ stripAnsi: true });
- expect(lines.join('\n').trim().length).toBeGreaterThan(0);
+ const output = lines.join('\n');
+ expect(output.trim().length).toBeGreaterThan(0);
+ expect(output).toContain('config.json');
})
);
});
diff --git a/ts/packages/cli/test/src/services/cli-user-config.test.ts b/ts/packages/cli/test/src/services/cli-user-config.test.ts
new file mode 100644
index 000000000..0e96c03ba
--- /dev/null
+++ b/ts/packages/cli/test/src/services/cli-user-config.test.ts
@@ -0,0 +1,120 @@
+import path from 'node:path';
+import * as tempy from 'tempy';
+import fs from 'node:fs';
+import { describe, it } from '@effect/vitest';
+import { assertEquals } from '@effect/vitest/utils';
+import { FileSystem } from '@effect/platform';
+import { BunFileSystem } from '@effect/platform-bun';
+import { ConfigProvider, Effect, Layer } from 'effect';
+import { extendConfigProvider } from 'src/services/config';
+import { defaultNodeOs, NodeOs } from 'src/services/node-os';
+import {
+ ComposioCliUserConfig,
+ ComposioCliUserConfigLive,
+ resolveCliConfigPathSync,
+} from 'src/services/cli-user-config';
+
+describe('ComposioCliUserConfig', () => {
+ const withMapConfigProvider = (map: Map<string, string>) =>
+ Layer.setConfigProvider(extendConfigProvider(ConfigProvider.fromMap(map)));
+
+ it.scoped('defaults experimental features off in stable releases', () => {
+ const cwd = tempy.temporaryDirectory();
+ const map = new Map([['DEBUG_OVERRIDE_VERSION', '1.2.3']]) satisfies Map<string, string>;
+ const NodeOsTest = Layer.succeed(NodeOs, defaultNodeOs({ homedir: cwd }));
+ const CliUserConfigTest = Layer.provideMerge(
+ ComposioCliUserConfigLive,
+ Layer.mergeAll(BunFileSystem.layer, NodeOsTest, withMapConfigProvider(map))
+ );
+
+ return Effect.gen(function* () {
+ const config = yield* ComposioCliUserConfig;
+ assertEquals(config.channel, 'stable');
+ assertEquals(config.data.experimentalFeatures.listen, undefined);
+ assertEquals(config.isExperimentalFeatureEnabled('listen'), false);
+ assertEquals(config.data.experimentalSubagentTarget, 'auto');
+ assertEquals(config.data.artifactDirectory, undefined);
+
+ const fs = yield* FileSystem.FileSystem;
+ assertEquals(yield* fs.exists(path.join(cwd, '.composio', 'config.json')), true);
+ }).pipe(Effect.provide(CliUserConfigTest));
+ });
+
+ it.scoped('defaults experimental features on in beta releases', () => {
+ const cwd = tempy.temporaryDirectory();
+ const map = new Map([['DEBUG_OVERRIDE_VERSION', '1.2.3-beta.4']]) satisfies Map<string, string>;
+ const NodeOsTest = Layer.succeed(NodeOs, defaultNodeOs({ homedir: cwd }));
+ const CliUserConfigTest = Layer.provideMerge(
+ ComposioCliUserConfigLive,
+ Layer.mergeAll(BunFileSystem.layer, NodeOsTest, withMapConfigProvider(map))
+ );
+
+ return Effect.gen(function* () {
+ const config = yield* ComposioCliUserConfig;
+ assertEquals(config.channel, 'beta');
+ assertEquals(config.data.experimentalFeatures.listen, undefined);
+ assertEquals(config.isExperimentalFeatureEnabled('listen'), true);
+ assertEquals(config.data.experimentalSubagentTarget, 'auto');
+ }).pipe(Effect.provide(CliUserConfigTest));
+ });
+
+ it.scoped('respects explicit persisted cli settings from config.json', () => {
+ const cwd = tempy.temporaryDirectory();
+ const map = new Map([['DEBUG_OVERRIDE_VERSION', '1.2.3-beta.4']]) satisfies Map<string, string>;
+ fs.mkdirSync(path.join(cwd, '.composio'), { recursive: true });
+ fs.writeFileSync(
+ path.join(cwd, '.composio', 'config.json'),
+ JSON.stringify({
+ experimental_features: {
+ listen: false,
+ },
+ artifact_directory: '/tmp/composio-artifacts',
+ experimental_subagent: {
+ target: 'claude',
+ },
+ })
+ );
+
+ const NodeOsTest = Layer.succeed(NodeOs, defaultNodeOs({ homedir: cwd }));
+ const CliUserConfigTest = Layer.provideMerge(
+ ComposioCliUserConfigLive,
+ Layer.mergeAll(BunFileSystem.layer, NodeOsTest, withMapConfigProvider(map))
+ );
+
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const config = yield* ComposioCliUserConfig;
+ assertEquals(config.data.experimentalFeatures.listen, false);
+ assertEquals(config.isExperimentalFeatureEnabled('listen'), false);
+ assertEquals(config.data.artifactDirectory, '/tmp/composio-artifacts');
+ assertEquals(config.data.experimentalSubagentTarget, 'claude');
+
+ const persisted = yield* fileSystem.readFileString(
+ path.join(cwd, '.composio', 'config.json'),
+ 'utf8'
+ );
+ const parsed = JSON.parse(persisted) as {
+ experimental_features: { listen: boolean };
+ artifact_directory: string;
+ experimental_subagent: { target: string };
+ };
+
+ assertEquals(parsed.experimental_features.listen, false);
+ assertEquals(parsed.artifact_directory, '/tmp/composio-artifacts');
+ assertEquals(parsed.experimental_subagent.target, 'claude');
+ }).pipe(Effect.provide(CliUserConfigTest));
+ });
+
+ it.effect('resolves sync config path from COMPOSIO_CACHE_DIR when provided', () => {
+ const cacheDir = tempy.temporaryDirectory();
+ process.env.COMPOSIO_CACHE_DIR = cacheDir;
+
+ return Effect.sync(() => {
+ try {
+ assertEquals(resolveCliConfigPathSync(), path.join(cacheDir, 'config.json'));
+ } finally {
+ delete process.env.COMPOSIO_CACHE_DIR;
+ }
+ });
+ });
+});