Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Add root skill-install flag for Claude, Codex, and OpenClaw (#3137)
Rahul Tarak5c27c0050a02
diff --git a/ts/packages/cli/README.md b/ts/packages/cli/README.mdindex f22a1d499..e37aacd61 100644--- a/ts/packages/cli/README.md+++ b/ts/packages/cli/README.md@@ -22,6 +22,7 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]### Optional Flags- `--log-level`: Set the log verbosity level. Accepted values: all, trace, debug, info, warning, error, fatal, none+- `--instal-skill [skill-name] <claude|codex|openclaw>`: Manually install the composio skill for a supported agent when automatic installation fails. `--install-skill` is accepted as an alias.## π§ Commands@@ -43,6 +44,7 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]- `composio generate py [-o, --output-dir <directory>] [--toolkits <toolkit>]`: Generate Python type stubs for toolkits, tools, and triggers from the Composio API.- `composio generate ts [-o, --output-dir <directory>] [--compact] [--transpiled] [--type-tools] [--toolkits <toolkit>]`: Generate TypeScript types for toolkits, tools, and triggers from the Composio API.- `composio upgrade [--beta]`: Self-update the Composio CLI from the stable channel, or from the beta channel with `--beta`.+- `composio --instal-skill [skill-name] <claude|codex|openclaw>`: Manually install the composio skill for Claude, Codex, or OpenClaw.## Configurationdiff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.tsindex 08b7a89c9..1f0093f9d 100644--- a/ts/packages/cli/src/commands/index.ts+++ b/ts/packages/cli/src/commands/index.ts@@ -38,6 +38,7 @@ import {resolveCommandProject,} from 'src/services/command-project';import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';+import { installSkill, type SkillInstallTarget } from 'src/effects/install-skill';import {experimental,type CommandVisibility,@@ -75,6 +76,94 @@ export const buildRootCommand = (visibility: CommandVisibility) => {return $defaultCmd.pipe(Command.withSubcommands(subcommands as any));};+const ROOT_INSTALL_SKILL_FLAGS = ['--instal-skill', '--install-skill'] as const;+const SKILL_INSTALL_TARGETS = ['claude', 'codex', 'openclaw'] as const satisfies ReadonlyArray<+ SkillInstallTarget+>;++type RootInstallSkillRequest =+ | {+ _tag: 'parsed';+ skillName?: string;+ target: SkillInstallTarget;+ }+ | { _tag: 'error'; message: string };++const isSkillInstallTarget = (value: string): value is SkillInstallTarget =>+ (SKILL_INSTALL_TARGETS as ReadonlyArray<string>).includes(value);++export const parseRootInstallSkillRequest = (+ argv: ReadonlyArray<string>+): RootInstallSkillRequest | undefined => {+ const args = argv.slice(2);+ for (let i = 0; i < args.length; i += 1) {+ const token = args[i];+ if (!token) continue;++ if ((ROOT_INSTALL_SKILL_FLAGS as ReadonlyArray<string>).includes(token)) {+ const rawValues: string[] = [];+ for (let j = i + 1; j < args.length; j += 1) {+ const next = args[j];+ if (!next) continue;+ if (next.startsWith('-')) break;+ rawValues.push(next);+ }++ if (rawValues.length === 0) {+ return {+ _tag: 'error',+ message:+ 'Missing target for --instal-skill. Usage: composio --instal-skill [skill-name] <claude|codex|openclaw>',+ };+ }++ if (rawValues.length === 1) {+ const [target] = rawValues;+ if (!isSkillInstallTarget(target)) {+ return {+ _tag: 'error',+ message:+ 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',+ };+ }+ return { _tag: 'parsed', target };+ }++ if (rawValues.length === 2) {+ const [skillName, target] = rawValues;+ if (!isSkillInstallTarget(target)) {+ return {+ _tag: 'error',+ message:+ 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',+ };+ }+ return { _tag: 'parsed', skillName, target };+ }++ return {+ _tag: 'error',+ message:+ 'Too many arguments for --instal-skill. Usage: composio --instal-skill [skill-name] <claude|codex|openclaw>',+ };+ }++ if (token === '--log-level') {+ i += 1;+ continue;+ }++ if (token.startsWith('--log-level=')) {+ continue;+ }++ if (!token.startsWith('-')) {+ return undefined;+ }+ }+ return undefined;+};+const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefined => {const args = argv.slice(2);const isRootExecute = args[0] === 'execute';@@ -269,6 +358,16 @@ export const runWithConfig = Effect.gen(function* () {const normalizedArgv = normalizeHiddenDebugFlags(normalizeListenStreamFlag(normalizeVersionShortFlag(argv)));+ const installSkillRequest = parseRootInstallSkillRequest(normalizedArgv);+ if (installSkillRequest) {+ if (installSkillRequest._tag === 'error') {+ return Effect.fail(new Error(installSkillRequest.message));+ }+ return installSkill({+ skillName: installSkillRequest.skillName,+ target: installSkillRequest.target,+ });+ }if (isRootHelp(normalizedArgv)) {return printRootHelp(visibility);}diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.tsindex e7ad64c59..2cd85267d 100644--- a/ts/packages/cli/src/commands/root-help.ts+++ b/ts/packages/cli/src/commands/root-help.ts@@ -1175,6 +1175,10 @@ export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void` ${dim('# Run a script with injected helpers')}`,` ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,'',+ ` ${dim('# Manually install the composio skill when auto-install fails')}`,+ ` ${name} --instal-skill claude`,+ ` ${name} --instal-skill composio-cli codex`,+ '',` ${dim('# Run a multi-step script with Promise.all')}`,` ${name} run '`,` const [emails, issues] = await Promise.all([`,@@ -1209,6 +1213,8 @@ export function printRootHelp(visibility: CommandVisibility): Effect.Effect<voidbold('FLAGS'),' -h, --help Show help for command',` --version Show ${name} version`,+ ' --instal-skill [skill-name] <claude|codex|openclaw>',+ ' Manually install the composio skill for a supported agent','',bold('LEARN MORE'),` Use \`${name} <command> --help\` for more information about a command.`,diff --git a/ts/packages/cli/src/effects/install-skill.ts b/ts/packages/cli/src/effects/install-skill.tsindex c5be37b40..3bf59e1b4 100644--- a/ts/packages/cli/src/effects/install-skill.ts+++ b/ts/packages/cli/src/effects/install-skill.ts@@ -16,6 +16,15 @@ import decompress from 'decompress';const SKILL_NAME = 'composio-cli';const SKILL_ASSET_NAME = 'composio-skill.zip';export type SkillReleaseChannel = CliReleaseChannel;+export type SkillInstallTarget = 'claude' | 'codex' | 'openclaw';++const SKILL_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;++const SKILL_TARGET_LABELS: Record<SkillInstallTarget, string> = {+ claude: 'Claude Code',+ codex: 'Codex',+ openclaw: 'OpenClaw',+};type GitHubConfig = GitHubRepoConfig & {TAG: Option.Option<string>;@@ -25,6 +34,44 @@ type GitHubConfig = GitHubRepoConfig & {const hasSkillAsset = (release: GitHubRelease) =>release.assets.some(asset => asset.name === SKILL_ASSET_NAME);+export const resolveInstalledSkillName = (skillName?: string): string => {+ const normalized = skillName?.trim();+ if (!normalized) {+ return SKILL_NAME;+ }+ if (+ normalized === '.' ||+ normalized === '..' ||+ !SKILL_NAME_PATTERN.test(normalized)+ ) {+ throw new Error(+ 'Invalid skill name. Use letters, numbers, dots, underscores, or hyphens only.'+ );+ }+ return normalized;+};++export const resolveTargetSkillPath = ({+ home,+ skillName,+ target,+}: {+ home: string;+ skillName: string;+ target: SkillInstallTarget;+}): string => {+ switch (target) {+ case 'claude':+ return path.join(home, '.claude', 'skills', skillName);+ case 'codex':+ return path.join(home, '.codex', 'skills', skillName);+ case 'openclaw':+ return path.join(home, '.openclaw', 'skills', skillName);+ }+};++const resolveTargetLabel = (target: SkillInstallTarget): string => SKILL_TARGET_LABELS[target];+export const inferSkillReleaseChannel = (tagOrVersion: string): SkillReleaseChannel =>tagOrVersion.includes('-beta.') ? 'beta' : 'stable';@@ -68,14 +115,16 @@ export const resolveSkillReleaseTag = ({* Install the composio-cli skill into the user's global agent skills directory.** - Downloads composio-skill.zip from the matching CLI GitHub release- * - Extracts to ~/.agents/skills/composio-cli/- * - Creates a symlink at ~/.claude/skills/composio-cli β ../../.agents/skills/composio-cli+ * - Extracts to ~/.agents/skills/<skill-name>/+ * - Creates a symlink in the selected agent's skills directory** Non-fatal: wrapped version catches all errors.*/export const installSkill = (options?: {readonly releaseTag?: string;readonly channel?: SkillReleaseChannel;+ readonly target?: SkillInstallTarget;+ readonly skillName?: string;}) =>Effect.gen(function* () {const os = yield* NodeOs;@@ -83,9 +132,11 @@ export const installSkill = (options?: {const httpClient = yield* HttpClient.HttpClient;const githubConfig = yield* Config.all(GITHUB_CONFIG);const home = os.homedir;+ const target = options?.target ?? 'claude';+ const skillName = resolveInstalledSkillName(options?.skillName);- const agentSkillDir = path.join(home, '.agents', 'skills', SKILL_NAME);- const claudeSkillLink = path.join(home, '.claude', 'skills', SKILL_NAME);+ const agentSkillDir = path.join(home, '.agents', 'skills', skillName);+ const targetSkillPath = resolveTargetSkillPath({ home, skillName, target });const tag = yield* resolveSkillReleaseTag({channel: options?.channel,@@ -161,25 +212,25 @@ export const installSkill = (options?: {fs.rmSync(tmpDir, { recursive: true, force: true });}- // Create symlink for Claude Code β always replace any existing entry- fs.mkdirSync(path.join(home, '.claude', 'skills'), { recursive: true });+ // Create agent-specific symlink β always replace any existing entry.+ fs.mkdirSync(path.dirname(targetSkillPath), { recursive: true });try {- const stat = fs.lstatSync(claudeSkillLink);+ const stat = fs.lstatSync(targetSkillPath);// Entry exists (symlink, broken symlink, or directory) β remove itif (stat.isSymbolicLink()) {- fs.unlinkSync(claudeSkillLink);+ fs.unlinkSync(targetSkillPath);} else if (stat.isDirectory()) {- fs.rmSync(claudeSkillLink, { recursive: true, force: true });+ fs.rmSync(targetSkillPath, { recursive: true, force: true });} else {- fs.unlinkSync(claudeSkillLink);+ fs.unlinkSync(targetSkillPath);}} catch {// lstatSync throws if nothing exists at the path β that's fine}- const relativeTarget = path.relative(path.dirname(claudeSkillLink), agentSkillDir);- fs.symlinkSync(relativeTarget, claudeSkillLink);+ const relativeTarget = path.relative(path.dirname(targetSkillPath), agentSkillDir);+ fs.symlinkSync(relativeTarget, targetSkillPath);- yield* ui.log.success('Installed composio-cli skill for Claude Code');+ yield* ui.log.success(`Installed ${skillName} skill for ${resolveTargetLabel(target)}`);});/**@@ -188,6 +239,8 @@ export const installSkill = (options?: {export const installSkillSafe = (options?: {readonly releaseTag?: string;readonly channel?: SkillReleaseChannel;+ readonly target?: SkillInstallTarget;+ readonly skillName?: string;}) =>installSkill(options).pipe(Effect.sandbox,@@ -195,7 +248,8 @@ export const installSkillSafe = (options?: {Effect.gen(function* () {const ui = yield* TerminalUI;yield* Effect.logDebug('Skill install failed:', cause);- yield* ui.log.warn('Could not install Claude Code skill (non-fatal)');+ const targetLabel = resolveTargetLabel(options?.target ?? 'claude');+ yield* ui.log.warn(`Could not install ${targetLabel} skill (non-fatal)`);})));diff --git a/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts b/ts/packages/cli/test/src/commands/install-skill-root-flag.test.tsnew file mode 100644index 000000000..257f672bf--- /dev/null+++ b/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts@@ -0,0 +1,73 @@+import { describe, expect, it } from '@effect/vitest';+import { parseRootInstallSkillRequest } from 'src/commands';++describe('CLI: --instal-skill', () => {+ it('parses the default skill name when only a target is provided', () => {+ expect(parseRootInstallSkillRequest(['node', 'composio', '--instal-skill', 'claude'])).toEqual({+ _tag: 'parsed',+ target: 'claude',+ });+ });++ it('parses an explicit skill name and target', () => {+ expect(+ parseRootInstallSkillRequest([+ 'node',+ 'composio',+ '--instal-skill',+ 'composio-cli',+ 'codex',+ ])+ ).toEqual({+ _tag: 'parsed',+ skillName: 'composio-cli',+ target: 'codex',+ });+ });++ it('accepts the --install-skill alias', () => {+ expect(parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'openclaw'])).toEqual(+ {+ _tag: 'parsed',+ target: 'openclaw',+ }+ );+ });++ it('accepts the root flag after leading global options', () => {+ expect(+ parseRootInstallSkillRequest([+ 'node',+ 'composio',+ '--log-level',+ 'debug',+ '--instal-skill',+ 'claude',+ ])+ ).toEqual({+ _tag: 'parsed',+ target: 'claude',+ });+ });++ it('does not intercept subcommand flags after a positional command', () => {+ expect(+ parseRootInstallSkillRequest(['node', 'composio', 'upgrade', '--install-skill', 'claude'])+ ).toBeUndefined();+ });++ it('returns a helpful error when the target is missing', () => {+ expect(parseRootInstallSkillRequest(['node', 'composio', '--instal-skill'])).toEqual({+ _tag: 'error',+ message:+ 'Missing target for --instal-skill. Usage: composio --instal-skill [skill-name] <claude|codex|openclaw>',+ });+ });++ it('returns a helpful error for invalid targets', () => {+ expect(parseRootInstallSkillRequest(['node', 'composio', '--instal-skill', 'cursor'])).toEqual({+ _tag: 'error',+ message: 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',+ });+ });+});diff --git a/ts/packages/cli/test/src/effects/install-skill.test.ts b/ts/packages/cli/test/src/effects/install-skill.test.tsindex 0766e80d1..b804ba8e2 100644--- a/ts/packages/cli/test/src/effects/install-skill.test.ts+++ b/ts/packages/cli/test/src/effects/install-skill.test.ts@@ -4,7 +4,9 @@ import { FetchHttpClient, HttpClient } from '@effect/platform';import { withHttpServer } from 'test/__utils__/http-server';import {inferSkillReleaseChannel,+ resolveInstalledSkillName,resolveSkillReleaseTag,+ resolveTargetSkillPath,type SkillReleaseChannel,} from 'src/effects/install-skill';import { GITHUB_CONFIG } from 'src/effects/github-config';@@ -43,6 +45,41 @@ describe('install-skill', () => {expect(inferSkillReleaseChannel('@composio/[email protected]')).toBe('beta');});+ it('defaults the installed skill name to composio-cli', () => {+ expect(resolveInstalledSkillName()).toBe('composio-cli');+ expect(resolveInstalledSkillName(' ')).toBe('composio-cli');+ });++ it('rejects unsafe installed skill names', () => {+ expect(() => resolveInstalledSkillName('../bad')).toThrow(/Invalid skill name/);+ expect(() => resolveInstalledSkillName('.')).toThrow(/Invalid skill name/);+ expect(() => resolveInstalledSkillName('..')).toThrow(/Invalid skill name/);+ });++ it('resolves the agent-specific skill path', () => {+ expect(+ resolveTargetSkillPath({+ home: '/tmp/test-home',+ skillName: 'composio-cli',+ target: 'claude',+ })+ ).toBe('/tmp/test-home/.claude/skills/composio-cli');+ expect(+ resolveTargetSkillPath({+ home: '/tmp/test-home',+ skillName: 'composio-cli',+ target: 'codex',+ })+ ).toBe('/tmp/test-home/.codex/skills/composio-cli');+ expect(+ resolveTargetSkillPath({+ home: '/tmp/test-home',+ skillName: 'composio-cli',+ target: 'openclaw',+ })+ ).toBe('/tmp/test-home/.openclaw/skills/composio-cli');+ });+it('resolves the latest stable release when the stable channel is requested', async () => {vi.stubGlobal('Bun', { which: vi.fn(() => null) });