@devries-cameron20 / composio Mirror · read-only
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 21, 06:00 UTC

next
md 34 lines 2.79 KB
Rendered Raw
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/`.