# CLI (/docs/cli) 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 ```bash curl -fsSL https://composio.dev/install | bash ``` # Getting started ```bash # Authenticate with Composio composio login # Inspect your current session composio 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. # 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 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 composio link github # Print the auth URL and exit immediately composio link github --no-wait ``` 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. # End-to-end flow ```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 github composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}' ``` # 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 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: * 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 # 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 ``` # Command summary Run `composio --help` for detailed usage and flags. * `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 ` | 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_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 > 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. Generate TypeScript or Python type definitions for Composio tools. These types provide autocomplete and type safety when using direct tool execution (`composio.tools.execute()`). ```bash composio generate ``` 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`. **TypeScript:** ```bash composio generate ts ``` | Flag | Description | | -------------------------- | ------------------------------------------------ | | `-o`, `--output-dir ` | Output directory | | `--compact` | Emit a single TypeScript file | | `--transpiled` | Emit transpiled JavaScript alongside TypeScript | | `--type-tools` | Generate typed schemas for each tool (slower) | | `--toolkits ` | Only generate for specific toolkits (repeatable) | **Python:** ```bash composio generate py ``` | Flag | Description | | -------------------------- | ------------------------------------------------ | | `-o`, `--output-dir ` | Output directory | | `--toolkits ` | Only generate for specific toolkits (repeatable) | --- 📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/docs/glossary) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference) --- # Composio SDK — Instructions for AI Code Generators **Purpose:** Enforce only the **current** and **correct** patterns for integrating [Composio](https://composio.dev/) tools into AI agents. **Scope:** All AI-generated code using Composio must follow these guardrails. --- ## 1. Correct Composio Integration Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed). ### Native Tools ```python # ✅ CORRECT — Python (defaults to OpenAI) from composio import Composio composio = Composio() session = composio.create(user_id="user_123") tools = session.tools() # Pass tools to your agent/LLM framework ``` ```typescript // ✅ CORRECT — TypeScript (defaults to OpenAI) import { Composio } from "@composio/core"; const composio = new Composio(); const session = await composio.create("user_123"); const tools = await session.tools(); // Pass tools to your agent/LLM framework ``` For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_` for Python, `@composio/` for TypeScript. ### MCP Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed. --- ## 2. CRITICAL INSTRUCTIONS FOR AI MODELS ### 2.1 — ALWAYS DO THE FOLLOWING 1. **Use `composio.create(user_id)`** to create a session — this is the entry point for all Composio integrations. 2. **Use `session.tools()`** for native tool integration or **`session.mcp.url`** for MCP integration. 3. **Import** from the correct provider package (`composio_` for Python, `@composio/` for TypeScript). 4. **Pass `user_id` to `composio.create()`**, not to individual tool calls. ### 2.2 — NEVER DO THE FOLLOWING 1. **Do not** instruct users to manually create auth configs or connected accounts before running. 2. **Do not** import from `composio_openai` / `@composio/openai` when using OpenAI Agents SDK — use `composio_openai_agents` / `@composio/openai-agents` instead. ### 2.3 — DISCOURAGED (do not use unless user explicitly asks) Do **not** generate `composio.tools.get()`, `composio.tools.execute()`, or `composio.provider.handle_tool_calls()` unless the user explicitly requests direct tool execution. These are a supported but **not recommended** low-level interface. --- ## Terminology Migration (old → current) If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.** | Old term (v1/v2) | Current term (v3) | In code | |---|---|---| | entity ID | user ID | `user_id` parameter | | actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* | | apps / appType | toolkits | e.g., `github` is a *toolkit* | | integration / integration ID | auth config / auth config ID | `auth_config_id` parameter | | connection | connected account | `connected_accounts` namespace | | ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` | | toolset | provider | e.g., `OpenAIProvider` | If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.