Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
feat(ai): add "create-cli" skill
jkomyno33e6c97f3189
diff --git a/.claude/skills/create-cli/SKILL.md b/.claude/skills/create-cli/SKILL.mdnew file mode 120000index 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 filediff --git a/ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc b/ts/packages/cli/.cursor/rules/cli-design-guidelines.mdcnew file mode 100644index 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.mdindex 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.