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): route Clack decoration to stderr and add ui.output() for composable data
All TerminalUI methods (logs, notes, spinners, intro/outro) now write to process.stderr via Clack's { output } option, keeping stdout clean for scripts and pipes. A new ui.output() method writes raw data to stdout, used by version and whoami commands so $(composio whoami) captures only the API key.
jkomyno committed
Feb 18, 2026 at 13:19 UTC
d09a6b4450c9c58c8acade31436d213e715f6bec
6 files changed
+177
-83
ts/packages/cli/AGENTS.md
+121
-68
@@ -23,49 +23,49 @@ Errors are captured via the custom `effect-errors/` module, which provides sourc
23
24
Each command is declared with `@effect/cli`'s `Command.make()` pattern:
25
26
-| Command | Description |
27
-|---|---|
28
-| `composio version` | Display CLI version |
29
-| `composio whoami` | Show logged-in user's API key |
30
-| `composio login [--no-browser]` | OAuth2 login with browser redirect |
31
-| `composio logout` | Clear stored API key |
32
-| `composio upgrade` | Self-update binary from GitHub releases |
33
-| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
34
-| `composio ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |
35
-| `composio py generate` | Generate Python type stubs |
26
+| Command | Description |
27
+| ------------------------------- | ---------------------------------------------------------- |
28
+| `composio version` | Display CLI version |
29
+| `composio whoami` | Show logged-in user's API key |
30
+| `composio login [--no-browser]` | OAuth2 login with browser redirect |
31
+| `composio logout` | Clear stored API key |
32
+| `composio upgrade` | Self-update binary from GitHub releases |
33
+| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
34
+| `composio ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |
35
+| `composio py generate` | Generate Python type stubs |
36
37
Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.
38
39
### Services (`src/services/`)
40
41
-| Service | Purpose |
42
-|---|---|
43
-| `ComposioUserContext` | Auth state — reads/writes `~/.composio/user-config.json`, merges env vars |
44
-| `ComposioSessionRepository` | Creates OAuth2 sessions, polls until `linked` state |
45
-| `ComposioToolkitsRepository` | API client — fetches toolkits, tools, trigger types; validates versions |
41
+| Service | Purpose |
42
+| ---------------------------------- | ---------------------------------------------------------------------------- |
43
+| `ComposioUserContext` | Auth state — reads/writes `~/.composio/user-config.json`, merges env vars |
44
+| `ComposioSessionRepository` | Creates OAuth2 sessions, polls until `linked` state |
45
+| `ComposioToolkitsRepository` | API client — fetches toolkits, tools, trigger types; validates versions |
46
| `ComposioToolkitsRepositoryCached` | Decorator over base repository with file-based caching and graceful fallback |
47
-| `NodeOs` | OS abstraction (`homedir`, `platform`, `arch`) |
48
-| `EnvLangDetector` | Detects project language (TS/Python) from config files and lock files |
49
-| `JsPackageManagerDetector` | Detects npm/pnpm/yarn/bun for helpful install instructions |
50
-| `UpgradeBinary` | Fetches latest release from GitHub, downloads and replaces binary |
47
+| `NodeOs` | OS abstraction (`homedir`, `platform`, `arch`) |
48
+| `EnvLangDetector` | Detects project language (TS/Python) from config files and lock files |
49
+| `JsPackageManagerDetector` | Detects npm/pnpm/yarn/bun for helpful install instructions |
50
+| `UpgradeBinary` | Fetches latest release from GitHub, downloads and replaces binary |
51
52
### Effects (`src/effects/`)
53
54
Reusable Effect computations for cross-cutting concerns:
55
56
-| Effect | Purpose |
57
-|---|---|
58
-| `app-config` | Reads `COMPOSIO_*` env vars (API_KEY, BASE_URL, CACHE_DIR, etc.) |
59
-| `debug-config` | Debug overrides (DEBUG_OVERRIDE_VERSION, etc.) |
60
-| `force-config` | Force flags (FORCE_USE_CACHE) |
61
-| `setup-cache-dir` | Ensures `~/.composio/` directory exists |
62
-| `toolkit-version-overrides` | Parses `COMPOSIO_TOOLKIT_VERSION_<NAME>=<ver>` env vars |
63
-| `validate-toolkit-versions` | Validates overrides against available API versions |
64
-| `with-log-level` | Configures logger from CLI flag or env var |
56
+| Effect | Purpose |
57
+| ------------------------------ | --------------------------------------------------------------------- |
58
+| `app-config` | Reads `COMPOSIO_*` env vars (API_KEY, BASE_URL, CACHE_DIR, etc.) |
59
+| `debug-config` | Debug overrides (DEBUG_OVERRIDE_VERSION, etc.) |
60
+| `force-config` | Force flags (FORCE_USE_CACHE) |
61
+| `setup-cache-dir` | Ensures `~/.composio/` directory exists |
62
+| `toolkit-version-overrides` | Parses `COMPOSIO_TOOLKIT_VERSION_<NAME>=<ver>` env vars |
63
+| `validate-toolkit-versions` | Validates overrides against available API versions |
64
+| `with-log-level` | Configures logger from CLI flag or env var |
65
| `find-composio-core-generated` | Locates `@composio/core` in node_modules (handles pnpm virtual store) |
66
-| `version` | Resolves CLI version from package.json |
67
-| `compare-semver` | Semantic version comparison for upgrade checks |
68
-| `log-metrics` | Formats and logs API request count and bytes transferred |
66
+| `version` | Resolves CLI version from package.json |
67
+| `compare-semver` | Semantic version comparison for upgrade checks |
68
+| `log-metrics` | Formats and logs API request count and bytes transferred |
69
70
### Models (`src/models/`)
71
@@ -119,14 +119,15 @@ The CLI uses the generator-based syntax throughout:
119
120
```typescript
121
Effect.gen(function* () {
122
- const service = yield* ServiceName; // resolve dependency
123
- const result = yield* someEffect; // await computation
124
- yield* Effect.log('message'); // side effect
122
+ const service = yield* ServiceName; // resolve dependency
123
+ const result = yield* someEffect; // await computation
124
+ yield* Effect.log('message'); // side effect
125
return result;
126
-})
126
+});
127
```
128
129
Key patterns:
130
+
131
- `Effect.all([...], { concurrency: 'unbounded' })` for parallel fetches
132
- `Layer.provide()` for dependency composition
133
- `Effect.mapError()` / `Effect.catchTag()` for typed error handling
@@ -134,20 +135,70 @@ Key patterns:
135
136
### Key Dependencies
137
137
-| Package | Role |
138
-|---|---|
139
-| `effect` | Core runtime, data types, concurrency |
140
-| `@effect/cli` | Command, Options, Args declaration and parsing |
141
-| `@effect/platform` | FileSystem, Terminal abstraction |
142
-| `@effect/platform-bun` | Bun runtime layer |
143
-| `@clack/prompts` | Terminal UI symbols (expanding to full interactive prompts) |
144
-| `ansis`, `picocolors` | Colored output |
145
-| `@composio/client` | Raw Composio API client |
146
-| `@composio/core` | Core SDK types and constants |
147
-| `@composio/ts-builders` | TypeScript AST code generation |
148
-| `semver` | Version comparison for upgrades |
149
-| `open` | Opens URLs in browser (login flow) |
150
-| `decompress` | Extracts downloaded binaries |
138
+| Package | Role |
139
+| ----------------------- | ------------------------------------------------------------------- |
140
+| `effect` | Core runtime, data types, concurrency |
141
+| `@effect/cli` | Command, Options, Args declaration and parsing |
142
+| `@effect/platform` | FileSystem, Terminal abstraction |
143
+| `@effect/platform-bun` | Bun runtime layer |
144
+| `@clack/prompts` | Terminal UI — prompts, spinners, logs, notes (all output to stderr) |
145
+| `ansis`, `picocolors` | Colored output |
146
+| `@composio/client` | Raw Composio API client |
147
+| `@composio/core` | Core SDK types and constants |
148
+| `@composio/ts-builders` | TypeScript AST code generation |
149
+| `semver` | Version comparison for upgrades |
150
+| `open` | Opens URLs in browser (login flow) |
151
+| `decompress` | Extracts downloaded binaries |
152
+
153
+---
154
+
155
+## Output Conventions: Composable CLI Output
156
+
157
+The CLI follows the Unix convention of separating human-readable decoration from machine-readable data:
158
+
159
+- **stdout** — data output only (`ui.output()`). This is what scripts and pipes capture.
160
+- **stderr** — all decoration (Clack spinners, logs, notes, intro/outro). Visible in terminal, invisible in pipes.
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.
170
+
171
+### Pattern
172
+
173
+```typescript
174
+// Data command (e.g., whoami):
175
+yield * ui.note(apiKey, 'API Key'); // Decoration → stderr (human sees pretty box)
176
+yield * ui.output(apiKey); // Data → stdout (scripts capture plain value)
177
+
178
+// Action command (e.g., login):
179
+yield * ui.intro('composio login'); // Decoration → stderr
180
+yield * ui.log.step('Redirecting'); // Decoration → stderr
181
+// No ui.output() call — nothing for scripts to capture
182
+```
183
+
184
+### How it works in practice
185
+
186
+```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
191
+
192
+composio login # All decoration visible (nothing to pipe)
193
+composio login 2>/dev/null # Silent (but still opens browser, polls API)
194
+```
195
+
196
+### Adding new commands
197
+
198
+When creating a new command, ask: "Does this command produce a value that scripts should capture?"
199
+
200
+- **Yes** → Use `ui.output(value)` for the data, `ui.log.*` / `ui.note()` for context
201
+- **No** → Use only `ui.log.*` / `ui.note()` / `ui.intro()` / `ui.outro()` — everything goes to stderr automatically
202
203
---
204
@@ -165,29 +216,30 @@ When working on CLI code that involves terminal UI, reference the Clack source f
216
217
### Key modules in `@clack/prompts`
218
168
-| Module | Purpose |
169
-|---|---|
170
-| `text.ts` | Text input prompt |
171
-| `password.ts` | Password input prompt |
172
-| `confirm.ts` | Yes/no confirmation prompt |
173
-| `select.ts` | Single-select list prompt |
174
-| `multi-select.ts` | Multi-select list prompt |
175
-| `group-multi-select.ts` | Grouped multi-select prompt |
176
-| `autocomplete.ts` | Autocomplete/search prompt |
177
-| `spinner.ts` | Loading spinner |
178
-| `progress-bar.ts` | Progress bar |
179
-| `log.ts` | Styled log messages |
180
-| `note.ts` | Boxed note output |
181
-| `task.ts` | Task runner with status |
182
-| `task-log.ts` | Task with streaming log output |
183
-| `stream.ts` | Streaming text output |
184
-| `box.ts` | Box drawing utility |
185
-| `messages.ts` | Intro/outro messages |
186
-| `common.ts` | Shared symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`, etc.) |
219
+| Module | Purpose |
220
+| ----------------------- | ------------------------------------------------------ |
221
+| `text.ts` | Text input prompt |
222
+| `password.ts` | Password input prompt |
223
+| `confirm.ts` | Yes/no confirmation prompt |
224
+| `select.ts` | Single-select list prompt |
225
+| `multi-select.ts` | Multi-select list prompt |
226
+| `group-multi-select.ts` | Grouped multi-select prompt |
227
+| `autocomplete.ts` | Autocomplete/search prompt |
228
+| `spinner.ts` | Loading spinner |
229
+| `progress-bar.ts` | Progress bar |
230
+| `log.ts` | Styled log messages |
231
+| `note.ts` | Boxed note output |
232
+| `task.ts` | Task runner with status |
233
+| `task-log.ts` | Task with streaming log output |
234
+| `stream.ts` | Streaming text output |
235
+| `box.ts` | Box drawing utility |
236
+| `messages.ts` | Intro/outro messages |
237
+| `common.ts` | Shared symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`, etc.) |
238
239
### Current clack usage in the CLI
240
241
The CLI currently imports from `@clack/prompts`:
242
+
243
- `S_BAR`, `S_BAR_H`, `unicodeOr` — Unicode box-drawing symbols for custom formatted output
244
245
### Guidelines
@@ -208,6 +260,7 @@ The CLI is built on the Effect.ts ecosystem. A local copy of the Effect source c
260
- **Branch:** `main`
261
262
When working on CLI code, reference the Effect source for accurate patterns:
263
+
264
- `ts/vendor/effect/packages/effect/src/` — core Effect runtime
265
- `ts/vendor/effect/packages/cli/src/` — @effect/cli (Command, Options, Args)
266
- `ts/vendor/effect/packages/platform/src/` — @effect/platform (FileSystem, Terminal)
ts/packages/cli/src/commands/version.cmd.ts
+1
@@ -18,6 +18,7 @@ export const versionCmd = Command.make('version', {}).pipe(
18
const ui = yield* TerminalUI;
19
const version = yield* getVersion;
20
yield* ui.log.info(version);
21
+ yield* ui.output(version);
22
23
yield* Effect.logDebug('Composio CLI version command executed successfully.');
24
})
ts/packages/cli/src/commands/whoami.cmd.ts
+5
-1
@@ -21,7 +21,11 @@ export const whoamiCmd = Command.make('whoami', {}).pipe(
21
yield* ctx.data.apiKey.pipe(
22
Option.match({
23
onNone: () => ui.log.warn('You are not logged in yet. Please run `composio login`.'),
24
- onSome: apiKey => ui.note(apiKey, 'API Key'),
24
+ onSome: apiKey =>
25
+ Effect.gen(function* () {
26
+ yield* ui.note(apiKey, 'API Key');
27
+ yield* ui.output(apiKey);
28
+ }),
29
})
30
);
31
})
ts/packages/cli/src/services/terminal-ui.ts
+34
-14
@@ -1,3 +1,5 @@
1
+import process from 'node:process';
2
+import type { Writable } from 'node:stream';
3
import * as p from '@clack/prompts';
4
import { Context, Effect, Exit, Layer } from 'effect';
5
@@ -19,9 +21,16 @@ export interface SpinnerHandle {
21
// ---------------------------------------------------------------------------
22
23
export interface TerminalUI {
22
- /** Display a session start marker (e.g., `┌ title`). */
24
+ /**
25
+ * Write raw data to stdout for piping and scripting.
26
+ * This is the ONLY method that writes to stdout — everything else goes to stderr.
27
+ * Use this for values that scripts should capture (API keys, version strings, etc.).
28
+ */
29
+ readonly output: (data: string) => Effect.Effect<void>;
30
+
31
+ /** Display a session start marker (e.g., `┌ title`). Writes to stderr. */
32
readonly intro: (title: string) => Effect.Effect<void>;
24
- /** Display a session end marker (e.g., `└ message`). */
33
+ /** Display a session end marker (e.g., `└ message`). Writes to stderr. */
34
readonly outro: (message: string) => Effect.Effect<void>;
35
36
/** Structured log output with severity-specific symbols. */
@@ -84,6 +93,12 @@ export const TerminalUI = Context.GenericTag<TerminalUI>('services/TerminalUI');
93
// TerminalUILive — production layer using @clack/prompts
94
// ---------------------------------------------------------------------------
95
96
+/**
97
+ * All decoration (spinners, logs, notes, intro/outro) writes to stderr.
98
+ * This keeps stdout clean for data output that scripts and pipes capture.
99
+ */
100
+const DECORATION: Writable = process.stderr;
101
+
102
function createClackSpinnerHandle(s: p.SpinnerResult, defaultMessage: string): SpinnerHandle {
103
return {
104
message: (msg: string) => Effect.sync(() => s.message(msg)),
@@ -93,24 +108,29 @@ function createClackSpinnerHandle(s: p.SpinnerResult, defaultMessage: string): S
108
}
109
110
const makeLive: TerminalUI = {
96
- intro: title => Effect.sync(() => p.intro(title)),
97
- outro: message => Effect.sync(() => p.outro(message)),
111
+ output: data =>
112
+ Effect.sync(() => {
113
+ process.stdout.write(`${data}\n`);
114
+ }),
115
+
116
+ intro: title => Effect.sync(() => p.intro(title, { output: DECORATION })),
117
+ outro: message => Effect.sync(() => p.outro(message, { output: DECORATION })),
118
119
log: {
100
- info: message => Effect.sync(() => p.log.info(message)),
101
- success: message => Effect.sync(() => p.log.success(message)),
102
- warn: message => Effect.sync(() => p.log.warn(message)),
103
- error: message => Effect.sync(() => p.log.error(message)),
104
- step: message => Effect.sync(() => p.log.step(message)),
105
- message: message => Effect.sync(() => p.log.message(message)),
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 })),
126
},
127
108
- note: (message, title) => Effect.sync(() => p.note(message, title ?? '')),
128
+ note: (message, title) => Effect.sync(() => p.note(message, title ?? '', { output: DECORATION })),
129
130
withSpinner: (message, effect, options) =>
131
Effect.acquireUseRelease(
132
Effect.sync(() => {
113
- const s = p.spinner();
133
+ const s = p.spinner({ output: DECORATION });
134
s.start(message);
135
return s;
136
}),
@@ -131,7 +151,7 @@ const makeLive: TerminalUI = {
151
152
makeSpinner: message =>
153
Effect.sync(() => {
134
- const s = p.spinner();
154
+ const s = p.spinner({ output: DECORATION });
155
s.start(message);
156
return createClackSpinnerHandle(s, message);
157
}),
@@ -139,7 +159,7 @@ const makeLive: TerminalUI = {
159
useMakeSpinner: (message, use) =>
160
Effect.acquireUseRelease(
161
Effect.sync(() => {
142
- const s = p.spinner();
162
+ const s = p.spinner({ output: DECORATION });
163
s.start(message);
164
return { raw: s, handle: createClackSpinnerHandle(s, message) };
165
}),
ts/packages/cli/test/__utils__/services/terminal-ui-test.ts
+2
@@ -10,6 +10,8 @@ import { TerminalUI } from 'src/services/terminal-ui';
10
export const TerminalUITest = Layer.succeed(
11
TerminalUI,
12
TerminalUI.of({
13
+ output: data => Console.log(data),
14
+
15
intro: title => Console.log(`-- ${title} --`),
16
outro: message => Console.log(`-- ${message} --`),
17
ts/packages/cli/test/src/services/terminal-ui.test.ts
+14
@@ -5,6 +5,20 @@ import { TestLive, MockConsole } from 'test/__utils__';
5
6
describe('TerminalUI', () => {
7
layer(TestLive())(it => {
8
+ // -----------------------------------------------------------------------
9
+ // Data output
10
+ // -----------------------------------------------------------------------
11
+
12
+ it.scoped('output writes raw data capturable by MockConsole', () =>
13
+ Effect.gen(function* () {
14
+ const ui = yield* TerminalUI;
15
+ yield* ui.output('ak_test123');
16
+
17
+ const lines = yield* MockConsole.getLines();
18
+ expect(lines).toContain('ak_test123');
19
+ })
20
+ );
21
+
22
// -----------------------------------------------------------------------
23
// Log text capture
24
// -----------------------------------------------------------------------