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 | # CLI Design |
| 2 | |
| 3 | ## Principles |
| 4 | |
| 5 | - Keep stdout for data and stderr for human-readable decoration. |
| 6 | - Use `ui.output()` only for values scripts should capture. |
| 7 | - Keep quiet/piped mode clean. |
| 8 | - Prefer flags over ambiguous positional arguments. |
| 9 | - Use `--json`, `--dry-run`, `--force`, `--no-input`, and `--no-browser` consistently when the command shape needs them. |
| 10 | - Never accept secrets through flags. |
| 11 | |
| 12 | ## Help And Errors |
| 13 | |
| 14 | - Help text is user experience. Lead with concise descriptions and common examples. |
| 15 | - Expected errors should tell the user what happened and the next command or fix. |
| 16 | - Unexpected errors should preserve debug detail through the existing effect-error machinery. |
| 17 | |
| 18 | ## Interactivity |
| 19 | |
| 20 | - Use `@clack/prompts` through the existing CLI UI abstractions. |
| 21 | - Prompt only when stdin is a TTY. |
| 22 | - Non-interactive mode should fail with actionable messages instead of hanging. |
| 23 | |
| 24 | ## Configuration And Exit Codes |
| 25 | |
| 26 | - Runtime config is read from environment variables via `effect/Config`. Every variable the CLI reads is declared, under its full name, in one of the catalogs in `src/config` (`APP_CONFIG` for user-facing `COMPOSIO_*` settings, `DEBUG_CONFIG`, `TELEMETRY_CONFIG`, `HOST_CONFIG`, `GITHUB_CONFIG`); add new variables there, never inline. Tests inject `ConfigProvider.fromEnvRecord({...})`. |
| 27 | - Persistent user/auth state lives in `~/.composio/config.json` and `~/.composio/user_data.json`. The API key can be stored in the OS keyring. `ComposioUserContext` applies environment overrides to stored values. |
| 28 | - Project-scoped data uses a project-local `.composio/` directory. |
| 29 | - Exit `0` on success and `1` on failure, or `75` (`EX_TEMPFAIL`) when the failure is a request that is safe to send again as it is: one the API refused with a 429, or one with an idempotent method that timed out, lost its connection, or got a 408 or 5xx (`retryAdviceFor` in `src/effects/retry-advice.ts`). A request that failed in flight and may have taken effect exits `1`; where the command knows it has a side effect (`composio execute`), it says to check before running it again. A command a signal cancels exits 128 + the signal's number: `130` (Ctrl-C), `143` (SIGTERM), `129` (SIGHUP). A listener stopped with Ctrl-C or SIGTERM once subscribed exits `0`; `composio run` ends the way its script did (its code, or the same signal). Never assign `process.exitCode`: an error declares `[Runtime.errorExitCode]` / `[Runtime.errorReported]` (effect `Runtime`), and `Runtime.defaultTeardown`, run by the CLI's runner (`src/run-main.ts`), picks the code. Never install signal handlers in a command; cooperate through `ShutdownSignal` instead (see `ts/packages/cli/AGENTS.md`). There is no distinct "invalid usage" exit code — do not invent one. |
| 30 | |
| 31 | ## References |
| 32 | |
| 33 | - CLI architecture: `ts/packages/cli/AGENTS.md`. |
| 34 | - Effect and Clack sources are read-only under `ts/vendor/`. |