Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix(cli): suppress decoration when piped and remove makeSpinner
Gate all TerminalUI decoration on process.stdout.isTTY so piped invocations (| pbcopy, $(...), > file) are completely silent. ui.output() writes raw data to stdout only when piped. Remove the unsafe makeSpinner API in favor of useMakeSpinner which auto-cleans up on interruption. Fix version command description, deduplicate versionCmd registration, and add ui.output() to login/generate commands for script composability.
jkomyno committed
Feb 18, 2026 at 13:50 UTC
eba0290679f848b78ffe8b5fd2723b757e97cda3
9 files changed
+137
-124
ts/packages/cli/AGENTS.md
+20
-11
@@ -161,12 +161,13 @@ The CLI follows the Unix convention of separating human-readable decoration from
161
162
### Rules
163
164
-1. **All `TerminalUI` methods except `output()` write to stderr** via Clack's `{ output: process.stderr }` option.
165
-2. **`ui.output(data)` writes to stdout** — use this for values that scripts should capture (API keys, version strings, generated paths).
166
-3. **Action commands** (login, logout, upgrade, generate) produce no stdout data — their output is purely decorative.
167
-4. **Data commands** (whoami, version) produce both decoration (stderr) and data (stdout).
168
-5. **Never write data to stderr** — decoration methods are for human context only.
169
-6. **Never write decoration to stdout** — it breaks pipes, `$(...)` captures, and `> file` redirects.
164
+1. **All `TerminalUI` methods except `output()` write to stderr** via Clack's `{ output: process.stderr }` option — but only in interactive mode.
165
+2. **`ui.output(data)` writes to stdout only when piped** — it checks `process.stdout.isTTY` and is a no-op in interactive terminals (the human already sees the data via decoration on stderr).
166
+3. **When stdout is piped, ALL decoration is suppressed** — `isInteractive` (`process.stdout.isTTY`) gates every decoration method. Only `ui.output()` writes in piped mode. This keeps `composio whoami | pbcopy` completely silent.
167
+4. **Action commands** (logout, upgrade) produce no stdout data — their output is purely decorative.
168
+5. **Data commands** (whoami, version, login, generate) call both decoration (stderr) and `ui.output()` (stdout). In interactive mode, only decoration is visible. In pipes/scripts, only the raw data is captured.
169
+6. **Never write data to stderr** — decoration methods are for human context only.
170
+7. **Never write decoration to stdout** — it breaks pipes, `$(...)` captures, and `> file` redirects.
171
172
### Pattern
173
@@ -183,13 +184,21 @@ yield * ui.log.step('Redirecting'); // Decoration → stderr
184
185
### How it works in practice
186
187
+The CLI checks `process.stdout.isTTY` once at startup to determine the output mode:
188
+
189
+- **Interactive** (`stdout` is TTY): decoration visible on stderr, `ui.output()` is a no-op.
190
+- **Piped** (`stdout` is NOT TTY): decoration suppressed, `ui.output()` writes raw data to stdout.
191
+
192
```bash
187
-composio whoami # Human sees pretty box AND plain key
188
-composio whoami 2>/dev/null # Only the API key (suppresses decoration)
189
-API_KEY=$(composio whoami) # Variable gets clean key, box shows in terminal
190
-composio whoami | pbcopy # Clipboard gets clean key
193
+composio whoami # Pretty box only (interactive)
194
+composio whoami | pbcopy # Silent — clipboard gets clean key
195
+API_KEY=$(composio whoami) # Silent — variable gets clean key
196
+composio whoami > file.txt # Silent — file gets clean key
197
+
198
+composio version # Decorated version (interactive)
199
+composio version | cat # Raw version string
200
192
-composio login # All decoration visible (nothing to pipe)
201
+composio login # All decoration visible, browser opens
202
composio login 2>/dev/null # Silent (but still opens browser, polls API)
203
```
204
ts/packages/cli/src/commands/$default.cmd.ts
-2
@@ -2,7 +2,6 @@ import { Context, Schema, LogLevel, String, pipe, Layer, Effect } from 'effect';
2
import { Command, Options } from '@effect/cli';
3
import { setMinimumLogLevel } from 'src/effects/with-log-level';
4
import type { ConfigError } from 'effect/ConfigError';
5
-import { versionCmd } from './version.cmd';
5
6
const logLevelChoices = LogLevel.allLevels.map(level => String.toLowerCase(level._tag));
7
@@ -45,7 +44,6 @@ class $DefaultCmdContext extends Context.Tag('cli/$DefaultCmdContext')<
44
* ```
45
*/
46
export const $defaultCmd = Command.make('composio', { logLevel }).pipe(
48
- Command.withSubcommands([versionCmd]),
47
Command.withDescription(
48
`Composio CLI - A tool for managing Python and TypeScript composio.dev projects.`
49
),
ts/packages/cli/src/commands/login.cmd.ts
+29
-27
@@ -51,6 +51,7 @@ export const loginCmd = Command.make('login', { noBrowser }, ({ noBrowser }) =>
51
}
52
53
yield* ui.note(url, 'Login URL');
54
+ yield* ui.output(url);
55
56
if (!noBrowser) {
57
// Open the given `url` in the default browser
@@ -64,34 +65,35 @@ export const loginCmd = Command.make('login', { noBrowser }, ({ noBrowser }) =>
65
);
66
}
67
67
- // Spinner during session polling
68
- const spinner = yield* ui.makeSpinner('Waiting for login...');
69
-
70
- // Retry operation until the session status is "linked" with exponential backoff
71
- const linkedSession = yield* Effect.retry(
72
- Effect.gen(function* () {
73
- const currentSession = yield* client.getSession({
74
- ...session,
75
- });
76
-
77
- // Check if session is linked
78
- if (currentSession.status === 'linked') {
79
- return currentSession;
80
- }
81
-
82
- // If still pending, fail to trigger retry
83
- return yield* Effect.fail(
84
- new Error(`Session status is still '${currentSession.status}', waiting for 'linked'`)
85
- );
86
- }),
87
- // Exponential backoff: start with 0.3s, max 5s, up to 15 retries
88
- Schedule.exponential('0.3 seconds').pipe(
89
- Schedule.intersect(Schedule.recurs(15)),
90
- Schedule.intersect(Schedule.spaced('5 seconds'))
68
+ // Retry operation until the session status is "linked" with exponential backoff.
69
+ // useMakeSpinner auto-cleans up the spinner on interruption (e.g., Ctrl+C).
70
+ const linkedSession = yield* ui.useMakeSpinner('Waiting for login...', spinner =>
71
+ Effect.retry(
72
+ Effect.gen(function* () {
73
+ const currentSession = yield* client.getSession({
74
+ ...session,
75
+ });
76
+
77
+ // Check if session is linked
78
+ if (currentSession.status === 'linked') {
79
+ return currentSession;
80
+ }
81
+
82
+ // If still pending, fail to trigger retry
83
+ return yield* Effect.fail(
84
+ new Error(`Session status is still '${currentSession.status}', waiting for 'linked'`)
85
+ );
86
+ }),
87
+ // Exponential backoff: start with 0.3s, max 5s, up to 15 retries
88
+ Schedule.exponential('0.3 seconds').pipe(
89
+ Schedule.intersect(Schedule.recurs(15)),
90
+ Schedule.intersect(Schedule.spaced('5 seconds'))
91
+ )
92
+ ).pipe(
93
+ Effect.tap(() => spinner.stop('Login successful')),
94
+ Effect.tapError(() => spinner.error('Login timed out. Please try again.'))
95
)
92
- ).pipe(Effect.tapError(() => spinner.error('Login timed out. Please try again.')));
93
-
94
- yield* spinner.stop('Login successful');
96
+ );
97
98
yield* Effect.logDebug(`Linked session: ${JSON.stringify(linkedSession)}`);
99
ts/packages/cli/src/commands/py/commands/py.generate.cmd.ts
+1
@@ -182,6 +182,7 @@ export function generatePythonTypeStubs({
182
yield* logMetrics(metrics);
183
184
yield* ui.outro('Done');
185
+ yield* ui.output(outputDir);
186
187
return outputDir;
188
});
ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts
+1
@@ -456,6 +456,7 @@ export function generateTypescriptTypeStubs({
456
yield* logMetrics(metrics);
457
458
yield* ui.outro('Done');
459
+ yield* ui.output(outputDir);
460
461
return outputDir;
462
});
ts/packages/cli/src/commands/version.cmd.ts
+1
-1
@@ -12,7 +12,7 @@ import { TerminalUI } from 'src/services/terminal-ui';
12
* ```
13
*/
14
export const versionCmd = Command.make('version', {}).pipe(
15
- Command.withDescription('Display your account information.'),
15
+ Command.withDescription('Display the current Composio CLI version.'),
16
Command.withHandler(() =>
17
Effect.gen(function* () {
18
const ui = yield* TerminalUI;
ts/packages/cli/src/services/terminal-ui.ts
+81
-67
@@ -1,10 +1,9 @@
1
import process from 'node:process';
2
-import type { Writable } from 'node:stream';
2
import * as p from '@clack/prompts';
3
import { Context, Effect, Exit, Layer } from 'effect';
4
5
// ---------------------------------------------------------------------------
7
-// SpinnerHandle — returned by `makeSpinner` for manual control
6
+// SpinnerHandle — returned by `useMakeSpinner` for manual control
7
// ---------------------------------------------------------------------------
8
9
export interface SpinnerHandle {
@@ -23,7 +22,12 @@ export interface SpinnerHandle {
22
export interface TerminalUI {
23
/**
24
* Write raw data to stdout for piping and scripting.
25
+ *
26
* This is the ONLY method that writes to stdout — everything else goes to stderr.
27
+ * When stdout is a TTY (interactive terminal), this is a no-op — the human already
28
+ * sees the data via decoration on stderr. When stdout is redirected (pipe, subshell,
29
+ * file), the raw value is written for machine consumption.
30
+ *
31
* Use this for values that scripts should capture (API keys, version strings, etc.).
32
*/
33
readonly output: (data: string) => Effect.Effect<void>;
@@ -65,15 +69,6 @@ export interface TerminalUI {
69
}
70
) => Effect.Effect<A, E, R>;
71
68
- /**
69
- * Create a controllable spinner for multi-step flows (e.g., login polling).
70
- * The caller is responsible for calling `stop()` or `error()`.
71
- *
72
- * WARNING: If the surrounding Effect fails, this spinner will NOT be cleaned up.
73
- * Use `useMakeSpinner` instead for automatic cleanup on error.
74
- */
75
- readonly makeSpinner: (message: string) => Effect.Effect<SpinnerHandle>;
76
-
72
/**
73
* Create a controllable spinner that is automatically stopped on error or interruption.
74
* The `use` function receives a SpinnerHandle and must return an Effect.
@@ -94,10 +89,16 @@ export const TerminalUI = Context.GenericTag<TerminalUI>('services/TerminalUI');
89
// ---------------------------------------------------------------------------
90
91
/**
97
- * All decoration (spinners, logs, notes, intro/outro) writes to stderr.
98
- * This keeps stdout clean for data output that scripts and pipes capture.
92
+ * Whether the CLI is running interactively (stdout is a TTY).
93
+ * When piped (stdout is NOT a TTY), all decoration is suppressed and only
94
+ * `output()` writes raw data to stdout for machine consumption.
95
*/
100
-const DECORATION: Writable = process.stderr;
96
+const isInteractive = !!process.stdout.isTTY;
97
+
98
+/** Run a decoration side-effect only in interactive mode. */
99
+function decorate(fn: () => void): void {
100
+ if (isInteractive) fn();
101
+}
102
103
function createClackSpinnerHandle(s: p.SpinnerResult, defaultMessage: string): SpinnerHandle {
104
return {
@@ -107,72 +108,85 @@ function createClackSpinnerHandle(s: p.SpinnerResult, defaultMessage: string): S
108
};
109
}
110
111
+/** No-op spinner handle used when decoration is suppressed (piped mode). */
112
+const silentSpinnerHandle: SpinnerHandle = {
113
+ message: () => Effect.void,
114
+ stop: () => Effect.void,
115
+ error: () => Effect.void,
116
+};
117
+
118
const makeLive: TerminalUI = {
119
output: data =>
120
Effect.sync(() => {
113
- process.stdout.write(`${data}\n`);
121
+ if (!isInteractive) {
122
+ process.stdout.write(`${data}\n`);
123
+ }
124
}),
125
116
- intro: title => Effect.sync(() => p.intro(title, { output: DECORATION })),
117
- outro: message => Effect.sync(() => p.outro(message, { output: DECORATION })),
126
+ intro: title => Effect.sync(() => decorate(() => p.intro(title, { output: process.stderr }))),
127
+ outro: message => Effect.sync(() => decorate(() => p.outro(message, { output: process.stderr }))),
128
129
log: {
120
- info: message => Effect.sync(() => p.log.info(message, { output: DECORATION })),
121
- success: message => Effect.sync(() => p.log.success(message, { output: DECORATION })),
122
- warn: message => Effect.sync(() => p.log.warn(message, { output: DECORATION })),
123
- error: message => Effect.sync(() => p.log.error(message, { output: DECORATION })),
124
- step: message => Effect.sync(() => p.log.step(message, { output: DECORATION })),
125
- message: message => Effect.sync(() => p.log.message(message, { output: DECORATION })),
130
+ info: message =>
131
+ Effect.sync(() => decorate(() => p.log.info(message, { output: process.stderr }))),
132
+ success: message =>
133
+ Effect.sync(() => decorate(() => p.log.success(message, { output: process.stderr }))),
134
+ warn: message =>
135
+ Effect.sync(() => decorate(() => p.log.warn(message, { output: process.stderr }))),
136
+ error: message =>
137
+ Effect.sync(() => decorate(() => p.log.error(message, { output: process.stderr }))),
138
+ step: message =>
139
+ Effect.sync(() => decorate(() => p.log.step(message, { output: process.stderr }))),
140
+ message: message =>
141
+ Effect.sync(() => decorate(() => p.log.message(message, { output: process.stderr }))),
142
},
143
128
- note: (message, title) => Effect.sync(() => p.note(message, title ?? '', { output: DECORATION })),
144
+ note: (message, title) =>
145
+ Effect.sync(() => decorate(() => p.note(message, title ?? '', { output: process.stderr }))),
146
147
withSpinner: (message, effect, options) =>
131
- Effect.acquireUseRelease(
132
- Effect.sync(() => {
133
- const s = p.spinner({ output: DECORATION });
134
- s.start(message);
135
- return s;
136
- }),
137
- () => effect,
138
- (s, exit) =>
139
- Effect.sync(() => {
140
- if (Exit.isSuccess(exit)) {
141
- const successMsg =
142
- typeof options?.successMessage === 'function'
143
- ? options.successMessage(exit.value)
144
- : (options?.successMessage ?? message);
145
- s.stop(successMsg);
146
- } else {
147
- s.error(options?.errorMessage ?? message);
148
- }
149
- })
150
- ),
151
-
152
- makeSpinner: message =>
153
- Effect.sync(() => {
154
- const s = p.spinner({ output: DECORATION });
155
- s.start(message);
156
- return createClackSpinnerHandle(s, message);
157
- }),
148
+ isInteractive
149
+ ? Effect.acquireUseRelease(
150
+ Effect.sync(() => {
151
+ const s = p.spinner({ output: process.stderr });
152
+ s.start(message);
153
+ return s;
154
+ }),
155
+ () => effect,
156
+ (s, exit) =>
157
+ Effect.sync(() => {
158
+ if (Exit.isSuccess(exit)) {
159
+ const successMsg =
160
+ typeof options?.successMessage === 'function'
161
+ ? options.successMessage(exit.value)
162
+ : (options?.successMessage ?? message);
163
+ s.stop(successMsg);
164
+ } else {
165
+ s.error(options?.errorMessage ?? message);
166
+ }
167
+ })
168
+ )
169
+ : effect,
170
171
useMakeSpinner: (message, use) =>
160
- Effect.acquireUseRelease(
161
- Effect.sync(() => {
162
- const s = p.spinner({ output: DECORATION });
163
- s.start(message);
164
- return { raw: s, handle: createClackSpinnerHandle(s, message) };
165
- }),
166
- ({ handle }) => use(handle),
167
- ({ raw }, exit) =>
168
- Effect.sync(() => {
169
- // Only clean up if the spinner is still active (user didn't call stop/error)
170
- // Clack spinners have an internal `isCancelled` state after stop/error/cancel
171
- if (Exit.isFailure(exit) && !raw.isCancelled) {
172
- raw.error(message);
173
- }
174
- })
175
- ),
172
+ isInteractive
173
+ ? Effect.acquireUseRelease(
174
+ Effect.sync(() => {
175
+ const s = p.spinner({ output: process.stderr });
176
+ s.start(message);
177
+ return { raw: s, handle: createClackSpinnerHandle(s, message) };
178
+ }),
179
+ ({ handle }) => use(handle),
180
+ ({ raw }, exit) =>
181
+ Effect.sync(() => {
182
+ // Only clean up if the spinner is still active (user didn't call stop/error)
183
+ // Clack spinners have an internal `isCancelled` state after stop/error/cancel
184
+ if (Exit.isFailure(exit) && !raw.isCancelled) {
185
+ raw.error(message);
186
+ }
187
+ })
188
+ )
189
+ : use(silentSpinnerHandle),
190
};
191
192
export const TerminalUILive = Layer.succeed(TerminalUI, makeLive);
ts/packages/cli/test/__utils__/services/terminal-ui-test.ts
-10
@@ -37,16 +37,6 @@ export const TerminalUITest = Layer.succeed(
37
return result;
38
}),
39
40
- makeSpinner: message =>
41
- Effect.gen(function* () {
42
- void message;
43
- return {
44
- message: (_msg: string) => Effect.void,
45
- stop: (msg?: string) => (msg ? Console.log(msg) : Effect.void),
46
- error: (msg?: string) => (msg ? Console.error(msg) : Effect.void),
47
- };
48
- }),
49
-
40
useMakeSpinner: (message, use) =>
41
Effect.gen(function* () {
42
let stopped = false;
ts/packages/cli/test/src/commands/$default.cmd.test.ts
+4
-6
@@ -14,7 +14,9 @@ describe('CLI: composio', () => {
14
15
expect(result).toEqual(
16
ValidationError.commandMismatch(
17
- HelpDoc.p("Invalid subcommand for composio - use 'version'")
17
+ HelpDoc.p(
18
+ "Invalid subcommand for composio - use one of 'version', 'upgrade', 'whoami', 'login', 'logout', 'generate', 'py', 'ts'"
19
+ )
20
)
21
);
22
})
@@ -54,11 +56,7 @@ describe('CLI: composio', () => {
56
57
[0;1mCOMMANDS[0m
58
57
- - version Display your account information.
58
-
59
- [0;1mCOMMANDS[0m
60
-
61
- - version Display your account information.
59
+ - version Display the current Composio CLI version.
60
61
- upgrade Upgrade your Composio CLI to the latest available version.
62