Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | ``` |