@devries-cameron20 / composio Mirror · read-only / commits / 29b4287ff
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 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