@devries-cameron20 / composio-1 / commits / 33e6c97f3
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.

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

jkomyno committed Feb 18, 2026 at 15:54 UTC 33e6c97f31895abf6506337bc7bc493c51bca355
3 files changed +333
.claude/skills/create-cli/SKILL.md new
+1
@@ -0,0 +1 @@
1 +../../../ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc
\ No newline at end of file
ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc new
+321
@@ -0,0 +1,321 @@
1 +---
2 +description: CLI design guidelines — arguments, flags, subcommands, help, output, errors, interactivity, config precedence. Apply when designing new commands or reviewing CLI UX.
3 +globs:
4 + - "src/**/*.ts"
5 +alwaysApply: true
6 +---
7 +
8 +# CLI Design Guidelines
9 +
10 +Design CLI surface area (syntax + behavior), human-first, script-friendly.
11 +Adapted from [clig.dev](https://clig.dev/) for our TypeScript + Effect.ts + Clack stack.
12 +
13 +## When to Use
14 +
15 +- Designing a CLI spec (before implementation) or refactoring CLI surface area.
16 +- Adding new commands, flags, or interactive prompts.
17 +- Reviewing CLI UX decisions.
18 +
19 +## Our Stack
20 +
21 +| Library | Role | Source reference |
22 +| ------- | ---- | --------------- |
23 +| `@effect/cli` | Command, Options, Args declaration and parsing | `ts/vendor/effect/packages/cli/src/` |
24 +| `@clack/prompts` | Interactive terminal UI (prompts, spinners, logs, notes) | `ts/vendor/clack/packages/prompts/src/` |
25 +| `effect` | Core runtime, services, layers, error handling | `ts/vendor/effect/packages/effect/src/` |
26 +| `@effect/platform` | FileSystem, Terminal abstraction | `ts/vendor/effect/packages/platform/src/` |
27 +
28 +Existing architecture is documented in `ts/packages/cli/AGENTS.md`.
29 +
30 +## Philosophy
31 +
32 +1. **Human-first design** — Optimize for humans; scripts work via `--json`, `--plain`, exit codes.
33 +2. **Simple parts that work together** — stdout for data, stderr for decoration, respect exit codes and signals.
34 +3. **Consistency** — Reuse standard flag names (`--help`, `--version`, `--json`, `--dry-run`).
35 +4. **Say just enough** — Brief success output, visible progress, no noise.
36 +5. **Ease of discovery** — Help text is UX. Lead with examples; suggest next commands on error.
37 +6. **Conversation as the norm** — Expect trial-and-error. Provide `--dry-run` and confirmations for scary actions.
38 +7. **Robustness** — Validate early, fail fast, no stack traces by default.
39 +8. **Empathy** — Make success likely; make failure informative. Character is fine; clutter is not.
40 +
41 +## Output Conventions
42 +
43 +The CLI separates human-readable decoration from machine-readable data:
44 +
45 +- **stdout** — data only (`ui.output()`). Captured by pipes and scripts.
46 +- **stderr** — all decoration (Clack spinners, logs, notes, intro/outro). Visible in terminal, invisible in pipes.
47 +
48 +Rules:
49 +
50 +1. All `TerminalUI` methods except `output()` write to stderr via `{ output: process.stderr }`.
51 +2. `ui.output(data)` writes to stdout only when piped — no-op in interactive mode.
52 +3. When stdout is piped, ALL decoration is suppressed. Only `ui.output()` writes.
53 +4. Never write data to stderr. Never write decoration to stdout.
54 +
55 +```typescript
56 +// Data command (e.g., whoami):
57 +yield* ui.note(apiKey, 'API Key'); // Decoration → stderr
58 +yield* ui.output(apiKey); // Data → stdout
59 +
60 +// Action command (e.g., login):
61 +yield* ui.intro('composio login'); // Decoration → stderr
62 +yield* ui.log.step('Redirecting'); // Decoration → stderr
63 +// No ui.output() — nothing for scripts to capture
64 +```
65 +
66 +When adding a command, ask: "Does this produce a value scripts should capture?"
67 +- **Yes** → `ui.output(value)` for data, `ui.log.*` / `ui.note()` for context.
68 +- **No** → Only `ui.log.*` / `ui.note()` / `ui.intro()` / `ui.outro()`.
69 +
70 +**Show state changes.** When a command modifies state, say what changed and the new state:
71 +
72 +```typescript
73 +// After logout:
74 +yield* ui.log.info('Removed API key from ~/.composio/user-config.json');
75 +
76 +// After generate:
77 +yield* ui.log.success('Generated 42 tools across 5 toolkits → src/generated/');
78 +```
79 +
80 +## Arguments & Flags
81 +
82 +Define options via `@effect/cli`:
83 +
84 +```typescript
85 +const toolkits = Options.text('toolkits').pipe(
86 + Options.optional,
87 + Options.withDescription('Comma-separated toolkit slugs'),
88 +);
89 +const force = Options.boolean('force').pipe(
90 + Options.withAlias('f'),
91 + Options.withDefault(false),
92 +);
93 +```
94 +
95 +Principles:
96 +- Prefer flags over positional args for clarity and extensibility.
97 +- Provide long versions of all flags; one-letter aliases only for the most common.
98 +- Default values should be right for most users.
99 +- Never accept secrets via flags — they leak to `ps` output and shell history. Use `--password-file`, stdin, or a secret manager instead.
100 +- Support `-` for stdin/stdout when input/output is a file path.
101 +
102 +Standard flag names:
103 +
104 +| Flag | Short | Purpose |
105 +| ---- | ----- | ------- |
106 +| `--help` | `-h` | Show help (built-in via @effect/cli) |
107 +| `--version` | | Print version to stdout |
108 +| `--quiet` | `-q` | Less output |
109 +| `--verbose` | `-v` | More output (never use `-v` for version) |
110 +| `--debug` | `-d` | Debug output |
111 +| `--force` | `-f` | Skip confirmations |
112 +| `--dry-run` | `-n` | Preview only |
113 +| `--json` | | Structured output |
114 +| `--output` | `-o` | Output file path |
115 +| `--no-input` | | Disable prompts; fail if required input missing |
116 +| `--no-browser` | | Skip browser-open steps |
117 +| `--no-color` | | Disable color output |
118 +
119 +## Subcommands
120 +
121 +```typescript
122 +const login = Command.make('login', { noBrowser }, handler);
123 +const generate = Command.make('generate', { toolkits, typeTools }, handler);
124 +const root = Command.make('composio').pipe(
125 + Command.withSubcommands([login, generate, /* ... */]),
126 +);
127 +```
128 +
129 +- Follow verb-noun pattern consistently: `composio login`, `composio generate`.
130 +- Share global flags via parent command composition.
131 +- Support `composio help <subcmd>` and `composio <subcmd> --help`.
132 +- Avoid ambiguous pairs (`update` vs `upgrade`) unless sharply differentiated.
133 +
134 +## Interactivity
135 +
136 +Use `@clack/prompts` for all interactive UI. All Clack output goes to stderr via `{ output: process.stderr }`.
137 +
138 +| Prompt | When to use |
139 +| ------ | ----------- |
140 +| `text()` | Free-form text input |
141 +| `password()` | Secret input (echo disabled) |
142 +| `confirm()` | Yes/no decisions |
143 +| `select()` | Choose one from a list |
144 +| `multiselect()` | Choose multiple from a list |
145 +| `spinner()` | Long-running operations |
146 +| `log.info/warn/error/step()` | Styled status messages |
147 +| `note()` | Boxed contextual info |
148 +| `intro()` / `outro()` | Session start/end markers |
149 +
150 +Rules:
151 +- Prompt only if stdin is a TTY.
152 +- `--no-input`: never prompt; fail with actionable message if required input missing.
153 +- Make escape hatches obvious (Ctrl-C).
154 +- Destructive operations: interactive confirmation + non-interactive requires `--force`.
155 +
156 +## Error Handling
157 +
158 +- Use the `effect-errors/` module for capture and formatting.
159 +- Catch and rewrite expected errors for humans; no stack traces by default.
160 +- Put the most important info last; use red intentionally.
161 +- For unexpected crashes: provide debug info path + bug report instructions.
162 +
163 +**Write actionable error messages.** Tell the user *what went wrong* and *how to fix it*:
164 +
165 +```
166 +// Bad:
167 +Error: EACCES
168 +
169 +// Good:
170 +Can't write to ~/.composio/user-config.json.
171 +You might need to fix permissions: chmod +w ~/.composio/user-config.json
172 +
173 +// Bad:
174 +Error: 401
175 +
176 +// Good:
177 +API key is invalid or expired.
178 +Run `composio login` to authenticate again.
179 +```
180 +
181 +**Suggest corrections** when the user mistypes a subcommand or flag. If they ran `composio genrate`, suggest `composio generate`.
182 +
183 +Exit codes:
184 +
185 +| Code | Meaning |
186 +| ---- | ------- |
187 +| `0` | Success |
188 +| `1` | Generic failure |
189 +| `2` | Invalid usage (parse/validation error) |
190 +
191 +## Help & Documentation
192 +
193 +- `@effect/cli` generates help text from Command/Options declarations.
194 +- If run with missing required args, show concise help + 1–2 examples + "use --help for more".
195 +- Lead with examples; show common flags first.
196 +- Link to docs URL per subcommand when applicable.
197 +- Provide both terminal help (offline, version-synced) and web docs (searchable, linkable).
198 +
199 +Good help text structure:
200 +
201 +```
202 +USAGE
203 + $ composio generate [--toolkits <slugs>] [--type-tools]
204 +
205 +OPTIONS
206 + --toolkits <slugs> Comma-separated toolkit slugs (default: all)
207 + --type-tools Generate full type definitions
208 + -o, --output <dir> Output directory (default: @composio/core/generated)
209 +
210 +EXAMPLES
211 + $ composio generate
212 + $ composio generate --toolkits github,slack --type-tools
213 +
214 +COMMANDS
215 + composio ts generate Generate TypeScript stubs
216 + composio py generate Generate Python stubs
217 +```
218 +
219 +**Suggest next commands** when it helps the user's flow:
220 +
221 +```
222 +✔ Logged in as user@example.com
223 + Next: run `composio generate` to generate type stubs for your toolkits.
224 +```
225 +
226 +## Color & Formatting
227 +
228 +- Use `ansis` or `picocolors` for colored output.
229 +- Respect `NO_COLOR` env var and `TERM=dumb`.
230 +- Provide `--no-color` flag.
231 +- No animations or progress bars when stdout isn't a TTY.
232 +- Spinners only in interactive mode, always on stderr.
233 +
234 +## Configuration Precedence
235 +
236 +High to low: **flags > process env > project config > user config > system config**.
237 +
238 +- Composio prefixes: `COMPOSIO_*` for app config, `DEBUG_OVERRIDE_*` for debug.
239 +- User config stored in `~/.composio/`.
240 +- Respect common env vars: `NO_COLOR`, `DEBUG`, `EDITOR`, `PAGER`, `TERM`, `TMPDIR`, `HOME`.
241 +
242 +## Naming
243 +
244 +- Subcommand names: simple, lowercase, single word when possible.
245 +- Avoid too-generic names that collide with system tools.
246 +- Keep names short but not cryptic — easy to type matters.
247 +- Never create implicit catch-all subcommands that prevent future expansion.
248 +- Don't allow arbitrary abbreviations (reserving `g` for `generate` blocks future `g`-commands).
249 +- Use explicit aliases only when there's a clear, stable mapping.
250 +
251 +## Robustness & Performance
252 +
253 +- Validate early; fail fast with good error messages.
254 +- Print something within ~100ms (especially before network I/O). Start a Clack spinner immediately before any network call.
255 +- Show progress for long tasks (interactive only) via Clack spinners.
256 +- Use timeouts for network calls; allow configuration.
257 +- Make reruns safe: idempotent where possible; recoverable on failure.
258 +- **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.
259 +
260 +## Future-Proofing
261 +
262 +- Interfaces are contracts: args, flags, subcommands, env vars, output modes.
263 +- Keep changes additive; deprecate loudly + early; provide migration paths.
264 +- Human output can evolve; keep scripts stable via `--json`/`--plain`.
265 +
266 +## Signals
267 +
268 +- Ctrl-C: exit quickly; say something immediately; bounded cleanup.
269 +- Use Effect's interrupt handling (`Effect.scoped`, fiber interruption).
270 +- Design for crash-only recovery; assume cleanup might not run.
271 +
272 +## CLI Spec Template
273 +
274 +When designing a new command, produce this spec:
275 +
276 +```
277 +1. Name: `composio <subcommand>`
278 +2. One-liner: Brief description
279 +3. USAGE: `composio [global flags] <subcommand> [args]`
280 +4. Options (via @effect/cli Options.*):
281 + - Flag table (name, type, default, required, description)
282 +5. I/O contract:
283 + - stdout: what data is emitted
284 + - stderr: what decoration is shown
285 +6. Exit codes: 0/1/2 + command-specific
286 +7. Env/config: COMPOSIO_* vars, ~/.composio/ files
287 +8. Examples: 5–10 invocations (interactive + piped)
288 +```
289 +
290 +## Example Invocations
291 +
292 +```bash
293 +# Interactive — user sees Clack decoration on stderr
294 +composio login
295 +composio generate --toolkits github,slack
296 +
297 +# Piped — only data on stdout, no decoration
298 +composio whoami | pbcopy
299 +API_KEY=$(composio whoami)
300 +composio version | cat
301 +
302 +# Non-interactive with force
303 +composio logout --force --no-input
304 +
305 +# Debug mode
306 +composio generate --debug --verbose
307 +```
308 +
309 +## Telemetry
310 +
311 +- Never phone home without explicit user consent.
312 +- Prefer opt-in. If opt-out, make it obvious and easy to disable (`COMPOSIO_DISABLE_TELEMETRY=true`).
313 +- Clearly explain what is collected, why, how, and retention period.
314 +- Consider alternatives: docs site analytics, download metrics, direct user feedback.
315 +
316 +## References
317 +
318 +- Community CLI Guidelines: https://clig.dev/
319 +- @effect/cli source: `ts/vendor/effect/packages/cli/src/`
320 +- @clack/prompts source: `ts/vendor/clack/packages/prompts/src/`
321 +- CLI architecture: `ts/packages/cli/AGENTS.md`
ts/packages/cli/AGENTS.md
+11
@@ -278,3 +278,14 @@ When working on CLI code, reference the Effect source for accurate patterns:
278
279 - The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/effect/`.
280 - The CLI's actual dependencies come from npm via `pnpm install`.
281 +
282 +---
283 +
284 +## CLI Design Guidelines
285 +
286 +For principles on how to design CLI interactions (arguments, flags, help text, output, errors, interactivity, config precedence), see:
287 +
288 +- **Full guidelines**: `ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc`
289 +- **Also available as**: `.claude/skills/create-cli/SKILL.md` (symlink)
290 +
291 +Use these guidelines when adding new commands, designing flag interfaces, or making UX decisions for the CLI.