Skip to content

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

feat(ai): add "create-cli" skill

jkomyno33e6c97f3189
diff --git a/.claude/skills/create-cli/SKILL.md b/.claude/skills/create-cli/SKILL.md
new file mode 120000
index 000000000..bb37a9f12
--- /dev/null
+++ b/.claude/skills/create-cli/SKILL.md
@@ -0,0 +1 @@
+../../../ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc
\ No newline at end of file
diff --git a/ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc b/ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc
new file mode 100644
index 000000000..13561b717
--- /dev/null
+++ b/ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc
@@ -0,0 +1,321 @@
+---
+description: CLI design guidelines — arguments, flags, subcommands, help, output, errors, interactivity, config precedence. Apply when designing new commands or reviewing CLI UX.
+globs:
+ - "src/**/*.ts"
+alwaysApply: true
+---
+
+# CLI Design Guidelines
+
+Design CLI surface area (syntax + behavior), human-first, script-friendly.
+Adapted from [clig.dev](https://clig.dev/) for our TypeScript + Effect.ts + Clack stack.
+
+## When to Use
+
+- Designing a CLI spec (before implementation) or refactoring CLI surface area.
+- Adding new commands, flags, or interactive prompts.
+- Reviewing CLI UX decisions.
+
+## Our Stack
+
+| Library | Role | Source reference |
+| ------- | ---- | --------------- |
+| `@effect/cli` | Command, Options, Args declaration and parsing | `ts/vendor/effect/packages/cli/src/` |
+| `@clack/prompts` | Interactive terminal UI (prompts, spinners, logs, notes) | `ts/vendor/clack/packages/prompts/src/` |
+| `effect` | Core runtime, services, layers, error handling | `ts/vendor/effect/packages/effect/src/` |
+| `@effect/platform` | FileSystem, Terminal abstraction | `ts/vendor/effect/packages/platform/src/` |
+
+Existing architecture is documented in `ts/packages/cli/AGENTS.md`.
+
+## Philosophy
+
+1. **Human-first design** — Optimize for humans; scripts work via `--json`, `--plain`, exit codes.
+2. **Simple parts that work together** — stdout for data, stderr for decoration, respect exit codes and signals.
+3. **Consistency** — Reuse standard flag names (`--help`, `--version`, `--json`, `--dry-run`).
+4. **Say just enough** — Brief success output, visible progress, no noise.
+5. **Ease of discovery** — Help text is UX. Lead with examples; suggest next commands on error.
+6. **Conversation as the norm** — Expect trial-and-error. Provide `--dry-run` and confirmations for scary actions.
+7. **Robustness** — Validate early, fail fast, no stack traces by default.
+8. **Empathy** — Make success likely; make failure informative. Character is fine; clutter is not.
+
+## Output Conventions
+
+The CLI separates human-readable decoration from machine-readable data:
+
+- **stdout** — data only (`ui.output()`). Captured by pipes and scripts.
+- **stderr** — all decoration (Clack spinners, logs, notes, intro/outro). Visible in terminal, invisible in pipes.
+
+Rules:
+
+1. All `TerminalUI` methods except `output()` write to stderr via `{ output: process.stderr }`.
+2. `ui.output(data)` writes to stdout only when piped — no-op in interactive mode.
+3. When stdout is piped, ALL decoration is suppressed. Only `ui.output()` writes.
+4. Never write data to stderr. Never write decoration to stdout.
+
+```typescript
+// Data command (e.g., whoami):
+yield* ui.note(apiKey, 'API Key'); // Decoration → stderr
+yield* ui.output(apiKey); // Data → stdout
+
+// Action command (e.g., login):
+yield* ui.intro('composio login'); // Decoration → stderr
+yield* ui.log.step('Redirecting'); // Decoration → stderr
+// No ui.output() — nothing for scripts to capture
+```
+
+When adding a command, ask: "Does this produce a value scripts should capture?"
+- **Yes** → `ui.output(value)` for data, `ui.log.*` / `ui.note()` for context.
+- **No** → Only `ui.log.*` / `ui.note()` / `ui.intro()` / `ui.outro()`.
+
+**Show state changes.** When a command modifies state, say what changed and the new state:
+
+```typescript
+// After logout:
+yield* ui.log.info('Removed API key from ~/.composio/user-config.json');
+
+// After generate:
+yield* ui.log.success('Generated 42 tools across 5 toolkits → src/generated/');
+```
+
+## Arguments & Flags
+
+Define options via `@effect/cli`:
+
+```typescript
+const toolkits = Options.text('toolkits').pipe(
+ Options.optional,
+ Options.withDescription('Comma-separated toolkit slugs'),
+);
+const force = Options.boolean('force').pipe(
+ Options.withAlias('f'),
+ Options.withDefault(false),
+);
+```
+
+Principles:
+- Prefer flags over positional args for clarity and extensibility.
+- Provide long versions of all flags; one-letter aliases only for the most common.
+- Default values should be right for most users.
+- Never accept secrets via flags — they leak to `ps` output and shell history. Use `--password-file`, stdin, or a secret manager instead.
+- Support `-` for stdin/stdout when input/output is a file path.
+
+Standard flag names:
+
+| Flag | Short | Purpose |
+| ---- | ----- | ------- |
+| `--help` | `-h` | Show help (built-in via @effect/cli) |
+| `--version` | | Print version to stdout |
+| `--quiet` | `-q` | Less output |
+| `--verbose` | `-v` | More output (never use `-v` for version) |
+| `--debug` | `-d` | Debug output |
+| `--force` | `-f` | Skip confirmations |
+| `--dry-run` | `-n` | Preview only |
+| `--json` | | Structured output |
+| `--output` | `-o` | Output file path |
+| `--no-input` | | Disable prompts; fail if required input missing |
+| `--no-browser` | | Skip browser-open steps |
+| `--no-color` | | Disable color output |
+
+## Subcommands
+
+```typescript
+const login = Command.make('login', { noBrowser }, handler);
+const generate = Command.make('generate', { toolkits, typeTools }, handler);
+const root = Command.make('composio').pipe(
+ Command.withSubcommands([login, generate, /* ... */]),
+);
+```
+
+- Follow verb-noun pattern consistently: `composio login`, `composio generate`.
+- Share global flags via parent command composition.
+- Support `composio help <subcmd>` and `composio <subcmd> --help`.
+- Avoid ambiguous pairs (`update` vs `upgrade`) unless sharply differentiated.
+
+## Interactivity
+
+Use `@clack/prompts` for all interactive UI. All Clack output goes to stderr via `{ output: process.stderr }`.
+
+| Prompt | When to use |
+| ------ | ----------- |
+| `text()` | Free-form text input |
+| `password()` | Secret input (echo disabled) |
+| `confirm()` | Yes/no decisions |
+| `select()` | Choose one from a list |
+| `multiselect()` | Choose multiple from a list |
+| `spinner()` | Long-running operations |
+| `log.info/warn/error/step()` | Styled status messages |
+| `note()` | Boxed contextual info |
+| `intro()` / `outro()` | Session start/end markers |
+
+Rules:
+- Prompt only if stdin is a TTY.
+- `--no-input`: never prompt; fail with actionable message if required input missing.
+- Make escape hatches obvious (Ctrl-C).
+- Destructive operations: interactive confirmation + non-interactive requires `--force`.
+
+## Error Handling
+
+- Use the `effect-errors/` module for capture and formatting.
+- Catch and rewrite expected errors for humans; no stack traces by default.
+- Put the most important info last; use red intentionally.
+- For unexpected crashes: provide debug info path + bug report instructions.
+
+**Write actionable error messages.** Tell the user *what went wrong* and *how to fix it*:
+
+```
+// Bad:
+Error: EACCES
+
+// Good:
+Can't write to ~/.composio/user-config.json.
+You might need to fix permissions: chmod +w ~/.composio/user-config.json
+
+// Bad:
+Error: 401
+
+// Good:
+API key is invalid or expired.
+Run `composio login` to authenticate again.
+```
+
+**Suggest corrections** when the user mistypes a subcommand or flag. If they ran `composio genrate`, suggest `composio generate`.
+
+Exit codes:
+
+| Code | Meaning |
+| ---- | ------- |
+| `0` | Success |
+| `1` | Generic failure |
+| `2` | Invalid usage (parse/validation error) |
+
+## Help & Documentation
+
+- `@effect/cli` generates help text from Command/Options declarations.
+- If run with missing required args, show concise help + 1–2 examples + "use --help for more".
+- Lead with examples; show common flags first.
+- Link to docs URL per subcommand when applicable.
+- Provide both terminal help (offline, version-synced) and web docs (searchable, linkable).
+
+Good help text structure:
+
+```
+USAGE
+ $ composio generate [--toolkits <slugs>] [--type-tools]
+
+OPTIONS
+ --toolkits <slugs> Comma-separated toolkit slugs (default: all)
+ --type-tools Generate full type definitions
+ -o, --output <dir> Output directory (default: @composio/core/generated)
+
+EXAMPLES
+ $ composio generate
+ $ composio generate --toolkits github,slack --type-tools
+
+COMMANDS
+ composio ts generate Generate TypeScript stubs
+ composio py generate Generate Python stubs
+```
+
+**Suggest next commands** when it helps the user's flow:
+
+```
+✔ Logged in as [email protected]
+ Next: run `composio generate` to generate type stubs for your toolkits.
+```
+
+## Color & Formatting
+
+- Use `ansis` or `picocolors` for colored output.
+- Respect `NO_COLOR` env var and `TERM=dumb`.
+- Provide `--no-color` flag.
+- No animations or progress bars when stdout isn't a TTY.
+- Spinners only in interactive mode, always on stderr.
+
+## Configuration Precedence
+
+High to low: **flags > process env > project config > user config > system config**.
+
+- Composio prefixes: `COMPOSIO_*` for app config, `DEBUG_OVERRIDE_*` for debug.
+- User config stored in `~/.composio/`.
+- Respect common env vars: `NO_COLOR`, `DEBUG`, `EDITOR`, `PAGER`, `TERM`, `TMPDIR`, `HOME`.
+
+## Naming
+
+- Subcommand names: simple, lowercase, single word when possible.
+- Avoid too-generic names that collide with system tools.
+- Keep names short but not cryptic — easy to type matters.
+- Never create implicit catch-all subcommands that prevent future expansion.
+- Don't allow arbitrary abbreviations (reserving `g` for `generate` blocks future `g`-commands).
+- Use explicit aliases only when there's a clear, stable mapping.
+
+## Robustness & Performance
+
+- Validate early; fail fast with good error messages.
+- Print something within ~100ms (especially before network I/O). Start a Clack spinner immediately before any network call.
+- Show progress for long tasks (interactive only) via Clack spinners.
+- Use timeouts for network calls; allow configuration.
+- Make reruns safe: idempotent where possible; recoverable on failure.
+- **Crash-only design**: assume cleanup might not run. Defer cleanup to the next invocation rather than relying on shutdown hooks. If a cache file is half-written, the next run should detect and rebuild it.
+
+## Future-Proofing
+
+- Interfaces are contracts: args, flags, subcommands, env vars, output modes.
+- Keep changes additive; deprecate loudly + early; provide migration paths.
+- Human output can evolve; keep scripts stable via `--json`/`--plain`.
+
+## Signals
+
+- Ctrl-C: exit quickly; say something immediately; bounded cleanup.
+- Use Effect's interrupt handling (`Effect.scoped`, fiber interruption).
+- Design for crash-only recovery; assume cleanup might not run.
+
+## CLI Spec Template
+
+When designing a new command, produce this spec:
+
+```
+1. Name: `composio <subcommand>`
+2. One-liner: Brief description
+3. USAGE: `composio [global flags] <subcommand> [args]`
+4. Options (via @effect/cli Options.*):
+ - Flag table (name, type, default, required, description)
+5. I/O contract:
+ - stdout: what data is emitted
+ - stderr: what decoration is shown
+6. Exit codes: 0/1/2 + command-specific
+7. Env/config: COMPOSIO_* vars, ~/.composio/ files
+8. Examples: 5–10 invocations (interactive + piped)
+```
+
+## Example Invocations
+
+```bash
+# Interactive — user sees Clack decoration on stderr
+composio login
+composio generate --toolkits github,slack
+
+# Piped — only data on stdout, no decoration
+composio whoami | pbcopy
+API_KEY=$(composio whoami)
+composio version | cat
+
+# Non-interactive with force
+composio logout --force --no-input
+
+# Debug mode
+composio generate --debug --verbose
+```
+
+## Telemetry
+
+- Never phone home without explicit user consent.
+- Prefer opt-in. If opt-out, make it obvious and easy to disable (`COMPOSIO_DISABLE_TELEMETRY=true`).
+- Clearly explain what is collected, why, how, and retention period.
+- Consider alternatives: docs site analytics, download metrics, direct user feedback.
+
+## References
+
+- Community CLI Guidelines: https://clig.dev/
+- @effect/cli source: `ts/vendor/effect/packages/cli/src/`
+- @clack/prompts source: `ts/vendor/clack/packages/prompts/src/`
+- CLI architecture: `ts/packages/cli/AGENTS.md`
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
index bbd3c1705..9f190113f 100644
--- a/ts/packages/cli/AGENTS.md
+++ b/ts/packages/cli/AGENTS.md
@@ -278,3 +278,14 @@ When working on CLI code, reference the Effect source for accurate patterns:
- The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/effect/`.
- The CLI's actual dependencies come from npm via `pnpm install`.
+
+---
+
+## CLI Design Guidelines
+
+For principles on how to design CLI interactions (arguments, flags, help text, output, errors, interactivity, config precedence), see:
+
+- **Full guidelines**: `ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc`
+- **Also available as**: `.claude/skills/create-cli/SKILL.md` (symlink)
+
+Use these guidelines when adding new commands, designing flag interfaces, or making UX decisions for the CLI.