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

docs(cli): update skills and docs for manage/generate restructure (#2939)

## Summary Updates all documentation, agent skills, and internal references to reflect the `manage` namespace and `generate ts`/`generate py` restructuring from the previous two PRs. ## Changes - Updated `docs/content/docs/cli.mdx` — all command examples now use `composio manage ...` and `composio generate ts/py` syntax - Updated `docs/content/docs/troubleshooting/cli.mdx` — corrected generation command references - Updated `docs/content/changelog/03-13-26-cli-improvements.mdx` — fixed references to `composio orgs switch` → `composio manage orgs switch` - Updated `ts/packages/cli/AGENTS.md` — command table and code generation pipeline docs - Updated `.claude/skills/implement-cli-command/SKILL.md` — directory structure, file naming conventions, subcommand group examples, and reference table all reflect the new layout - Updated `.claude/skills/create-cli/SKILL.md` — help output examples use `composio generate ts/py` - Updated `.claude/skills/create-cli-e2e/SKILL.md` — e2e test examples use `composio manage tools ...` ## Type of change - [x] Documentation ## How Has This Been Tested? - Documentation changes are text-only; verified formatting renders correctly ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [x] I added tests or explain why not applicable - [x] I added a changeset if this change affects published packages Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>

Rahul Tarak committed Mar 18, 2026 at 18:05 UTC 02e72116da369da1a1a12429e7a5fbd18fe973e8
6 files changed +61 -61
.claude/skills/create-cli-e2e/SKILL.md
-1
@@ -225,7 +225,6 @@ e2e(import.meta.url, {
225 it('exits with non-zero code', () => {
226 expect(missingArgResult.exitCode).not.toBe(0);
227 });
228 -
228 it('stderr contains an error message', () => {
229 expect(missingArgResult.stderr).not.toBe('');
230 });
.claude/skills/create-cli/SKILL.md
+2 -2
@@ -176,8 +176,8 @@ EXAMPLES
176 $ composio generate --toolkits github,slack --type-tools
177
178 COMMANDS
179 - composio ts generate Generate TypeScript stubs
180 - composio py generate Generate Python stubs
179 + composio generate ts Generate TypeScript stubs
180 + composio generate py Generate Python stubs
181 ```
182
183 **Suggest next commands** when it helps the user's flow:
.claude/skills/implement-cli-command/SKILL.md
+29 -27
@@ -33,13 +33,18 @@ src/
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)
@@ -53,11 +58,11 @@ src/
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`.
@@ -147,8 +152,7 @@ const $cmd = $defaultCmd.pipe(
152 loginCmd,
153 logoutCmd,
154 generateCmd,
150 - pyCmd,
151 - tsCmd,
155 + manageCmd,
156 myCmd, // Add here
157 ])
158 );
@@ -175,8 +179,8 @@ For commands like `composio manage toolkits list`, `composio manage toolkits inf
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
@@ -184,8 +188,7 @@ src/commands/toolkits/
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';
@@ -199,8 +202,7 @@ export const toolkitsCmd = Command.make('toolkits').pipe(
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';
@@ -238,21 +240,22 @@ export const toolkitsCmd$List = Command.make('list', { searchOpt }).pipe(
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.
@@ -408,8 +411,7 @@ const [toolkits, tools, triggerTypes] = yield* Effect.all(
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: { ... }) {
@@ -425,9 +427,8 @@ export const tsCmd$Generate = Command.make('generate', { ... }).pipe(
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({ ... })),
@@ -534,10 +535,11 @@ recordings/
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
docs/content/changelog/03-13-26-cli-improvements.mdx
+2 -2
@@ -46,7 +46,7 @@ composio link github --no-wait # Prints redirect URL and JSON, exits
46 The `composio whoami` command no longer displays API keys in the output. This improves security and reduces the risk of accidental exposure in logs or screenshots.
47
48 - API key is removed from both display and JSON output.
49 -- Hints for `composio orgs switch` and `composio init` are shown instead.
49 +- Hints for `composio manage orgs switch` and `composio init` are shown instead.
50
51 ---
52
@@ -86,4 +86,4 @@ composio init # Interactive project selection
86
87 - **Login JSON output**: When using the org/project picker, the JSON output now reflects the final selection (not the initial session state).
88 - **Picker error handling**: If the org/project picker fails (e.g. API error), the CLI shows a warning, emits JSON with session data, and displays hints so you are not left without guidance.
89 -- **Modularized org/project selection**: The selection logic is shared between `composio login` and `composio orgs switch`.
89 +- **Modularized org/project selection**: The selection logic is shared between `composio login` and `composio manage orgs switch`.
docs/content/docs/cli.mdx
+16 -17
@@ -33,32 +33,32 @@ composio whoami
33
34 ```bash
35 # Connect your GitHub account
36 -composio connected-accounts link github
36 +composio manage connected-accounts link github
37
38 # Print connect URL + JSON and exit immediately (no wait)
39 -composio connected-accounts link github --no-wait
39 +composio manage connected-accounts link github --no-wait
40
41 # Search for tools
42 -composio tools search "star a github repo"
42 +composio manage tools search "star a github repo"
43
44 # Look up a tool's input schema
45 -composio tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
45 +composio manage tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
46
47 # Execute a tool (star the Composio repo!)
48 -composio tools execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
48 +composio manage tools execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
49 ```
50
51 ## Set up and listen to triggers
52
53 ```bash
54 # Find your connected account ID
55 -composio connected-accounts list --toolkits github
55 +composio manage connected-accounts list --toolkits github
56
57 # Create a trigger for star events on your repo
58 -composio triggers create GITHUB_STAR_ADDED_EVENT --connected-account-id your-connected-account-id --trigger-config '{"owner":"your-username","repo":"your-repo"}'
58 +composio manage triggers create GITHUB_STAR_ADDED_EVENT --connected-account-id your-connected-account-id --trigger-config '{"owner":"your-username","repo":"your-repo"}'
59
60 # Listen to all GitHub trigger events on your account in real time
61 -composio triggers listen --toolkits github --table
61 +composio manage triggers listen --toolkits github --table
62 ```
63
64 ## Available commands
@@ -73,15 +73,14 @@ Run `composio <command> --help` for detailed usage and flags.
73 | `composio logout` | | Remove stored authentication |
74 | `composio whoami` | | Display your account and workspace information (without API keys) |
75 | `composio init` | | Initialize a Composio project in the current directory |
76 -| `composio toolkits` | `list`, `search`, `info`, `version` | Discover and inspect toolkits |
77 -| `composio tools` | `list`, `search`, `info`, `execute` | Discover, inspect, and execute tools |
78 -| `composio connected-accounts` | `list`, `info`, `whoami`, `link`, `delete` | Manage connected accounts |
79 -| `composio auth-configs` | `list`, `info`, `create`, `delete` | Manage auth configurations |
80 -| `composio triggers` | `list`, `info`, `create`, `status`, `listen`, `enable`, `disable`, `delete` | Subscribe to events and manage trigger instances |
81 -| `composio logs` | `tools`, `triggers` | Inspect tool and trigger execution logs |
82 -| `composio generate` | | Generate type stubs (auto-detects language) |
83 -| `composio ts` | `generate` | Generate TypeScript type stubs |
84 -| `composio py` | `generate` | Generate Python type stubs |
76 +| `composio manage toolkits` | `list`, `search`, `info`, `version` | Discover and inspect toolkits |
77 +| `composio manage tools` | `list`, `search`, `info`, `execute` | Discover, inspect, and execute tools |
78 +| `composio manage connected-accounts` | `list`, `info`, `whoami`, `link`, `delete` | Manage connected accounts |
79 +| `composio manage auth-configs` | `list`, `info`, `create`, `delete` | Manage auth configurations |
80 +| `composio manage triggers` | `list`, `info`, `create`, `status`, `listen`, `enable`, `disable`, `delete` | Subscribe to events and manage trigger instances |
81 +| `composio manage logs` | `tools`, `triggers` | Inspect tool and trigger execution logs |
82 +| `composio generate ts` | `(options)` | Generate TypeScript type stubs |
83 +| `composio generate py` | `(options)` | Generate Python type stubs |
84 | `composio upgrade` | | Upgrade CLI to the latest version |
85 | `composio version` | | Display the current CLI version |
86
ts/packages/cli/AGENTS.md
+12 -12
@@ -27,17 +27,17 @@ Errors are captured via the custom `effect-errors/` module, which provides sourc
27
28 Each command is declared with `@effect/cli`'s `Command.make()` pattern:
29
30 -| Command | Description |
31 -| -------------------------------------------------------- | ----------------------------------------------------------- |
32 -| `composio version` | Display CLI version |
33 -| `composio whoami` | Show logged-in user's API key |
34 -| `composio login [--no-browser] [--no-wait] [--key text]` | Login with browser redirect |
35 -| `composio logout` | Clear stored API key |
36 -| `composio upgrade` | Self-update binary from GitHub releases |
37 -| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
38 -| `composio ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |
39 -| `composio py generate` | Generate Python type stubs |
40 -| `composio manage <subcommand>` | Manage Composio resources (toolkits, tools, accounts, etc.) |
30 +| Command | Description |
31 +| -------------------------------------------------------- | ---------------------------------------------------------- |
32 +| `composio version` | Display CLI version |
33 +| `composio whoami` | Show logged-in user's API key |
34 +| `composio login [--no-browser] [--no-wait] [--key text]` | Login with browser redirect |
35 +| `composio logout` | Clear stored API key |
36 +| `composio upgrade` | Self-update binary from GitHub releases |
37 +| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
38 +| `composio generate ts` | Generate TypeScript type stubs for toolkits/tools/triggers |
39 +| `composio generate py` | Generate Python type stubs |
40 +| `composio manage <command>` | Manage Composio resources (toolkits, tools, accounts, triggers, logs, orgs, projects) |
41
42 Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.
43
@@ -86,7 +86,7 @@ Each model has `fromJSON`/`toJSON` helpers using `JSONTransformSchema()`.
86
87 ### Code Generation (`src/generation/`)
88
89 -Multi-stage pipeline for `composio ts generate` and `composio py generate`:
89 +Multi-stage pipeline for `composio generate ts` and `composio generate py`:
90
91 1. **Fetch** — Toolkits, tools, trigger types from API (optionally filtered by `--toolkits`)
92 2. **Index** — Groups tools/triggers by toolkit prefix into a `ToolkitIndex` map