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
feat: adding cli touchups here (#3035)
Rahul Tarak8fcb46bd8be1
diff --git a/.github/workflows/build-cli-binaries.yml b/.github/workflows/build-cli-binaries.ymlindex 3e853c2a6..b76a20b7e 100644--- a/.github/workflows/build-cli-binaries.yml+++ b/.github/workflows/build-cli-binaries.yml@@ -119,6 +119,11 @@ jobs:- name: Display checksumsrun: cat ts/packages/cli/dist/binaries/checksums.txt+ - name: Package skill files+ working-directory: ts/packages/cli+ run: |+ cd skills && zip -r ../dist/binaries/composio-skill.zip composio-cli/+- name: Create GitHub Releaseuses: softprops/action-gh-release@v2with:diff --git a/ts/packages/cli/src/analytics/dispatch.ts b/ts/packages/cli/src/analytics/dispatch.tsindex 4bf9814a0..11ac34955 100644--- a/ts/packages/cli/src/analytics/dispatch.ts+++ b/ts/packages/cli/src/analytics/dispatch.ts@@ -59,7 +59,11 @@ type ConsumerShortTermCacheState = Record<>;const ensureAnalyticsDir = () => {- fs.mkdirSync(analyticsDir(), { recursive: true });+ try {+ fs.mkdirSync(analyticsDir(), { recursive: true });+ } catch {+ // Non-fatal — analytics directory creation may fail in sandboxed environments.+ }};const encodeBase64Url = (value: string): string => {diff --git a/ts/packages/cli/src/cli-main.ts b/ts/packages/cli/src/cli-main.tsindex 2d1bbf431..92ef413ef 100644--- a/ts/packages/cli/src/cli-main.ts+++ b/ts/packages/cli/src/cli-main.ts@@ -6,6 +6,7 @@ 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 { matchCommandFromArgv, getCommandHelpText } from 'src/commands/root-help';import * as constants from 'src/constants';import { ComposioCliConfig } from 'src/cli-config';import { BaseConfigProviderLive, ConfigLive, extendConfigProvider } from 'src/services/config';@@ -104,6 +105,7 @@ const layers = Layer.mergeAll(ProjectContextLive,BunContext.layer,BunFileSystem.layer,+ FetchHttpClient.layer,StdinLive,TerminalUILive,Logger.pretty@@ -193,11 +195,22 @@ 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-]+)'/);- if (flagMatch && valueOptionNames.has(flagMatch[1])) {- return Console.error(`Tip: ${flagMatch[1]} requires a value, e.g. ${flagMatch[1]} "value"`);- }- return Effect.void;+ 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;+ })+ )+ );}),Effect.withSpan('composio-cli', {attributes: {@@ -225,6 +238,11 @@ runWithArgs.pipe().trim();if (message.length > 0) {yield* Console.error(message);+ const cmdName = matchCommandFromArgv(process.argv);+ const helpText = cmdName ? getCommandHelpText(cmdName) : undefined;+ if (helpText) {+ yield* Console.error(helpText);+ }process.exitCode = 1;}}diff --git a/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.link.cmd.ts b/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.link.cmd.tsindex efa099836..bafae296c 100644--- a/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.link.cmd.ts+++ b/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.link.cmd.ts@@ -6,9 +6,9 @@ import { ComposioUserContext } from 'src/services/user-context';import { TerminalUI } from 'src/services/terminal-ui';import { requireAuth } from 'src/effects/require-auth';import { resolveToolRouterSession } from 'src/effects/create-tool-router-session';-import { extractMessage } from 'src/utils/api-error-extraction';+import { extractMessage, extractSlug } from 'src/utils/api-error-extraction';import { ProjectContext } from 'src/services/project-context';-import { ComposioClientSingleton } from 'src/services/composio-clients';+import { ComposioClientSingleton, getSessionInfoByUserApiKey } from 'src/services/composio-clients';import {resolveCommandProject,formatResolveCommandProjectError,@@ -168,6 +168,40 @@ const validateLinkResponse = (});});+const handleNoManagedAuth = (ui: TerminalUI, toolkitSlug: string, noBrowser: boolean) =>+ Effect.gen(function* () {+ const userContext = yield* ComposioUserContext;+ const webURL = userContext.data.webURL.replace(/\/+$/, '');+ const apiKey = Option.getOrUndefined(userContext.data.apiKey);++ let orgSlug = '~';+ if (apiKey) {+ const sessionInfo = yield* getSessionInfoByUserApiKey({+ baseURL: userContext.data.baseURL,+ userApiKey: apiKey,+ }).pipe(Effect.catchAll(() => Effect.succeed(null)));++ if (sessionInfo?.project.org.name) {+ orgSlug = sessionInfo.project.org.name;+ }+ }++ const dashboardUrl = `${webURL}/${orgSlug}/~/connect/apps/${toolkitSlug}?open=true`;++ yield* ui.log.warn(+ `Composio does not manage auth for "${toolkitSlug}" — opening the dashboard to connect manually.`+ );++ if (!noBrowser) {+ yield* Effect.tryPromise(() => open(dashboardUrl, { wait: false })).pipe(+ Effect.catchAll(() => ui.log.warn('Could not open the browser automatically.'))+ );+ }++ yield* ui.note(dashboardUrl, 'Dashboard URL');+ yield* ui.output(dashboardUrl, noBrowser ? { force: true } : undefined);+ });+const runConnectedAccountsLink = (params: {toolkit: Option.Option<string>;authConfig: Option.Option<string>;@@ -345,6 +379,13 @@ const runConnectedAccountsLink = (params: {Effect.asSome,Effect.catchAll(error =>Effect.gen(function* () {+ const slug = extractSlug(error);++ if (slug === 'ToolRouterV2_NoManagedAuth') {+ yield* handleNoManagedAuth(ui, toolkitSlug, params.noBrowser);+ return Option.none();+ }+const message =extractMessage(error) ?? `Failed to create link for toolkit "${toolkitSlug}".`;yield* ui.log.error(message);@@ -352,6 +393,9 @@ const runConnectedAccountsLink = (params: {yield* ui.log.step('Browse available toolkits:\n> composio dev toolkits list');return Option.none();})+ ),+ Effect.tap(() =>+ invalidateConsumerConnectedToolkitsCache().pipe(Effect.catchAll(() => Effect.void))));@@ -361,7 +405,6 @@ const runConnectedAccountsLink = (params: {if (Option.isNone(validatedLink)) return;const { connectedAccountId: connAccountId, redirectUrl } = validatedLink.value;- yield* invalidateConsumerConnectedToolkitsCache().pipe(Effect.catchAll(() => Effect.void));if (params.noWait) {yield* showRedirectUrl(ui, redirectUrl, params.noBrowser);diff --git a/ts/packages/cli/src/commands/login.cmd.ts b/ts/packages/cli/src/commands/login.cmd.tsindex f74eb966d..6d2382208 100644--- a/ts/packages/cli/src/commands/login.cmd.ts+++ b/ts/packages/cli/src/commands/login.cmd.ts@@ -12,6 +12,7 @@ import { TerminalUI } from 'src/services/terminal-ui';import { commandHintStep } from 'src/services/command-hints';import { runOrgSelection } from 'src/effects/select-org-project';import { primeConsumerConnectedToolkitsCacheInBackground } from 'src/services/consumer-short-term-cache';+import { installSkillSafe } from 'src/effects/install-skill';export const noBrowser = Options.boolean('no-browser').pipe(Options.withDefault(false),@@ -36,6 +37,11 @@ const yesOpt = Options.boolean('yes').pipe(Options.withDescription('Skip org picker; use session default org'));+const noSkillInstall = Options.boolean('no-skill-install').pipe(+ Options.withDefault(false),+ Options.withDescription('Skip installing the composio-cli skill for Claude Code')+);+/*** Verifies credentials via session/info and stores them.*@@ -433,8 +439,8 @@ export const browserLogin = (params: {*/export const loginCmd = Command.make('login',- { noBrowser, noWait, key: keyOpt, yes: yesOpt },- ({ noBrowser, noWait, key, yes }) =>+ { noBrowser, noWait, key: keyOpt, yes: yesOpt, noSkillInstall },+ ({ noBrowser, noWait, key, yes, noSkillInstall }) =>Effect.gen(function* () {const ui = yield* TerminalUI;const ctx = yield* ComposioUserContext;@@ -447,6 +453,9 @@ export const loginCmd = Command.make(noWait,skipOrgProjectPicker: true,});+ if (!noSkillInstall) {+ yield* installSkillSafe();+ }return;}@@ -467,5 +476,9 @@ export const loginCmd = Command.make(noWait,skipOrgProjectPicker: yes,});++ if (!noSkillInstall && !noWait) {+ yield* installSkillSafe();+ }})).pipe(Command.withDescription('Log in to the Composio SDK.'));diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.tsindex 4fe68f703..51125bf2f 100644--- a/ts/packages/cli/src/commands/root-help.ts+++ b/ts/packages/cli/src/commands/root-help.ts@@ -411,8 +411,10 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp> = {// ── Account commands ──────────────────────────────────────────────────login: {- usage: 'composio login [--no-browser] [--no-wait] [--key text] [-y, --yes]',- description: 'Log in to the Composio CLI session.',+ usage:+ 'composio login [--no-browser] [--no-wait] [--key text] [-y, --yes] [--no-skill-install]',+ description:+ 'Log in to the Composio CLI session. By default, also installs the composio-cli skill for Claude Code.',options: [{name: '--key <text>',@@ -423,6 +425,10 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp> = {{ name: '--no-browser', description: 'Login without browser interaction' },{ name: '--no-wait', description: 'Print login URL and session info, then exit' },{ name: '-y, --yes', description: 'Skip org picker; use session default org' },+ {+ name: '--no-skill-install',+ description: 'Skip installing the composio-cli skill for Claude Code',+ },],},logout: {@@ -441,6 +447,39 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp> = {usage: 'composio upgrade',description: 'Upgrade your Composio CLI to the latest available version.',},+ files: {+ usage: 'composio files',+ description: 'Where the Composio CLI stores data on disk.',+ examples: [+ '~/.composio/',+ ' CLI configuration and cache directory.',+ ' user_data.json Your auth state (API key, org, base URL)',+ ' toolkits.json Cached toolkit list from the API',+ ' tools.json Cached tool definitions',+ ' trigger-types.json Cached trigger type definitions',+ ' consumer-short-term-cache.json Per-org connected toolkits cache (15-min TTL)',+ ' analytics.json Anonymous install ID for telemetry',+ '',+ ' All caches are safe to delete — they will be re-fetched on next use.',+ '',+ '$TMPDIR/composio/ (or COMPOSIO_SESSION_DIR / COMPOSIO_CACHE_DIR)',+ ' Session artifacts directory. Each CLI session gets a unique subdirectory',+ ' scoped to your working directory. Stores session history and files',+ ' created during `run` and `execute` (e.g. large tool outputs).',+ ' Use `composio artifacts cwd` to print the current session path.',+ '',+ '.composio/ (per-project, optional)',+ ' Per-directory project config. Scoped to the nearest parent that has one.',+ ' .env Allows COMPOSIO_ORG_ID and COMPOSIO_PROJECT_ID overrides',+ ' project.json Project context (org, project binding)',+ '',+ 'Environment variables that control paths:',+ ' COMPOSIO_SESSION_DIR Override session artifacts root',+ ' COMPOSIO_CACHE_DIR Override cache directory (also used for artifacts fallback)',+ ' COMPOSIO_CACHE_DIR is useful in sandboxed environments where ~/.composio or',+ ' $TMPDIR may not be writable.',+ ],+ },// ── Tools commands ────────────────────────────────────────────────────@@ -865,6 +904,29 @@ export function printSubcommandHelp(cmd: string): Effect.Effect<void> {return Console.log(renderSubcommandHelp(help));}+/**+ * 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 {+ 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--) {+ const key = args.slice(0, len).join(' ');+ if (key in SUBCOMMAND_HELP) return key;+ }+ return undefined;+}++/**+ * Get rendered help text for a command, or undefined if not found.+ */+export function getCommandHelpText(cmd: string): string | undefined {+ const help = SUBCOMMAND_HELP[cmd];+ if (!help) return undefined;+ return renderSubcommandHelp(help);+}+// ── Main help output ───────────────────────────────────────────────────/**@@ -896,14 +958,19 @@ export function printRootHelp(): Effect.Effect<void> {...renderCompactCommands(OTHER_COMMANDS),'',bold('EXAMPLES'),- ` ${dim('# Find a tool')}`,- ` ${name} search "create github issue"`,+ ` ${dim('# Find tools — supports multiple queries at once')}`,+ ` ${name} search "send an email" "create github issue"`,+ ` ${name} search "list calendar events" --toolkits google_calendar --limit 5`,'',- ` ${dim('# Connect your GitHub account')}`,+ ` ${dim('# Connect your account for a toolkit')}`,` ${name} link github`,'',` ${dim('# Execute a tool')}`,- ` ${name} execute GITHUB_CREATE_ISSUE -d '{ repo: "owner/repo", title: "Bug" }'`,+ ` ${name} execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,+ '',+ ` ${dim('# Execute multiple tools in parallel')}`,+ ` ${name} execute -p GMAIL_SEND_EMAIL -d '{ recipient_email: "[email protected]", subject: "Hi" }' \\`,+ ` SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL -d '{ channel: "general", text: "Hello" }'`,'',` ${dim('# Call an API directly through proxy')}`,` ${name} proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail`,@@ -911,12 +978,36 @@ export function printRootHelp(): 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('# Run a multi-step script with Promise.all')}`,+ ` ${name} run '`,+ ` const [emails, issues] = await Promise.all([`,+ ` execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),`,+ ` execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),`,+ ` ]);`,+ ` const brief = await subAgent(\`Summarize:\\n\${emails.prompt()}\\n\${issues.prompt()}\`);`,+ ` console.log(brief);`,+ ` '`,+ '',bold('DEVELOPER COMMANDS'),...renderCompactCommands(DEVELOPER_COMMANDS),'',bold('ACCOUNT'),...renderCompactCommands(ACCOUNT_COMMANDS),'',+ 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),`,+ ` trigger types, and per-org consumer caches. These caches speed up`,+ ` repeated commands — safe to delete, they will be re-fetched on next use.`,+ '',+ ` ${bold('/tmp/composio/')}`,+ ` Session artifacts directory. Each CLI session gets a unique subdirectory`,+ ` scoped to your working directory. Stores session history and files`,+ ` created during ${bold('run')} and ${bold('execute')} commands (e.g. downloaded attachments,`,+ ` generated outputs). Use \`${name} artifacts cwd\` to print the path for`,+ ` the current directory's session.`,+ '',bold('FLAGS'),' -h, --help Show help for command',` --version Show ${name} version`,diff --git a/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts b/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.tsindex e79d190ee..7f7c9286b 100644--- a/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts+++ b/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts@@ -210,7 +210,7 @@ const persistLargeExecuteOutput = (toolSlug: string, json: string, sharedDirectologId: '',storedInFile: true,tokenCount: getExecuteOutputEncoder().encode(json).length,- outputFilePath,+ outputFilePath: outputFilePath ?? '(could not write to disk)',} satisfies StoredExecuteOutputSummary;});diff --git a/ts/packages/cli/src/commands/upgrade.cmd.ts b/ts/packages/cli/src/commands/upgrade.cmd.tsindex f8e7c1087..0ea5282fa 100644--- a/ts/packages/cli/src/commands/upgrade.cmd.ts+++ b/ts/packages/cli/src/commands/upgrade.cmd.ts@@ -1,6 +1,7 @@import { Command } from '@effect/cli';import { Effect } from 'effect';import { UpgradeBinary } from 'src/services/upgrade-binary';+import { installSkillSafe } from 'src/effects/install-skill';/*** CLI command to upgrade the CLI to the latest available version.@@ -13,6 +14,9 @@ import { UpgradeBinary } from 'src/services/upgrade-binary';export const upgradeCmd = Command.make('upgrade', {}, () =>Effect.gen(function* () {const upgradeBinary = yield* UpgradeBinary;- yield* upgradeBinary.upgrade();+ const newReleaseTag = yield* upgradeBinary.upgrade();+ if (newReleaseTag) {+ yield* installSkillSafe({ releaseTag: newReleaseTag });+ }})).pipe(Command.withDescription('Upgrade your Composio CLI to the latest available version.'));diff --git a/ts/packages/cli/src/effects/install-skill.ts b/ts/packages/cli/src/effects/install-skill.tsnew file mode 100644index 000000000..3b4d1b14f--- /dev/null+++ b/ts/packages/cli/src/effects/install-skill.ts@@ -0,0 +1,140 @@+import * as fs from 'node:fs';+import * as path from 'node:path';+import { Effect, Config, Option } from 'effect';+import { HttpClient } from '@effect/platform';+import { NodeOs } from 'src/services/node-os';+import { TerminalUI } from 'src/services/terminal-ui';+import { GITHUB_CONFIG } from 'src/effects/github-config';+import { APP_VERSION } from 'src/constants';+import decompress from 'decompress';++const SKILL_NAME = 'composio-cli';+const SKILL_ASSET_NAME = 'composio-skill.zip';++/**+ * 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+ *+ * Non-fatal: wrapped version catches all errors.+ */+export const installSkill = (options?: { readonly releaseTag?: string }) =>+ Effect.gen(function* () {+ const os = yield* NodeOs;+ const ui = yield* TerminalUI;+ const httpClient = yield* HttpClient.HttpClient;+ const githubConfig = yield* Config.all(GITHUB_CONFIG);+ const home = os.homedir;++ const agentSkillDir = path.join(home, '.agents', 'skills', SKILL_NAME);+ const claudeSkillLink = path.join(home, '.claude', 'skills', SKILL_NAME);++ // Resolve the release tag — prefer explicit override, then env config, then current version+ const tag =+ options?.releaseTag ??+ Option.getOrElse(githubConfig.TAG, () => `@composio/cli@${APP_VERSION}`);++ // Find the skill asset URL from the release+ const releaseUrl = `${githubConfig.API_BASE_URL}/repos/${githubConfig.OWNER}/${githubConfig.REPO}/releases/tags/${encodeURIComponent(tag)}`;+ const releaseResponse = yield* httpClient+ .get(releaseUrl)+ .pipe(+ Effect.catchAll(error => Effect.fail(new Error(`Failed to fetch release ${tag}: ${error}`)))+ );++ if (releaseResponse.status < 200 || releaseResponse.status >= 300) {+ return yield* Effect.fail(+ new Error(`Release ${tag} not found (HTTP ${releaseResponse.status})`)+ );+ }++ const release = (yield* releaseResponse.json.pipe(+ Effect.catchAll(() => Effect.fail(new Error('Failed to parse release JSON')))+ )) as { assets: Array<{ name: string; browser_download_url: string }> };++ const skillAsset = release.assets.find(a => a.name === SKILL_ASSET_NAME);+ if (!skillAsset) {+ return yield* Effect.fail(+ new Error(`Skill asset ${SKILL_ASSET_NAME} not found in release ${tag}`)+ );+ }++ // Download the skill zip+ const downloadResponse = yield* httpClient+ .get(skillAsset.browser_download_url)+ .pipe(Effect.catchAll(error => Effect.fail(new Error(`Failed to download skill: ${error}`))));++ if (downloadResponse.status < 200 || downloadResponse.status >= 300) {+ return yield* Effect.fail(+ new Error(`Failed to download skill (HTTP ${downloadResponse.status})`)+ );+ }++ const zipData = yield* downloadResponse.arrayBuffer.pipe(+ Effect.catchAll(() => Effect.fail(new Error('Failed to read skill zip data')))+ );++ // Extract to a temp dir, then move into place+ const tmpDir = path.join(os.homedir, '.agents', '.tmp-skill-install');+ fs.mkdirSync(tmpDir, { recursive: true });++ try {+ const zipPath = path.join(tmpDir, SKILL_ASSET_NAME);+ fs.writeFileSync(zipPath, new Uint8Array(zipData));++ yield* Effect.tryPromise({+ try: () => decompress(zipPath, tmpDir),+ catch: error => new Error(`Failed to extract skill zip: ${error}`),+ });++ // The zip contains composio-cli/ directory+ const extractedDir = path.join(tmpDir, SKILL_NAME);+ if (!fs.existsSync(extractedDir)) {+ return yield* Effect.fail(new Error('Extracted skill directory not found'));+ }++ // Remove old skill dir and move new one into place+ fs.rmSync(agentSkillDir, { recursive: true, force: true });+ fs.mkdirSync(path.dirname(agentSkillDir), { recursive: true });+ fs.cpSync(extractedDir, agentSkillDir, { recursive: true });+ } finally {+ 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 });+ try {+ const stat = fs.lstatSync(claudeSkillLink);+ // Entry exists (symlink, broken symlink, or directory) — remove it+ if (stat.isSymbolicLink()) {+ fs.unlinkSync(claudeSkillLink);+ } else if (stat.isDirectory()) {+ fs.rmSync(claudeSkillLink, { recursive: true, force: true });+ } else {+ fs.unlinkSync(claudeSkillLink);+ }+ } catch {+ // lstatSync throws if nothing exists at the path — that's fine+ }+ const relativeTarget = path.relative(path.dirname(claudeSkillLink), agentSkillDir);+ fs.symlinkSync(relativeTarget, claudeSkillLink);++ yield* ui.log.success('Installed composio-cli skill for Claude Code');+ });++/**+ * Wrapped version that catches all errors and logs a warning instead of failing.+ */+export const installSkillSafe = (options?: { readonly releaseTag?: string }) =>+ installSkill(options).pipe(+ Effect.sandbox,+ Effect.catchAll(cause =>+ 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)');+ })+ )+ );diff --git a/ts/packages/cli/src/services/cli-session-artifacts.ts b/ts/packages/cli/src/services/cli-session-artifacts.tsindex bfd90a7c3..6cd127b0c 100644--- a/ts/packages/cli/src/services/cli-session-artifacts.ts+++ b/ts/packages/cli/src/services/cli-session-artifacts.ts@@ -1,9 +1,14 @@import fs from 'node:fs';+import os from 'node:os';import path from 'node:path';import { Effect, Option } from 'effect';import { getOrCreateProbablyMyCliSessionIdForCurrentCwd } from 'src/services/consumer-short-term-cache';-const CLI_SESSION_ARTIFACTS_ROOT = '/tmp/composio';+const resolveArtifactsRoot = (): string =>+ process.env.COMPOSIO_SESSION_DIR?.trim() ||+ process.env.COMPOSIO_CACHE_DIR?.trim() ||+ path.join(os.tmpdir(), 'composio');+const SESSION_HISTORY_FILE = 'session-history.jsonl';export type CliSessionArtifacts = {@@ -22,13 +27,19 @@ export const resolveCliSessionArtifacts = (params?: {readonly consumerUserId?: string;}) =>Effect.gen(function* () {- const sessionIdOption = yield* getOrCreateProbablyMyCliSessionIdForCurrentCwd(params);+ const sessionIdOption = yield* getOrCreateProbablyMyCliSessionIdForCurrentCwd(params).pipe(+ Effect.catchAll(() => Effect.succeed(Option.none<string>()))+ );if (Option.isNone(sessionIdOption)) {return Option.none<CliSessionArtifacts>();}- const directoryPath = path.join(CLI_SESSION_ARTIFACTS_ROOT, sessionIdOption.value);- fs.mkdirSync(directoryPath, { recursive: true });+ const directoryPath = path.join(resolveArtifactsRoot(), sessionIdOption.value);+ try {+ fs.mkdirSync(directoryPath, { recursive: true });+ } catch {+ return Option.none<CliSessionArtifacts>();+ }return Option.some({sessionId: sessionIdOption.value,directoryPath,@@ -55,7 +66,11 @@ export const appendCliSessionHistory = (params: {sessionId: artifactsOption.value.sessionId,...params.entry,});- fs.appendFileSync(artifactsOption.value.historyFilePath, `${line}\n`, 'utf8');+ try {+ fs.appendFileSync(artifactsOption.value.historyFilePath, `${line}\n`, 'utf8');+ } catch {+ // Best-effort — session history write is non-fatal.+ }});export const storeCliSessionArtifact = (params: {@@ -75,14 +90,18 @@ export const storeCliSessionArtifact = (params: {consumerUserId: params.consumerUserId,}).pipe(Effect.map(Option.map(artifacts => artifacts.directoryPath)))) ||- path.join(CLI_SESSION_ARTIFACTS_ROOT, `adhoc_${randomToken(12)}`);+ path.join(resolveArtifactsRoot(), `adhoc_${randomToken(12)}`);- fs.mkdirSync(directoryPath, { recursive: true });- const extension = (params.extension ?? 'json').replace(/^\.+/, '') || 'json';- const filePath = path.join(- directoryPath,- `${sanitizeArtifactName(params.name)}_${randomToken()}.${extension}`- );- fs.writeFileSync(filePath, params.contents, 'utf8');- return filePath;+ try {+ fs.mkdirSync(directoryPath, { recursive: true });+ const extension = (params.extension ?? 'json').replace(/^\.+/, '') || 'json';+ const filePath = path.join(+ directoryPath,+ `${sanitizeArtifactName(params.name)}_${randomToken()}.${extension}`+ );+ fs.writeFileSync(filePath, params.contents, 'utf8');+ return filePath;+ } catch {+ return undefined;+ }});diff --git a/ts/packages/cli/src/services/consumer-short-term-cache.ts b/ts/packages/cli/src/services/consumer-short-term-cache.tsindex b33fd4c9b..a9decce28 100644--- a/ts/packages/cli/src/services/consumer-short-term-cache.ts+++ b/ts/packages/cli/src/services/consumer-short-term-cache.ts@@ -101,8 +101,10 @@ const writeCache = (state: CacheState) =>Effect.gen(function* () {const fs = yield* FileSystem.FileSystem;const cacheDir = yield* setupCacheDir;- yield* fs.makeDirectory(cacheDir, { recursive: true });- yield* fs.writeFileString(cachePath(cacheDir), JSON.stringify(state, null, 2));+ yield* fs.makeDirectory(cacheDir, { recursive: true }).pipe(Effect.catchAll(() => Effect.void));+ yield* fs+ .writeFileString(cachePath(cacheDir), JSON.stringify(state, null, 2))+ .pipe(Effect.catchAll(() => Effect.void));});const getAlwaysConnectedNoAuthToolkits = () =>diff --git a/ts/packages/cli/src/services/master-detector.ts b/ts/packages/cli/src/services/master-detector.tsindex 19bd0b5aa..90870caa8 100644--- a/ts/packages/cli/src/services/master-detector.ts+++ b/ts/packages/cli/src/services/master-detector.ts@@ -1,9 +1,9 @@export type MasterKind = 'claude' | 'codex' | 'user';-const hasEnvPrefix = (env: NodeJS.ProcessEnv, prefix: string): boolean =>+const hasEnvPrefix = (env: Record<string, string | undefined>, prefix: string): boolean =>Object.keys(env).some(key => key.startsWith(prefix));-export const detectMaster = (env: NodeJS.ProcessEnv = process.env): MasterKind => {+export const detectMaster = (env: Record<string, string | undefined> = process.env): MasterKind => {if (hasEnvPrefix(env, 'CODEX_')) {return 'codex';}diff --git a/ts/packages/cli/src/services/upgrade-binary.ts b/ts/packages/cli/src/services/upgrade-binary.tsindex 6ca7d8d9b..2f6abc88a 100644--- a/ts/packages/cli/src/services/upgrade-binary.ts+++ b/ts/packages/cli/src/services/upgrade-binary.ts@@ -482,7 +482,7 @@ export class UpgradeBinary extends Effect.Service<UpgradeBinary>()('services/Upgyield* ui.log.info(`New local version available (current: ${APP_VERSION})`);yield* replaceBinary(upgradeTargetOpt.value, currentPath);yield* ui.outro('Upgrade completed');- return;+ return undefined;}const didUpgrade = yield* ui.useMakeSpinner('Checking for updates...', spinner =>@@ -535,13 +535,15 @@ export class UpgradeBinary extends Effect.Service<UpgradeBinary>()('services/Upgyield* replaceBinary(extractedBinaryPath, currentPath);yield* spinner.stop('Upgrade completed!');- return true;+ return release.tag_name;}));yield* ui.outro(didUpgrade ? 'Restart your terminal to use the new version.' : 'No upgrade needed.');++ return didUpgrade || undefined; // release tag string, or undefined if no upgrade});return {diff --git a/ts/packages/cli/src/utils/api-error-extraction.ts b/ts/packages/cli/src/utils/api-error-extraction.tsindex 0e5c4de09..4e7926fcd 100644--- a/ts/packages/cli/src/utils/api-error-extraction.ts+++ b/ts/packages/cli/src/utils/api-error-extraction.ts@@ -22,26 +22,40 @@ export type ApiErrorDetails = {* Extract a human-readable message from an unknown error value.* Checks `.message`, then `.error` (string or `.error.message`).*/-export const extractMessage = (value: unknown): string | undefined => {+export const extractMessage = (value: unknown, seen?: Set<unknown>): string | undefined => {if (typeof value === 'string') return value;- if (value instanceof Error) return value.message;++ // Walk the .cause / .error chain to find the deepest meaningful message.+ // Effect's UnknownException stores the real error in .cause; the Composio SDK+ // stores the API response body in .error (which itself has .error.message).+ // We prefer the deepest message because outer wrappers often have generic+ // messages like "An unknown error occurred in Effect.tryPromise".if (value && typeof value === 'object') {- if ('message' in value && typeof (value as { message?: unknown }).message === 'string') {- return (value as { message: string }).message;+ const visited = seen ?? new Set<unknown>();+ if (visited.has(value)) return undefined;+ visited.add(value);++ // Try .cause chain first (Effect's UnknownException → real SDK error)+ if ('cause' in value) {+ const causeMsg = extractMessage((value as { cause?: unknown }).cause, visited);+ if (causeMsg) return causeMsg;}++ // Try .error chain (SDK error → API response body → nested .error.message)if ('error' in value) {const inner = (value as { error?: unknown }).error;- if (typeof inner === 'string') return inner;- if (- inner &&- typeof inner === 'object' &&- 'message' in inner &&- typeof (inner as { message?: unknown }).message === 'string'- ) {- return (inner as { message: string }).message;- }+ const innerMsg = extractMessage(inner, visited);+ if (innerMsg) return innerMsg;+ }++ // Fall back to the wrapper's own message+ if ('message' in value && typeof (value as { message?: unknown }).message === 'string') {+ return (value as { message: string }).message;}}++ if (value instanceof Error) return value.message;+return undefined;};diff --git a/ts/packages/cli/test/__utils__/services/test-layer.ts b/ts/packages/cli/test/__utils__/services/test-layer.tsindex 8d6254c9d..a1a47ea36 100644--- a/ts/packages/cli/test/__utils__/services/test-layer.ts+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts@@ -873,7 +873,9 @@ export const TestLayer = (input?: TestLiveInput) =>primary_tool_slugs: matchedTools.map(tool => tool.slug),related_tool_slugs: [],toolkits: Array.from(- new Set(matchedTools.map(tool => tool.slug.split('_')[0]?.toLowerCase() ?? '').filter(Boolean))+ new Set(+ matchedTools.map(tool => tool.slug.split('_')[0]?.toLowerCase() ?? '').filter(Boolean)+ )),matchedTools,};@@ -1109,6 +1111,7 @@ export const TestLayer = (input?: TestLiveInput) =>BunContext.layer,MockTerminal.layer,BunPath.layer,+ FetchHttpClient.layer,ConsumerProjectResolveFetchMock,StdinTest,TerminalUILayer,diff --git a/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts b/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.tsindex 3390aae3d..9c59be059 100644--- a/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts+++ b/ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts@@ -438,7 +438,7 @@ describe('CLI: composio execute', () => {expect(output.logId).toBe('log_large_output');expect(output.tokenCount).toBeGreaterThan(10_000);expect(output.outputFilePath).toMatch(- /^\/tmp\/composio\/[^/]+\/GMAIL_SEND_EMAIL_OUTPUT_[^.]+\.json$/+ /composio\/[^/]+\/GMAIL_SEND_EMAIL_OUTPUT_[^.]+\.json$/);expect(fs.existsSync(output.outputFilePath)).toBe(true);const storedJson = fs.readFileSync(output.outputFilePath, 'utf8');