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): stamp telemetry with journey_stage + cli_channel; tag installer origin

Kshitij Jhunjhunwala5254e9075192
diff --git a/install.sh b/install.sh
index 6a2488de5..fbd6233ab 100755
--- a/install.sh
+++ b/install.sh
@@ -310,7 +310,7 @@ success "Composio CLI was installed successfully to $Bold_Green$(tildify "$exe")
echo
install_err=$(mktemp)
-if COMPOSIO_INSTALL_DIR="$COMPOSIO_INSTALL_DIR" "$exe" install 2>"$install_err"; then
+if COMPOSIO_INSTALL_DIR="$COMPOSIO_INSTALL_DIR" COMPOSIO_CLI_INVOCATION_ORIGIN=installer "$exe" install 2>"$install_err"; then
cat "$install_err" >&2 # Show CLI's TerminalUI output on success
else
info "Setting up shell integration..."
diff --git a/ts/packages/cli/CHANGELOG.md b/ts/packages/cli/CHANGELOG.md
index e8a938bcf..06da0dc36 100644
--- a/ts/packages/cli/CHANGELOG.md
+++ b/ts/packages/cli/CHANGELOG.md
@@ -11,6 +11,7 @@
### Minor Changes
- Telemetry now delivers directly to PostHog, so pre-login `install`/`setup` events are captured. Opt-outs are unchanged.
+- Telemetry events now carry `journey_stage` (install/setup/login/connect/execute/other) and `cli_channel` (stable/beta) properties, and `install.sh` marks its `composio install` run with `invocation_origin: installer` so script installs are distinguishable from manual ones. npm and Homebrew installs do not run `install.sh`, so they emit no install-stage events.
- a0bef5d: Bump `@composio/client` to `0.1.0-alpha.74`.
- 025a657: Drop CommonJS entrypoints and publish the TypeScript SDK packages as ESM-only packages. This is a breaking change within the existing 0.x release line: consumers must use Node.js 22.22.3 or newer. CommonJS callers can only rely on Node's native `require(esm)` interop, and the SDK no longer ships custom CommonJS compatibility machinery or `.cjs` artifacts.
diff --git a/ts/packages/cli/src/analytics/events.ts b/ts/packages/cli/src/analytics/events.ts
index 7bf73c077..df0807270 100644
--- a/ts/packages/cli/src/analytics/events.ts
+++ b/ts/packages/cli/src/analytics/events.ts
@@ -1,4 +1,6 @@
import type { CliCommandTelemetryContext, TrackEvent } from './types';
+import { APP_VERSION } from 'src/constants';
+import { inferSkillReleaseChannel } from 'src/effects/install-skill';
import { ToolInputValidationError } from 'src/services/tool-input-validation';
import { toolkitFromToolSlug } from 'src/utils/toolkit-from-tool-slug';
@@ -44,6 +46,75 @@ export const CLI_ANALYTICS_EVENTS = {
CLI_TOOL_INVOCATION_FAILED: 'CLI_TOOL_INVOCATION_FAILED',
} as const;
+type CliAnalyticsEventName = (typeof CLI_ANALYTICS_EVENTS)[keyof typeof CLI_ANALYTICS_EVENTS];
+
+// Contract with the downstream metrics flow page: stage values group the
+// adoption funnel, so renaming or removing one is a breaking change there.
+export const CLI_JOURNEY_STAGES = [
+ 'install',
+ 'setup',
+ 'login',
+ 'connect',
+ 'execute',
+ 'other',
+] as const;
+
+export type CliJourneyStage = (typeof CLI_JOURNEY_STAGES)[number];
+
+export const CLI_EVENT_JOURNEY_STAGES = {
+ CLI_COMMAND_INVOKED: 'other',
+ CLI_COMMAND_SUCCEEDED: 'other',
+ CLI_COMMAND_FAILED: 'other',
+ CLI_EXECUTE_INVOKED: 'execute',
+ CLI_EXECUTE_SUCCEEDED: 'execute',
+ CLI_EXECUTE_FAILED: 'execute',
+ CLI_SEARCH_INVOKED: 'other',
+ CLI_SEARCH_SUCCEEDED: 'other',
+ CLI_SEARCH_FAILED: 'other',
+ CLI_LINK_INVOKED: 'connect',
+ CLI_LINK_SUCCEEDED: 'connect',
+ CLI_LINK_FAILED: 'connect',
+ CLI_LOGIN_INVOKED: 'login',
+ CLI_LOGIN_SUCCEEDED: 'login',
+ CLI_LOGIN_FAILED: 'login',
+ CLI_LOGOUT_INVOKED: 'other',
+ CLI_LOGOUT_SUCCEEDED: 'other',
+ CLI_LOGOUT_FAILED: 'other',
+ CLI_PROXY_INVOKED: 'other',
+ CLI_PROXY_SUCCEEDED: 'other',
+ CLI_PROXY_FAILED: 'other',
+ CLI_RUN_INVOKED: 'other',
+ CLI_RUN_SUCCEEDED: 'other',
+ CLI_RUN_FAILED: 'other',
+ CLI_INSTALL_INVOKED: 'install',
+ CLI_INSTALL_SUCCEEDED: 'install',
+ CLI_INSTALL_FAILED: 'install',
+ CLI_SETUP_INVOKED: 'setup',
+ CLI_SETUP_SUCCEEDED: 'setup',
+ CLI_SETUP_FAILED: 'setup',
+ CLI_SETUP_HOST_DETECTED: 'setup',
+ CLI_SETUP_CANCELLED: 'setup',
+ CLI_SETUP_SKIPPED: 'setup',
+ CLI_PLUGIN_SETUP_SUCCEEDED: 'setup',
+ CLI_PLUGIN_SETUP_FAILED: 'setup',
+ CLI_PLUGIN_UNINSTALL_SUCCEEDED: 'setup',
+ CLI_TOOL_INVOCATION_VALIDATION_FAILED: 'execute',
+ CLI_TOOL_INVOCATION_TOOL_NOT_FOUND: 'execute',
+ CLI_TOOL_INVOCATION_FAILED: 'execute',
+} as const satisfies Record<CliAnalyticsEventName, CliJourneyStage>;
+
+const buildEvent = (
+ name: CliAnalyticsEventName,
+ properties: Record<string, unknown>
+): TrackEvent => ({
+ name,
+ properties: {
+ ...properties,
+ journey_stage: CLI_EVENT_JOURNEY_STAGES[name],
+ cli_channel: inferSkillReleaseChannel(APP_VERSION),
+ },
+});
+
const KNOWN_COMMAND_TOKENS = new Set([
'version',
'upgrade',
@@ -400,9 +471,8 @@ export const createCliCommandTelemetryContext = (
: undefined,
});
-const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_INVOKED,
- properties: {
+const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_INVOKED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
cli_version: context.cliVersion,
@@ -411,27 +481,23 @@ const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEv
arg_count: Math.max(0, context.argv.length - 2),
stdout_is_tty: context.stdoutIsTTY,
stderr_is_tty: context.stderrIsTTY,
- },
-});
+ });
-const getCliCommandSucceededEvent = (context: CliCommandTelemetryContext): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_SUCCEEDED,
- properties: {
+const getCliCommandSucceededEvent = (context: CliCommandTelemetryContext): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_SUCCEEDED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
cli_version: context.cliVersion,
command_path: context.commandPath,
duration_ms: Date.now() - context.startedAt,
flag_names: context.flagNames,
- },
-});
+ });
const getCliCommandFailedEvent = (
context: CliCommandTelemetryContext,
error: unknown
-): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED,
- properties: {
+): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
cli_version: context.cliVersion,
@@ -440,14 +506,13 @@ const getCliCommandFailedEvent = (
flag_names: context.flagNames,
error_name: errorNameOf(error),
error_message: errorMessageOf(error),
- },
-});
+ });
type SpecialLifecycleFamily = {
readonly match: (commandPath: string) => boolean;
- readonly invokedEventName: string;
- readonly succeededEventName: string;
- readonly failedEventName: string;
+ readonly invokedEventName: CliAnalyticsEventName;
+ readonly succeededEventName: CliAnalyticsEventName;
+ readonly failedEventName: CliAnalyticsEventName;
readonly getProperties: (context: CliCommandTelemetryContext) => Record<string, unknown>;
};
@@ -527,10 +592,7 @@ export const getPrimaryLifecycleInvokedEvent = (
if (!family || isGenericOnlyCommand(context.commandPath)) {
return getCliCommandInvokedEvent(context);
}
- return {
- name: family.invokedEventName,
- properties: family.getProperties(context),
- };
+ return buildEvent(family.invokedEventName, family.getProperties(context));
};
export const getPrimaryLifecycleSucceededEvent = (
@@ -540,10 +602,7 @@ export const getPrimaryLifecycleSucceededEvent = (
if (!family || isGenericOnlyCommand(context.commandPath)) {
return getCliCommandSucceededEvent(context);
}
- return {
- name: family.succeededEventName,
- properties: family.getProperties(context),
- };
+ return buildEvent(family.succeededEventName, family.getProperties(context));
};
export const getPrimaryLifecycleFailedEvent = (
@@ -554,14 +613,11 @@ export const getPrimaryLifecycleFailedEvent = (
if (!family || isGenericOnlyCommand(context.commandPath)) {
return getCliCommandFailedEvent(context, error);
}
- return {
- name: family.failedEventName,
- properties: {
- ...family.getProperties(context),
- error_name: errorNameOf(error),
- error_message: errorMessageOf(error),
- },
- };
+ return buildEvent(family.failedEventName, {
+ ...family.getProperties(context),
+ error_name: errorNameOf(error),
+ error_message: errorMessageOf(error),
+ });
};
export const getPluginLifecycleSucceededEvent = (params: {
@@ -569,21 +625,21 @@ export const getPluginLifecycleSucceededEvent = (params: {
readonly target: 'claude' | 'codex';
readonly action: 'installed' | 'enabled' | 'configured' | 'uninstalled';
readonly cliVersion: string;
-}): TrackEvent => ({
- name:
+}): TrackEvent =>
+ buildEvent(
params.operation === 'uninstall'
? CLI_ANALYTICS_EVENTS.CLI_PLUGIN_UNINSTALL_SUCCEEDED
: CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_SUCCEEDED,
- properties: {
- source: 'cli',
- invocation_origin: getInvocationOrigin(),
- cli_version: params.cliVersion,
- command_path: 'setup',
- operation: params.operation,
- agent_host: params.target,
- action: params.action,
- },
-});
+ {
+ source: 'cli',
+ invocation_origin: getInvocationOrigin(),
+ cli_version: params.cliVersion,
+ command_path: 'setup',
+ operation: params.operation,
+ agent_host: params.target,
+ action: params.action,
+ }
+ );
export const getPluginLifecycleFailedEvent = (params: {
readonly operation: 'setup' | 'uninstall';
@@ -591,9 +647,8 @@ export const getPluginLifecycleFailedEvent = (params: {
readonly phase: 'install' | 'uninstall';
readonly error: unknown;
readonly cliVersion: string;
-}): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_FAILED,
- properties: {
+}): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_FAILED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
cli_version: params.cliVersion,
@@ -603,8 +658,7 @@ export const getPluginLifecycleFailedEvent = (params: {
phase: params.phase,
error_name: errorNameOf(params.error),
error_message: errorMessageOf(params.error),
- },
-});
+ });
export const getSetupHostDetectedEvent = (params: {
readonly operation: 'setup' | 'uninstall';
@@ -616,9 +670,8 @@ export const getSetupHostDetectedEvent = (params: {
readonly unsupportedReasonCode?:
'codex_too_old' | 'no_json_inspection' | 'host_command_failed' | 'unknown';
readonly cliVersion: string;
-}): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_HOST_DETECTED,
- properties: {
+}): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_HOST_DETECTED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
cli_version: params.cliVersion,
@@ -630,16 +683,14 @@ export const getSetupHostDetectedEvent = (params: {
supported: params.supported,
host_version: params.hostVersion,
unsupported_reason_code: params.unsupportedReasonCode,
- },
-});
+ });
export const getSetupCancelledEvent = (params: {
readonly operation: 'setup' | 'uninstall';
readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all';
readonly cliVersion: string;
-}): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_CANCELLED,
- properties: {
+}): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_CANCELLED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
cli_version: params.cliVersion,
@@ -647,16 +698,14 @@ export const getSetupCancelledEvent = (params: {
operation: params.operation,
requested_target: params.requestedTarget,
reason: 'user_declined',
- },
-});
+ });
export const getSetupSkippedEvent = (params: {
readonly operation: 'setup' | 'uninstall';
readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all';
readonly cliVersion: string;
-}): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_SKIPPED,
- properties: {
+}): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_SKIPPED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
cli_version: params.cliVersion,
@@ -664,8 +713,7 @@ export const getSetupSkippedEvent = (params: {
operation: params.operation,
requested_target: params.requestedTarget,
reason: 'no_host_detected',
- },
-});
+ });
export const getToolExecuteValidationFailedEvent = (params: {
readonly toolSlug: string;
@@ -676,9 +724,8 @@ export const getToolExecuteValidationFailedEvent = (params: {
readonly stage: 'dry_run' | 'validation' | 'execution';
readonly failureOrigin: 'fast_fail' | 'main_endpoint';
readonly logId?: string;
-}): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_VALIDATION_FAILED,
- properties: {
+}): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_VALIDATION_FAILED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
tool_slug: params.toolSlug,
@@ -693,8 +740,7 @@ export const getToolExecuteValidationFailedEvent = (params: {
unknown_keys: extractUnknownKeys(params.error.issues),
schema_path: params.error.schemaPath,
...argumentShape(params.args),
- },
-});
+ });
export const isMaybeToolNotFoundError = (params: {
readonly message?: string;
@@ -731,9 +777,8 @@ export const getToolExecuteToolNotFoundEvent = (params: {
readonly status?: number;
readonly apiCode?: number;
readonly message?: string;
-}): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_TOOL_NOT_FOUND,
- properties: {
+}): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_TOOL_NOT_FOUND, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
tool_slug: params.toolSlug,
@@ -748,8 +793,7 @@ export const getToolExecuteToolNotFoundEvent = (params: {
api_error_code: params.apiCode,
error_message: params.message?.slice(0, 500),
...argumentShape(params.args),
- },
-});
+ });
export const getToolExecuteFailedEvent = (params: {
readonly toolSlug: string;
@@ -765,9 +809,8 @@ export const getToolExecuteFailedEvent = (params: {
readonly message?: string;
readonly errorName?: string;
readonly isNoConnectionError?: boolean;
-}): TrackEvent => ({
- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_FAILED,
- properties: {
+}): TrackEvent =>
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_FAILED, {
source: 'cli',
invocation_origin: getInvocationOrigin(),
tool_slug: params.toolSlug,
@@ -784,5 +827,4 @@ export const getToolExecuteFailedEvent = (params: {
error_message: params.message?.slice(0, 500),
is_no_connection_error: Boolean(params.isNoConnectionError),
...argumentShape(params.args),
- },
-});
+ });
diff --git a/ts/packages/cli/test/src/analytics.events.test.ts b/ts/packages/cli/test/src/analytics.events.test.ts
index 5586f7b34..57115b379 100644
--- a/ts/packages/cli/test/src/analytics.events.test.ts
+++ b/ts/packages/cli/test/src/analytics.events.test.ts
@@ -1,7 +1,10 @@
-import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { afterEach, describe, expect, it, vi } from 'vitest';
import { createCliCodactFailureBody } from 'src/analytics/dispatch';
import {
CLI_ANALYTICS_EVENTS,
+ CLI_EVENT_JOURNEY_STAGES,
+ CLI_JOURNEY_STAGES,
createCliCommandTelemetryContext,
getPluginLifecycleFailedEvent,
getPluginLifecycleSucceededEvent,
@@ -18,6 +21,8 @@ import {
isMaybeToolValidationError,
} from 'src/analytics/events';
import { APP_VERSION } from 'src/constants';
+import { inferSkillReleaseChannel } from 'src/effects/install-skill';
+import { CLI_RELEASE_CHANNELS } from 'src/experimental-features';
import { ToolInputValidationError } from 'src/services/tool-input-validation';
describe('CLI analytics execute failure events', () => {
@@ -326,3 +331,100 @@ describe('CLI analytics setup runtime-context events', () => {
});
});
});
+
+describe('CLI analytics journey taxonomy', () => {
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ });
+
+ const contextFor = (argv: ReadonlyArray<string>) =>
+ createCliCommandTelemetryContext(['bun', 'composio', ...argv], APP_VERSION, {
+ stdoutIsTTY: false,
+ stderrIsTTY: false,
+ });
+
+ const lifecycleCases: ReadonlyArray<[ReadonlyArray<string>, string]> = [
+ [['execute', 'GMAIL_SEND_EMAIL'], 'execute'],
+ [['search', 'send email'], 'other'],
+ [['link', 'github'], 'connect'],
+ [['login'], 'login'],
+ [['logout'], 'other'],
+ [['proxy', '/api/v3/toolkits'], 'other'],
+ [['run', 'echo hi'], 'other'],
+ [['install'], 'install'],
+ [['setup'], 'setup'],
+ [['version'], 'other'],
+ ];
+
+ it.each(lifecycleCases)('stamps %j lifecycle events with journey_stage %s', (argv, stage) => {
+ const context = contextFor(argv);
+
+ expect(getPrimaryLifecycleInvokedEvent(context)?.properties?.journey_stage).toBe(stage);
+ expect(getPrimaryLifecycleSucceededEvent(context)?.properties?.journey_stage).toBe(stage);
+ expect(
+ getPrimaryLifecycleFailedEvent(context, new Error('boom'))?.properties?.journey_stage
+ ).toBe(stage);
+ });
+
+ it('maps every analytics event name to a declared journey stage', () => {
+ for (const name of Object.values(CLI_ANALYTICS_EVENTS)) {
+ expect(CLI_JOURNEY_STAGES).toContain(CLI_EVENT_JOURNEY_STAGES[name]);
+ }
+ });
+
+ it('stamps standalone setup and tool-invocation events with their stages', () => {
+ expect(
+ getPluginLifecycleSucceededEvent({
+ operation: 'setup',
+ target: 'claude',
+ action: 'installed',
+ cliVersion: APP_VERSION,
+ })?.properties?.journey_stage
+ ).toBe('setup');
+
+ expect(
+ getSetupSkippedEvent({
+ operation: 'setup',
+ requestedTarget: 'auto',
+ cliVersion: APP_VERSION,
+ })?.properties?.journey_stage
+ ).toBe('setup');
+
+ expect(
+ getToolExecuteFailedEvent({
+ toolSlug: 'GMAIL_SEND_EMAIL',
+ args: {},
+ surface: 'root',
+ projectMode: 'consumer',
+ stage: 'execution',
+ failureOrigin: 'main_endpoint',
+ })?.properties?.journey_stage
+ ).toBe('execute');
+ });
+
+ it('stamps events with the release channel of the running build', () => {
+ const properties = getPrimaryLifecycleInvokedEvent(contextFor(['login']))?.properties;
+
+ expect(properties?.cli_channel).toBe(inferSkillReleaseChannel(APP_VERSION));
+ expect(CLI_RELEASE_CHANNELS).toContain(properties?.cli_channel);
+ });
+
+ it('propagates the installer invocation origin from the environment', () => {
+ vi.stubEnv('COMPOSIO_CLI_INVOCATION_ORIGIN', 'installer');
+
+ expect(getPrimaryLifecycleInvokedEvent(contextFor(['install']))?.properties).toMatchObject({
+ invocation_origin: 'installer',
+ journey_stage: 'install',
+ });
+ });
+
+ it('marks the install.sh shell-integration run as installer-origin', () => {
+ const installScript = readFileSync(
+ new URL('../../../../../install.sh', import.meta.url),
+ 'utf8'
+ );
+ const installLine = installScript.split('\n').find(line => line.includes('"$exe" install '));
+
+ expect(installLine).toContain('COMPOSIO_CLI_INVOCATION_ORIGIN=installer');
+ });
+});