33
│ ├── login.cmd.ts # Complex command (options, spinner, polling)
34
│ ├── logout.cmd.ts # Action command (no stdout data)
35
│ ├── upgrade.cmd.ts # Action command (delegates to service)
36
-│ ├── generate.cmd.ts # Command that auto-delegates to subcommands
36
+│ ├── generate/
37
+│ │ ├── generate.cmd.ts # Parent command group for `composio generate`
38
+│ │ ├── generate-py.cmd.ts # `composio generate py`
39
+│ │ └── generate-ts.cmd.ts # `composio generate ts`
40
+│ ├── manage/
41
+│ │ └── manage.cmd.ts # Parent command group for `composio manage`
42
│ ├── ts/
38
-│ │ ├── ts.cmd.ts # Parent command group
43
+│ │ ├── ts.cmd.ts # Existing TS generation internals, referenced from generate/
44
│ │ └── commands/
40
-│ │ └── ts.generate.cmd.ts # Subcommand with complex logic
45
+│ │ └── ts.generate.cmd.ts # Reusable TS generation logic
46
│ └── py/
42
-│ ├── py.cmd.ts
47
+│ ├── py.cmd.ts # Existing Python generation internals, referenced from generate/
48
│ └── commands/
49
│ └── py.generate.cmd.ts
50
├── services/ # Effect services (dependency injection)
58
### File Naming Convention
59
60
- Command files: `<name>.cmd.ts` (e.g., `version.cmd.ts`, `login.cmd.ts`)
56
-- Subcommand files: `<parent>.<name>.cmd.ts` inside `commands/` (e.g., `ts.generate.cmd.ts`)
57
-- Parent command groups: `<name>.cmd.ts` at the group level (e.g., `ts/ts.cmd.ts`)
61
+- Subcommand implementation files: `<parent>.<name>.cmd.ts` inside `commands/` (e.g., `ts.generate.cmd.ts`)
62
+- Parent command groups: `<name>.cmd.ts` at the group level (e.g., `generate/generate.cmd.ts`, `manage/manage.cmd.ts`)
63
+- Wrapper subcommand entrypoints can also live beside their parent group (e.g., `generate/generate-py.cmd.ts`, `generate/generate-ts.cmd.ts`)
64
65
## Creating a New Command
60
-
66
### Step 1: Create the Command File
67
68
Create `src/commands/<name>.cmd.ts`.
152
loginCmd,
153
logoutCmd,
154
generateCmd,
150
- pyCmd,
151
- tsCmd,
155
+ manageCmd,
156
myCmd, // Add here
157
])
158
);
179
### Step 1: Create the Directory Structure
180
181
```
178
-src/commands/toolkits/
179
-├── toolkits.cmd.ts # Parent command group
182
+src/commands/manage/toolkits/
183
+├── toolkits.cmd.ts # Parent command group under `manage`
184
└── commands/
185
├── toolkits.list.cmd.ts # composio manage toolkits list
186
└── toolkits.info.cmd.ts # composio manage toolkits info
188
189
### Step 2: Create the Parent Command
190
187
-`src/commands/toolkits/toolkits.cmd.ts`:
188
-
191
+`src/commands/manage/toolkits/toolkits.cmd.ts`:
192
```typescript
193
import { Command } from '@effect/cli';
194
import { toolkitsCmd$List } from './commands/toolkits.list.cmd';
202
203
### Step 3: Create Each Subcommand
204
202
-`src/commands/toolkits/commands/toolkits.list.cmd.ts`:
203
-
205
+`src/commands/manage/toolkits/commands/toolkits.list.cmd.ts`:
206
```typescript
207
import { Command, Options } from '@effect/cli';
208
import { Effect, Option } from 'effect';
240
);
241
```
242
241
-### Step 4: Register the Parent in index.ts
243
+### Step 4: Register the Parent in `manage/manage.cmd.ts`
244
245
```typescript
246
+import { Command } from '@effect/cli';
247
import { toolkitsCmd } from './toolkits/toolkits.cmd';
248
246
-const $cmd = $defaultCmd.pipe(
249
+export const manageCmd = Command.make('manage').pipe(
250
+ Command.withDescription('Manage existing Composio resources.'),
251
Command.withSubcommands([
248
- // ... existing commands
252
+ // ... existing manage subcommands
253
toolkitsCmd,
254
])
255
);
256
```
257
258
## Option Declaration Patterns
255
-
259
Options are declared at module level using `@effect/cli`'s `Options` API. The template above demonstrates the most common types (required text, optional text). For other option types, see `ts/vendor/effect/packages/cli/src/Options.ts`.
260
261
Both `Options.optional(Options.text(...))` (wrapping) and `Options.text(...).pipe(Options.optional)` (piped) are valid. Use whichever reads better.
411
412
## Extracting Reusable Logic
413
411
-For commands that share logic (e.g., `composio generate` delegates to `composio ts generate`):
412
-
414
+For commands that share logic (e.g., `composio generate` delegates to `composio generate ts`):
415
```typescript
416
// In ts.generate.cmd.ts — export the logic separately
417
export function generateTypescriptTypeStubs(params: { ... }) {
427
);
428
429
// Other commands can reuse it
428
-// In generate.cmd.ts
429
-import { generateTypescriptTypeStubs } from './ts/commands/ts.generate.cmd';
430
-
430
+// In generate/generate-ts.cmd.ts
431
+import { generateTypescriptTypeStubs } from '../ts/commands/ts.generate.cmd';
432
yield* Match.value(envLang).pipe(
433
Match.when('TypeScript', () => generateTypescriptTypeStubs({ ... })),
434
Match.when('Python', () => generatePythonTypeStubs({ ... })),
535
| `src/commands/login.cmd.ts` | Complex command (options, spinner, polling, retry) |
536
| `src/commands/logout.cmd.ts` | Action command (no stdout data) |
537
| `src/commands/upgrade.cmd.ts` | Action command delegating to service |
537
-| `src/commands/generate.cmd.ts` | Auto-detection and delegation to subcommands |
538
-| `src/commands/ts/commands/ts.generate.cmd.ts` | Full subcommand with parallel fetching, spinner, file I/O |
538
+| `src/commands/generate/generate.cmd.ts` | Parent `generate` command and delegation entrypoint |
539
+| `src/commands/manage/manage.cmd.ts` | Parent `manage` command and subcommand registration |
540
+| `src/commands/ts/commands/ts.generate.cmd.ts` | Reusable TS generation logic used by `generate ts` |
541
| `src/commands/index.ts` | Command tree registration |
542
| `src/bin.ts` | Entry point, layer composition, error handling |
543
| `src/services/terminal-ui.ts` | TerminalUI service interface |
544
| `src/services/composio-clients.ts` | API client service (HTTP, pagination, metrics) |
543
-| `ts/packages/cli/AGENTS.md` | CLI architecture, services, effects, output conventions |
545
+| `ts/packages/cli/AGENTS.md` | CLI architecture, services, effects, output conventions |
\ No newline at end of file