Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 276 lines 18.9 KB
Rendered Raw
1 # @composio/cli
2
3 > A CLI for discovering tools, executing them, connecting accounts, scripting workflows, and generating type stubs.
4
5 This package defines the Composio CLI used to interact with the Composio platform. It supports root workflows for searching and executing tools, plus developer-oriented `dev` commands for project, trigger, log, and connected-account management.
6
7 ## Overview
8
9 The CLI is built using:
10
11 - [TypeScript](https://www.typescriptlang.org/)
12 - [The Effect ecosystem](https://effect.website/docs)
13 - [Bun](https://bun.sh/)
14 - [Vitest](https://vitest.dev/)
15
16 ## Windows x64 (experimental)
17
18 Run in PowerShell:
19
20 ```powershell
21 irm https://raw.githubusercontent.com/ComposioHQ/composio/next/install.ps1 | iex
22 ```
23
24 See [INSTALL.md](../../../INSTALL.md#windows-x64-experimental) for options, requirements, and known limitations.
25
26 ## 🧑‍💻 Usage
27
28 ```
29 composio [--log-level All|Trace|Debug|Info|Warn|Error|Fatal|None]
30 ```
31
32 ### Optional Flags
33
34 - `--log-level`: Set the log verbosity level. Accepted values (case-sensitive): All, Trace, Debug, Info, Warn, Error, Fatal, None
35 - `composio setup skill <claude|codex|openclaw> [--name skill-name]`: Install the CLI skill for an agent host.
36
37 ## 🧭 Commands
38
39 - `composio version` (also `composio --version` or `-v`): Display the current CLI version.
40 - `composio whoami`: Show the currently logged-in user/account.
41 - `composio login [--no-browser] [--no-wait] [--key text] [--user-api-key text] [--org text] [-y, --yes] [--no-skill-install]`: Log in to the Composio CLI session.
42 - `composio logout`: Log out from the Composio CLI session.
43 - `composio orgs list|switch`: Inspect and switch your default organization context.
44 - `composio search <query...> [--toolkits text] [--limit integer] [--human]`: Find tools by use case across toolkits/apps.
45 - `composio execute <slug> [-d, --data text] [--dry-run] [--get-schema]`: Execute a tool by slug, with schema and connection checks.
46 - `composio link [<toolkit>] [--no-wait]`: Connect an account for a toolkit/app.
47 - `composio run <code> [-- ...args]` or `composio run --file <path> [-- ...args]`: Run inline or file-based TS/JS workflows with Composio helpers injected.
48 - `composio proxy <url> --toolkit <toolkit> [-X method] [-H header]... [-d data]`: Call a toolkit API directly through Composio using a connected account.
49 - `composio tools list|info`: Inspect available tools and their cached schemas.
50 - `composio triggers list <toolkit>|info`: Inspect toolkit-scoped trigger types and their schemas.
51 - `composio connections list [--toolkit <toolkit>]`: Print toolkit connections as JSON with each account's id, status, alias, and provider display name when available.
52 - `composio connections remove <account>`: Remove a toolkit connection after confirmation; pass `--yes` to skip the prompt, which is required when not running interactively.
53 - `composio artifacts cwd`: Print the cwd-scoped CLI session artifacts directory.
54 - `composio dev <subcommand>`: Developer workflows for init, playground execution, logs, toolkits, auth configs, accounts, triggers, orgs, and projects.
55 - `composio generate [-o, --output-dir <directory>] [--toolkits <toolkit>] [--type-tools]`: Auto-detect the project language (Python or TypeScript) and generate type stubs for toolkits, tools, and triggers.
56 - `composio generate py [-o, --output-dir <directory>] [--toolkits <toolkit>]`: Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
57 - `composio generate ts [-o, --output-dir <directory>] [--compact] [--transpiled] [--type-tools] [--toolkits <toolkit>]`: Generate TypeScript types for toolkits, tools, and triggers from the Composio API.
58 - `composio upgrade [--beta]`: Self-update the Composio CLI from the stable channel, or from the beta channel with `--beta`.
59 - `composio setup skill <claude|codex|openclaw> [--name skill-name]`: Manually install the composio skill for Claude, Codex, or OpenClaw.
60
61 Use `composio execute <slug> --get-schema` to print a tool's input schema as JSON.
62 `composio execute <slug> --help` now shows command options and examples.
63
64 ### Creating development triggers
65
66 For a project with 2FA enabled, pass the user who owns the connected account:
67
68 ```bash
69 composio dev triggers create GMAIL_NEW_GMAIL_MESSAGE --connected-account-id ca_123 --user-id user_123
70 ```
71
72 Every `composio dev` command that acts as a user (`playground-execute`,
73 `connected-accounts link`, `toolkits list` and `info`, `triggers create`) follows
74 one rule. It acts on the developer project (this directory's, or the one
75 `--project-name` names) as the shared `--user-id`, which works before or after
76 the subcommand. When omitted, it uses the directory project's test user (only
77 when acting on that same project), then the global test user configured by
78 `composio login`, and names the one it used on stderr. Setting both
79 `COMPOSIO_ORG_ID` and `COMPOSIO_PROJECT_ID` in the process environment overrides
80 directory configuration, including its test user. If no test user is resolved,
81 `triggers create` omits `user_id` and the server applies the project's ownership
82 policy. Root commands such as `composio execute` and `composio link` always act as
83 your own (consumer) user and take no `--user-id`.
84
85 ## Configuration
86
87 The Composio CLI supports configuration via environment variables. It stores authenticated user context in `user_data.json` and general CLI settings in `config.json`.
88
89 By default, both files are stored in `~/.composio`, but you can specify a custom location using the `COMPOSIO_CACHE_DIR` environment variable.
90
91 | Environment Variable | JSON config | Description | Default |
92 | ---------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
93 | COMPOSIO_USER_API_KEY | `user_data.json`: `api_key` | Composio user API key | None |
94 | COMPOSIO_ENVIRONMENT | - | Selects the production or staging URL defaults | production |
95 | COMPOSIO_BASE_URL | `user_data.json`: `base_url` | The base URL of the Composio backend API (see below) | https://backend.composio.dev |
96 | COMPOSIO_WEB_URL | `user_data.json`: `web_url` | The base URL of the Composio web app (see below) | https://dashboard.composio.dev/ |
97 | COMPOSIO_CACHE_DIR | - | The directory where the Composio CLI stores cache files | ~/.composio |
98 | COMPOSIO_SESSION_DIR | `config.json`: `artifact_directory` | The root directory for CLI session artifacts | `COMPOSIO_CACHE_DIR`, then `artifact_directory`, then `$TMPDIR/composio` |
99 | COMPOSIO_BIN_DIR | - | The directory `composio install` adds to `PATH` (see below) | Resolved from the running binary |
100 | COMPOSIO_LOG_LEVEL | - | The log level for the Composio CLI (case-sensitive: All, Trace, Debug, Info, Warn, Error, Fatal, None) | None |
101 | COMPOSIO_ORG_ID | - | The organization ID used for project-scoped commands | Active project |
102 | COMPOSIO_PROJECT_ID | - | The project ID used for project-scoped commands | Active project |
103 | COMPOSIO_AGENTS_BASE_URL | - | The base URL of the Composio agents service | https://agents.composio.dev |
104 | COMPOSIO_WEBHOOK_SECRET | - | The signing secret for events forwarded by `composio dev triggers listen` | Generated for the current session |
105 | COMPOSIO_DISABLE_CONNECTED_ACCOUNT_CACHE | - | Disables the connected-account cache | true |
106 | COMPOSIO_PERF_DEBUG | - | Set to `1` to write performance diagnostics | 0 |
107 | COMPOSIO_TOOL_DEBUG | - | Set to `1` to write tool diagnostics | 0 |
108 | COMPOSIO_CLI_TELEMETRY_DISABLED | - | Set to `1` to disable CLI telemetry (`COMPOSIO_DISABLE_TELEMETRY` and `TELEMETRY_DISABLED` also work) | 0 |
109 | DEBUG_OVERRIDE_VERSION | - | The version to use when upgrading the Composio CLI (for debugging) | None |
110 | FORCE_USE_CACHE | - | Whether to force the use of previously cached HTTP responses | None |
111 | NO_COLOR | - | If set, disables color output in the CLI (https://no-color.org/) | None |
112
113 `composio login` records the backend it logged in to as `base_url` and `web_url` in `user_data.json`, and later commands keep using it. Setting `COMPOSIO_BASE_URL` or `COMPOSIO_ENVIRONMENT` overrides it; when that sends the stored API key to a different backend, the CLI prints a warning on stderr. A key from `COMPOSIO_USER_API_KEY` always uses the backend the environment selects. `composio logout` forgets the recorded backend.
114
115 The CLI, its installer, and the Composio agent plugins use these variables to coordinate nested commands. They aren't intended for manual configuration.
116
117 | Environment Variable | Description | Default |
118 | ------------------------------ | ---------------------------------------------------------------------------------------------------- | ------- |
119 | COMPOSIO_CLI_INVOCATION_ORIGIN | Identifies whether another CLI surface, such as `composio run`, invoked it | cli |
120 | COMPOSIO_CLI_PARENT_RUN_ID | Reuses the parent run ID for nested command telemetry | None |
121 | COMPOSIO_RUN_OUTPUT_DIR | Shares one artifact directory across nested `composio run` commands | None |
122 | COMPOSIO_RUN_STAGED_FILES_FILE | Points to the temporary JSON file containing upload names and types for the child `composio execute` | None |
123 | COMPOSIO_AGENT_HOST | Names the agent host (`claude` or `codex`) whose chat the command runs in; set by the plugin's hook | None |
124 | COMPOSIO_AGENT_SESSION_ID | Carries that host's ID for the chat; read only together with `COMPOSIO_AGENT_HOST` | None |
125
126 Additionally, `composio upgrade` supports the following environment variables:
127
128 | Environment Variable | Description | Default |
129 | ---------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------- |
130 | COMPOSIO_GITHUB_API_BASE_URL | The base URL for the GitHub API | https://api.github.com |
131 | COMPOSIO_GITHUB_OWNER | The owner of the Composio repository on GitHub | ComposioHQ |
132 | COMPOSIO_GITHUB_REPO | The repository name for the Composio CLI | composio |
133 | COMPOSIO_GITHUB_TAG | The tag to use when fetching the Composio CLI binary from Github | latest |
134 | COMPOSIO_GITHUB_ACCESS_TOKEN | The access token for the GitHub API. Useful during development to avoid getting rate-limited by Github | None |
135
136 Every variable above is declared in `src/config/`, one catalog per purpose; that directory is the place to look up or add a setting.
137
138 ### Choosing the PATH entry with `COMPOSIO_BIN_DIR`
139
140 `composio install` writes a single `PATH` line into your shell config. The directory it points at is resolved in this order:
141
142 1. `COMPOSIO_BIN_DIR`, when set to an absolute path
143 2. `~/.local/bin`, when its `composio` entry point resolves to the binary that is running
144 3. the directory of the running binary
145
146 Set `COMPOSIO_BIN_DIR` when the entry point users should reach is not the binary itself — a shim, a symlink farm, or a version-manager `bin` directory:
147
148 ```bash
149 COMPOSIO_BIN_DIR="$HOME/.local/bin" composio install
150 ```
151
152 The command aborts with a non-zero exit code, writing nothing, when the resolved directory is relative or contains a character that cannot be embedded safely in a quoted rc line (`` ` ``, `$`, `"`, `\`, a newline, or the `:` PATH separator).
153
154 ### CLI binary release tags
155
156 CLI binaries are published as GitHub release assets.
157
158 - Current tag format: `@composio/cli@<semver>` (for example `@composio/cli@0.1.24`)
159 - Temporary compatibility: legacy `v<semver>` tags are also supported during migration
160 - `composio upgrade` and `install.sh` can resolve either format during the compatibility window
161
162 If you pin upgrades with `COMPOSIO_GITHUB_TAG`, prefer the package-scoped tag format:
163
164 ```bash
165 COMPOSIO_GITHUB_TAG='@composio/cli@0.1.24' composio upgrade
166 ```
167
168 To pull from the beta channel instead of the stable channel:
169
170 ```bash
171 composio upgrade --beta
172 ```
173
174 ### Plugin setup release dependency
175
176 `composio setup` installs plugins from these public marketplace repositories:
177
178 - Claude Code: `ComposioHQ/composio-plugin-cc`
179 - Codex: `ComposioHQ/composio-plugin-openai`
180
181 Both repositories must be publicly accessible with a `composio@composio` entry before releasing a CLI version that advertises automatic plugin setup. The CLI release must also contain `composio-skill.zip`; Claude setup installs that standalone skill, while the Codex plugin bundles its own copy.
182
183 ## Caching
184
185 The CLI implements a file-based caching system for improved performance and offline capabilities.
186
187 ### Cache Features
188
189 - **Cache-first reads**: When `FORCE_USE_CACHE=true`, the CLI first checks for cached data before making API calls. If you already ran `composio generate` before, it will work even if you're offline.
190 - **Best-effort writes**: All successful API responses are automatically cached to disk for future use. Writes are atomic — a run interrupted mid-write leaves the previous cache intact rather than a truncated file.
191 - **Graceful fallback**: If cache files are corrupted or missing, the CLI falls back to making API calls.
192 - **Parameter-aware caching**: Methods with parameters include those parameters in the cache key.
193
194 ### Cache Structure
195
196 Cache files are stored in the directory specified by:
197
198 1. `COMPOSIO_CACHE_DIR` environment variable (if set)
199 2. `~/.composio/` directory (default)
200
201 The following files are cached:
202
203 - `toolkits.json` - Results from toolkit listings
204 - `tools-as-enums.json` - Results from tool enum listings
205 - `tools.json` - Results from tool listings
206 - `trigger-types-as-enums.json` - Results from trigger type enumerations
207 - `trigger-types.json` - Results from paginated trigger types payloads
208
209 ### Known toolkit slugs
210
211 `known-toolkit-slugs.json` also lives in the cache directory, but it is not one of the files above.
212
213 Running a tool means knowing which toolkit it belongs to, and the tool slug alone does not say: `GOOGLE_ANALYTICS_RUN_REPORT` belongs to `google_analytics`, not `google`. The CLI ships with the list of toolkit slugs that existed when it was built and records any it learns afterwards in this file, so resolving a toolkit costs a small local read instead of downloading the catalog.
214
215 It holds derived data, not saved API responses, so it is read on every run regardless of `FORCE_USE_CACHE` — that variable keeps its meaning of opting in to replaying previously cached API responses. Deleting the file is safe: the CLI re-learns what it needs. Being out of date is also safe, because the backend never removes a toolkit; a slug the file has never seen simply costs one catalog fetch, after which it is remembered and refreshed weekly in the background.
216
217 ## Development
218
219 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.
220
221 ### Installation
222
223 ```bash
224 pnpm install
225 ```
226
227 ### Build TypeScript code
228
229 ```bash
230 bun run build
231 ```
232
233 ### Build self-contained executable
234
235 ```bash
236 bun run build:binary
237 ```
238
239 or
240
241 ```bash
242 bun run ./scripts/build-binary.ts
243 ```
244
245 ### Install self-contained executable
246
247 ```bash
248 bun run install:binary
249 ```
250
251 or
252
253 ```bash
254 bun run ./scripts/install-binary.ts ./dist/composio
255 ```
256
257 By default, the executable will be installed in `~/.composio/composio`.
258 You can customize the installation directory by setting the `COMPOSIO_INSTALL_DIR` environment variable.
259
260 ### Run interactively
261
262 ```bash
263 bun cli
264 ```
265
266 For instance, to generate type stubs for a TypeScript project, you can run:
267
268 ```bash
269 bun cli generate ts
270 ```
271
272 ### Test
273
274 ```bash
275 bun run test
276 ```