Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: improve CLI workflow guide (#3055)
Rahul Tarak29b4287ff74a
diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdxindex 4528e15a9..782ec6433 100644--- a/docs/content/docs/cli.mdx+++ b/docs/content/docs/cli.mdx@@ -1,10 +1,18 @@---title: CLI-description: Install the Composio CLI to manage toolkits, execute tools, handle authentication, and generate type-safe code from the terminal.+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.keywords: [cli, command line, terminal, toolkits, tools, authentication, generate types]----The Composio CLI lets you manage toolkits, execute tools, handle auth, inspect logs, and generate type-safe code from the terminal.+The Composio CLI is best understood as a workflow tool, not just a list of commands.++The default flow is:++1. If you already know the tool slug, start with `composio execute`.+2. If you do not know the slug, use `composio search`.+3. If the inputs are unclear, use `composio execute --get-schema` or `--dry-run`.+4. If `execute` reports that the toolkit is not connected, run `composio link` and retry.+5. Use `composio run` for multi-step workflows and `composio proxy` for raw API calls.## Installation@@ -18,100 +26,214 @@ curl -fsSL https://composio.dev/install | bash# Authenticate with Composiocomposio login-# Initialize a project in the current directory-composio init--# Check your account+# Inspect your current sessioncomposio whoami````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.-`composio whoami` shows account and workspace context, and does not include API keys in display or JSON output.+`composio whoami` shows account and workspace context and does not include API keys in display or JSON output.++## Execute a tool++`composio execute` is the main command for actually running tools.++```bash+# Execute a tool directly+composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'++# Validate without executing+composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'++# Read arguments from a file+composio execute GITHUB_CREATE_ISSUE -d @issue.json++# Read arguments from stdin+cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -+```++The `-d` / `--data` flag accepts:++- JSON+- JS-style object literals+- `@file`+- `-` for stdin++By default, `execute` does two useful checks for you:++- validates arguments against the cached tool schema+- checks whether the required toolkit account is connected-## Search and execute a tool+If you just need a schema or a safe preview, stay inside `execute`:++```bash+composio execute GITHUB_CREATE_ISSUE --get-schema+composio execute GITHUB_CREATE_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'+```++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.++If you need several independent tool calls and do not need script logic, use top-level parallel execute instead of jumping straight to `run`:++```bash+composio execute --parallel \+ GMAIL_FETCH_EMAILS -d '{ max_results: 2 }' \+ GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'+```++## Search for the right slug++Use `composio search` only when the slug is unknown.++```bash+composio search "create a github issue"+composio search "send an email" --toolkits gmail+composio search "send an email" "create a github issue"+composio search "my emails" "my github issues" --toolkits gmail,github+```++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`.++Use `--human` when you want a readable summary in the terminal. Leave it off when you want JSON output for scripting.++## Inspect a known slug++Use `composio tools info` as a compact fallback when you already know the slug and want a quick summary:++```bash+composio tools info GITHUB_CREATE_ISSUE+composio tools list gmail+```++For most execution questions, `composio execute --get-schema` or `--dry-run` is a better first step than `tools info`.++## Connect accounts with link++`composio link` connects an external account for a toolkit such as GitHub, Gmail, or Slack.```bash-# Connect your GitHub accountcomposio link github-# Print connect URL + JSON and exit immediately (no wait)+# Print the auth URL and exit immediatelycomposio link github --no-wait+```-# Search for tools-composio search "star a github repo"+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.-# Look up a tool's input schema-composio manage tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER+## End-to-end flow-# Execute a tool (star the Composio repo!)+```bash+composio search "star a github repo" --human+composio tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER+composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'+composio link githubcomposio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'```-## Set up and listen to triggers+## Script multi-step workflows with run++Use `composio run` when one tool call is not enough and you want to stay inside the CLI.++The runtime injects helpers that mirror the CLI:++- `execute(slug, data?)`+- `search(query, opts?)`+- `proxy(toolkit)`+- `experimental_subAgent(prompt, opts?)`+- `z`++Examples:++```bash+# Inline workflow+composio run '+ const issue = await execute("GITHUB_CREATE_ISSUE", {+ owner: "acme",+ repo: "app",+ title: "Bug report",+ body: "Steps to reproduce..."+ });+ console.log(issue);+'++# Run a workflow from a file+composio run --file ./workflow.ts -- --repo composiohq/composio+```++Use `run` when you want loops, conditionals, `Promise.all`, `search()` inside a script, `proxy()`, `experimental_subAgent()`, or a reusable workflow file.++## Call raw APIs with proxy++Use `composio proxy` when you want authenticated access to a toolkit API endpoint directly rather than going through a dedicated Composio tool.```bash-# Find your connected account ID-composio manage connected-accounts list --toolkits github+composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail+composio proxy https://gmail.googleapis.com/gmail/v1/users/me/drafts --toolkit gmail -X POST -H 'content-type: application/json' -d '{"message":{"raw":"..."}}'+```++Use `proxy` when:-# Create a trigger for star events on your repo-composio manage triggers create GITHUB_STAR_ADDED_EVENT --connected-account-id your-connected-account-id --trigger-config '{"owner":"your-username","repo":"your-repo"}'+- there is no dedicated tool for the endpoint you need+- you already know the exact API endpoint to call+- you want Composio to handle auth while you keep full control over the request-# Listen to all GitHub trigger events on your account in real time-composio listen --toolkits github --table+## Developer project commands++Use the `dev` namespace only for developer-project setup and inspection commands, not for the normal consumer-style search and execute flow.++```bash+# Initialize local developer project context+composio dev init++# Execute a tool against a playground user+composio dev playground-execute GITHUB_CREATE_ISSUE --user-id demo-user -d '{"owner":"acme","repo":"app","title":"Bug"}'++# Inspect triggers and logs+composio dev listen --toolkits github --table+composio dev logs tools+composio dev logs triggers```-## Available commands+## Command summaryRun `composio <command> --help` for detailed usage and flags.-<div className="cli-commands">--| Command | Subcommands | Description |-| --- | --- | --- |-| `composio login` | | Authenticate with your Composio account and select default org/project |-| `composio logout` | | Remove stored authentication |-| `composio whoami` | | Display your account and workspace information (without API keys) |-| `composio init` | | Initialize a Composio project in the current directory |-| `composio search` | | Search for tools by use-case query (alias for `manage tools search`) |-| `composio execute` | | Execute a tool by slug (alias for `manage tools execute`) |-| `composio link` | | Connect an account for a toolkit (alias for `manage connected-accounts link`) |-| `composio listen` | | Listen to trigger events in real time (alias for `manage triggers listen`) |-| `composio manage toolkits` | `list`, `search`, `info`, `version` | Discover and inspect toolkits |-| `composio manage tools` | `list`, `search`, `info`, `execute` | Discover, inspect, and execute tools |-| `composio manage connected-accounts` | `list`, `info`, `whoami`, `link`, `delete` | Manage connected accounts |-| `composio manage auth-configs` | `list`, `info`, `create`, `delete` | Manage auth configurations |-| `composio manage triggers` | `list`, `info`, `create`, `status`, `listen`, `enable`, `disable`, `delete` | Subscribe to events and manage trigger instances |-| `composio manage logs` | `tools`, `triggers` | Inspect tool and trigger execution logs |-| `composio generate ts` | `(options)` | Generate TypeScript type stubs |-| `composio generate py` | `(options)` | Generate Python type stubs |-| `composio upgrade` | | Upgrade CLI to the latest version |-| `composio version` | | Display the current CLI version |--</div>+- `composio execute`: First choice when the slug is known.+- `composio search`: Discovery step when the slug is unknown.+- `composio link`: Recovery step when a toolkit account is missing.+- `composio run`: Programmatic workflows and LLM-driven scripting.+- `composio proxy`: Raw authenticated API access.+- `composio dev`: Developer-project commands only.## Global flags-| Flag | Description |-| --- | --- |-| `--log-level <level>` | Set log level: `silent`, `error`, `warn`, `info`, `debug` |-| `--help` | Show help for any command |+| Flag | Description |+| --------------------- | ----------------------------------------------------------------------------------- |+| `--log-level <level>` | Set log level: `all`, `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `none` |+| `--help` | Show help for any command |## Environment variables-| Variable | Description |-| --- | --- |-| `COMPOSIO_API_KEY` | Your Composio API key |-| `COMPOSIO_BASE_URL` | Custom API base URL |-| `COMPOSIO_LOG_LEVEL` | Logging level: `silent`, `error`, `warn`, `info`, `debug` |-| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |-| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override toolkit version (e.g., `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`) |-| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |+| Variable | Description |+| ------------------------------------ | ---------------------------------------------------------------------------- |+| `COMPOSIO_API_KEY` | Your Composio API key |+| `COMPOSIO_BASE_URL` | Custom API base URL |+| `COMPOSIO_WEB_URL` | Custom Composio dashboard URL |+| `COMPOSIO_CACHE_DIR` | Override the CLI cache directory |+| `COMPOSIO_SESSION_DIR` | Override the session artifacts root directory |+| `COMPOSIO_LOG_LEVEL` | Default logging level |+| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |+| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override toolkit version (e.g. `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`) |+| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |+| `FORCE_USE_CACHE` | Force cache-first reads for generated toolkit and tool metadata |+| `DEBUG_OVERRIDE_VERSION` | Override the target CLI version during upgrade debugging |## Generate type definitions<Callout type="info">-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.+ 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.</Callout>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 pcomposio generate```-The CLI auto-detects your project language. For explicit control, use `composio generate ts` or `composio generate py`.+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`.<Tabs items={['TypeScript', 'Python']}><Tab value="TypeScript">@@ -135,6 +257,7 @@ The CLI auto-detects your project language. For explicit control, use `composio| `--transpiled` | Emit transpiled JavaScript alongside TypeScript || `--type-tools` | Generate typed schemas for each tool (slower) || `--toolkits <names>` | Only generate for specific toolkits (repeatable) |+</Tab><Tab value="Python">```bash@@ -145,5 +268,6 @@ The CLI auto-detects your project language. For explicit control, use `composio| --- | --- || `-o`, `--output-dir <dir>` | Output directory || `--toolkits <names>` | Only generate for specific toolkits (repeatable) |+</Tab></Tabs>diff --git a/docs/content/docs/troubleshooting/cli.mdx b/docs/content/docs/troubleshooting/cli.mdxindex aeecbab04..a8e4d295f 100644--- a/docs/content/docs/troubleshooting/cli.mdx+++ b/docs/content/docs/troubleshooting/cli.mdx@@ -44,6 +44,12 @@ For CI/CD, use environment variable:export COMPOSIO_API_KEY="your-api-key"```+If a toolkit account is missing or expired, reconnect it directly:++```bash+composio link github+```+## Type generation issues### Project type not detected@@ -63,6 +69,12 @@ Specify output directory explicitly:composio generate --output-dir ./my-types```+If project auto-detection is wrong, initialize local developer context first or use the language-specific command explicitly:++```bash+composio dev init+```+## Debug CLI issuesEnable debug logging:@@ -80,7 +92,9 @@ composio version## Common issues- **API key not found**: Run `composio login`+- **Toolkit account not connected**: Run `composio link <toolkit>`- **Project type detection fails**: Use language-specific commands or ensure you're in project root+- **Developer commands fail due to missing project context**: Run `composio dev init`- **Network timeout**: Check internet connection and proxy settings- **Permission denied**: Check directory write permissionsdiff --git a/ts/packages/cli/README.md b/ts/packages/cli/README.mdindex 2a5276363..842f6dc8e 100644--- a/ts/packages/cli/README.md+++ b/ts/packages/cli/README.md@@ -1,8 +1,8 @@# @composio/cli-> A tool for managing Composio.dev projects in Python and TypeScript.+> A CLI for discovering tools, executing them, connecting accounts, scripting workflows, and generating type stubs.-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.+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.## Overview@@ -25,18 +25,23 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]## 🧭 Commands-| Command | Description |-| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |-| `composio version` | Display the current CLI version. |-| `composio whoami` | Show the currently logged-in user/account. |-| `composio login [--no-browser] [--no-wait] [--key text]` | Log in to the Composio SDK. |-| `composio logout` | Log out from the Composio SDK. |-| `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. |-| `composio py` | Python project-specific commands. |-| `composio py generate [-o, --output-dir <directory>] [--toolkits <toolkit>]` | Generate Python type stubs for toolkits, tools, and triggers from the Composio API. |-| `composio ts` | TypeScript project-specific commands. |-| `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. |-| `composio upgrade` | Self-update the Composio CLI if a new release is out. |+- `composio version`: Display the current CLI version.+- `composio whoami`: Show the currently logged-in user/account.+- `composio login [--no-browser] [--no-wait] [--key text] [-y, --yes] [--no-skill-install]`: Log in to the Composio CLI session.+- `composio logout`: Log out from the Composio CLI session.+- `composio orgs list|switch`: Inspect and switch your default organization context.+- `composio search <query...> [--toolkits text] [--limit integer] [--human]`: Find tools by use case across toolkits/apps.+- `composio execute <slug> [-d, --data text] [--dry-run] [--get-schema]`: Execute a tool by slug, with schema and connection checks.+- `composio link [<toolkit>] [--no-wait]`: Connect an account for a toolkit/app.+- `composio run <code> [-- ...args]` or `composio run --file <path> [-- ...args]`: Run inline or file-based TS/JS workflows with Composio helpers injected.+- `composio proxy <url> --toolkit <toolkit> [-X method] [-H header]... [-d data]`: Call a toolkit API directly through Composio using a connected account.+- `composio tools list|info`: Inspect available tools and their cached schemas.+- `composio artifacts cwd`: Print the cwd-scoped CLI session artifacts directory.+- `composio dev <subcommand>`: Developer workflows for init, playground execution, logs, toolkits, auth configs, accounts, triggers, orgs, and projects.+- `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.+- `composio generate py [-o, --output-dir <directory>] [--toolkits <toolkit>]`: Generate Python type stubs for toolkits, tools, and triggers from the Composio API.+- `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.+- `composio upgrade`: Self-update the Composio CLI if a new release is out.## Configuration@@ -45,16 +50,16 @@ Additionally, for storing and retrieving user session context, a `user_data.jsonBy default, this file is stored in `~/.composio`, but you can specify a custom location using the `COMPOSIO_CACHE_DIR` environment variable.-| Environment Variable | User JSON config | Description | Default |-| ---------------------- | ---------------- | ------------------------------------------------------------------ | ----------------------------- |-| COMPOSIO_API_KEY | `api_key` | Composio backend API key | None |-| COMPOSIO_BASE_URL | `base_url` | The base URL of the Composio backend API | https://backend.composio.dev |+| Environment Variable | User JSON config | Description | Default |+| ---------------------- | ---------------- | ------------------------------------------------------------------ | ------------------------------- |+| COMPOSIO_API_KEY | `api_key` | Composio backend API key | None |+| COMPOSIO_BASE_URL | `base_url` | The base URL of the Composio backend API | https://backend.composio.dev || COMPOSIO_WEB_URL | `web_url` | The base URL of the Composio web app | https://dashboard.composio.dev/ |-| COMPOSIO_CACHE_DIR | - | The directory where the Composio CLI stores cache files | ~/.composio |-| COMPOSIO_LOG_LEVEL | - | The log level for the Composio CLI | None |-| DEBUG_OVERRIDE_VERSION | - | The version to use when upgrading the Composio CLI (for debugging) | None |-| FORCE_USE_CACHE | - | Whether to force the use of previously cached HTTP responses | None |-| NO_COLOR | - | If set, disables color output in the CLI (https://no-color.org/) | None |+| COMPOSIO_CACHE_DIR | - | The directory where the Composio CLI stores cache files | ~/.composio |+| COMPOSIO_LOG_LEVEL | - | The log level for the Composio CLI | None |+| DEBUG_OVERRIDE_VERSION | - | The version to use when upgrading the Composio CLI (for debugging) | None |+| FORCE_USE_CACHE | - | Whether to force the use of previously cached HTTP responses | None |+| NO_COLOR | - | If set, disables color output in the CLI (https://no-color.org/) | None |Additionally, `composio upgrade` supports the following environment variables:@@ -156,7 +161,7 @@ bun cliFor instance, to generate type stubs for a TypeScript project, you can run:```bash-bun cli ts generate+bun cli generate ts```### Test