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.

feat(cli): add composio config experimental command (#3156)

Rahul Tarak2fe9370ae9ba
diff --git a/ts/packages/cli/skills-src/composio-cli/index.ts b/ts/packages/cli/skills-src/composio-cli/index.ts
index 783c4bb2b..b7284ac13 100644
--- a/ts/packages/cli/skills-src/composio-cli/index.ts
+++ b/ts/packages/cli/skills-src/composio-cli/index.ts
@@ -296,8 +296,11 @@ const renderCommand = (build: SkillBuildContext, command: SkillCommand) => {
return lines.join('\n');
};
-export const renderComposioCliSkill = (channel: SkillReleaseChannel) => {
- const build = resolveSkillBuildContext(channel);
+export const renderComposioCliSkill = (
+ channel: SkillReleaseChannel,
+ featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>>
+) => {
+ const build = resolveSkillBuildContext(channel, featureOverrides);
const lines: string[] = [
'---',
`name: ${frontmatter.name}`,
@@ -331,8 +334,11 @@ export const renderComposioCliSkill = (channel: SkillReleaseChannel) => {
return lines.join('\n') + '\n';
};
-export const renderReferenceFiles = (channel: SkillReleaseChannel) => {
- const build = resolveSkillBuildContext(channel);
+export const renderReferenceFiles = (
+ channel: SkillReleaseChannel,
+ featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>>
+) => {
+ const build = resolveSkillBuildContext(channel, featureOverrides);
return Object.fromEntries(
referenceDocuments.map(document => [
`${document.slug}.md`,
@@ -361,15 +367,21 @@ const copyDir = (sourceDir: string, targetDir: string) => {
export const buildComposioCliSkill = ({
channel,
outputRoot,
+ featureOverrides,
}: {
channel: SkillReleaseChannel;
outputRoot: string;
+ featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>>;
}) => {
const skillOutputDir = path.join(outputRoot, 'composio-cli');
fs.rmSync(skillOutputDir, { recursive: true, force: true });
fs.mkdirSync(skillOutputDir, { recursive: true });
- fs.writeFileSync(path.join(skillOutputDir, 'SKILL.md'), renderComposioCliSkill(channel), 'utf8');
+ fs.writeFileSync(
+ path.join(skillOutputDir, 'SKILL.md'),
+ renderComposioCliSkill(channel, featureOverrides),
+ 'utf8'
+ );
const agentsSourceDir = path.join(sourceAssetsDir, 'agents');
if (fs.existsSync(agentsSourceDir)) {
@@ -378,7 +390,9 @@ export const buildComposioCliSkill = ({
const referencesOutputDir = path.join(skillOutputDir, 'references');
fs.mkdirSync(referencesOutputDir, { recursive: true });
- for (const [fileName, markdown] of Object.entries(renderReferenceFiles(channel))) {
+ for (const [fileName, markdown] of Object.entries(
+ renderReferenceFiles(channel, featureOverrides)
+ )) {
fs.writeFileSync(path.join(referencesOutputDir, fileName), markdown, 'utf8');
}
diff --git a/ts/packages/cli/skills-src/composio-cli/reference-schema.ts b/ts/packages/cli/skills-src/composio-cli/reference-schema.ts
index 399071678..c4b7f9f0c 100644
--- a/ts/packages/cli/skills-src/composio-cli/reference-schema.ts
+++ b/ts/packages/cli/skills-src/composio-cli/reference-schema.ts
@@ -34,6 +34,7 @@ export type ReferenceDocument = {
const TOP_LEVEL_COMMANDS = new Set([
'artifacts',
+ 'config',
'dev',
'execute',
'link',
@@ -47,11 +48,15 @@ const TOP_LEVEL_COMMANDS = new Set([
'whoami',
]);
-export const resolveSkillBuildContext = (channel: SkillReleaseChannel): SkillBuildContext => ({
+export const resolveSkillBuildContext = (
+ channel: SkillReleaseChannel,
+ overrides?: Partial<Record<SkillFeatureFlag, boolean>>
+): SkillBuildContext => ({
channel,
experimentalFeatures: {
[CLI_EXPERIMENTAL_FEATURES.LISTEN]: channel === 'beta',
[CLI_EXPERIMENTAL_FEATURES.MULTI_ACCOUNT]: channel === 'beta',
+ ...overrides,
},
});
diff --git a/ts/packages/cli/src/commands/config/config.cmd.ts b/ts/packages/cli/src/commands/config/config.cmd.ts
new file mode 100644
index 000000000..6e307f0d5
--- /dev/null
+++ b/ts/packages/cli/src/commands/config/config.cmd.ts
@@ -0,0 +1,7 @@
+import { Command } from '@effect/cli';
+import { configExperimentalCmd } from './config.experimental.cmd';
+
+export const configCmd = Command.make('config').pipe(
+ Command.withDescription('View and manage CLI configuration.'),
+ Command.withSubcommands([configExperimentalCmd])
+);
diff --git a/ts/packages/cli/src/commands/config/config.experimental.cmd.ts b/ts/packages/cli/src/commands/config/config.experimental.cmd.ts
new file mode 100644
index 000000000..5998ac8d8
--- /dev/null
+++ b/ts/packages/cli/src/commands/config/config.experimental.cmd.ts
@@ -0,0 +1,187 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Command, Args } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { ComposioCliUserConfig } from 'src/services/cli-user-config';
+import { TerminalUI } from 'src/services/terminal-ui';
+import { NodeOs } from 'src/services/node-os';
+import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
+import { buildComposioCliSkill } from '../../../skills-src/composio-cli/index';
+import type { SkillFeatureFlag } from '../../../skills-src/composio-cli/reference-schema';
+
+const knownFeatures: readonly string[] = Object.values(CLI_EXPERIMENTAL_FEATURES);
+
+const featureArg = Args.text({ name: 'feature' }).pipe(
+ Args.withDescription(`Experimental feature name. Known features: ${knownFeatures.join(', ')}`),
+ Args.optional
+);
+
+const stateArg = Args.text({ name: 'state' }).pipe(
+ Args.withDescription('Set to "on" or "off"'),
+ Args.optional
+);
+
+const SKILL_NAME = 'composio-cli';
+
+/**
+ * Find every directory where the composio-cli skill is currently installed.
+ * Known locations:
+ * ~/.agents/skills/composio-cli (canonical install target)
+ * ~/.claude/skills/composio-cli (Claude Code — may be a symlink or a real dir)
+ *
+ * We resolve symlinks so we don't rebuild the same physical directory twice,
+ * but we also rebuild any real (non-symlink) copies so everything stays in sync.
+ */
+const discoverSkillRoots = (home: string): string[] => {
+ const candidates = [path.join(home, '.agents', 'skills'), path.join(home, '.claude', 'skills')];
+
+ const seen = new Set<string>();
+ const roots: string[] = [];
+
+ for (const parent of candidates) {
+ const skillDir = path.join(parent, SKILL_NAME);
+ try {
+ const stat = fs.lstatSync(skillDir);
+ if (stat.isSymbolicLink()) {
+ // Resolve the symlink target — we'll rebuild the real directory it points to
+ const realDir = fs.realpathSync(skillDir);
+ const realParent = path.dirname(realDir);
+ if (!seen.has(realParent)) {
+ seen.add(realParent);
+ roots.push(realParent);
+ }
+ } else if (stat.isDirectory()) {
+ if (!seen.has(parent)) {
+ seen.add(parent);
+ roots.push(parent);
+ }
+ }
+ } catch {
+ // Directory doesn't exist — skip
+ }
+ }
+
+ // Always include ~/.agents/skills as a fallback so there's at least one target
+ const agentSkillsRoot = path.join(home, '.agents', 'skills');
+ if (!seen.has(agentSkillsRoot)) {
+ roots.push(agentSkillsRoot);
+ }
+
+ return roots;
+};
+
+const rebuildSkill = Effect.gen(function* () {
+ const ui = yield* TerminalUI;
+ const os = yield* NodeOs;
+ const cliConfig = yield* ComposioCliUserConfig;
+ const home = os.homedir;
+
+ // Build the feature overrides from the current config
+ const featureOverrides: Partial<Record<SkillFeatureFlag, boolean>> = {};
+ for (const name of knownFeatures) {
+ featureOverrides[name as SkillFeatureFlag] = cliConfig.isExperimentalFeatureEnabled(name);
+ }
+
+ const roots = discoverSkillRoots(home);
+ for (const root of roots) {
+ buildComposioCliSkill({
+ channel: cliConfig.channel,
+ outputRoot: root,
+ featureOverrides,
+ });
+ }
+
+ yield* ui.log.step(
+ roots.length === 1
+ ? `Rebuilt skill in ${roots[0]}`
+ : `Rebuilt skill in ${roots.length} locations`
+ );
+});
+
+export const configExperimentalCmd = Command.make(
+ 'experimental',
+ { feature: featureArg, state: stateArg },
+ ({ feature, state }) =>
+ Effect.gen(function* () {
+ const ui = yield* TerminalUI;
+ const cliConfig = yield* ComposioCliUserConfig;
+
+ // No args: list all experimental features and their state
+ if (Option.isNone(feature)) {
+ const features = cliConfig.data.experimentalFeatures;
+ const lines: string[] = [];
+ for (const name of knownFeatures) {
+ const enabled = cliConfig.isExperimentalFeatureEnabled(name);
+ const configured = name in features;
+ const suffix = configured ? '' : ` (default, channel: ${cliConfig.channel})`;
+ lines.push(` ${name}: ${enabled ? 'on' : 'off'}${suffix}`);
+ }
+
+ // Show any custom features not in the known list
+ for (const [name, value] of Object.entries(features)) {
+ if (!knownFeatures.includes(name)) {
+ lines.push(` ${name}: ${value ? 'on' : 'off'}`);
+ }
+ }
+
+ if (lines.length === 0) {
+ yield* ui.log.info('No experimental features available.');
+ } else {
+ yield* ui.note(lines.join('\n'), 'Experimental Features');
+ yield* ui.output(JSON.stringify(features));
+ }
+ return;
+ }
+
+ const featureName = feature.value;
+
+ // Feature name only: show current state
+ if (Option.isNone(state)) {
+ const enabled = cliConfig.isExperimentalFeatureEnabled(featureName);
+ yield* ui.log.info(`${featureName}: ${enabled ? 'on' : 'off'}`);
+ yield* ui.output(enabled ? 'on' : 'off');
+ return;
+ }
+
+ const stateValue = state.value.toLowerCase();
+ if (stateValue !== 'on' && stateValue !== 'off') {
+ yield* ui.log.error(`Invalid state "${state.value}". Use "on" or "off".`);
+ return yield* Effect.fail(new Error(`Invalid state: ${state.value}`));
+ }
+
+ const enabled = stateValue === 'on';
+ yield* cliConfig.update({
+ experimentalFeatures: {
+ ...cliConfig.data.experimentalFeatures,
+ [featureName]: enabled,
+ },
+ });
+
+ yield* ui.log.success(`${featureName}: ${stateValue}`);
+
+ // Rebuild the skill so Claude Code picks up the new feature flags
+ yield* rebuildSkill.pipe(
+ Effect.catchAll(error =>
+ Effect.gen(function* () {
+ yield* Effect.logDebug('Skill rebuild failed:', error);
+ yield* ui.log.warn('Could not rebuild skill (non-fatal)');
+ })
+ )
+ );
+
+ yield* ui.output(stateValue);
+ })
+).pipe(
+ Command.withDescription(
+ [
+ 'View or toggle experimental feature flags.',
+ '',
+ 'Usage:',
+ ' composio config experimental List all features',
+ ' composio config experimental <feature> Show current state',
+ ' composio config experimental <feature> on|off Enable or disable',
+ '',
+ `Known features: ${knownFeatures.join(', ')}`,
+ ].join('\n')
+ )
+);
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index f0b0781ca..08b7a89c9 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -26,6 +26,7 @@ import { rootToolsCmd } from './tools/tools.cmd';
import { rootTriggersCmd } from './triggers/root-triggers.cmd';
import { rootConnectedAccountsCmd$Link } from './connected-accounts/commands/connected-accounts.link.cmd';
import { orgsCmd } from './orgs/orgs.cmd';
+import { configCmd } from './config/config.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';
@@ -65,6 +66,7 @@ const ROOT_COMMANDS: ReadonlyArray<TaggedValue<Command.Command<any, any, any, an
tagged(rootToolsCmd$Execute),
tagged(generateCmd),
tagged(orgsCmd),
+ tagged(configCmd),
];
export const buildRootCommand = (visibility: CommandVisibility) => {
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
index c86baca44..e7ad64c59 100644
--- a/ts/packages/cli/src/commands/root-help.ts
+++ b/ts/packages/cli/src/commands/root-help.ts
@@ -170,6 +170,7 @@ const ACCOUNT_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
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' }),
+ tagged({ name: 'config', description: 'View and manage CLI configuration' }),
];
// ── Render helpers ─────────────────────────────────────────────────────
@@ -357,20 +358,37 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
],
}),
link: {
- usage: 'composio link [<toolkit>] [--no-wait]',
+ usage: 'composio link [<toolkit>] [--no-wait] [--alias text] [--list]',
description:
'Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf. Opens a browser for OAuth authorization and waits for confirmation.',
args: [{ name: '<toolkit>', description: 'Toolkit slug to link (e.g. "github", "gmail")' }],
+ options: [
+ {
+ name: '--alias <text>',
+ description:
+ 'Alias for the connected account. Required when creating an additional account for the same toolkit (requires multi_account experimental feature)',
+ },
+ ],
flags: [
{
name: '--no-wait',
description: 'Print link info and exit without waiting for authorization',
},
+ {
+ name: '--list',
+ description:
+ 'List existing connected accounts for the toolkit instead of creating a new link',
+ },
+ ],
+ examples: [
+ 'composio link github',
+ 'composio link gmail --alias work',
+ 'composio link github --list',
],
- examples: ['composio link github'],
seeAlso: [
'composio search "<query>" Find tools to use after linking',
"composio execute <slug> -d '{ ... }' Execute a tool with your connected account",
+ 'composio config experimental Manage experimental features',
],
},
run: {
@@ -927,6 +945,24 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
],
flags: [{ name: '--case-sensitive', description: 'Case-sensitive filtering' }],
},
+ config: {
+ usage: 'composio config <subcommand>',
+ description: 'View and manage CLI configuration.',
+ seeAlso: ['composio config experimental'],
+ },
+ 'config experimental': {
+ usage: 'composio config experimental [<feature>] [on|off]',
+ description: 'View or toggle experimental feature flags.',
+ args: [
+ { name: '<feature>', description: 'Feature name (e.g., listen, multi_account)' },
+ { name: 'on|off', description: 'Enable or disable the feature' },
+ ],
+ examples: [
+ 'composio config experimental # List all features',
+ 'composio config experimental listen # Show current state',
+ 'composio config experimental multi_account on # Enable multi_account',
+ ],
+ },
'dev logs triggers': {
usage:
'composio dev logs triggers [--trigger text] [--trigger-id text] [--limit integer] [--time 5m|30m|6h|1d|1w] [<log_id>]',