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, 04:45 UTC
CLI Design
Principles
- Keep stdout for data and stderr for human-readable decoration.
- Use
ui.output()only for values scripts should capture. - Keep quiet/piped mode clean.
- Prefer flags over ambiguous positional arguments.
- Use
--json,--dry-run,--force,--no-input, and--no-browserconsistently when the command shape needs them. - Never accept secrets through flags.
Help And Errors
- Help text is user experience. Lead with concise descriptions and common examples.
- Expected errors should tell the user what happened and the next command or fix.
- Unexpected errors should preserve debug detail through the existing effect-error machinery.
Interactivity
- Use
@clack/promptsthrough the existing CLI UI abstractions. - Prompt only when stdin is a TTY.
- Non-interactive mode should fail with actionable messages instead of hanging.
Configuration And Exit Codes
- 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 insrc/config(APP_CONFIGfor user-facingCOMPOSIO_*settings,DEBUG_CONFIG,TELEMETRY_CONFIG,HOST_CONFIG,GITHUB_CONFIG); add new variables there, never inline. Tests injectConfigProvider.fromEnvRecord({...}). - Persistent user/auth state lives in
~/.composio/config.jsonand~/.composio/user_data.json. The API key can be stored in the OS keyring.ComposioUserContextapplies environment overrides to stored values. - Project-scoped data uses a project-local
.composio/directory. - Exit
0on success and1on failure, or75(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 (retryAdviceForinsrc/effects/retry-advice.ts). A request that failed in flight and may have taken effect exits1; 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 exits0;composio runends the way its script did (its code, or the same signal). Never assignprocess.exitCode: an error declares[Runtime.errorExitCode]/[Runtime.errorReported](effectRuntime), andRuntime.defaultTeardown, run by the CLI's runner (src/run-main.ts), picks the code. Never install signal handlers in a command; cooperate throughShutdownSignalinstead (seets/packages/cli/AGENTS.md). There is no distinct "invalid usage" exit code — do not invent one.
References
- CLI architecture:
ts/packages/cli/AGENTS.md. - Effect and Clack sources are read-only under
ts/vendor/.