@devries-cameron20 / composio Mirror · read-only / commits / d09a6b445
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 08:15 UTC

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 // -----------------------------------------------------------------------