@devries-cameron20 / composio Mirror · read-only / commits / 0e5c5d813
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 07:15 UTC

docs(cli): add a contributor walkthrough and command summaries (#5179)

This PR: - adds a contributor walkthrough tracing `connections list --toolkit` through argument parsing, Effect composition, the native Effect client, registration metadata, and its argv-level test - maps the main phases of `execute`, `listen`, `run`, and `proxy`, with links to their handlers - generates quoted help summaries in `COMMANDS.md` and replaces the stale handwritten command inventory with links to the catalog and guide - validates the catalog and example command with 8 focused tests, workspace typechecking, Effect diagnostics, agent-guidance and routing checks, lint, and formatting VHS recordings are omitted because the change documents contributor workflows and updates catalog generation without changing the command surface.

Alberto Schiabel committed Nov 1, 2026 at 23:16 UTC 0e5c5d8130367248bf08585081e3df31a1b89169
5 files changed +243 -118
ts/packages/cli/AGENTS.md
+2 -30
@@ -35,39 +35,11 @@ The invocation learns which command it runs after `effect/cli` parsed argv, neve
35
36 ### Commands — `src/commands/`
37
38 -Each command uses `effect/cli`'s `Command.make()` pattern. Current top-level commands:
39 -
40 -| Group / Command | Purpose |
41 -| -------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
42 -| `version` | Display CLI version |
43 -| `whoami` | Show logged-in user info (writes raw API key to stdout when piped — see Output Conventions) |
44 -| `login` | Login with browser redirect or direct user/API key (`--no-browser`, `--no-wait`, `--key`, `--user-api-key`, `--org`) |
45 -| `logout` | Clear stored API key |
46 -| `signup` | Create a Composio account |
47 -| `upgrade` | Self-update binary from GitHub releases |
48 -| `init` | Bootstrap a Composio project in the current directory |
49 -| `install` | Set up shell integration (PATH and completions) |
50 -| `generate {ts | py}` | Generate type stubs (auto-detects project language if no subcommand) |
51 -| `agent` | Manage AI agent presets |
52 -| `toolkits` | List / inspect / version toolkits |
53 -| `tools` | List / inspect / `execute` tools |
54 -| `triggers` | List / manage trigger types |
55 -| `auth-configs` | Manage auth-config resources (`ac_*`) |
56 -| `connected-accounts` | Manage connected accounts (`ca_*`) |
57 -| `connections` | Alias / helper for connected-account flows |
58 -| `orgs` | Manage organizations |
59 -| `projects` | Manage projects |
60 -| `logs` | View tool-execution logs |
61 -| `config` | Read/write CLI config |
62 -| `listen` | Listen for events |
63 -| `proxy` | Proxy authenticated API requests |
64 -| `run` | Run a saved script / preset |
65 -| `dev` | Developer-only utilities |
66 -| `artifacts` | Manage generated artifacts |
38 +Each command uses `effect/cli`'s `Command.make()` pattern. The [contributor guide](CONTRIBUTING.md) traces a command from its flags through its handler and argv-level test.
39
40 Named options use `Flag.String()`, `Flag.Boolean()`, `Flag.Int()`, `Flag.Literals()`, `Flag.Directory()` (from `effect/cli`); positionals use `Argument.String()` / `Argument.variadic()`. Both share `.withDefault`/`.withDescription`/`.withAlias`/`.optional` combinators. Feature flags live in `feature-tags.ts` and `experimental-features.ts`.
41
70 -To find a command's source, grep [`src/commands/COMMANDS.md`](src/commands/COMMANDS.md) for its path: one row per command registration with its tree (root or `dev`), the `.cmd.ts` file that defines it, other registrations of the same definition (root shortcuts such as `link`), whether it needs a login, and whether it is unlisted or experimental. It is generated from the command tree (`test/src/commands/commands-map.test.ts`, which finds each registration's definition among the `.cmd.ts` exports); after adding, moving, or renaming a command, run `pnpm --filter @composio/cli run commands:map` and commit the result. `pnpm test` fails while it is stale.
42 +To find a command's source, grep [`src/commands/COMMANDS.md`](src/commands/COMMANDS.md) for its path: one row per command registration with its help summary, tree (root or `dev`), the `.cmd.ts` file that defines it, other registrations of the same definition (root shortcuts such as `link`), whether it needs a login, and whether it is unlisted or experimental. It is generated from the command tree (`test/src/commands/commands-map.test.ts`, which finds each registration's definition among the `.cmd.ts` exports); after adding, moving, renaming, or changing the description of a command, run `pnpm --filter @composio/cli run commands:map` and commit the result. `pnpm test` fails while it is stale.
43
44 #### Command module layout
45
ts/packages/cli/CONTRIBUTING.md new
+140
@@ -0,0 +1,140 @@
1 +# Contributing to the CLI
2 +
3 +The CLI keeps command declarations, behavior, and output in separate files. The [command catalog](src/commands/COMMANDS.md) maps each command registration to its help summary and source file. The catalog comes from the command tree and includes root shortcuts, login requirements, and hidden or experimental commands.
4 +
5 +This guide follows `composio connections list --toolkit github` through its declaration, handler, and test. The [glossary](GLOSSARY.md) defines command trees, projects, acting users, and invocation outcomes. [AGENTS.md](AGENTS.md) contains the detailed implementation rules.
6 +
7 +## Find the behavior to change
8 +
9 +A command path identifies its registration in the CLI. The root tree acts on the logged-in person's consumer project. The dev tree acts on a developer project. A root shortcut can reuse a definition registered elsewhere, such as `link` and `dev connected-accounts link`.
10 +
11 +The usual file layout places related code in one directory.
12 +
13 +| File | Responsibility |
14 +| --------------------------- | ---------------------------------------------------------- |
15 +| `<group>.<name>.cmd.ts` | Declares arguments, flags, help, examples, and the handler |
16 +| `<group>.<name>.handler.ts` | Composes the command's behavior as an Effect |
17 +| `<group>.<name>.format.ts` | Formats output when the command needs a separate renderer |
18 +| `<group>.<name>.errors.ts` | Defines command-specific failures when needed |
19 +| `<group>.cmd.ts` | Registers the group's subcommands and shared metadata |
20 +
21 +Tests mirror this layout under `test/src/commands/`. A `.cmd.test.ts` exercises argv through the full invocation. A `.handler.test.ts` can exercise behavior without parsing arguments. Some commands still use the older single-file layout. A substantive change migrates one command at a time, as described in [the layout rules](AGENTS.md#command-module-layout).
22 +
23 +## Follow a filter through `connections list`
24 +
25 +The command lists the acting user's connected accounts as JSON, grouped by toolkit. The optional `--toolkit` flag limits the request to one toolkit. A change to that filter touches its declaration, handler, and argv-level test.
26 +
27 +### The declaration defines the input
28 +
29 +[connections.list.cmd.ts](src/commands/connections/list/connections.list.cmd.ts) contains the flag and passes the handler to `Command.make`. The following excerpt is the current flag declaration.
30 +
31 +```typescript
32 +const toolkit = Flag.String('toolkit').pipe(
33 + Flag.withDescription('Filter by toolkit slug (e.g. "gmail")'),
34 + Flag.optional
35 +);
36 +```
37 +
38 +`effect/cli` parses named options through `Flag` and positionals through `Argument`. `Flag.optional` produces an `Option<string>`. Defaults and aliases also belong in the declaration, so parsing and help describe the same input.
39 +
40 +The command file declares input and help. It contains no request logic or service lookups.
41 +
42 +### The handler composes the behavior
43 +
44 +[connections.list.handler.ts](src/commands/connections/list/connections.list.handler.ts) declares its own `ConnectionsListParams` type. Passing the handler to `Command.make` checks that the parsed input satisfies that type.
45 +
46 +The handler performs five steps.
47 +
48 +1. It resolves `TerminalUI`, the client factory, and the optional toolkit slug.
49 +2. It resolves the acting user and project through `actingUser()`.
50 +3. It gets a client scoped to that project's organization and project, then lists the user's accounts.
51 +4. It decodes the response and resolves each account's permission group.
52 +5. It formats the accounts and writes JSON through `TerminalUI.output`.
53 +
54 +This excerpt shows the current request. The surrounding Effect has already resolved the client, toolkit slug, and consumer user id.
55 +
56 +<!-- prettier-ignore -->
57 +```typescript
58 +const rawResult = yield* client.connectedAccounts
59 + .list(
60 + {
61 + toolkit_slugs: toolkitSlug ? [toolkitSlug] : undefined,
62 + user_ids: [consumerUserId],
63 + limit: 1000,
64 + },
65 + idempotent
66 + )
67 + .pipe(failedWith(ConnectionsListRequestError, 'Failed to list connections.'));
68 +```
69 +
70 +`yield*` runs an Effect within `Effect.gen`. A typed failure stops the remaining steps unless a combinator handles it. The `idempotent` option enables the CLI's retry policy for this read. Execution and proxy requests have different retry constraints.
71 +
72 +The CLI uses native Effects from `@composio/client/effect`. [ComposioClientSingleton](src/services/composio-clients.ts) constructs clients with explicit credentials, project scope, HTTP transport, identity headers, and schema loaders. A handler gets its scoped client from that factory. It does not wrap native client calls in `Effect.tryPromise` or construct a second client.
73 +
74 +The handler's dependencies come from Effect services. [InvocationLive](src/invocation/live.ts) supplies production implementations. `TestLive` supplies test implementations for the same invocation. This keeps filesystem access, HTTP requests, terminal output, and other dependencies replaceable in tests.
75 +
76 +### The registration supplies shared behavior
77 +
78 +[connections.cmd.ts](src/commands/connections/connections.cmd.ts) registers `list` through `withRegisteredSubcommands` and declares `requiresLogin: true` for the group. The selected command inherits that requirement. The handler does not repeat the login check.
79 +
80 +Registration also supplies the command path used by invocation hooks and lifecycle telemetry. New groups use `withRegisteredSubcommands`, rather than calling `Command.withSubcommands` directly. [ADR 0001](docs/adr/0001-command-identity-after-parse.md) explains why identity comes from the parsed registration.
81 +
82 +For dev commands, `CommandSurface` supplies the tree and shared flags. `actingUser()` resolves the user and project together. A handler does not recreate the fallback from an explicit `--user-id` to a directory or global test user. A `--user-id` used only to filter results remains a user filter.
83 +
84 +### The argv-level test verifies the change
85 +
86 +[connections.list.cmd.test.ts](test/src/commands/connections/list/connections.list.cmd.test.ts) runs `cli(['connections', 'list', '--toolkit', 'github'])` over `TestLive`. Its fixture includes accounts from multiple toolkits. The assertion checks that the resulting JSON contains only GitHub accounts.
87 +
88 +For a change to toolkit filtering, the regression belongs in this test. A request-mapping change also needs an assertion on the request sent by the handler. An output change needs an assertion on the resulting JSON. The test should establish the changed behavior through the command's input and output.
89 +
90 +The test helper calls the same [runInvocation](src/invocation/invocation.ts) function as the binary. Parsing, registration metadata, invocation hooks, error reporting, and lifecycle telemetry remain on the test path.
91 +
92 +## Read a larger handler
93 +
94 +The larger commands use the same declaration and handler layout. These source maps identify their main phases without requiring a contributor to read every helper first.
95 +
96 +| Command | Main phases | Starting point |
97 +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
98 +| `execute` / `dev playground-execute` | Selects single or parallel execution. The single-tool path handles schema-only requests, resolves execution context, checks connections, then validates or executes and reports the result. | [runToolsExecuteCommand and runToolsExecute](src/commands/tools/execute/tools.execute.handler.ts) |
99 +| `listen` | Resolves the acting user and account, prepares event files, acquires a temporary trigger when needed, processes realtime events, then releases resources and reports write failures. | [runListen](src/commands/listen/listen.handler.ts) |
100 +| `run` | Checks script input, resolves helper context and companion modules, prepares the child process, forwards signals, cleans up temporary files, then preserves the child's exit outcome. | [runScript](src/commands/run/run.handler.ts) |
101 +| `proxy` | Resolves the acting user, validates request input, selects the connected account and session, checks permissions, sends the proxy request, then formats the response. | [runProxy](src/commands/proxy/proxy.handler.ts) |
102 +
103 +## Understand one invocation
104 +
105 +[bin.ts](src/bin.ts) passes a normal invocation to [cli-main.ts](src/cli-main.ts), which supplies production dependencies and the process runner. The command assembly performs compatibility normalization for `run` script arguments and bare `listen --stream` before `effect/cli` parses argv.
106 +
107 +For a selected command, registration begins its identity and runs its enabled invocation hooks. The invocation reports the invoked event, then checks unsupported shared flags and any login requirement before running the handler. The invocation reports success or failure and puts an unreported failure on screen once. The runner owns process signals and the final exit outcome.
108 +
109 +Explicit help, version, and parse failures follow separate paths and skip selected-command hooks. [command-lifecycle-telemetry.ts](src/services/command-lifecycle-telemetry.ts) defines the lifecycle interface. A command declares shared policy through `withCommandMeta`, rather than adding another argv parser or lifecycle reporter.
110 +
111 +## Verify a command change
112 +
113 +Commands below run from the repository root after the pinned toolchain and dependencies are installed, as described in the [repository setup](../../../CONTRIBUTING.md#development-setup).
114 +
115 +The focused test for the example is the first check.
116 +
117 +```bash
118 +pnpm --filter @composio/cli exec vitest run test/src/commands/connections/list/connections.list.cmd.test.ts
119 +```
120 +
121 +A new command needs a mirrored argv-level test and a registration in its group or the root tree. When a command path, registration, or help summary changes, the catalog is regenerated and committed with the change.
122 +
123 +```bash
124 +pnpm --filter @composio/cli run commands:map
125 +```
126 +
127 +Before pushing CLI source changes, the required checks include workspace typechecking and Effect diagnostics. The diagnostic check catches dropped Effects, including a client request that was created but never yielded.
128 +
129 +```bash
130 +pnpm typecheck
131 +pnpm --filter @composio/cli run lint:effect
132 +```
133 +
134 +The package test command also validates bundled skills, registered lint exceptions, command-test paths, and the generated catalog.
135 +
136 +```bash
137 +pnpm --filter @composio/cli test
138 +```
139 +
140 +A compiled-binary or packaging change also needs the relevant [Docker CLI checks](../../e2e-tests/cli/README.md). Documentation-only changes do not need a Changeset.
ts/packages/cli/README.md
+2
@@ -204,6 +204,8 @@ It holds derived data, not saved API responses, so it is read on every run regar
204
205 ## Development
206
207 +The [contributor guide](CONTRIBUTING.md) explains command structure, argument parsing, Effect composition, and verification through a worked example. The generated [command catalog](src/commands/COMMANDS.md) lists command registrations and their source files.
208 +
209 ### Installation
210
211 ```bash
ts/packages/cli/src/commands/COMMANDS.md
+83 -82
@@ -2,91 +2,92 @@
2
3 # Commands
4
5 -Every command registration of the CLI and the file that defines it. To find a command, grep this file for its path.
5 +Every command registration of the CLI, its help summary, and the file that defines it. The help summaries quote the command definitions.
6
7 -- **Tree**: `dev` for commands under `composio dev` (developer mode), `root` otherwise.
7 +- **Help summary**: the command’s short description, or the first line of its description when no short description exists.
8 +- **Tree**: `dev` for commands in the dev tree, `root` otherwise.
9 - **Also at**: other registrations of the same definition, such as a root shortcut.
10 - **Login**: the command needs a logged-in user (`requiresLogin`, inherited from its group).
11 - **Visibility**: `unlisted` commands are left out of help but still run; `experimental` ones exist only while their experimental feature is enabled.
12 - `composio help <command>` mirrors every row and is not listed.
13
13 -| Command | Tree | Source | Alias | Also at | Login | Visibility |
14 -| ------------------------------- | ---- | ----------------------------------------------------------------------------------------- | ----- | ----------------------------- | ----- | ------------ |
15 -| `composio` | root | `ts/packages/cli/src/commands/$default.cmd.ts` | | | no | listed |
16 -| `agent` | root | `ts/packages/cli/src/commands/agent/agent.cmd.ts` | | | no | listed |
17 -| `agent claim` | root | `ts/packages/cli/src/commands/agent/claim/agent.claim.cmd.ts` | | | no | listed |
18 -| `agent inbox` | root | `ts/packages/cli/src/commands/agent/inbox/agent.inbox.cmd.ts` | | | no | listed |
19 -| `agent login` | root | `ts/packages/cli/src/commands/agent/login/agent.login.cmd.ts` | | | no | listed |
20 -| `agent signup` | root | `ts/packages/cli/src/commands/agent/signup/agent.signup.cmd.ts` | | | no | listed |
21 -| `agent whoami` | root | `ts/packages/cli/src/commands/agent/whoami/agent.whoami.cmd.ts` | | | no | listed |
22 -| `artifacts` | root | `ts/packages/cli/src/commands/artifacts/artifacts.cmd.ts` | | | no | listed |
23 -| `artifacts cwd` | root | `ts/packages/cli/src/commands/artifacts/cwd/artifacts.cwd.cmd.ts` | | | no | listed |
24 -| `config` | root | `ts/packages/cli/src/commands/config/config.cmd.ts` | | | no | listed |
25 -| `config experimental` | root | `ts/packages/cli/src/commands/config/config.experimental.cmd.ts` | | | no | listed |
26 -| `connections` | root | `ts/packages/cli/src/commands/connections/connections.cmd.ts` | | | yes | listed |
27 -| `connections list` | root | `ts/packages/cli/src/commands/connections/list/connections.list.cmd.ts` | | | yes | listed |
28 -| `connections remove` | root | `ts/packages/cli/src/commands/connections/remove/connections.remove.cmd.ts` | | | yes | listed |
29 -| `debug` | root | `ts/packages/cli/src/commands/debug/debug.cmd.ts` | | | no | unlisted |
30 -| `debug api-info` | root | `ts/packages/cli/src/commands/debug/api-info/debug.api-info.cmd.ts` | | | no | unlisted |
31 -| `debug generate-graph` | root | `ts/packages/cli/src/commands/debug/generate-graph/debug.generate-graph.cmd.ts` | | | no | unlisted |
32 -| `debug who-is-my-master` | root | `ts/packages/cli/src/commands/debug/who-is-my-master/debug.who-is-my-master.cmd.ts` | | | no | unlisted |
33 -| `dev` | dev | `ts/packages/cli/src/commands/dev.cmd.ts` | | | no | listed |
34 -| `dev auth-configs` | dev | `ts/packages/cli/src/commands/auth-configs/auth-configs.cmd.ts` | | | yes | listed |
35 -| `dev auth-configs create` | dev | `ts/packages/cli/src/commands/auth-configs/create/auth-configs.create.cmd.ts` | | | yes | listed |
36 -| `dev auth-configs info` | dev | `ts/packages/cli/src/commands/auth-configs/info/auth-configs.info.cmd.ts` | | | yes | listed |
37 -| `dev auth-configs list` | dev | `ts/packages/cli/src/commands/auth-configs/list/auth-configs.list.cmd.ts` | | | yes | listed |
38 -| `dev connected-accounts` | dev | `ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts` | | | yes | listed |
39 -| `dev connected-accounts info` | dev | `ts/packages/cli/src/commands/connected-accounts/info/connected-accounts.info.cmd.ts` | | | yes | listed |
40 -| `dev connected-accounts link` | dev | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `link` | yes | listed |
41 -| `dev connected-accounts list` | dev | `ts/packages/cli/src/commands/connected-accounts/list/connected-accounts.list.cmd.ts` | | | yes | listed |
42 -| `dev connected-accounts whoami` | dev | `ts/packages/cli/src/commands/connected-accounts/whoami/connected-accounts.whoami.cmd.ts` | | | yes | listed |
43 -| `dev init` | dev | `ts/packages/cli/src/commands/init.cmd.ts` | | | no | listed |
44 -| `dev listen` | dev | `ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts` | | `dev triggers listen` | yes | listed |
45 -| `dev logs` | dev | `ts/packages/cli/src/commands/logs/logs.cmd.ts` | | | yes | listed |
46 -| `dev logs tools` | dev | `ts/packages/cli/src/commands/logs/tools/logs.tools.cmd.ts` | | | yes | listed |
47 -| `dev logs triggers` | dev | `ts/packages/cli/src/commands/logs/triggers/logs.triggers.cmd.ts` | | | yes | listed |
48 -| `dev playground-execute` | dev | `ts/packages/cli/src/commands/tools/execute/tools.execute.cmd.ts` | | | yes | listed |
49 -| `dev projects` | dev | `ts/packages/cli/src/commands/projects/projects.cmd.ts` | | | no | listed |
50 -| `dev projects list` | dev | `ts/packages/cli/src/commands/projects/list/projects.list.cmd.ts` | | | yes | listed |
51 -| `dev projects switch` | dev | `ts/packages/cli/src/commands/projects/switch/projects.switch.cmd.ts` | | | no | listed |
52 -| `dev toolkits` | dev | `ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts` | | | yes | listed |
53 -| `dev toolkits info` | dev | `ts/packages/cli/src/commands/toolkits/info/toolkits.info.cmd.ts` | | | yes | listed |
54 -| `dev toolkits list` | dev | `ts/packages/cli/src/commands/toolkits/list/toolkits.list.cmd.ts` | | | yes | listed |
55 -| `dev toolkits search` | dev | `ts/packages/cli/src/commands/toolkits/search/toolkits.search.cmd.ts` | | | yes | listed |
56 -| `dev toolkits version` | dev | `ts/packages/cli/src/commands/toolkits/version/toolkits.version.cmd.ts` | | | yes | listed |
57 -| `dev triggers` | dev | `ts/packages/cli/src/commands/triggers/triggers.cmd.ts` | | | yes | listed |
58 -| `dev triggers create` | dev | `ts/packages/cli/src/commands/triggers/create/triggers.create.cmd.ts` | | | yes | listed |
59 -| `dev triggers disable` | dev | `ts/packages/cli/src/commands/triggers/disable/triggers.disable.cmd.ts` | | | yes | listed |
60 -| `dev triggers enable` | dev | `ts/packages/cli/src/commands/triggers/enable/triggers.enable.cmd.ts` | | | yes | listed |
61 -| `dev triggers info` | dev | `ts/packages/cli/src/commands/triggers/info/triggers.info.cmd.ts` | | `triggers info` | yes | listed |
62 -| `dev triggers list` | dev | `ts/packages/cli/src/commands/triggers/list/triggers.list.cmd.ts` | | `triggers list` | yes | listed |
63 -| `dev triggers listen` | dev | `ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts` | | `dev listen` | yes | listed |
64 -| `dev triggers status` | dev | `ts/packages/cli/src/commands/triggers/status/triggers.status.cmd.ts` | | | yes | listed |
65 -| `execute` | root | `ts/packages/cli/src/commands/tools/execute/tools.execute.cmd.ts` | | | yes | listed |
66 -| `generate` | root | `ts/packages/cli/src/commands/generate/generate.cmd.ts` | | | no | listed |
67 -| `generate py` | root | `ts/packages/cli/src/commands/generate/py/generate.py.cmd.ts` | | | no | listed |
68 -| `generate ts` | root | `ts/packages/cli/src/commands/generate/ts/generate.ts.cmd.ts` | | | no | listed |
69 -| `help` | root | `ts/packages/cli/src/commands/root-help.ts` | | | no | listed |
70 -| `install` | root | `ts/packages/cli/src/commands/install/install.cmd.ts` | | | no | listed |
71 -| `link` | root | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `dev connected-accounts link` | yes | listed |
72 -| `listen` | root | `ts/packages/cli/src/commands/listen/listen.cmd.ts` | | | yes | experimental |
73 -| `login` | root | `ts/packages/cli/src/commands/login/login.cmd.ts` | | | no | listed |
74 -| `logout` | root | `ts/packages/cli/src/commands/logout.cmd.ts` | | | no | listed |
75 -| `orgs` | root | `ts/packages/cli/src/commands/orgs/orgs.cmd.ts` | | | yes | listed |
76 -| `orgs list` | root | `ts/packages/cli/src/commands/orgs/list/orgs.list.cmd.ts` | | | yes | listed |
77 -| `orgs switch` | root | `ts/packages/cli/src/commands/orgs/switch/orgs.switch.cmd.ts` | | | yes | listed |
78 -| `proxy` | root | `ts/packages/cli/src/commands/proxy/proxy.cmd.ts` | | | yes | listed |
79 -| `run` | root | `ts/packages/cli/src/commands/run/run.cmd.ts` | | | no | listed |
80 -| `search` | root | `ts/packages/cli/src/commands/tools/search/tools.search.cmd.ts` | | | yes | listed |
81 -| `setup` | root | `ts/packages/cli/src/commands/setup.cmd.ts` | | | no | listed |
82 -| `setup skill` | root | `ts/packages/cli/src/commands/setup-skill.cmd.ts` | | | no | listed |
83 -| `signup` | root | `ts/packages/cli/src/commands/signup/signup.cmd.ts` | | | no | listed |
84 -| `tools` | root | `ts/packages/cli/src/commands/tools/tools.cmd.ts` | | | yes | listed |
85 -| `tools info` | root | `ts/packages/cli/src/commands/tools/info/tools.info.cmd.ts` | | | yes | listed |
86 -| `tools list` | root | `ts/packages/cli/src/commands/tools/list/tools.list.cmd.ts` | | | yes | listed |
87 -| `triggers` | root | `ts/packages/cli/src/commands/triggers/root-triggers.cmd.ts` | | | yes | listed |
88 -| `triggers info` | root | `ts/packages/cli/src/commands/triggers/info/triggers.info.cmd.ts` | | `dev triggers info` | yes | listed |
89 -| `triggers list` | root | `ts/packages/cli/src/commands/triggers/list/triggers.list.cmd.ts` | | `dev triggers list` | yes | listed |
90 -| `upgrade` | root | `ts/packages/cli/src/commands/upgrade/upgrade.cmd.ts` | | | no | listed |
91 -| `version` | root | `ts/packages/cli/src/commands/version.cmd.ts` | | | no | listed |
92 -| `whoami` | root | `ts/packages/cli/src/commands/whoami.cmd.ts` | | | no | listed |
14 +| Command | Help summary | Tree | Source | Alias | Also at | Login | Visibility |
15 +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------- | ----- | ----------------------------- | ----- | ------------ |
16 +| `composio` | “Connect AI agents to external tools. Start with search, execute, and link.” | root | `ts/packages/cli/src/commands/$default.cmd.ts` | | | no | listed |
17 +| `agent` | “Manage Composio agent identity, inbox, and handoff.” | root | `ts/packages/cli/src/commands/agent/agent.cmd.ts` | | | no | listed |
18 +| `agent claim` | “Invite a human admin to claim this agent org.” | root | `ts/packages/cli/src/commands/agent/claim/agent.claim.cmd.ts` | | | no | listed |
19 +| `agent inbox` | “Read the stored Composio agent inbox.” | root | `ts/packages/cli/src/commands/agent/inbox/agent.inbox.cmd.ts` | | | no | listed |
20 +| `agent login` | “Log in with an existing Composio agent key.” | root | `ts/packages/cli/src/commands/agent/login/agent.login.cmd.ts` | | | no | listed |
21 +| `agent signup` | “Sign up and optionally log in as a Composio agent.” | root | `ts/packages/cli/src/commands/agent/signup/agent.signup.cmd.ts` | | | no | listed |
22 +| `agent whoami` | “Show the stored Composio agent identity.” | root | `ts/packages/cli/src/commands/agent/whoami/agent.whoami.cmd.ts` | | | no | listed |
23 +| `artifacts` | “Inspect session artifact directories.” | root | `ts/packages/cli/src/commands/artifacts/artifacts.cmd.ts` | | | no | listed |
24 +| `artifacts cwd` | “Print the cwd-scoped session artifact directory.” | root | `ts/packages/cli/src/commands/artifacts/cwd/artifacts.cwd.cmd.ts` | | | no | listed |
25 +| `config` | “View and manage CLI configuration.” | root | `ts/packages/cli/src/commands/config/config.cmd.ts` | | | no | listed |
26 +| `config experimental` | “View or toggle experimental feature flags.” | root | `ts/packages/cli/src/commands/config/config.experimental.cmd.ts` | | | no | listed |
27 +| `connections` | “Inspect and remove connected toolkit accounts.” | root | `ts/packages/cli/src/commands/connections/connections.cmd.ts` | | | yes | listed |
28 +| `connections list` | “List connections as JSON with each account id and status, plus its alias, word_id, and provider display name when available.” | root | `ts/packages/cli/src/commands/connections/list/connections.list.cmd.ts` | | | yes | listed |
29 +| `connections remove` | “Interactively remove a connection by toolkit slug, alias, word_id, or connected account ID.” | root | `ts/packages/cli/src/commands/connections/remove/connections.remove.cmd.ts` | | | yes | listed |
30 +| `debug` | “Internal CLI diagnostics.” | root | `ts/packages/cli/src/commands/debug/debug.cmd.ts` | | | no | unlisted |
31 +| `debug api-info` | | root | `ts/packages/cli/src/commands/debug/api-info/debug.api-info.cmd.ts` | | | no | unlisted |
32 +| `debug generate-graph` | | root | `ts/packages/cli/src/commands/debug/generate-graph/debug.generate-graph.cmd.ts` | | | no | unlisted |
33 +| `debug who-is-my-master` | | root | `ts/packages/cli/src/commands/debug/who-is-my-master/debug.who-is-my-master.cmd.ts` | | | no | unlisted |
34 +| `dev` | “Developer workflows: init, playground execution, logs, projects, toolkits, accounts, and triggers.” | dev | `ts/packages/cli/src/commands/dev.cmd.ts` | | | no | listed |
35 +| `dev auth-configs` | “View and manage Composio auth configs.” | dev | `ts/packages/cli/src/commands/auth-configs/auth-configs.cmd.ts` | | | yes | listed |
36 +| `dev auth-configs create` | “Create a new auth config.” | dev | `ts/packages/cli/src/commands/auth-configs/create/auth-configs.create.cmd.ts` | | | yes | listed |
37 +| `dev auth-configs info` | “View details of a specific auth config.” | dev | `ts/packages/cli/src/commands/auth-configs/info/auth-configs.info.cmd.ts` | | | yes | listed |
38 +| `dev auth-configs list` | “List auth configs.” | dev | `ts/packages/cli/src/commands/auth-configs/list/auth-configs.list.cmd.ts` | | | yes | listed |
39 +| `dev connected-accounts` | “View and manage Composio connected accounts.” | dev | `ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts` | | | yes | listed |
40 +| `dev connected-accounts info` | “View details of a specific connected account.” | dev | `ts/packages/cli/src/commands/connected-accounts/info/connected-accounts.info.cmd.ts` | | | yes | listed |
41 +| `dev connected-accounts link` | “Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf.” | dev | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `link` | yes | listed |
42 +| `dev connected-accounts list` | “List connected accounts.” | dev | `ts/packages/cli/src/commands/connected-accounts/list/connected-accounts.list.cmd.ts` | | | yes | listed |
43 +| `dev connected-accounts whoami` | “Show the external account profile for a connected account.” | dev | `ts/packages/cli/src/commands/connected-accounts/whoami/connected-accounts.whoami.cmd.ts` | | | yes | listed |
44 +| `dev init` | “Initialize this directory with a developer project.” | dev | `ts/packages/cli/src/commands/init.cmd.ts` | | | no | listed |
45 +| `dev listen` | “Listen to realtime trigger events for your developer project and optionally forward them into your local dev environment.” | dev | `ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts` | | `dev triggers listen` | yes | listed |
46 +| `dev logs` | “Inspect trigger and tool execution logs.” | dev | `ts/packages/cli/src/commands/logs/logs.cmd.ts` | | | yes | listed |
47 +| `dev logs tools` | “List tool execution logs, or pass a log_id to fetch a specific log.” | dev | `ts/packages/cli/src/commands/logs/tools/logs.tools.cmd.ts` | | | yes | listed |
48 +| `dev logs triggers` | “List trigger logs.” | dev | `ts/packages/cli/src/commands/logs/triggers/logs.triggers.cmd.ts` | | | yes | listed |
49 +| `dev playground-execute` | “Test tool executions against playground users using your developer project auth configs.” | dev | `ts/packages/cli/src/commands/tools/execute/tools.execute.cmd.ts` | | | yes | listed |
50 +| `dev projects` | “Inspect developer projects and project context helpers.” | dev | `ts/packages/cli/src/commands/projects/projects.cmd.ts` | | | no | listed |
51 +| `dev projects list` | “List developer projects for the current organization.” | dev | `ts/packages/cli/src/commands/projects/list/projects.list.cmd.ts` | | | yes | listed |
52 +| `dev projects switch` | “Switch the developer project for this directory.” | dev | `ts/packages/cli/src/commands/projects/switch/projects.switch.cmd.ts` | | | no | listed |
53 +| `dev toolkits` | “Discover and inspect Composio toolkits.” | dev | `ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts` | | | yes | listed |
54 +| `dev toolkits info` | “View details of a specific toolkit.” | dev | `ts/packages/cli/src/commands/toolkits/info/toolkits.info.cmd.ts` | | | yes | listed |
55 +| `dev toolkits list` | “List available toolkits with connection status.” | dev | `ts/packages/cli/src/commands/toolkits/list/toolkits.list.cmd.ts` | | | yes | listed |
56 +| `dev toolkits search` | “Search toolkits by use case.” | dev | `ts/packages/cli/src/commands/toolkits/search/toolkits.search.cmd.ts` | | | yes | listed |
57 +| `dev toolkits version` | “Show latest and recent versions for a toolkit.” | dev | `ts/packages/cli/src/commands/toolkits/version/toolkits.version.cmd.ts` | | | yes | listed |
58 +| `dev triggers` | “Inspect and subscribe to trigger events.” | dev | `ts/packages/cli/src/commands/triggers/triggers.cmd.ts` | | | yes | listed |
59 +| `dev triggers create` | “Create a new trigger instance.” | dev | `ts/packages/cli/src/commands/triggers/create/triggers.create.cmd.ts` | | | yes | listed |
60 +| `dev triggers disable` | “Disable a trigger instance.” | dev | `ts/packages/cli/src/commands/triggers/disable/triggers.disable.cmd.ts` | | | yes | listed |
61 +| `dev triggers enable` | “Enable a trigger instance.” | dev | `ts/packages/cli/src/commands/triggers/enable/triggers.enable.cmd.ts` | | | yes | listed |
62 +| `dev triggers info` | “View details of a specific trigger type.” | dev | `ts/packages/cli/src/commands/triggers/info/triggers.info.cmd.ts` | | `triggers info` | yes | listed |
63 +| `dev triggers list` | “List available trigger types.” | dev | `ts/packages/cli/src/commands/triggers/list/triggers.list.cmd.ts` | | `triggers list` | yes | listed |
64 +| `dev triggers listen` | “Listen to realtime trigger events for your developer project and optionally forward them into your local dev environment.” | dev | `ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts` | | `dev listen` | yes | listed |
65 +| `dev triggers status` | “Show active triggers with optional filters.” | dev | `ts/packages/cli/src/commands/triggers/status/triggers.status.cmd.ts` | | | yes | listed |
66 +| `execute` | “Execute a tool by slug. Validates inputs against cached schemas and checks connections” | root | `ts/packages/cli/src/commands/tools/execute/tools.execute.cmd.ts` | | | yes | listed |
67 +| `generate` | “Generate type stubs for toolkits, tools, and triggers, auto-detecting project language (TypeScript \| Python)” | root | `ts/packages/cli/src/commands/generate/generate.cmd.ts` | | | no | listed |
68 +| `generate py` | “Generate Python type stubs for toolkits, tools, and triggers.” | root | `ts/packages/cli/src/commands/generate/py/generate.py.cmd.ts` | | | no | listed |
69 +| `generate ts` | “Generate TypeScript type stubs for toolkits, tools, and triggers.” | root | `ts/packages/cli/src/commands/generate/ts/generate.ts.cmd.ts` | | | no | listed |
70 +| `help` | “Show help for a command.” | root | `ts/packages/cli/src/commands/root-help.ts` | | | no | listed |
71 +| `install` | “Set up shell integration (PATH and completions). Set COMPOSIO_BIN_DIR to choose the directory added to PATH; it otherwise defaults to ~/.local/bin when that holds this executable, and to the directory of the running binary.” | root | `ts/packages/cli/src/commands/install/install.cmd.ts` | | | no | listed |
72 +| `link` | “Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf.” | root | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `dev connected-accounts link` | yes | listed |
73 +| `listen` | “Listen to consumer-project realtime events. Trigger slugs create a temporary trigger; top-level composio.* event types subscribe directly.” | root | `ts/packages/cli/src/commands/listen/listen.cmd.ts` | | | yes | experimental |
74 +| `login` | “Log in to the Composio SDK.” | root | `ts/packages/cli/src/commands/login/login.cmd.ts` | | | no | listed |
75 +| `logout` | “Log out from the Composio SDK.” | root | `ts/packages/cli/src/commands/logout.cmd.ts` | | | no | listed |
76 +| `orgs` | “Manage default global organization/project context.” | root | `ts/packages/cli/src/commands/orgs/orgs.cmd.ts` | | | yes | listed |
77 +| `orgs list` | “List organizations and show current global selection.” | root | `ts/packages/cli/src/commands/orgs/list/orgs.list.cmd.ts` | | | yes | listed |
78 +| `orgs switch` | “Switch current organization context.” | root | `ts/packages/cli/src/commands/orgs/switch/orgs.switch.cmd.ts` | | | yes | listed |
79 +| `proxy` | “curl-like access to any toolkit API through Composio using your connected account.” | root | `ts/packages/cli/src/commands/proxy/proxy.cmd.ts` | | | yes | listed |
80 +| `run` | “Run inline TS/JS code or a file with injected Composio helpers that behave like their CLI counterparts.” | root | `ts/packages/cli/src/commands/run/run.cmd.ts` | | | no | listed |
81 +| `search` | “Find tools by use case. Defaults to full JSON output; use `--human` for formatted output.” | root | `ts/packages/cli/src/commands/tools/search/tools.search.cmd.ts` | | | yes | listed |
82 +| `setup` | “Install or uninstall Composio plugins for supported agent hosts.” | root | `ts/packages/cli/src/commands/setup.cmd.ts` | | | no | listed |
83 +| `setup skill` | “Install the Composio CLI skill for an agent host.” | root | `ts/packages/cli/src/commands/setup-skill.cmd.ts` | | | no | listed |
84 +| `signup` | “Sign up and optionally log in as a Composio agent.” | root | `ts/packages/cli/src/commands/signup/signup.cmd.ts` | | | no | listed |
85 +| `tools` | “Browse and inspect tools before executing them.” | root | `ts/packages/cli/src/commands/tools/tools.cmd.ts` | | | yes | listed |
86 +| `tools info` | “View a brief summary of a tool and show the CLI-facing input schema used by `composio execute`.” | root | `ts/packages/cli/src/commands/tools/info/tools.info.cmd.ts` | | | yes | listed |
87 +| `tools list` | “List available tools for a toolkit.” | root | `ts/packages/cli/src/commands/tools/list/tools.list.cmd.ts` | | | yes | listed |
88 +| `triggers` | “Browse and inspect trigger types before creating subscriptions.” | root | `ts/packages/cli/src/commands/triggers/root-triggers.cmd.ts` | | | yes | listed |
89 +| `triggers info` | “View details of a specific trigger type.” | root | `ts/packages/cli/src/commands/triggers/info/triggers.info.cmd.ts` | | `dev triggers info` | yes | listed |
90 +| `triggers list` | “List available trigger types.” | root | `ts/packages/cli/src/commands/triggers/list/triggers.list.cmd.ts` | | `dev triggers list` | yes | listed |
91 +| `upgrade` | “Upgrade your Composio CLI. Pass a version (e.g. "0.13.1" or "0.13.1-beta.42") to install a specific release, or omit it to install the latest.” | root | `ts/packages/cli/src/commands/upgrade/upgrade.cmd.ts` | | | no | listed |
92 +| `version` | “Display the current Composio CLI version.” | root | `ts/packages/cli/src/commands/version.cmd.ts` | | | no | listed |
93 +| `whoami` | “Display your account information.” | root | `ts/packages/cli/src/commands/whoami.cmd.ts` | | | no | listed |
ts/packages/cli/test/src/commands/commands-map.test.ts
+16 -6
@@ -1,7 +1,7 @@
1 /**
2 * Keeps `src/commands/COMMANDS.md` in step with the command tree: one row per command
3 - * registration, with the file that defines it. `pnpm --filter @composio/cli run commands:map`
4 - * rewrites the file; `pnpm test` fails while it is stale.
3 + * registration, with its help summary and the file that defines it.
4 + * `pnpm --filter @composio/cli run commands:map` rewrites the file; `pnpm test` fails while it is stale.
5 *
6 * A registration's source file is the `.cmd.ts` module that exports its definition, so no command
7 * declares its own file. A definition is recognised by its name and its `examples` array:
@@ -105,25 +105,35 @@ const visibility = ({ registration, path }: (typeof rows)[number]) =>
105
106 const code = (text: string | undefined) => (text ? `\`${text}\`` : '');
107
108 +/** Quote command help without letting table separators or placeholders change the Markdown. */
109 +const helpSummary = (command: Command.Command.Any): string => {
110 + const summary = (command.shortDescription ?? command.description)?.split('\n')[0]?.trim();
111 + return summary
112 + ? `“${summary.replace(/\|/g, '\\|').replace(/</g, '&lt;').replace(/>/g, '&gt;')}”`
113 + : '';
114 +};
115 +
116 const COMMANDS_MD = [
117 '<!-- Generated from the command tree by `pnpm --filter @composio/cli run commands:map`. Do not edit; `pnpm test` fails while it is stale. -->',
118 '',
119 '# Commands',
120 '',
113 - 'Every command registration of the CLI and the file that defines it. To find a command, grep this file for its path.',
121 + 'Every command registration of the CLI, its help summary, and the file that defines it. The help summaries quote the command definitions.',
122 '',
115 - '- **Tree**: `dev` for commands under `composio dev` (developer mode), `root` otherwise.',
123 + '- **Help summary**: the command’s short description, or the first line of its description when no short description exists.',
124 + '- **Tree**: `dev` for commands in the dev tree, `root` otherwise.',
125 '- **Also at**: other registrations of the same definition, such as a root shortcut.',
126 '- **Login**: the command needs a logged-in user (`requiresLogin`, inherited from its group).',
127 '- **Visibility**: `unlisted` commands are left out of help but still run; `experimental` ones exist only while their experimental feature is enabled.',
128 '- `composio help <command>` mirrors every row and is not listed.',
129 '',
121 - '| Command | Tree | Source | Alias | Also at | Login | Visibility |',
122 - '| --- | --- | --- | --- | --- | --- | --- |',
130 + '| Command | Help summary | Tree | Source | Alias | Also at | Login | Visibility |',
131 + '| --- | --- | --- | --- | --- | --- | --- | --- |',
132 ...rows.map(row => {
133 const { registration, path, source } = row;
134 const cells = [
135 code(path),
136 + helpSummary(registration.command),
137 registration.identity.path[0] === 'dev' ? 'dev' : 'root',
138 code(source),
139 code(registration.command.alias),