Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
feat(cli): route Clack decoration to stderr and add ui.output() for composable data
jkomynod09a6b4450c9
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.mdindex f05ccf216..2acba2e80 100644--- a/ts/packages/cli/AGENTS.md+++ b/ts/packages/cli/AGENTS.md@@ -23,49 +23,49 @@ Errors are captured via the custom `effect-errors/` module, which provides sourcEach command is declared with `@effect/cli`'s `Command.make()` pattern:-| Command | Description |-|---|---|-| `composio version` | Display CLI version |-| `composio whoami` | Show logged-in user's API key |-| `composio login [--no-browser]` | OAuth2 login with browser redirect |-| `composio logout` | Clear stored API key |-| `composio upgrade` | Self-update binary from GitHub releases |-| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |-| `composio ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |-| `composio py generate` | Generate Python type stubs |+| Command | Description |+| ------------------------------- | ---------------------------------------------------------- |+| `composio version` | Display CLI version |+| `composio whoami` | Show logged-in user's API key |+| `composio login [--no-browser]` | OAuth2 login with browser redirect |+| `composio logout` | Clear stored API key |+| `composio upgrade` | Self-update binary from GitHub releases |+| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |+| `composio ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |+| `composio py generate` | Generate Python type stubs |Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.### Services (`src/services/`)-| Service | Purpose |-|---|---|-| `ComposioUserContext` | Auth state — reads/writes `~/.composio/user-config.json`, merges env vars |-| `ComposioSessionRepository` | Creates OAuth2 sessions, polls until `linked` state |-| `ComposioToolkitsRepository` | API client — fetches toolkits, tools, trigger types; validates versions |+| Service | Purpose |+| ---------------------------------- | ---------------------------------------------------------------------------- |+| `ComposioUserContext` | Auth state — reads/writes `~/.composio/user-config.json`, merges env vars |+| `ComposioSessionRepository` | Creates OAuth2 sessions, polls until `linked` state |+| `ComposioToolkitsRepository` | API client — fetches toolkits, tools, trigger types; validates versions || `ComposioToolkitsRepositoryCached` | Decorator over base repository with file-based caching and graceful fallback |-| `NodeOs` | OS abstraction (`homedir`, `platform`, `arch`) |-| `EnvLangDetector` | Detects project language (TS/Python) from config files and lock files |-| `JsPackageManagerDetector` | Detects npm/pnpm/yarn/bun for helpful install instructions |-| `UpgradeBinary` | Fetches latest release from GitHub, downloads and replaces binary |+| `NodeOs` | OS abstraction (`homedir`, `platform`, `arch`) |+| `EnvLangDetector` | Detects project language (TS/Python) from config files and lock files |+| `JsPackageManagerDetector` | Detects npm/pnpm/yarn/bun for helpful install instructions |+| `UpgradeBinary` | Fetches latest release from GitHub, downloads and replaces binary |### Effects (`src/effects/`)Reusable Effect computations for cross-cutting concerns:-| Effect | Purpose |-|---|---|-| `app-config` | Reads `COMPOSIO_*` env vars (API_KEY, BASE_URL, CACHE_DIR, etc.) |-| `debug-config` | Debug overrides (DEBUG_OVERRIDE_VERSION, etc.) |-| `force-config` | Force flags (FORCE_USE_CACHE) |-| `setup-cache-dir` | Ensures `~/.composio/` directory exists |-| `toolkit-version-overrides` | Parses `COMPOSIO_TOOLKIT_VERSION_<NAME>=<ver>` env vars |-| `validate-toolkit-versions` | Validates overrides against available API versions |-| `with-log-level` | Configures logger from CLI flag or env var |+| Effect | Purpose |+| ------------------------------ | --------------------------------------------------------------------- |+| `app-config` | Reads `COMPOSIO_*` env vars (API_KEY, BASE_URL, CACHE_DIR, etc.) |+| `debug-config` | Debug overrides (DEBUG_OVERRIDE_VERSION, etc.) |+| `force-config` | Force flags (FORCE_USE_CACHE) |+| `setup-cache-dir` | Ensures `~/.composio/` directory exists |+| `toolkit-version-overrides` | Parses `COMPOSIO_TOOLKIT_VERSION_<NAME>=<ver>` env vars |+| `validate-toolkit-versions` | Validates overrides against available API versions |+| `with-log-level` | Configures logger from CLI flag or env var || `find-composio-core-generated` | Locates `@composio/core` in node_modules (handles pnpm virtual store) |-| `version` | Resolves CLI version from package.json |-| `compare-semver` | Semantic version comparison for upgrade checks |-| `log-metrics` | Formats and logs API request count and bytes transferred |+| `version` | Resolves CLI version from package.json |+| `compare-semver` | Semantic version comparison for upgrade checks |+| `log-metrics` | Formats and logs API request count and bytes transferred |### Models (`src/models/`)@@ -119,14 +119,15 @@ The CLI uses the generator-based syntax throughout:```typescriptEffect.gen(function* () {- const service = yield* ServiceName; // resolve dependency- const result = yield* someEffect; // await computation- yield* Effect.log('message'); // side effect+ const service = yield* ServiceName; // resolve dependency+ const result = yield* someEffect; // await computation+ yield* Effect.log('message'); // side effectreturn result;-})+});```Key patterns:+- `Effect.all([...], { concurrency: 'unbounded' })` for parallel fetches- `Layer.provide()` for dependency composition- `Effect.mapError()` / `Effect.catchTag()` for typed error handling@@ -134,20 +135,70 @@ Key patterns:### Key Dependencies-| Package | Role |-|---|---|-| `effect` | Core runtime, data types, concurrency |-| `@effect/cli` | Command, Options, Args declaration and parsing |-| `@effect/platform` | FileSystem, Terminal abstraction |-| `@effect/platform-bun` | Bun runtime layer |-| `@clack/prompts` | Terminal UI symbols (expanding to full interactive prompts) |-| `ansis`, `picocolors` | Colored output |-| `@composio/client` | Raw Composio API client |-| `@composio/core` | Core SDK types and constants |-| `@composio/ts-builders` | TypeScript AST code generation |-| `semver` | Version comparison for upgrades |-| `open` | Opens URLs in browser (login flow) |-| `decompress` | Extracts downloaded binaries |+| Package | Role |+| ----------------------- | ------------------------------------------------------------------- |+| `effect` | Core runtime, data types, concurrency |+| `@effect/cli` | Command, Options, Args declaration and parsing |+| `@effect/platform` | FileSystem, Terminal abstraction |+| `@effect/platform-bun` | Bun runtime layer |+| `@clack/prompts` | Terminal UI — prompts, spinners, logs, notes (all output to stderr) |+| `ansis`, `picocolors` | Colored output |+| `@composio/client` | Raw Composio API client |+| `@composio/core` | Core SDK types and constants |+| `@composio/ts-builders` | TypeScript AST code generation |+| `semver` | Version comparison for upgrades |+| `open` | Opens URLs in browser (login flow) |+| `decompress` | Extracts downloaded binaries |++---++## Output Conventions: Composable CLI Output++The CLI follows the Unix convention of separating human-readable decoration from machine-readable data:++- **stdout** — data output only (`ui.output()`). This is what scripts and pipes capture.+- **stderr** — all decoration (Clack spinners, logs, notes, intro/outro). Visible in terminal, invisible in pipes.++### Rules++1. **All `TerminalUI` methods except `output()` write to stderr** via Clack's `{ output: process.stderr }` option.+2. **`ui.output(data)` writes to stdout** — use this for values that scripts should capture (API keys, version strings, generated paths).+3. **Action commands** (login, logout, upgrade, generate) produce no stdout data — their output is purely decorative.+4. **Data commands** (whoami, version) produce both decoration (stderr) and data (stdout).+5. **Never write data to stderr** — decoration methods are for human context only.+6. **Never write decoration to stdout** — it breaks pipes, `$(...)` captures, and `> file` redirects.++### Pattern++```typescript+// Data command (e.g., whoami):+yield * ui.note(apiKey, 'API Key'); // Decoration → stderr (human sees pretty box)+yield * ui.output(apiKey); // Data → stdout (scripts capture plain value)++// Action command (e.g., login):+yield * ui.intro('composio login'); // Decoration → stderr+yield * ui.log.step('Redirecting'); // Decoration → stderr+// No ui.output() call — nothing for scripts to capture+```++### How it works in practice++```bash+composio whoami # Human sees pretty box AND plain key+composio whoami 2>/dev/null # Only the API key (suppresses decoration)+API_KEY=$(composio whoami) # Variable gets clean key, box shows in terminal+composio whoami | pbcopy # Clipboard gets clean key++composio login # All decoration visible (nothing to pipe)+composio login 2>/dev/null # Silent (but still opens browser, polls API)+```++### Adding new commands++When creating a new command, ask: "Does this command produce a value that scripts should capture?"++- **Yes** → Use `ui.output(value)` for the data, `ui.log.*` / `ui.note()` for context+- **No** → Use only `ui.log.*` / `ui.note()` / `ui.intro()` / `ui.outro()` — everything goes to stderr automatically---@@ -165,29 +216,30 @@ When working on CLI code that involves terminal UI, reference the Clack source f### Key modules in `@clack/prompts`-| Module | Purpose |-|---|---|-| `text.ts` | Text input prompt |-| `password.ts` | Password input prompt |-| `confirm.ts` | Yes/no confirmation prompt |-| `select.ts` | Single-select list prompt |-| `multi-select.ts` | Multi-select list prompt |-| `group-multi-select.ts` | Grouped multi-select prompt |-| `autocomplete.ts` | Autocomplete/search prompt |-| `spinner.ts` | Loading spinner |-| `progress-bar.ts` | Progress bar |-| `log.ts` | Styled log messages |-| `note.ts` | Boxed note output |-| `task.ts` | Task runner with status |-| `task-log.ts` | Task with streaming log output |-| `stream.ts` | Streaming text output |-| `box.ts` | Box drawing utility |-| `messages.ts` | Intro/outro messages |-| `common.ts` | Shared symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`, etc.) |+| Module | Purpose |+| ----------------------- | ------------------------------------------------------ |+| `text.ts` | Text input prompt |+| `password.ts` | Password input prompt |+| `confirm.ts` | Yes/no confirmation prompt |+| `select.ts` | Single-select list prompt |+| `multi-select.ts` | Multi-select list prompt |+| `group-multi-select.ts` | Grouped multi-select prompt |+| `autocomplete.ts` | Autocomplete/search prompt |+| `spinner.ts` | Loading spinner |+| `progress-bar.ts` | Progress bar |+| `log.ts` | Styled log messages |+| `note.ts` | Boxed note output |+| `task.ts` | Task runner with status |+| `task-log.ts` | Task with streaming log output |+| `stream.ts` | Streaming text output |+| `box.ts` | Box drawing utility |+| `messages.ts` | Intro/outro messages |+| `common.ts` | Shared symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`, etc.) |### Current clack usage in the CLIThe CLI currently imports from `@clack/prompts`:+- `S_BAR`, `S_BAR_H`, `unicodeOr` — Unicode box-drawing symbols for custom formatted output### Guidelines@@ -208,6 +260,7 @@ The CLI is built on the Effect.ts ecosystem. A local copy of the Effect source c- **Branch:** `main`When working on CLI code, reference the Effect source for accurate patterns:+- `ts/vendor/effect/packages/effect/src/` — core Effect runtime- `ts/vendor/effect/packages/cli/src/` — @effect/cli (Command, Options, Args)- `ts/vendor/effect/packages/platform/src/` — @effect/platform (FileSystem, Terminal)diff --git a/ts/packages/cli/src/commands/version.cmd.ts b/ts/packages/cli/src/commands/version.cmd.tsindex 8356c2204..f67abbbcf 100644--- a/ts/packages/cli/src/commands/version.cmd.ts+++ b/ts/packages/cli/src/commands/version.cmd.ts@@ -18,6 +18,7 @@ export const versionCmd = Command.make('version', {}).pipe(const ui = yield* TerminalUI;const version = yield* getVersion;yield* ui.log.info(version);+ yield* ui.output(version);yield* Effect.logDebug('Composio CLI version command executed successfully.');})diff --git a/ts/packages/cli/src/commands/whoami.cmd.ts b/ts/packages/cli/src/commands/whoami.cmd.tsindex 9c5bf9501..a0824ac7b 100644--- a/ts/packages/cli/src/commands/whoami.cmd.ts+++ b/ts/packages/cli/src/commands/whoami.cmd.ts@@ -21,7 +21,11 @@ export const whoamiCmd = Command.make('whoami', {}).pipe(yield* ctx.data.apiKey.pipe(Option.match({onNone: () => ui.log.warn('You are not logged in yet. Please run `composio login`.'),- onSome: apiKey => ui.note(apiKey, 'API Key'),+ onSome: apiKey =>+ Effect.gen(function* () {+ yield* ui.note(apiKey, 'API Key');+ yield* ui.output(apiKey);+ }),}));})diff --git a/ts/packages/cli/src/services/terminal-ui.ts b/ts/packages/cli/src/services/terminal-ui.tsindex c0ec89c8a..d74a794e8 100644--- a/ts/packages/cli/src/services/terminal-ui.ts+++ b/ts/packages/cli/src/services/terminal-ui.ts@@ -1,3 +1,5 @@+import process from 'node:process';+import type { Writable } from 'node:stream';import * as p from '@clack/prompts';import { Context, Effect, Exit, Layer } from 'effect';@@ -19,9 +21,16 @@ export interface SpinnerHandle {// ---------------------------------------------------------------------------export interface TerminalUI {- /** Display a session start marker (e.g., `┌ title`). */+ /**+ * Write raw data to stdout for piping and scripting.+ * This is the ONLY method that writes to stdout — everything else goes to stderr.+ * Use this for values that scripts should capture (API keys, version strings, etc.).+ */+ readonly output: (data: string) => Effect.Effect<void>;++ /** Display a session start marker (e.g., `┌ title`). Writes to stderr. */readonly intro: (title: string) => Effect.Effect<void>;- /** Display a session end marker (e.g., `└ message`). */+ /** Display a session end marker (e.g., `└ message`). Writes to stderr. */readonly outro: (message: string) => Effect.Effect<void>;/** Structured log output with severity-specific symbols. */@@ -84,6 +93,12 @@ export const TerminalUI = Context.GenericTag<TerminalUI>('services/TerminalUI');// TerminalUILive — production layer using @clack/prompts// ---------------------------------------------------------------------------+/**+ * All decoration (spinners, logs, notes, intro/outro) writes to stderr.+ * This keeps stdout clean for data output that scripts and pipes capture.+ */+const DECORATION: Writable = process.stderr;+function createClackSpinnerHandle(s: p.SpinnerResult, defaultMessage: string): SpinnerHandle {return {message: (msg: string) => Effect.sync(() => s.message(msg)),@@ -93,24 +108,29 @@ function createClackSpinnerHandle(s: p.SpinnerResult, defaultMessage: string): S}const makeLive: TerminalUI = {- intro: title => Effect.sync(() => p.intro(title)),- outro: message => Effect.sync(() => p.outro(message)),+ output: data =>+ Effect.sync(() => {+ process.stdout.write(`${data}\n`);+ }),++ intro: title => Effect.sync(() => p.intro(title, { output: DECORATION })),+ outro: message => Effect.sync(() => p.outro(message, { output: DECORATION })),log: {- info: message => Effect.sync(() => p.log.info(message)),- success: message => Effect.sync(() => p.log.success(message)),- warn: message => Effect.sync(() => p.log.warn(message)),- error: message => Effect.sync(() => p.log.error(message)),- step: message => Effect.sync(() => p.log.step(message)),- message: message => Effect.sync(() => p.log.message(message)),+ info: message => Effect.sync(() => p.log.info(message, { output: DECORATION })),+ success: message => Effect.sync(() => p.log.success(message, { output: DECORATION })),+ warn: message => Effect.sync(() => p.log.warn(message, { output: DECORATION })),+ error: message => Effect.sync(() => p.log.error(message, { output: DECORATION })),+ step: message => Effect.sync(() => p.log.step(message, { output: DECORATION })),+ message: message => Effect.sync(() => p.log.message(message, { output: DECORATION })),},- note: (message, title) => Effect.sync(() => p.note(message, title ?? '')),+ note: (message, title) => Effect.sync(() => p.note(message, title ?? '', { output: DECORATION })),withSpinner: (message, effect, options) =>Effect.acquireUseRelease(Effect.sync(() => {- const s = p.spinner();+ const s = p.spinner({ output: DECORATION });s.start(message);return s;}),@@ -131,7 +151,7 @@ const makeLive: TerminalUI = {makeSpinner: message =>Effect.sync(() => {- const s = p.spinner();+ const s = p.spinner({ output: DECORATION });s.start(message);return createClackSpinnerHandle(s, message);}),@@ -139,7 +159,7 @@ const makeLive: TerminalUI = {useMakeSpinner: (message, use) =>Effect.acquireUseRelease(Effect.sync(() => {- const s = p.spinner();+ const s = p.spinner({ output: DECORATION });s.start(message);return { raw: s, handle: createClackSpinnerHandle(s, message) };}),diff --git a/ts/packages/cli/test/__utils__/services/terminal-ui-test.ts b/ts/packages/cli/test/__utils__/services/terminal-ui-test.tsindex 2046ed1a1..b30cdf35a 100644--- a/ts/packages/cli/test/__utils__/services/terminal-ui-test.ts+++ b/ts/packages/cli/test/__utils__/services/terminal-ui-test.ts@@ -10,6 +10,8 @@ import { TerminalUI } from 'src/services/terminal-ui';export const TerminalUITest = Layer.succeed(TerminalUI,TerminalUI.of({+ output: data => Console.log(data),+intro: title => Console.log(`-- ${title} --`),outro: message => Console.log(`-- ${message} --`),diff --git a/ts/packages/cli/test/src/services/terminal-ui.test.ts b/ts/packages/cli/test/src/services/terminal-ui.test.tsindex 2d0c0764a..aab88f320 100644--- a/ts/packages/cli/test/src/services/terminal-ui.test.ts+++ b/ts/packages/cli/test/src/services/terminal-ui.test.ts@@ -5,6 +5,20 @@ import { TestLive, MockConsole } from 'test/__utils__';describe('TerminalUI', () => {layer(TestLive())(it => {+ // -----------------------------------------------------------------------+ // Data output+ // -----------------------------------------------------------------------++ it.scoped('output writes raw data capturable by MockConsole', () =>+ Effect.gen(function* () {+ const ui = yield* TerminalUI;+ yield* ui.output('ak_test123');++ const lines = yield* MockConsole.getLines();+ expect(lines).toContain('ak_test123');+ })+ );+// -----------------------------------------------------------------------// Log text capture// -----------------------------------------------------------------------