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.

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

Rahul Tarak02e72116da36
diff --git a/.claude/skills/create-cli-e2e/SKILL.md b/.claude/skills/create-cli-e2e/SKILL.md
index 78c6cf609..49a566956 100644
--- a/.claude/skills/create-cli-e2e/SKILL.md
+++ b/.claude/skills/create-cli-e2e/SKILL.md
@@ -225,7 +225,6 @@ e2e(import.meta.url, {
it('exits with non-zero code', () => {
expect(missingArgResult.exitCode).not.toBe(0);
});
-
it('stderr contains an error message', () => {
expect(missingArgResult.stderr).not.toBe('');
});
diff --git a/.claude/skills/create-cli/SKILL.md b/.claude/skills/create-cli/SKILL.md
index 43e911d3a..0afdb46a1 100644
--- a/.claude/skills/create-cli/SKILL.md
+++ b/.claude/skills/create-cli/SKILL.md
@@ -176,8 +176,8 @@ EXAMPLES
$ composio generate --toolkits github,slack --type-tools
COMMANDS
- composio ts generate Generate TypeScript stubs
- composio py generate Generate Python stubs
+ composio generate ts Generate TypeScript stubs
+ composio generate py Generate Python stubs
```
**Suggest next commands** when it helps the user's flow:
diff --git a/.claude/skills/implement-cli-command/SKILL.md b/.claude/skills/implement-cli-command/SKILL.md
index 0e8ab42f2..2ce528966 100644
--- a/.claude/skills/implement-cli-command/SKILL.md
+++ b/.claude/skills/implement-cli-command/SKILL.md
@@ -33,13 +33,18 @@ src/
│ ├── login.cmd.ts # Complex command (options, spinner, polling)
│ ├── logout.cmd.ts # Action command (no stdout data)
│ ├── upgrade.cmd.ts # Action command (delegates to service)
-│ ├── generate.cmd.ts # Command that auto-delegates to subcommands
+│ ├── generate/
+│ │ ├── generate.cmd.ts # Parent command group for `composio generate`
+│ │ ├── generate-py.cmd.ts # `composio generate py`
+│ │ └── generate-ts.cmd.ts # `composio generate ts`
+│ ├── manage/
+│ │ └── manage.cmd.ts # Parent command group for `composio manage`
│ ├── ts/
-│ │ ├── ts.cmd.ts # Parent command group
+│ │ ├── ts.cmd.ts # Existing TS generation internals, referenced from generate/
│ │ └── commands/
-│ │ └── ts.generate.cmd.ts # Subcommand with complex logic
+│ │ └── ts.generate.cmd.ts # Reusable TS generation logic
│ └── py/
-│ ├── py.cmd.ts
+│ ├── py.cmd.ts # Existing Python generation internals, referenced from generate/
│ └── commands/
│ └── py.generate.cmd.ts
├── services/ # Effect services (dependency injection)
@@ -53,11 +58,11 @@ src/
### File Naming Convention
- Command files: `<name>.cmd.ts` (e.g., `version.cmd.ts`, `login.cmd.ts`)
-- Subcommand files: `<parent>.<name>.cmd.ts` inside `commands/` (e.g., `ts.generate.cmd.ts`)
-- Parent command groups: `<name>.cmd.ts` at the group level (e.g., `ts/ts.cmd.ts`)
+- Subcommand implementation files: `<parent>.<name>.cmd.ts` inside `commands/` (e.g., `ts.generate.cmd.ts`)
+- Parent command groups: `<name>.cmd.ts` at the group level (e.g., `generate/generate.cmd.ts`, `manage/manage.cmd.ts`)
+- Wrapper subcommand entrypoints can also live beside their parent group (e.g., `generate/generate-py.cmd.ts`, `generate/generate-ts.cmd.ts`)
## Creating a New Command
-
### Step 1: Create the Command File
Create `src/commands/<name>.cmd.ts`.
@@ -147,8 +152,7 @@ const $cmd = $defaultCmd.pipe(
loginCmd,
logoutCmd,
generateCmd,
- pyCmd,
- tsCmd,
+ manageCmd,
myCmd, // Add here
])
);
@@ -175,8 +179,8 @@ For commands like `composio manage toolkits list`, `composio manage toolkits inf
### Step 1: Create the Directory Structure
```
-src/commands/toolkits/
-├── toolkits.cmd.ts # Parent command group
+src/commands/manage/toolkits/
+├── toolkits.cmd.ts # Parent command group under `manage`
└── commands/
├── toolkits.list.cmd.ts # composio manage toolkits list
└── toolkits.info.cmd.ts # composio manage toolkits info
@@ -184,8 +188,7 @@ src/commands/toolkits/
### Step 2: Create the Parent Command
-`src/commands/toolkits/toolkits.cmd.ts`:
-
+`src/commands/manage/toolkits/toolkits.cmd.ts`:
```typescript
import { Command } from '@effect/cli';
import { toolkitsCmd$List } from './commands/toolkits.list.cmd';
@@ -199,8 +202,7 @@ export const toolkitsCmd = Command.make('toolkits').pipe(
### Step 3: Create Each Subcommand
-`src/commands/toolkits/commands/toolkits.list.cmd.ts`:
-
+`src/commands/manage/toolkits/commands/toolkits.list.cmd.ts`:
```typescript
import { Command, Options } from '@effect/cli';
import { Effect, Option } from 'effect';
@@ -238,21 +240,22 @@ export const toolkitsCmd$List = Command.make('list', { searchOpt }).pipe(
);
```
-### Step 4: Register the Parent in index.ts
+### Step 4: Register the Parent in `manage/manage.cmd.ts`
```typescript
+import { Command } from '@effect/cli';
import { toolkitsCmd } from './toolkits/toolkits.cmd';
-const $cmd = $defaultCmd.pipe(
+export const manageCmd = Command.make('manage').pipe(
+ Command.withDescription('Manage existing Composio resources.'),
Command.withSubcommands([
- // ... existing commands
+ // ... existing manage subcommands
toolkitsCmd,
])
);
```
## Option Declaration Patterns
-
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`.
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(
## Extracting Reusable Logic
-For commands that share logic (e.g., `composio generate` delegates to `composio ts generate`):
-
+For commands that share logic (e.g., `composio generate` delegates to `composio generate ts`):
```typescript
// In ts.generate.cmd.ts — export the logic separately
export function generateTypescriptTypeStubs(params: { ... }) {
@@ -425,9 +427,8 @@ export const tsCmd$Generate = Command.make('generate', { ... }).pipe(
);
// Other commands can reuse it
-// In generate.cmd.ts
-import { generateTypescriptTypeStubs } from './ts/commands/ts.generate.cmd';
-
+// In generate/generate-ts.cmd.ts
+import { generateTypescriptTypeStubs } from '../ts/commands/ts.generate.cmd';
yield* Match.value(envLang).pipe(
Match.when('TypeScript', () => generateTypescriptTypeStubs({ ... })),
Match.when('Python', () => generatePythonTypeStubs({ ... })),
@@ -534,10 +535,11 @@ recordings/
| `src/commands/login.cmd.ts` | Complex command (options, spinner, polling, retry) |
| `src/commands/logout.cmd.ts` | Action command (no stdout data) |
| `src/commands/upgrade.cmd.ts` | Action command delegating to service |
-| `src/commands/generate.cmd.ts` | Auto-detection and delegation to subcommands |
-| `src/commands/ts/commands/ts.generate.cmd.ts` | Full subcommand with parallel fetching, spinner, file I/O |
+| `src/commands/generate/generate.cmd.ts` | Parent `generate` command and delegation entrypoint |
+| `src/commands/manage/manage.cmd.ts` | Parent `manage` command and subcommand registration |
+| `src/commands/ts/commands/ts.generate.cmd.ts` | Reusable TS generation logic used by `generate ts` |
| `src/commands/index.ts` | Command tree registration |
| `src/bin.ts` | Entry point, layer composition, error handling |
| `src/services/terminal-ui.ts` | TerminalUI service interface |
| `src/services/composio-clients.ts` | API client service (HTTP, pagination, metrics) |
-| `ts/packages/cli/AGENTS.md` | CLI architecture, services, effects, output conventions |
+| `ts/packages/cli/AGENTS.md` | CLI architecture, services, effects, output conventions |
\ No newline at end of file
diff --git a/docs/content/changelog/03-13-26-cli-improvements.mdx b/docs/content/changelog/03-13-26-cli-improvements.mdx
index f66941d9b..b72d0a81f 100644
--- a/docs/content/changelog/03-13-26-cli-improvements.mdx
+++ b/docs/content/changelog/03-13-26-cli-improvements.mdx
@@ -46,7 +46,7 @@ composio link github --no-wait # Prints redirect URL and JSON, exits
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.
- API key is removed from both display and JSON output.
-- Hints for `composio orgs switch` and `composio init` are shown instead.
+- Hints for `composio manage orgs switch` and `composio init` are shown instead.
---
@@ -86,4 +86,4 @@ composio init # Interactive project selection
- **Login JSON output**: When using the org/project picker, the JSON output now reflects the final selection (not the initial session state).
- **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.
-- **Modularized org/project selection**: The selection logic is shared between `composio login` and `composio orgs switch`.
+- **Modularized org/project selection**: The selection logic is shared between `composio login` and `composio manage orgs switch`.
diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdx
index 9d46c95fc..5af44d09c 100644
--- a/docs/content/docs/cli.mdx
+++ b/docs/content/docs/cli.mdx
@@ -33,32 +33,32 @@ composio whoami
```bash
# Connect your GitHub account
-composio connected-accounts link github
+composio manage connected-accounts link github
# Print connect URL + JSON and exit immediately (no wait)
-composio connected-accounts link github --no-wait
+composio manage connected-accounts link github --no-wait
# Search for tools
-composio tools search "star a github repo"
+composio manage tools search "star a github repo"
# Look up a tool's input schema
-composio tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
+composio manage tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
# Execute a tool (star the Composio repo!)
-composio tools execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
+composio manage tools execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
```
## Set up and listen to triggers
```bash
# Find your connected account ID
-composio connected-accounts list --toolkits github
+composio manage connected-accounts list --toolkits github
# Create a trigger for star events on your repo
-composio triggers create GITHUB_STAR_ADDED_EVENT --connected-account-id your-connected-account-id --trigger-config '{"owner":"your-username","repo":"your-repo"}'
+composio manage triggers create GITHUB_STAR_ADDED_EVENT --connected-account-id your-connected-account-id --trigger-config '{"owner":"your-username","repo":"your-repo"}'
# Listen to all GitHub trigger events on your account in real time
-composio triggers listen --toolkits github --table
+composio manage triggers listen --toolkits github --table
```
## Available commands
@@ -73,15 +73,14 @@ Run `composio <command> --help` for detailed usage and flags.
| `composio logout` | | Remove stored authentication |
| `composio whoami` | | Display your account and workspace information (without API keys) |
| `composio init` | | Initialize a Composio project in the current directory |
-| `composio toolkits` | `list`, `search`, `info`, `version` | Discover and inspect toolkits |
-| `composio tools` | `list`, `search`, `info`, `execute` | Discover, inspect, and execute tools |
-| `composio connected-accounts` | `list`, `info`, `whoami`, `link`, `delete` | Manage connected accounts |
-| `composio auth-configs` | `list`, `info`, `create`, `delete` | Manage auth configurations |
-| `composio triggers` | `list`, `info`, `create`, `status`, `listen`, `enable`, `disable`, `delete` | Subscribe to events and manage trigger instances |
-| `composio logs` | `tools`, `triggers` | Inspect tool and trigger execution logs |
-| `composio generate` | | Generate type stubs (auto-detects language) |
-| `composio ts` | `generate` | Generate TypeScript type stubs |
-| `composio py` | `generate` | Generate Python type stubs |
+| `composio manage toolkits` | `list`, `search`, `info`, `version` | Discover and inspect toolkits |
+| `composio manage tools` | `list`, `search`, `info`, `execute` | Discover, inspect, and execute tools |
+| `composio manage connected-accounts` | `list`, `info`, `whoami`, `link`, `delete` | Manage connected accounts |
+| `composio manage auth-configs` | `list`, `info`, `create`, `delete` | Manage auth configurations |
+| `composio manage triggers` | `list`, `info`, `create`, `status`, `listen`, `enable`, `disable`, `delete` | Subscribe to events and manage trigger instances |
+| `composio manage logs` | `tools`, `triggers` | Inspect tool and trigger execution logs |
+| `composio generate ts` | `(options)` | Generate TypeScript type stubs |
+| `composio generate py` | `(options)` | Generate Python type stubs |
| `composio upgrade` | | Upgrade CLI to the latest version |
| `composio version` | | Display the current CLI version |
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
index 52fb95efe..8c8f384e2 100644
--- a/ts/packages/cli/AGENTS.md
+++ b/ts/packages/cli/AGENTS.md
@@ -27,17 +27,17 @@ Errors are captured via the custom `effect-errors/` module, which provides sourc
Each command is declared with `@effect/cli`'s `Command.make()` pattern:
-| Command | Description |
-| -------------------------------------------------------- | ----------------------------------------------------------- |
-| `composio version` | Display CLI version |
-| `composio whoami` | Show logged-in user's API key |
-| `composio login [--no-browser] [--no-wait] [--key text]` | Login with browser redirect |
-| `composio logout` | Clear stored API key |
-| `composio upgrade` | Self-update binary from GitHub releases |
-| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
-| `composio ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |
-| `composio py generate` | Generate Python type stubs |
-| `composio manage <subcommand>` | Manage Composio resources (toolkits, tools, accounts, etc.) |
+| Command | Description |
+| -------------------------------------------------------- | ---------------------------------------------------------- |
+| `composio version` | Display CLI version |
+| `composio whoami` | Show logged-in user's API key |
+| `composio login [--no-browser] [--no-wait] [--key text]` | Login with browser redirect |
+| `composio logout` | Clear stored API key |
+| `composio upgrade` | Self-update binary from GitHub releases |
+| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
+| `composio generate ts` | Generate TypeScript type stubs for toolkits/tools/triggers |
+| `composio generate py` | Generate Python type stubs |
+| `composio manage <command>` | Manage Composio resources (toolkits, tools, accounts, triggers, logs, orgs, projects) |
Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.
@@ -86,7 +86,7 @@ Each model has `fromJSON`/`toJSON` helpers using `JSONTransformSchema()`.
### Code Generation (`src/generation/`)
-Multi-stage pipeline for `composio ts generate` and `composio py generate`:
+Multi-stage pipeline for `composio generate ts` and `composio generate py`:
1. **Fetch** — Toolkits, tools, trigger types from API (optionally filtered by `--toolkits`)
2. **Index** — Groups tools/triggers by toolkit prefix into a `ToolkitIndex` map