Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Command data and lifecycle |
| 2 | |
| 3 | ## Producing and consuming data |
| 4 | |
| 5 | [TerminalUI](../../../../ts/packages/cli/src/services/terminal-ui.ts) owns terminal output and prompts. Each stream reports whether it is attached to a terminal through `isTTY`. The three stream capabilities are independent. |
| 6 | |
| 7 | | Concern | Current behavior | |
| 8 | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | |
| 9 | | Machine data | `ui.output(text)` writes a newline to redirected stdout. Visible TTY stdout stays silent unless `{ force: true }` is set. | |
| 10 | | Human decoration | `ui.log`, `note`, `intro`, `outro`, and spinners use stderr and disappear when stderr is not a TTY. | |
| 11 | | Persistent diagnostics | `ui.error(text)` writes to stderr even when redirected. It also carries protocol metadata such as `RUN_LOG_FILE`. | |
| 12 | | Prompts | `canPrompt` requires both stdin and stderr to be TTYs. Piping stdout alone does not disable prompts. | |
| 13 | |
| 14 | A command serializes its machine result before calling `output`. A command without a separate human renderer uses `force: true` when its data must remain visible on a terminal. Output consumers must follow that command's contract. `proxy` can return text or JSON, while listeners emit a stream rather than one JSON document. |
| 15 | |
| 16 | [resolveExplicitTextInput](../../../../ts/packages/cli/src/effects/resolve-optional-text-input.ts) resolves an input flag: a literal string, `@file`, or `-` / `@-` to read stdin to end of input. With no flag it returns `undefined` and never reads stdin, so a command such as `proxy` or `listen` cannot wait on a pipe it was handed. `composio execute` alone also reads JSON piped without `-d` (`resolveInput` in `tools.execute.arguments.ts`) and fails when the pipe sends nothing within `PIPED_STDIN_SILENCE_TIMEOUT`. The command validates supplied data with its own parser and schema before using it. |
| 17 | |
| 18 | [Stdin.readAll](../../../../ts/packages/cli/src/services/stdin.ts) buffers size-limited input until end of input (EOF). It is not a reader for an unlimited event stream. A producer that never closes stdin keeps the command waiting. `TestLive({ stdin: { isTTY: false, data: '...' } })` supplies finite test input without consuming the test runner's stdin. |
| 19 | |
| 20 | ## Commands that do more than request and print |
| 21 | |
| 22 | | Command | Behavior that changes the implementation approach | |
| 23 | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 24 | | `listen` | A realtime subscription can run indefinitely without `--timeout` or `--max-events`. It writes payload files and an `events.jsonl` index, and emits status and event lines. `--stream` also emits inline payload values. | |
| 25 | | `dev triggers listen` | A long-lived listener can append to an output file or forward events to a URL. Each sink can fail independently. | |
| 26 | | `run` | A child process inherits stdin, stdout, and stderr. Arbitrary script output is not a CLI JSON result. The command announces a log path on stderr and preserves the child's exit outcome. | |
| 27 | | `proxy` | A successful proxy operation can contain an upstream HTTP error response. The command's exit code alone does not establish an upstream success status. | |
| 28 | |
| 29 | The [listen handler](../../../../ts/packages/cli/src/commands/listen/listen.handler.ts) uses scoped event fibers and `acquireUseRelease` for temporary-trigger cleanup. It does not collect the full event stream into memory. Its in-memory event-id set still grows with the subscription, so an agent session needs a bounded duration or event count. |
| 30 | |
| 31 | [Sink failure handling](../../../../ts/packages/cli/src/commands/triggers/sink-failures.ts) counts failures and continues by default. The stop summary remains visible on redirected stderr. `--fail-fast` stops on the first sink failure and exits 1. A clean listener exit therefore does not prove every event was saved or forwarded. On a count or timeout stop, accepted event work gets a bounded drain. A signal stop interrupts active event fibers before release, so it does not guarantee that every accepted write completed. |
| 32 | |
| 33 | ## Ctrl+C, Ctrl+D and cleanup |
| 34 | |
| 35 | The [runner](../../../../ts/packages/cli/src/run-main.ts) owns SIGINT, SIGTERM, and SIGHUP. Handlers cooperate through [ShutdownSignal](../../../../ts/packages/cli/src/services/shutdown-signal.ts). Resource cleanup belongs in scoped Effects and finalizers. |
| 36 | |
| 37 | | Situation | Result | |
| 38 | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
| 39 | | Ctrl+C interrupts a normal command | An interruption-only outcome after SIGINT exits 130. SIGTERM and SIGHUP use 143 and 129. | |
| 40 | | A subscribed listener receives Ctrl+C or SIGTERM | It cooperates and normally exits 0 after release. Before subscription confirmation, interruption still uses 130 or 143. | |
| 41 | | `run` receives a stop signal | It forwards the signal to its child process group and mirrors how the child ends. A child that handles the signal can exit 0. | |
| 42 | | A second signal arrives, or shutdown exceeds 10 seconds | The runner forces termination. Finalizers are not guaranteed to complete. | |
| 43 | | A finite stdin read receives EOF | `Stdin.readAll()` returns the buffered input. In a Unix terminal in cooked mode, Ctrl+D on an empty input line produces EOF. It is not a process-wide stop signal. | |
| 44 | | Clack reports prompt cancellation | `confirm` returns false. `select` returns the first option. Ctrl+D has no CLI-wide cancellation contract in raw prompts and is not a substitute for Ctrl+C. | |
| 45 | |
| 46 | When prompting is unavailable, `confirm` returns its configured default, which is true if omitted. `select` returns the first option. A handler must not treat either fallback as a person's explicit approval. Destructive commands need an explicit noninteractive policy, as in `connections remove --yes`. |
| 47 | |
| 48 | ## Recovery for agents |
| 49 | |
| 50 | A parsed, authenticated invocation can still fail after a remote action took effect. [Idempotent request options](../../../../ts/packages/cli/src/services/composio-request.ts) enable retries only for calls known to be safe to repeat. An agent checks remote state before repeating a create, delete, execution, or proxy action after a timeout or interruption. |
| 51 | |
| 52 | A recovery flow keeps stdout and stderr separate, inspects the exit outcome, and applies the command's output contract. A nonzero exit can still accompany useful execution JSON. A zero listener exit can accompany sink-failure diagnostics. For `run`, the child script defines the meaning of its output and exit status. |
| 53 | |
| 54 | After a listener is force-killed, temporary-trigger cleanup and accepted writes may be incomplete. Existing payload files and the stop diagnostics are evidence, not proof of complete delivery. Prompt defaults, EOF, and a clean shutdown do not authorize an agent to infer that a requested side effect succeeded. |