Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 2.79 KB

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-browser consistently 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/prompts through 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 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({...}).
  • 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.
  • Project-scoped data uses a project-local .composio/ directory.
  • 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.

References

  • CLI architecture: ts/packages/cli/AGENTS.md.
  • Effect and Clack sources are read-only under ts/vendor/.