Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(cli): add composio version --check for machine-readable update status

Kshitij Jhunjhunwala304e2fda3ca1
diff --git a/ts/packages/cli/src/commands/version.cmd.ts b/ts/packages/cli/src/commands/version.cmd.ts
index 80d347b08..d40c47559 100644
--- a/ts/packages/cli/src/commands/version.cmd.ts
+++ b/ts/packages/cli/src/commands/version.cmd.ts
@@ -1,7 +1,17 @@
-import { Command } from '@effect/cli';
+import { Command, Options } from '@effect/cli';
import { Effect } from 'effect';
import { getVersion } from 'src/effects/version';
+import { getUpdateStatus } from 'src/services/update-check';
import { TerminalUI } from 'src/services/terminal-ui';
+import { bold, cyanBright } from 'src/ui/colors';
+
+const check = Options.boolean('check').pipe(
+ Options.withDescription(
+ 'Check for a newer stable release and print a machine-readable JSON status ' +
+ '({current, latestStable, updateAvailable, lastChecked}). ' +
+ 'Refreshes the release cache when it is older than 24 hours.'
+ )
+);
/**
* CLI command to display the version of the Composio CLI.
@@ -9,13 +19,28 @@ import { TerminalUI } from 'src/services/terminal-ui';
* @example
* ```bash
* composio version
+ * composio version --check
* ```
*/
-export const versionCmd = Command.make('version', {}).pipe(
+export const versionCmd = Command.make('version', { check }).pipe(
Command.withDescription('Display the current Composio CLI version.'),
- Command.withHandler(() =>
+ Command.withHandler(({ check }) =>
Effect.gen(function* () {
const ui = yield* TerminalUI;
+
+ if (check) {
+ const status = yield* getUpdateStatus;
+ if (status.updateAvailable && status.latestStable) {
+ yield* ui.log.info(
+ `Update available: ${status.current} → ${bold(cyanBright(status.latestStable))} — run ${cyanBright('composio upgrade')}`
+ );
+ } else {
+ yield* ui.log.info(`${status.current} is up to date.`);
+ }
+ yield* ui.output(JSON.stringify(status));
+ return;
+ }
+
const version = yield* getVersion;
yield* ui.log.info(version);
yield* ui.output(version);
diff --git a/ts/packages/cli/src/services/update-check.ts b/ts/packages/cli/src/services/update-check.ts
index 221f4d69c..96c9fed4d 100644
--- a/ts/packages/cli/src/services/update-check.ts
+++ b/ts/packages/cli/src/services/update-check.ts
@@ -33,6 +33,18 @@ export interface UpdateCheckState {
latestVersion: string; // e.g. "0.3.0"
}
+/** Machine-readable update status for `composio version --check`. */
+export interface UpdateStatus {
+ /** Installed CLI version (release-tag.txt next to the binary, or APP_VERSION). */
+ current: string;
+ /** Latest known stable release with a binary for this platform, if known. */
+ latestStable: string | null;
+ /** True when a strictly newer stable release than `current` is available. */
+ updateAvailable: boolean;
+ /** When the release list was last fetched (ISO-8601), if ever. */
+ lastChecked: string | null;
+}
+
const UpdateCheckStateSchema = Schema.parseJson(
Schema.Struct({
lastChecked: Schema.String,
@@ -232,7 +244,36 @@ export function createUpdateChecker(config: UpdateCheckConfig) {
);
});
- return { showUpdateNotice, checkForUpdate };
+ /**
+ * Refresh the release cache (self-throttled to the check interval) and
+ * report a machine-readable status. Unlike the notice, this ignores the
+ * TTY gate — callers asked for the data explicitly.
+ */
+ const getUpdateStatus: Effect.Effect<UpdateStatus, never, FileSystem.FileSystem | Path.Path> =
+ Effect.gen(function* () {
+ yield* checkForUpdate;
+ const state = yield* Effect.option(readState);
+
+ const cachedLatest = Option.getOrUndefined(Option.map(state, s => s.latestVersion));
+ // The cache falls back to the current version when no release was found,
+ // so a prerelease can leak into latestVersion — never report that as stable.
+ const latestStable =
+ cachedLatest && semver.valid(cachedLatest) && semver.prerelease(cachedLatest) === null
+ ? cachedLatest
+ : null;
+
+ return {
+ current: config.currentVersion,
+ latestStable,
+ updateAvailable: latestStable !== null && semver.gt(latestStable, config.currentVersion),
+ lastChecked: Option.getOrElse(
+ Option.map(state, s => s.lastChecked),
+ () => null as string | null
+ ),
+ } satisfies UpdateStatus;
+ }).pipe(Effect.orDie);
+
+ return { showUpdateNotice, checkForUpdate, getUpdateStatus };
}
// ── Public API (production defaults, fire-and-forget) ───────────────────
@@ -247,6 +288,16 @@ export const showUpdateNotice = Effect.gen(function* () {
yield* createUpdateChecker(config).showUpdateNotice(terminal);
}).pipe(Effect.provide(DefaultConfigLayers));
+/**
+ * Refresh the release cache if stale and return a machine-readable status.
+ * Powers `composio version --check`.
+ */
+export const getUpdateStatus: Effect.Effect<UpdateStatus> = Effect.gen(function* () {
+ const stateFile = yield* defaultStateFile;
+ const config = yield* defaultConfig(stateFile);
+ return yield* createUpdateChecker(config).getUpdateStatus;
+}).pipe(Effect.provide(DefaultConfigLayers));
+
/** Fire-and-forget background fetch to GitHub. */
export function checkForUpdateInBackground(): void {
// Runs from cli-main before the runtime boots; runPromiseExit never throws back
diff --git a/ts/packages/cli/test/src/services/update-check.test.ts b/ts/packages/cli/test/src/services/update-check.test.ts
index 6a07a9edf..d33e65f6b 100644
--- a/ts/packages/cli/test/src/services/update-check.test.ts
+++ b/ts/packages/cli/test/src/services/update-check.test.ts
@@ -244,6 +244,81 @@ describe('showUpdateNotice', () => {
);
});
+// ── getUpdateStatus ─────────────────────────────────────────────────────
+
+describe('getUpdateStatus', () => {
+ it.effect('reports an available update for a stale stable install', () =>
+ Effect.gen(function* () {
+ const config = makeConfig({
+ currentVersion: '0.2.0',
+ fetchFn: vi.fn().mockResolvedValue({
+ ok: true,
+ json: () => Promise.resolve(makeReleasesPayload(['0.3.0'])),
+ }) as unknown as typeof fetch,
+ });
+ const { getUpdateStatus } = createUpdateChecker(config);
+
+ const status = yield* getUpdateStatus;
+
+ expect(status).toEqual({
+ current: '0.2.0',
+ latestStable: '0.3.0',
+ updateAvailable: true,
+ lastChecked: expect.any(String),
+ });
+ }).pipe(Effect.provide(PlatformLayers))
+ );
+
+ it.effect('reports no update when the fetch fails and no cache exists', () =>
+ Effect.gen(function* () {
+ const config = makeConfig({
+ currentVersion: '0.2.0',
+ fetchFn: vi.fn().mockRejectedValue(new Error('offline')) as unknown as typeof fetch,
+ });
+ const { getUpdateStatus } = createUpdateChecker(config);
+
+ const status = yield* getUpdateStatus;
+
+ expect(status.updateAvailable).toBe(false);
+ expect(status.lastChecked).toEqual(expect.any(String));
+ }).pipe(Effect.provide(PlatformLayers))
+ );
+
+ it.effect('does not report a cached prerelease as latestStable', () =>
+ Effect.gen(function* () {
+ const config = makeConfig({ currentVersion: '0.2.32-beta.289' });
+ writeState(config, {
+ lastChecked: new Date().toISOString(),
+ latestVersion: '0.2.32-beta.289',
+ });
+ const { getUpdateStatus } = createUpdateChecker(config);
+
+ const status = yield* getUpdateStatus;
+
+ expect(status.latestStable).toBeNull();
+ expect(status.updateAvailable).toBe(false);
+ }).pipe(Effect.provide(PlatformLayers))
+ );
+
+ it.effect('uses the fresh cache without fetching', () =>
+ Effect.gen(function* () {
+ const fetchFn = vi.fn();
+ const config = makeConfig({
+ currentVersion: '0.2.0',
+ fetchFn: fetchFn as unknown as typeof fetch,
+ });
+ writeState(config, { lastChecked: new Date().toISOString(), latestVersion: '0.2.1' });
+ const { getUpdateStatus } = createUpdateChecker(config);
+
+ const status = yield* getUpdateStatus;
+
+ expect(fetchFn).not.toHaveBeenCalled();
+ expect(status.latestStable).toBe('0.2.1');
+ expect(status.updateAvailable).toBe(true);
+ }).pipe(Effect.provide(PlatformLayers))
+ );
+});
+
// ── checkForUpdate ──────────────────────────────────────────────────────
describe('checkForUpdate', () => {