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 22, 00:45 UTC
docs: improve CLI workflow guide (#3055)
## Summary - rewrite the CLI docs page around the real top-level workflow - explain when to use `execute`, `search`, `--get-schema`, `--dry-run`, `link`, `run`, and `proxy` - keep `composio dev` clearly separated from the normal end-user flow ## Testing - `pnpm exec prettier --check docs/content/docs/cli.mdx`
Rahul Tarak committed
Mar 27, 2026 at 07:49 UTC
29b4287ff74accde83b6c23fd54cea706cdc27dc
3 files changed
+228
-85
docs/content/docs/cli.mdx
+185
-61
@@ -1,10 +1,18 @@
1
---
2
title: CLI
3
-description: Install the Composio CLI to manage toolkits, execute tools, handle authentication, and generate type-safe code from the terminal.
3
+description: Install the Composio CLI to search for tools, inspect schemas, execute them, connect accounts, script workflows, and generate type-safe code from the terminal.
4
keywords: [cli, command line, terminal, toolkits, tools, authentication, generate types]
5
---
6
7
-The Composio CLI lets you manage toolkits, execute tools, handle auth, inspect logs, and generate type-safe code from the terminal.
7
+The Composio CLI is best understood as a workflow tool, not just a list of commands.
8
+
9
+The default flow is:
10
+
11
+1. If you already know the tool slug, start with `composio execute`.
12
+2. If you do not know the slug, use `composio search`.
13
+3. If the inputs are unclear, use `composio execute --get-schema` or `--dry-run`.
14
+4. If `execute` reports that the toolkit is not connected, run `composio link` and retry.
15
+5. Use `composio run` for multi-step workflows and `composio proxy` for raw API calls.
16
17
## Installation
18
@@ -18,100 +26,214 @@ curl -fsSL https://composio.dev/install | bash
26
# Authenticate with Composio
27
composio login
28
21
-# Initialize a project in the current directory
22
-composio init
23
-
24
-# Check your account
29
+# Inspect your current session
30
composio whoami
31
```
32
33
`composio login` opens a browser-based flow, then prompts you to choose your default organization and project. Use `composio login -y` to skip the picker and use session defaults for non-interactive runs.
34
30
-`composio whoami` shows account and workspace context, and does not include API keys in display or JSON output.
35
+`composio whoami` shows account and workspace context and does not include API keys in display or JSON output.
36
+
37
+## Execute a tool
38
+
39
+`composio execute` is the main command for actually running tools.
40
+
41
+```bash
42
+# Execute a tool directly
43
+composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
44
+
45
+# Validate without executing
46
+composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'
47
+
48
+# Read arguments from a file
49
+composio execute GITHUB_CREATE_ISSUE -d @issue.json
50
+
51
+# Read arguments from stdin
52
+cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -
53
+```
54
+
55
+The `-d` / `--data` flag accepts:
56
+
57
+- JSON
58
+- JS-style object literals
59
+- `@file`
60
+- `-` for stdin
61
+
62
+By default, `execute` does two useful checks for you:
63
+
64
+- validates arguments against the cached tool schema
65
+- checks whether the required toolkit account is connected
66
32
-## Search and execute a tool
67
+If you just need a schema or a safe preview, stay inside `execute`:
68
+
69
+```bash
70
+composio execute GITHUB_CREATE_ISSUE --get-schema
71
+composio execute GITHUB_CREATE_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'
72
+```
73
+
74
+If the command output is very large, the CLI may store it in the session artifacts directory instead of printing everything inline. Use `composio artifacts cwd` to find that directory for the current working tree.
75
+
76
+If you need several independent tool calls and do not need script logic, use top-level parallel execute instead of jumping straight to `run`:
77
+
78
+```bash
79
+composio execute --parallel \
80
+ GMAIL_FETCH_EMAILS -d '{ max_results: 2 }' \
81
+ GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'
82
+```
83
+
84
+## Search for the right slug
85
+
86
+Use `composio search` only when the slug is unknown.
87
+
88
+```bash
89
+composio search "create a github issue"
90
+composio search "send an email" --toolkits gmail
91
+composio search "send an email" "create a github issue"
92
+composio search "my emails" "my github issues" --toolkits gmail,github
93
+```
94
+
95
+Use multiple quoted queries when you are exploring several related tasks at once. Read the returned slugs, choose the best match, then move back to `execute`.
96
+
97
+Use `--human` when you want a readable summary in the terminal. Leave it off when you want JSON output for scripting.
98
+
99
+## Inspect a known slug
100
+
101
+Use `composio tools info` as a compact fallback when you already know the slug and want a quick summary:
102
+
103
+```bash
104
+composio tools info GITHUB_CREATE_ISSUE
105
+composio tools list gmail
106
+```
107
+
108
+For most execution questions, `composio execute --get-schema` or `--dry-run` is a better first step than `tools info`.
109
+
110
+## Connect accounts with link
111
+
112
+`composio link` connects an external account for a toolkit such as GitHub, Gmail, or Slack.
113
114
```bash
35
-# Connect your GitHub account
115
composio link github
116
38
-# Print connect URL + JSON and exit immediately (no wait)
117
+# Print the auth URL and exit immediately
118
composio link github --no-wait
119
+```
120
41
-# Search for tools
42
-composio search "star a github repo"
121
+You usually do not start with `link`. The normal flow is to try `execute` first. If the CLI tells you there is no active connection for the toolkit, run `link` and retry the exact same command.
122
44
-# Look up a tool's input schema
45
-composio manage tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
123
+## End-to-end flow
124
47
-# Execute a tool (star the Composio repo!)
125
+```bash
126
+composio search "star a github repo" --human
127
+composio tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
128
+composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'
129
+composio link github
130
composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
131
```
132
51
-## Set up and listen to triggers
133
+## Script multi-step workflows with run
134
+
135
+Use `composio run` when one tool call is not enough and you want to stay inside the CLI.
136
+
137
+The runtime injects helpers that mirror the CLI:
138
+
139
+- `execute(slug, data?)`
140
+- `search(query, opts?)`
141
+- `proxy(toolkit)`
142
+- `experimental_subAgent(prompt, opts?)`
143
+- `z`
144
+
145
+Examples:
146
+
147
+```bash
148
+# Inline workflow
149
+composio run '
150
+ const issue = await execute("GITHUB_CREATE_ISSUE", {
151
+ owner: "acme",
152
+ repo: "app",
153
+ title: "Bug report",
154
+ body: "Steps to reproduce..."
155
+ });
156
+ console.log(issue);
157
+'
158
+
159
+# Run a workflow from a file
160
+composio run --file ./workflow.ts -- --repo composiohq/composio
161
+```
162
+
163
+Use `run` when you want loops, conditionals, `Promise.all`, `search()` inside a script, `proxy()`, `experimental_subAgent()`, or a reusable workflow file.
164
+
165
+## Call raw APIs with proxy
166
+
167
+Use `composio proxy` when you want authenticated access to a toolkit API endpoint directly rather than going through a dedicated Composio tool.
168
169
```bash
54
-# Find your connected account ID
55
-composio manage connected-accounts list --toolkits github
170
+composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail
171
+composio proxy https://gmail.googleapis.com/gmail/v1/users/me/drafts --toolkit gmail -X POST -H 'content-type: application/json' -d '{"message":{"raw":"..."}}'
172
+```
173
+
174
+Use `proxy` when:
175
57
-# Create a trigger for star events on your repo
58
-composio manage triggers create GITHUB_STAR_ADDED_EVENT --connected-account-id your-connected-account-id --trigger-config '{"owner":"your-username","repo":"your-repo"}'
176
+- there is no dedicated tool for the endpoint you need
177
+- you already know the exact API endpoint to call
178
+- you want Composio to handle auth while you keep full control over the request
179
60
-# Listen to all GitHub trigger events on your account in real time
61
-composio listen --toolkits github --table
180
+## Developer project commands
181
+
182
+Use the `dev` namespace only for developer-project setup and inspection commands, not for the normal consumer-style search and execute flow.
183
+
184
+```bash
185
+# Initialize local developer project context
186
+composio dev init
187
+
188
+# Execute a tool against a playground user
189
+composio dev playground-execute GITHUB_CREATE_ISSUE --user-id demo-user -d '{"owner":"acme","repo":"app","title":"Bug"}'
190
+
191
+# Inspect triggers and logs
192
+composio dev listen --toolkits github --table
193
+composio dev logs tools
194
+composio dev logs triggers
195
```
196
64
-## Available commands
197
+## Command summary
198
199
Run `composio <command> --help` for detailed usage and flags.
200
68
-<div className="cli-commands">
69
-
70
-| Command | Subcommands | Description |
71
-| --- | --- | --- |
72
-| `composio login` | | Authenticate with your Composio account and select default org/project |
73
-| `composio logout` | | Remove stored authentication |
74
-| `composio whoami` | | Display your account and workspace information (without API keys) |
75
-| `composio init` | | Initialize a Composio project in the current directory |
76
-| `composio search` | | Search for tools by use-case query (alias for `manage tools search`) |
77
-| `composio execute` | | Execute a tool by slug (alias for `manage tools execute`) |
78
-| `composio link` | | Connect an account for a toolkit (alias for `manage connected-accounts link`) |
79
-| `composio listen` | | Listen to trigger events in real time (alias for `manage triggers listen`) |
80
-| `composio manage toolkits` | `list`, `search`, `info`, `version` | Discover and inspect toolkits |
81
-| `composio manage tools` | `list`, `search`, `info`, `execute` | Discover, inspect, and execute tools |
82
-| `composio manage connected-accounts` | `list`, `info`, `whoami`, `link`, `delete` | Manage connected accounts |
83
-| `composio manage auth-configs` | `list`, `info`, `create`, `delete` | Manage auth configurations |
84
-| `composio manage triggers` | `list`, `info`, `create`, `status`, `listen`, `enable`, `disable`, `delete` | Subscribe to events and manage trigger instances |
85
-| `composio manage logs` | `tools`, `triggers` | Inspect tool and trigger execution logs |
86
-| `composio generate ts` | `(options)` | Generate TypeScript type stubs |
87
-| `composio generate py` | `(options)` | Generate Python type stubs |
88
-| `composio upgrade` | | Upgrade CLI to the latest version |
89
-| `composio version` | | Display the current CLI version |
90
-
91
-</div>
201
+- `composio execute`: First choice when the slug is known.
202
+- `composio search`: Discovery step when the slug is unknown.
203
+- `composio link`: Recovery step when a toolkit account is missing.
204
+- `composio run`: Programmatic workflows and LLM-driven scripting.
205
+- `composio proxy`: Raw authenticated API access.
206
+- `composio dev`: Developer-project commands only.
207
208
## Global flags
209
95
-| Flag | Description |
96
-| --- | --- |
97
-| `--log-level <level>` | Set log level: `silent`, `error`, `warn`, `info`, `debug` |
98
-| `--help` | Show help for any command |
210
+| Flag | Description |
211
+| --------------------- | ----------------------------------------------------------------------------------- |
212
+| `--log-level <level>` | Set log level: `all`, `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `none` |
213
+| `--help` | Show help for any command |
214
215
## Environment variables
216
102
-| Variable | Description |
103
-| --- | --- |
104
-| `COMPOSIO_API_KEY` | Your Composio API key |
105
-| `COMPOSIO_BASE_URL` | Custom API base URL |
106
-| `COMPOSIO_LOG_LEVEL` | Logging level: `silent`, `error`, `warn`, `info`, `debug` |
107
-| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |
108
-| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override toolkit version (e.g., `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`) |
109
-| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |
217
+| Variable | Description |
218
+| ------------------------------------ | ---------------------------------------------------------------------------- |
219
+| `COMPOSIO_API_KEY` | Your Composio API key |
220
+| `COMPOSIO_BASE_URL` | Custom API base URL |
221
+| `COMPOSIO_WEB_URL` | Custom Composio dashboard URL |
222
+| `COMPOSIO_CACHE_DIR` | Override the CLI cache directory |
223
+| `COMPOSIO_SESSION_DIR` | Override the session artifacts root directory |
224
+| `COMPOSIO_LOG_LEVEL` | Default logging level |
225
+| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |
226
+| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override toolkit version (e.g. `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`) |
227
+| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |
228
+| `FORCE_USE_CACHE` | Force cache-first reads for generated toolkit and tool metadata |
229
+| `DEBUG_OVERRIDE_VERSION` | Override the target CLI version during upgrade debugging |
230
231
## Generate type definitions
232
233
<Callout type="info">
114
-Type generation is only useful if you're using [direct tool execution](/docs/tools-direct/executing-tools). If you're using sessions with meta tools, you don't need this.
234
+ Type generation is only useful if you're using [direct tool
235
+ execution](/docs/tools-direct/executing-tools). If you're using sessions with meta tools, you
236
+ don't need this.
237
</Callout>
238
239
Generate TypeScript or Python type definitions for Composio tools. These types provide autocomplete and type safety when using direct tool execution (`composio.tools.execute()`).
@@ -120,7 +242,7 @@ Generate TypeScript or Python type definitions for Composio tools. These types p
242
composio generate
243
```
244
123
-The CLI auto-detects your project language. For explicit control, use `composio generate ts` or `composio generate py`.
245
+The CLI auto-detects your project language. When no `--output-dir` is provided, TypeScript generation writes to the project default location and emits transpiled JavaScript alongside TypeScript. For explicit control, use `composio generate ts` or `composio generate py`.
246
247
<Tabs items={['TypeScript', 'Python']}>
248
<Tab value="TypeScript">
@@ -135,6 +257,7 @@ The CLI auto-detects your project language. For explicit control, use `composio
257
| `--transpiled` | Emit transpiled JavaScript alongside TypeScript |
258
| `--type-tools` | Generate typed schemas for each tool (slower) |
259
| `--toolkits <names>` | Only generate for specific toolkits (repeatable) |
260
+
261
</Tab>
262
<Tab value="Python">
263
```bash
@@ -145,5 +268,6 @@ The CLI auto-detects your project language. For explicit control, use `composio
268
| --- | --- |
269
| `-o`, `--output-dir <dir>` | Output directory |
270
| `--toolkits <names>` | Only generate for specific toolkits (repeatable) |
271
+
272
</Tab>
273
</Tabs>
docs/content/docs/troubleshooting/cli.mdx
+14
@@ -44,6 +44,12 @@ For CI/CD, use environment variable:
44
export COMPOSIO_API_KEY="your-api-key"
45
```
46
47
+If a toolkit account is missing or expired, reconnect it directly:
48
+
49
+```bash
50
+composio link github
51
+```
52
+
53
## Type generation issues
54
55
### Project type not detected
@@ -63,6 +69,12 @@ Specify output directory explicitly:
69
composio generate --output-dir ./my-types
70
```
71
72
+If project auto-detection is wrong, initialize local developer context first or use the language-specific command explicitly:
73
+
74
+```bash
75
+composio dev init
76
+```
77
+
78
## Debug CLI issues
79
80
Enable debug logging:
@@ -80,7 +92,9 @@ composio version
92
## Common issues
93
94
- **API key not found**: Run `composio login`
95
+- **Toolkit account not connected**: Run `composio link <toolkit>`
96
- **Project type detection fails**: Use language-specific commands or ensure you're in project root
97
+- **Developer commands fail due to missing project context**: Run `composio dev init`
98
- **Network timeout**: Check internet connection and proxy settings
99
- **Permission denied**: Check directory write permissions
100
ts/packages/cli/README.md
+29
-24
@@ -1,8 +1,8 @@
1
# @composio/cli
2
3
-> A tool for managing Composio.dev projects in Python and TypeScript.
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 provides a powerful and flexible way to manage and execute tools, handle authentication, and integrate with various platforms and frameworks.
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
@@ -25,18 +25,23 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]
25
26
## 🧭 Commands
27
28
-| Command | Description |
29
-| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
30
-| `composio version` | Display the current CLI version. |
31
-| `composio whoami` | Show the currently logged-in user/account. |
32
-| `composio login [--no-browser] [--no-wait] [--key text]` | Log in to the Composio SDK. |
33
-| `composio logout` | Log out from the Composio SDK. |
34
-| `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. |
35
-| `composio py` | Python project-specific commands. |
36
-| `composio py generate [-o, --output-dir <directory>] [--toolkits <toolkit>]` | Generate Python type stubs for toolkits, tools, and triggers from the Composio API. |
37
-| `composio ts` | TypeScript project-specific commands. |
38
-| `composio ts generate [-o, --output-dir <directory>] [--compact] [--transpiled] [--type-tools] [--toolkits <toolkit>]` | Generate TypeScript types for toolkits, tools, and triggers from the Composio API. |
39
-| `composio upgrade` | Self-update the Composio CLI if a new release is out. |
28
+- `composio version`: Display the current CLI version.
29
+- `composio whoami`: Show the currently logged-in user/account.
30
+- `composio login [--no-browser] [--no-wait] [--key text] [-y, --yes] [--no-skill-install]`: Log in to the Composio CLI session.
31
+- `composio logout`: Log out from the Composio CLI session.
32
+- `composio orgs list|switch`: Inspect and switch your default organization context.
33
+- `composio search <query...> [--toolkits text] [--limit integer] [--human]`: Find tools by use case across toolkits/apps.
34
+- `composio execute <slug> [-d, --data text] [--dry-run] [--get-schema]`: Execute a tool by slug, with schema and connection checks.
35
+- `composio link [<toolkit>] [--no-wait]`: Connect an account for a toolkit/app.
36
+- `composio run <code> [-- ...args]` or `composio run --file <path> [-- ...args]`: Run inline or file-based TS/JS workflows with Composio helpers injected.
37
+- `composio proxy <url> --toolkit <toolkit> [-X method] [-H header]... [-d data]`: Call a toolkit API directly through Composio using a connected account.
38
+- `composio tools list|info`: Inspect available tools and their cached schemas.
39
+- `composio artifacts cwd`: Print the cwd-scoped CLI session artifacts directory.
40
+- `composio dev <subcommand>`: Developer workflows for init, playground execution, logs, toolkits, auth configs, accounts, triggers, orgs, and projects.
41
+- `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.
42
+- `composio generate py [-o, --output-dir <directory>] [--toolkits <toolkit>]`: Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
43
+- `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.
44
+- `composio upgrade`: Self-update the Composio CLI if a new release is out.
45
46
## Configuration
47
@@ -45,16 +50,16 @@ Additionally, for storing and retrieving user session context, a `user_data.json
50
51
By default, this file is stored in `~/.composio`, but you can specify a custom location using the `COMPOSIO_CACHE_DIR` environment variable.
52
48
-| Environment Variable | User JSON config | Description | Default |
49
-| ---------------------- | ---------------- | ------------------------------------------------------------------ | ----------------------------- |
50
-| COMPOSIO_API_KEY | `api_key` | Composio backend API key | None |
51
-| COMPOSIO_BASE_URL | `base_url` | The base URL of the Composio backend API | https://backend.composio.dev |
53
+| Environment Variable | User JSON config | Description | Default |
54
+| ---------------------- | ---------------- | ------------------------------------------------------------------ | ------------------------------- |
55
+| COMPOSIO_API_KEY | `api_key` | Composio backend API key | None |
56
+| COMPOSIO_BASE_URL | `base_url` | The base URL of the Composio backend API | https://backend.composio.dev |
57
| COMPOSIO_WEB_URL | `web_url` | The base URL of the Composio web app | https://dashboard.composio.dev/ |
53
-| COMPOSIO_CACHE_DIR | - | The directory where the Composio CLI stores cache files | ~/.composio |
54
-| COMPOSIO_LOG_LEVEL | - | The log level for the Composio CLI | None |
55
-| DEBUG_OVERRIDE_VERSION | - | The version to use when upgrading the Composio CLI (for debugging) | None |
56
-| FORCE_USE_CACHE | - | Whether to force the use of previously cached HTTP responses | None |
57
-| NO_COLOR | - | If set, disables color output in the CLI (https://no-color.org/) | None |
58
+| COMPOSIO_CACHE_DIR | - | The directory where the Composio CLI stores cache files | ~/.composio |
59
+| COMPOSIO_LOG_LEVEL | - | The log level for the Composio CLI | None |
60
+| DEBUG_OVERRIDE_VERSION | - | The version to use when upgrading the Composio CLI (for debugging) | None |
61
+| FORCE_USE_CACHE | - | Whether to force the use of previously cached HTTP responses | None |
62
+| NO_COLOR | - | If set, disables color output in the CLI (https://no-color.org/) | None |
63
64
Additionally, `composio upgrade` supports the following environment variables:
65
@@ -156,7 +161,7 @@ bun cli
161
For instance, to generate type stubs for a TypeScript project, you can run:
162
163
```bash
159
-bun cli ts generate
164
+bun cli generate ts
165
```
166
167
### Test