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: adding cli touchups here (#3035)

Rahul Tarak8fcb46bd8be1
diff --git a/.github/workflows/build-cli-binaries.yml b/.github/workflows/build-cli-binaries.yml
index 3e853c2a6..b76a20b7e 100644
--- a/.github/workflows/build-cli-binaries.yml
+++ b/.github/workflows/build-cli-binaries.yml
@@ -119,6 +119,11 @@ jobs:
- name: Display checksums
run: 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 Release
uses: softprops/action-gh-release@v2
with:
diff --git a/ts/packages/cli/src/analytics/dispatch.ts b/ts/packages/cli/src/analytics/dispatch.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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, sharedDirecto
logId: '',
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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/Upg
yield* 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/Upg
yield* 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.ts
index 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.ts
index 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.ts
index 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');