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): improve CLI errors
jkomyno committed
Jul 23, 2025 at 05:22 UTC
cd4dd576d1a6ddfe0041c7244e2db44398e69374
9 files changed
+186
-32
pnpm-lock.yaml
+47
-3
@@ -511,6 +511,9 @@ importers:
511
512
ts/packages/cli:
513
dependencies:
514
+ '@clack/prompts':
515
+ specifier: 1.0.0-alpha.1
516
+ version: 1.0.0-alpha.1
517
'@composio/client':
518
specifier: 0.1.0-alpha.29
519
version: 0.1.0-alpha.29
@@ -547,6 +550,9 @@ importers:
550
open:
551
specifier: ^10.2.0
552
version: 10.2.0
553
+ picocolors:
554
+ specifier: ^1.1.1
555
+ version: 1.1.1
556
semver:
557
specifier: ^7.7.2
558
version: 7.7.2
@@ -1088,6 +1094,12 @@ packages:
1094
'@changesets/write@0.4.0':
1095
resolution: {integrity: sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==}
1096
1097
+ '@clack/core@1.0.0-alpha.1':
1098
+ resolution: {integrity: sha512-rFbCU83JnN7l3W1nfgCqqme4ZZvTTgsiKQ6FM0l+r0P+o2eJpExcocBUWUIwnDzL76Aca9VhUdWmB2MbUv+Qyg==}
1099
+
1100
+ '@clack/prompts@1.0.0-alpha.1':
1101
+ resolution: {integrity: sha512-07MNT0OsxjKOcyVfX8KhXBhJiyUbDP1vuIAcHc+nx5v93MJO23pX3X/k3bWz6T3rpM9dgWPq90i4Jq7gZAyMbw==}
1102
+
1103
'@cloudflare/kv-asset-handler@0.4.0':
1104
resolution: {integrity: sha512-+tv3z+SPp+gqTIcImN9o0hqE9xyfQjI1XD9pL6NuKjua9B1y7mNYv0S9cP+QEbA4ppVgGZEmKOvHX5G5Ei1CVA==}
1105
engines: {node: '>=18.0.0'}
@@ -5750,6 +5762,9 @@ packages:
5762
resolution: {integrity: sha512-FoqMu0NCGBLCcAkS1qA+XJIQTR6/JHfQXl+uGteNCQ76T91DMUjPa9xfmeqMY3z80nLSg9yQmNjK0Px6RWsH/A==}
5763
engines: {node: '>=18'}
5764
5765
+ sisteransi@1.0.5:
5766
+ resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
5767
+
5768
slash@3.0.0:
5769
resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
5770
engines: {node: '>=8'}
@@ -7097,6 +7112,17 @@ snapshots:
7112
human-id: 4.1.1
7113
prettier: 2.8.8
7114
7115
+ '@clack/core@1.0.0-alpha.1':
7116
+ dependencies:
7117
+ picocolors: 1.1.1
7118
+ sisteransi: 1.0.5
7119
+
7120
+ '@clack/prompts@1.0.0-alpha.1':
7121
+ dependencies:
7122
+ '@clack/core': 1.0.0-alpha.1
7123
+ picocolors: 1.1.1
7124
+ sisteransi: 1.0.5
7125
+
7126
'@cloudflare/kv-asset-handler@0.4.0':
7127
dependencies:
7128
mime: 3.0.0
@@ -9590,6 +9616,14 @@ snapshots:
9616
chai: 5.2.0
9617
tinyrainbow: 2.0.0
9618
9619
+ '@vitest/mocker@3.2.4(vite@6.3.5(@types/node@20.19.1)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))':
9620
+ dependencies:
9621
+ '@vitest/spy': 3.2.4
9622
+ estree-walker: 3.0.3
9623
+ magic-string: 0.30.17
9624
+ optionalDependencies:
9625
+ vite: 6.3.5(@types/node@20.19.1)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
9626
+
9627
'@vitest/mocker@3.2.4(vite@6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))':
9628
dependencies:
9629
'@vitest/spy': 3.2.4
@@ -9598,6 +9632,14 @@ snapshots:
9632
optionalDependencies:
9633
vite: 6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
9634
9635
+ '@vitest/mocker@3.2.4(vite@6.3.5(@types/node@24.0.3)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))':
9636
+ dependencies:
9637
+ '@vitest/spy': 3.2.4
9638
+ estree-walker: 3.0.3
9639
+ magic-string: 0.30.17
9640
+ optionalDependencies:
9641
+ vite: 6.3.5(@types/node@24.0.3)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
9642
+
9643
'@vitest/pretty-format@3.2.4':
9644
dependencies:
9645
tinyrainbow: 2.0.0
@@ -9627,7 +9669,7 @@ snapshots:
9669
sirv: 3.0.1
9670
tinyglobby: 0.2.14
9671
tinyrainbow: 2.0.0
9630
- vitest: 3.2.4(@types/node@22.15.32)(@vitest/ui@3.2.4)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
9672
+ vitest: 3.2.4(@types/node@24.0.3)(@vitest/ui@3.2.4)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
9673
9674
'@vitest/utils@3.2.4':
9675
dependencies:
@@ -12131,6 +12173,8 @@ snapshots:
12173
mrmime: 2.0.1
12174
totalist: 3.0.1
12175
12176
+ sisteransi@1.0.5: {}
12177
+
12178
slash@3.0.0: {}
12179
12180
slice-ansi@5.0.0:
@@ -12689,7 +12733,7 @@ snapshots:
12733
dependencies:
12734
'@types/chai': 5.2.2
12735
'@vitest/expect': 3.2.4
12692
- '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
12736
+ '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@20.19.1)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
12737
'@vitest/pretty-format': 3.2.4
12738
'@vitest/runner': 3.2.4
12739
'@vitest/snapshot': 3.2.4
@@ -12773,7 +12817,7 @@ snapshots:
12817
dependencies:
12818
'@types/chai': 5.2.2
12819
'@vitest/expect': 3.2.4
12776
- '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
12820
+ '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@24.0.3)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
12821
'@vitest/pretty-format': 3.2.4
12822
'@vitest/runner': 3.2.4
12823
'@vitest/snapshot': 3.2.4
ts/packages/cli/package.json
+2
@@ -54,6 +54,7 @@
54
"vitest": "^3.2.4"
55
},
56
"dependencies": {
57
+ "@clack/prompts": "1.0.0-alpha.1",
58
"@composio/client": "0.1.0-alpha.29",
59
"@composio/core": "workspace:*",
60
"@composio/ts-builders": "workspace:*",
@@ -66,6 +67,7 @@
67
"effect-errors": "^1.10.11",
68
"indent-string": "^5.0.0",
69
"open": "^10.2.0",
70
+ "picocolors": "^1.1.1",
71
"semver": "^7.7.2",
72
"superjson": "^2.2.2"
73
},
ts/packages/cli/src/bin.ts
+18
-6
@@ -1,6 +1,6 @@
1
import process from 'node:process';
2
-import { Cause, Effect, Exit, Layer, Logger } from 'effect';
3
-import { prettyPrint } from 'effect-errors';
2
+import { Cause, Console, Effect, Exit, Layer, Logger } from 'effect';
3
+import { captureErrors, prettyPrintFromCapturedErrors } from 'effect-errors';
4
import { CliConfig } from '@effect/cli';
5
import { FetchHttpClient } from '@effect/platform';
6
import { BunContext, BunRuntime, BunFileSystem } from '@effect/platform-bun';
@@ -91,9 +91,6 @@ const runWithArgs = Effect.flatMap(runWithConfig, run => run(process.argv)) sati
91
* - collects and displays errors
92
*/
93
runWithArgs.pipe(
94
- Effect.provide(layers),
95
- Effect.withConfigProvider(extendConfigProvider(BaseConfigProviderLive)),
96
- Effect.provide(BunContext.layer),
94
Effect.scoped,
95
Effect.withSpan('composio-cli', {
96
attributes: {
@@ -102,7 +99,22 @@ runWithArgs.pipe(
99
},
100
}),
101
Effect.sandbox,
105
- Effect.catchAll(e => Effect.fail(prettyPrint(e))),
102
+ Effect.catchAll(
103
+ Effect.fn(function* (cause) {
104
+ const captured = yield* captureErrors(cause, {
105
+ stripCwd: true,
106
+ });
107
+ const message = prettyPrintFromCapturedErrors(captured, {
108
+ hideStackTrace: true,
109
+ stripCwd: true,
110
+ enabled: true,
111
+ });
112
+
113
+ yield* Console.error(message);
114
+ })
115
+ ),
116
+ Effect.provide(layers),
117
+ Effect.withConfigProvider(extendConfigProvider(BaseConfigProviderLive)),
118
BunRuntime.runMain({
119
teardown,
120
})
ts/packages/cli/src/models/tools.ts
+9
-2
@@ -1,10 +1,17 @@
1
import { Brand, Schema } from 'effect';
2
import { JSONTransformSchema } from './utils/json-transform-schema';
3
+import { extractActual } from './utils/extract-actual';
4
4
-export const Tool = Schema.String;
5
+export const Tool = Schema.String.annotations({ identifier: 'Tool' });
6
export type Tool = Schema.Schema.Type<typeof Tool>;
7
7
-export const Tools = Schema.Array(Tool);
8
+export const Tools = Schema.Array(Tool).annotations({
9
+ identifier: 'Array<Tool>',
10
+ message: issue => ({
11
+ message: `Expected an array of strings, got ${extractActual(issue)}`,
12
+ override: true,
13
+ }),
14
+});
15
export type Tools = Schema.Schema.Type<typeof Tools>;
16
17
export const ToolsJSON = JSONTransformSchema(Tools);
ts/packages/cli/src/models/trigger-types.ts
+10
-2
@@ -1,10 +1,18 @@
1
import { Brand, Schema } from 'effect';
2
import { JSONTransformSchema } from './utils/json-transform-schema';
3
+import { extractActual } from './utils/extract-actual';
4
4
-export const TriggerType = Schema.String;
5
+export const TriggerType = Schema.String.annotations({ identifier: 'TriggerType' });
6
export type TriggerType = Schema.Schema.Type<typeof TriggerType>;
7
7
-export const TriggerTypes = Schema.Array(TriggerType);
8
+export const TriggerTypes = Schema.Array(TriggerType).annotations({
9
+ identifier: 'Array<TriggerType>',
10
+ title: 'TriggerTypes',
11
+ message: issue => ({
12
+ message: `Expected an array of strings, got ${extractActual(issue)}`,
13
+ override: true,
14
+ }),
15
+});
16
export type TriggerTypes = Schema.Schema.Type<typeof TriggerTypes>;
17
18
export const TriggerTypesJSON = JSONTransformSchema(TriggerTypes);
ts/packages/cli/src/models/utils/extract-actual.ts
new
+13
@@ -0,0 +1,13 @@
1
+import type { ParseIssue } from 'effect/ParseResult';
2
+
3
+export function extractActual({ actual }: ParseIssue, cap = 50) {
4
+ // Cap the length of the actual value to 30 characters
5
+ let str = undefined;
6
+
7
+ if (typeof actual === 'object') {
8
+ str = JSON.stringify(actual);
9
+ }
10
+
11
+ str = String(actual);
12
+ return str.slice(0, cap) + (str.length > cap ? '...' : '');
13
+}
ts/packages/cli/src/services/composio-clients.ts
+44
-13
@@ -1,11 +1,12 @@
1
-import { pipe, Data, Effect, Option, Schema, Array, Order } from 'effect';
1
+import { pipe, Data, Effect, Option, Schema, Array, Order, ParseResult } from 'effect';
2
import { Composio as _RawComposioClient } from '@composio/client';
3
import { Toolkit, Toolkits } from 'src/models/toolkits';
4
import { Tools } from 'src/models/tools';
5
import { LinkedSession, Session, RetrievedSession } from 'src/models/session';
6
-import { TriggerType } from 'src/models/trigger-types';
6
+import { TriggerTypes } from 'src/models/trigger-types';
7
import { ComposioUserContext, ComposioUserContextLive } from './user-context';
8
import type { NoSuchElementException } from 'effect/Cause';
9
+import { renderPrettyError } from './utils/pretty-error';
10
11
/**
12
* Error types
@@ -15,16 +16,14 @@ import type { NoSuchElementException } from 'effect/Cause';
16
* Error thrown when a HTTP request fails.
17
*/
18
export class HttpServerError extends Data.TaggedError('services/HttpServerError')<{
18
- readonly cause: Error;
19
- readonly message: string;
19
+ readonly cause?: unknown;
20
}> {}
21
22
/**
23
* Error thrown when a HTTP response doesn't match the expected response schema.
24
*/
25
export class HttpDecodingError extends Data.TaggedError('services/HttpDecodingError')<{
26
- readonly cause: Error;
27
- readonly message: string;
26
+ readonly cause?: unknown;
27
}> {}
28
29
export type HttpError = HttpServerError | HttpDecodingError;
@@ -52,9 +51,24 @@ export type ToolkitsResponse = Schema.Schema.Type<typeof ToolkitsResponse>;
51
export const ToolsResponse = Tools;
52
export type ToolsResponse = Schema.Schema.Type<typeof ToolsResponse>;
53
55
-export const TriggerTypesResponse = Schema.Array(TriggerType);
54
+export const TriggerTypesResponse = TriggerTypes;
55
export type TriggerResponse = Schema.Schema.Type<typeof TriggerTypesResponse>;
56
57
+/**
58
+ * Error response schemas
59
+ */
60
+export const HttpErrorResponse = Schema.Struct({
61
+ status: Schema.Int,
62
+ error: Schema.Struct({
63
+ error: Schema.Struct({
64
+ message: Schema.NonEmptyString,
65
+ suggested_fix: Schema.String,
66
+ code: Schema.Int,
67
+ }),
68
+ }),
69
+}).annotations({ identifier: 'HttpErrorResponse' });
70
+export type HttpErrorResponse = Schema.Schema.Type<typeof HttpErrorResponse>;
71
+
72
/**
73
* Utilities
74
*/
@@ -70,11 +84,27 @@ const callClient = <T, S extends Schema.Schema<any, any>>(
84
const client = yield* clientSingleton.get();
85
const json = yield* Effect.tryPromise({
86
try: () => apiCall(client),
73
- catch: error => {
74
- const e = error as Error;
87
+ catch: e => {
88
+ const decodedOpt = Schema.decodeUnknownOption(HttpErrorResponse)(e);
89
+
90
+ if (Option.isNone(decodedOpt)) {
91
+ return new HttpServerError({
92
+ cause: e,
93
+ });
94
+ }
95
+
96
+ const {
97
+ status,
98
+ error: { error },
99
+ } = decodedOpt.value;
100
+ const pretty = renderPrettyError([
101
+ ['code', error.code],
102
+ ['message', error.message],
103
+ ['suggested fix', error.suggested_fix],
104
+ ]);
105
+
106
return new HttpServerError({
76
- cause: e,
77
- message: e.message,
107
+ cause: `HTTP ${status}\n${pretty}`,
108
});
109
},
110
});
@@ -82,9 +112,10 @@ const callClient = <T, S extends Schema.Schema<any, any>>(
112
return yield* pipe(
113
Schema.decodeUnknown(responseSchema)(json),
114
Effect.catchTag('ParseError', e => {
115
+ const message = ParseResult.TreeFormatter.formatErrorSync(e);
116
+
117
return new HttpDecodingError({
86
- cause: e,
87
- message: e.message,
118
+ cause: `ParseError\n ${message}`,
119
});
120
})
121
);
ts/packages/cli/src/services/upgrade-binary.ts
+10
-6
@@ -10,10 +10,11 @@ import { CompareSemverError, semverComparator } from 'src/effects/compare-semver
10
// Note: `node:zlib` does not support Github's zip files
11
import decompress from 'decompress';
12
import type { Predicate } from 'effect/Predicate';
13
+import { renderPrettyError } from './utils/pretty-error';
14
15
export class UpgradeBinaryError extends Data.TaggedError('services/UpgradeBinaryError')<{
15
- readonly cause: Error;
16
- readonly message: string;
16
+ readonly cause?: unknown;
17
+ readonly message?: string;
18
}> {}
19
20
/**
@@ -62,10 +63,13 @@ export class UpgradeBinary extends Effect.Service<UpgradeBinary>()('services/Upg
63
const response = yield* Effect.gen(function* () {
64
const resp = yield* httpClient.get(url);
65
if (resp.status < 200 || resp.status >= 300) {
66
+ const json = yield* resp.json;
67
+ const keyValues = Object.entries(json as object);
68
+ const pretty = renderPrettyError(keyValues);
69
+
70
return yield* Effect.fail(
71
new UpgradeBinaryError({
67
- cause: new Error(`HTTP ${resp.status}`),
68
- message: `Failed to fetch ${urlSuffix} release from GitHub`,
72
+ cause: `HTTP ${resp.status}\n${pretty}`,
73
})
74
);
75
}
@@ -74,7 +78,7 @@ export class UpgradeBinary extends Effect.Service<UpgradeBinary>()('services/Upg
78
Effect.catchAll(error =>
79
Effect.fail(
80
new UpgradeBinaryError({
77
- cause: new Error(String(error)),
81
+ cause: error,
82
message: `Failed to fetch ${urlSuffix} release from GitHub`,
83
})
84
)
@@ -87,7 +91,7 @@ export class UpgradeBinary extends Effect.Service<UpgradeBinary>()('services/Upg
91
Effect.catchAll(error =>
92
Effect.fail(
93
new UpgradeBinaryError({
90
- cause: error as Error,
94
+ cause: error,
95
message: 'Failed to parse GitHub release JSON response',
96
})
97
)
ts/packages/cli/src/services/utils/pretty-error.ts
new
+33
@@ -0,0 +1,33 @@
1
+import colors from 'picocolors';
2
+import { S_BAR, S_BAR_H, unicodeOr } from '@clack/prompts';
3
+
4
+const S_CORNER_TOP_LEFT = unicodeOr('╭', '+');
5
+const S_CORNER_BOTTOM_LEFT = unicodeOr('╰', '+');
6
+
7
+export function renderPrettyError(errorLines: Array<[key: string, value: unknown]>): string {
8
+ return renderPrettyErrorGen(errorLines).toArray().join('\n');
9
+}
10
+
11
+function* renderPrettyErrorGen(
12
+ errorLines: Array<[key: string, value: unknown]>
13
+): Generator<string, void, unknown> {
14
+ if (errorLines.length === 0) {
15
+ yield '';
16
+ } else if (errorLines.length <= 2) {
17
+ for (const [key, value] of errorLines) {
18
+ yield `${colors.gray(S_BAR)} ${colors.blueBright(key)}: ${value}`;
19
+ }
20
+ } else if (errorLines.length > 2) {
21
+ for (let i = 0; i < errorLines.length; i++) {
22
+ const [key, value] = errorLines[i];
23
+
24
+ if (i === 0) {
25
+ yield `${colors.gray(`${S_CORNER_TOP_LEFT}${S_BAR_H}`)} ${colors.blueBright(key)}: ${value}`;
26
+ } else if (i === errorLines.length - 1) {
27
+ yield `${colors.gray(`${S_CORNER_BOTTOM_LEFT}${S_BAR_H}`)} ${colors.blueBright(key)}: ${value}`;
28
+ } else {
29
+ yield `${colors.gray(S_BAR)} ${colors.blueBright(key)}: ${value}`;
30
+ }
31
+ }
32
+ }
33
+}