Related Pages

Related topics: Core SDK Models & Authentication, Provider Integrations & Tool Router

Composio Overview & Repository Structure

Composio is a toolkit-and-tool platform that lets AI agents call authenticated actions against hundreds of external services (GitHub, Airtable, HackerNews, etc.) without the agent code having to own OAuth flows, token refresh, or per-API SDK glue. This repository (ComposioHQ/composio) is the monorepo that ships the official Software Development Kits (SDKs) in both TypeScript and Python, plus a developer CLI and a set of framework-specific provider adapters. As stated by the repo's top-level README: *"This repository contains the official Software Development Kits (SDKs) for Composio, providing seamless integration capabilities for Python and Typescript Agentic Frameworks and Libraries."* Source: README.md

High-Level Architecture

The repository is a pnpm + Turbo monorepo whose top-level package.json defines shared dev tooling (eslint, prettier, turbo, vitest, tsdown) and a lint-staged block that runs eslint --fix on TypeScript and ruff check --fix on Python. Source: package.json. The TypeScript tree lives under ts/ and the Python tree under python/, with parallel concepts in each language (core SDK + framework provider packages).

graph TB
    subgraph "Composio Monorepo"
        TS["ts/ (pnpm workspace)"]
        PY["python/ (setuptools/uv)"]
    end

    subgraph "TypeScript packages"
        CORE["@composio/core<br/>(tools, toolkits, triggers,<br/>auth, connected accounts)"]
        CLI["@composio/cli<br/>(login, whoami, generate, dev)"]
        TSB["@composio/ts-builders<br/>(AST helpers for stubs)"]
        LCPROV["@composio/langchain"]
        VERCELPROV["@composio/vercel"]
        OAIPROV["@composio/openai-agents"]
        GOOGLEPROV["@composio/google"]
    end

    subgraph "Python packages"
        PYBASE["composio"]
        PYLGRAPH["composio-langgraph"]
        PYOPENAI["composio-openai"]
    end

    TS --> CORE
    TS --> CLI
    TS --> TSB
    CORE --> LCPROV
    CORE --> VERCELPROV
    CORE --> OAIPROV
    CORE --> GOOGLEPROV
    PY --> PYBASE
    PYBASE --> PYLGRAPH
    PYBASE --> PYOPENAI

    USER["Agent code<br/>(OpenAI, LangChain,<br/>Vercel AI SDK, LangGraph)"] -->|imports| LCPROV
    USER -->|imports| CORE
    USER -->|imports| PYLGRAPH

Core SDK: `@composio/core`

@composio/core is the TypeScript entry point. The package is the runtime that talks to the Composio backend and exposes the domain objects you manipulate. Its README enumerates the six surfaces the core SDK manages: Tools, Toolkits, Triggers, AuthConfigs, ConnectedAccounts, and ActionExecution. Source: ts/packages/core/README.md. The package metadata in package.json declares the gitHead, repository URL, and homepage pointing back into this monorepo, confirming it is published from ts/packages/core/. Source: ts/packages/core/package.json.

The canonical "hello world" for the core SDK is initializing a Composio client and fetching tools scoped to a userId:

import { Composio } from '@composio/core';
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});
const tools = await composio.tools.get('[email protected]', {
  toolkits: ['HACKERNEWS'],
});

Source: README.md and ts/packages/core/README.md.

The core package also ships a docs generator: ts/packages/core/scripts/README.md documents a TypeDoc-based pipeline that "extracts JSDoc from src/models/*.ts → JSON AST", then a generate-docs.ts transform produces MDX files under docs/content/reference/sdk-reference/typescript/. A INTERNAL_CLASSES set hides framework-internal classes, while a USER_INSTANTIATED_CLASSES set explicitly shows constructors. CI is handled by .github/workflows/generate-sdk-docs.yml. Source: ts/packages/core/scripts/README.md.

Framework Providers

The TypeScript tree publishes one provider package per supported agent framework. Each provider declares @composio/core as a peer dependency, pinning it to the >=0.10.0 <1.0.0 range. For example, the LangChain provider requires @composio/core and @langchain/core. Source: ts/packages/providers/langchain/package.json. The Vercel provider peers on ai: ^5.0.0 || ^6.0.0. Source: ts/packages/providers/vercel/package.json. The OpenAI Agents provider peers on @openai/agents: ^0.1.3. Source: ts/packages/providers/openai-agents/package.json. The Google provider peers on @google/genai: ^1.1.0. Source: ts/packages/providers/google/package.json.

On the Python side, the parallel packages are composio-langgraph and composio-openai, both of which document the same "fetch tools → hand them to the agent" pattern. The LangGraph provider README shows initializing a ComposioToolSet, calling get_actions(actions=[Action.GITHUB_ACTIVITY_STAR_REPO_FOR_AUTHENTICATED_USER, ...]), and feeding the result into a LangGraph ToolNode. Source: python/providers/langgraph/README.md. The OpenAI provider follows the same shape with toolset.get_tools(apps=[App.GITHUB]) and an openai_client.chat.completions.create(...) call. Source: python/providers/openai/README.md.

CLI: `@composio/cli`

The CLI is built on TypeScript, the Effect ecosystem, Bun, and Vitest. Its README describes it as *"A CLI for discovering tools, executing them, connecting accounts, scripting workflows, and generating type stubs."* Source: ts/packages/cli/README.md. User-visible subcommands include version, whoami, login, a generate command that emits TypeScript types for toolkits/tools/triggers (with --compact, --transpiled, --type-tools, --toolkits flags), and a self-upgrade command. Session state is persisted to ~/.composio/user_data.json by default, overridable via the COMPOSIO_CACHE_DIR env var, with COMPOSIO_API_KEY, COMPOSIO_BASE_URL, and COMPOSIO_WEB_URL controlling runtime configuration. Source: ts/packages/cli/README.md.

The CLI's type-stub generation is powered by @composio/ts-builders, a small utility package for programmatically constructing TypeScript ASTs (e.g., ConstDeclaration, TypeBuilder, ValueBuilder, Writer). Source: ts/packages/ts-builders/README.md and ts/packages/ts-builders/src/ConstDeclaration.ts.

Examples and Developer Workflows

The ts/examples/ directory contains runnable end-to-end demos. The Vercel example walks through initializing the SDK with the Vercel provider, calling the HackerNews tool, and streaming an OpenAI GPT-4 response — requiring both COMPOSIO_API_KEY and OPENAI_API_KEY in .env. Source: ts/examples/vercel/README.md and ts/examples/toolkits/README.md. The json-schema-to-zod example is a Bun-based project that demonstrates converting Composio's JSON schemas into Zod validators for runtime validation in the Vercel AI SDK. Source: ts/examples/json-schema-to-zod/package.json.

Community-Relevant Operational Notes

Several recurring community pain points map directly to pieces of this repo:

• CLI auth and key issues — Issue #3482 ("Composio entirely unusable: MCP → 500, CLI whoami null, execute → 401, login → 403") and #3485 ("Composio Connect MCP returns 401 Invalid consumer API key for regenerated ck_ keys") both involve the login / whoami / execute surfaces documented in the CLI README. The CLI exposes COMPOSIO_API_KEY and a user_data.json session file, which is exactly the surface a wedged auth state would touch. Source: ts/packages/cli/README.md.
• MCP endpoint access — The CLI v0.2.32-beta.265 changelog notes that "MCP, files, and realtime routes to scoped API key permissions" were added, which is the permission model that the connect.composio.dev/mcp endpoint relies on.
• Provider dependency freshness — Issue #1448 requests bumping composio-langgraph to support langgraph >= 0.3.0; the current Python provider README installs pip install composio-langgraph and uses LangGraph 0.1+ APIs, illustrating the same gap. Source: python/providers/langgraph/README.md.
• Auth connection failures — Issue #3483 ("Can't connect airtable") relates to the ConnectedAccounts / AuthConfigs flow that the core SDK documents. Source: ts/packages/core/README.md.
• V3 surface planning — Issue #1523 ("RFC: V3 API and SDK surface") tracks the next major of the API and SDK layout described above.

See Also

• Composio Core SDK Reference
• TypeScript Provider Packages
• Python Provider Packages
• Composio CLI
• Auth and Connected Accounts

Related Pages

Related topics: Composio Overview & Repository Structure, Provider Integrations & Tool Router, CLI, Operations & Troubleshooting

Core SDK Models & Authentication

Overview

The @composio/core package is the central TypeScript/Node.js SDK for the Composio platform. It exposes a unified client (Composio) that gives programmatic access to the platform's resources — Tools, Toolkits, Triggers, AuthConfigs, ConnectedAccounts, and ActionExecution — and routes tool calls to user-supplied LLM providers such as OpenAI Agents, LangChain, and Vercel AI SDK. Source: ts/packages/core/README.md:9-15.

Authentication is split between two distinct surfaces: (1) platform authentication, performed with a Composio API key passed to the Composio constructor or supplied through the CLI's login flow, and (2) third-party (user) authentication, performed by linking end-user connected accounts to an AuthConfig for a specific toolkit (e.g. GitHub, Airtable, HackerNews). Source: ts/packages/core/README.md:11-15 and ts/packages/cli/README.md:25-29.

The SDK is the single integration point for every framework provider in the monorepo; provider packages such as @composio/langchain only add a Provider implementation and depend on @composio/core as a workspace:* peer. Source: ts/packages/providers/langchain/package.json:42-50.

Core SDK Models

The model layer is defined as TypeScript classes under ts/packages/core/src/models/, and these classes are the documented entry points for SDK consumers. The reference docs site is auto-generated by extracting JSDoc from each model file. Source: ts/packages/core/scripts/README.md:7-12.

Source: ts/packages/core/README.md:11-15.

The Composio client exposes these as namespaced properties, e.g. composio.tools, composio.toolkits, composio.triggers, composio.authConfigs, composio.connectedAccounts. The simplest tool-fetching call looks like this in the OpenAI Agents example shipped in the repo root: Source: README.md:36-42.

import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';

const composio = new Composio({ provider: new OpenAIAgentsProvider() });
const tools = await composio.tools.get('[email protected]', { toolkits: ['HACKERNEWS'] });

The Python surface mirrors the same six concepts, accessed through ComposioToolSet rather than the namespaced Composio client. Source: python/providers/openai/README.md:30-34 and python/providers/langgraph/README.md:30-39.

Authentication

Platform API key

The Composio constructor accepts an apiKey option. If it is omitted, the SDK falls back to the COMPOSIO_API_KEY environment variable. Source: ts/packages/core/README.md:36-44.

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });

The CLI uses the same key model and offers several alternate entry points during composio login:

composio login [--no-browser] [--no-wait] [--key text]
               [--user-api-key text] [--org text] [-y, --yes]
               [--no-skill-install]

Source: ts/packages/cli/README.md:25-29. This makes it possible to authenticate in headless environments (--no-browser) or to inject a pre-provisioned key directly (--key / --user-api-key).

End-user / per-toolkit authentication

Connecting an end user to a third-party service is a two-step process: an AuthConfig defines *how* Composio talks to a toolkit, and a ConnectedAccount records *which* end user has linked their account. The Python example for LangGraph drives this with composio-cli add github, after which GitHub tools become callable. Source: python/providers/langgraph/README.md:14-22.

from composio_langgraph import Action, ComposioToolSet
tools = composio_toolset.get_actions(actions=[
    Action.GITHUB_ACTIVITY_STAR_REPO_FOR_AUTHENTICATED_USER,
    Action.GITHUB_USERS_GET_AUTHENTICATED,
])

The same pattern applies to OpenAI: ComposioToolSet().get_tools(apps=[App.GITHUB]). Source: python/providers/openai/README.md:30-34.

Telemetry & SDK instrumentation

Successful and failed tool calls are batched and forwarded by a dedicated telemetry stack: TelemetryTransport is the user-facing class, BatchProcessor buffers up to 100 events (or flushes every 2 seconds), and TelemetryService performs the HTTP send. Source: ts/packages/core/src/telemetry/README.md:9-50. This matters for authentication because invalid-key errors (401) are reported through the same channel, which is what surfaces in composio whoami when the session is in a wedged state.

Initialization, Providers, and Common Failure Modes

Provider selection

Each framework provider is a separate package that contributes a Provider implementation. Examples shipped in the repo include:

• @composio/openai-agents — used in the root README's quick start. Source: README.md:32-42.
• @composio/langchain — depends on @langchain/core ^1.1.4. Source: ts/packages/providers/langchain/package.json:39-50.
• @composio/vercel — used with @ai-sdk/openai in the Vercel example. Source: ts/examples/vercel/README.md:11-19.

If no provider is given, the SDK accepts a default provider configured by the platform.

Known failure modes reported by the community

Several recurring issues in the issue tracker map directly to the surfaces described above:

• 401 on regenerated ck_ consumer keys when calling the https://connect.composio.dev/mcp endpoint with the x-consumer-api-key header — see #3485.
• CLI whoami returning a half-populated session with null email/org, and composio login itself returning 403 — see #3482.
• API key creation in the dashboard failing because the dashboard CSP blocks the reCAPTCHA script that the new-key modal relies on — see #3484. The dashboard reCAPTCHA is a separate code path from the SDK and CLI, but it is the recommended way to mint a new key when the CLI login is unavailable.
• Per-toolkit connect failures (e.g. Airtable) where an AuthConfig (ac_…) was created but the ConnectedAccount step does not complete — see #3483.

When you hit any of these, the operational checklist is the same: verify the COMPOSIO_API_KEY (or the scoped ck_/user-api-key) is valid and matches the environment the CLI is talking to, confirm the AuthConfig exists, and only then re-attempt the ConnectedAccount link. Source: ts/packages/cli/README.md:25-29 and ts/packages/core/README.md:36-44.

See Also

• Composio README — quick start and TypeScript installation
• CLI reference — login, whoami, and developer commands
• LangChain provider
• OpenAI provider (Python)
• LangGraph provider (Python)
• Telemetry internals

Related Pages

Related topics: Composio Overview & Repository Structure, Core SDK Models & Authentication, CLI, Operations & Troubleshooting

Provider Integrations & Tool Router

Composio exposes a unified surface for connecting its tool execution layer to many agentic frameworks, and a separate Tool Router facility for ad‑hoc discovery, session, and execution workflows. This page documents both pieces, grounded in the repository source.

1. Purpose and Scope

The repository ships official Software Development Kits (SDKs) for Python and TypeScript that allow agentic frameworks to call external tools through Composio. The Provider layer is the adapter that converts Composio's tool descriptor format into the tool format each framework expects (OpenAI Agents, LangChain, Google GenAI, Vercel AI SDK, Claude Agent SDK, LangGraph, CrewAI, AutoGen, LlamaIndex, and others). Source: README.md:1-12.

The Tool Router is a higher‑level orchestration entry point. It exposes session.toolkits() style cursor‑paginated discovery, supports preloading, and offers a per‑user session handle that integrates directly with providers. Source: ts/examples/tool-router/package.json:1-26, ts/e2e-tests/README.md:1-22.

flowchart LR
    A[Agent / LLM] --> P[Provider Adapter]
    P --> C[Composio Core]
    C --> T[Toolkit Execution]
    T --> E[External Apps / APIs]
    C --> TR[Tool Router Session]
    TR -->|tools| P
    A -.HTTP MCP.-> MCP[Composio Connect MCP]
    MCP --> C

2. Provider Integrations

2.1 TypeScript Providers

Each TypeScript provider is a workspace package under ts/packages/providers/ and declares a peer dependency on @composio/core. For example, the OpenAI Agents provider pins @openai/agents: ^0.1.3 and zod, and the LangChain provider pins @langchain/core: ^1.1.4. Source: ts/packages/providers/openai-agents/package.json:15-28, ts/packages/providers/langchain/package.json:14-27.

The Google provider exposes a peer on @google/genai: ^1.1.0. Source: ts/packages/providers/google/package.json:12-22. The Vercel and Claude Agent SDK providers are listed in the tool‑router example's dependency manifest, which pulls @composio/vercel, @composio/claude-agent-sdk, @composio/openai-agents, and @composio/core together. Source: ts/examples/tool-router/package.json:19-31.

Providers are constructed via the provider field on the Composio client. A typical quick start looks like:

import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, run } from '@openai/agents';

const composio = new Composio({ provider: new OpenAIAgentsProvider() });
const tools = await composio.tools.get('[email protected]', { toolkits: ['HACKERNEWS'] });
const agent = new Agent({ name: 'HN assistant', tools });
const result = await run(agent, 'Latest HN post?');

Source: README.md:21-46.

2.2 Python Providers

Python ships a parallel set of provider packages. The Python top‑level README documents direct integrations for OpenAI, LangChain, LangGraph, CrewAI, AutoGen, Anthropic, Google AI, and LlamaIndex. Source: python/README.md:1-49.

The OpenAI provider README walks through App.GITHUB action fetching and a chat.completions.create round‑trip. Source: python/providers/openai/README.md:1-31. The LangGraph provider README shows the Action.GITHUB_ACTIVITY_STAR_REPO_FOR_AUTHENTICATED_USER enum and a ToolNode pattern. Source: python/providers/langgraph/README.md:1-39.

2.3 Provider Capability Matrix

Source: ts/packages/providers/openai-agents/package.json:15-28, ts/packages/providers/langchain/package.json:14-27, ts/packages/providers/google/package.json:12-22, ts/examples/tool-router/package.json:19-31, python/providers/openai/README.md:1-31, python/providers/langgraph/README.md:1-39.

3. Tool Router

The Tool Router is the "search + execute + session" surface aimed at dynamic tool selection. The tool-router-example package demonstrates a Bun runtime entry point that integrates OpenAI, Anthropic via Claude Agent SDK, Vercel AI SDK, and LangChain MCP adapters against a single Composio client. Source: ts/examples/tool-router/package.json:1-31.

Tool Router also supports per‑session pagination: session.toolkits() returns a cursor that can be advanced, validated by the e2e suite under e2e-tests/tool-router-pagination/. Source: ts/e2e-tests/README.md:1-22.

Runtime coverage for the Tool Router includes Node.js, Deno, and Cloudflare Workers. The Cloudflare Workers sub‑suite contains cf-workers-tool-router-ai/, which exercises the AI SDK adapter on the edge. Source: ts/e2e-tests/README.md:1-22.

The pre‑load entry point in the example project is configured via "preload": "bun src/preload.ts", indicating that Tool Router supports warming toolkit data before the agent loop starts. Source: ts/examples/tool-router/package.json:7-13.

4. CLI, Docs Generation, and MCP

The @composio/cli is the developer‑facing tool built on the Effect ecosystem, Bun, and Vitest. It exposes whoami, login, version, toolkits, and execution commands, plus a --log-level flag and a manual --install-skill flag for agent integration. Source: ts/packages/cli/README.md:1-30.

SDK reference docs for the TypeScript surface are produced automatically: TypeDoc extracts JSDoc from ts/packages/core/src/models/*.ts, and generate-docs.ts emits MDX into docs/content/reference/sdk-reference/typescript/. The CI workflow .github/workflows/generate-sdk-docs.yml opens a PR on changes to ts/packages/core/src/**. Source: ts/packages/core/scripts/README.md:1-21.

Python additionally documents an MCP (Model Context Protocol) entry point using composio.mcp.create("my-mcp-server", toolkits=["github", "gmail"], manually_manage_connections=False) and mcp_server.generate("user123") to mint a per‑user server URL. Source: python/README.md:1-49.

5. Known Community Issues Affecting Providers and Tool Router

• MCP unreachable / auth wedges — Reports of HTTP 500 on https://connect.composio.dev/mcp and CLI whoami returning null email/org. Source: #3482.
• Regenerated ck_ consumer keys rejected with 401 — Composio Connect MCP does not accept freshly issued keys. Source: #3485.
• Airtable connection failures — composio==0.13.1 Python users cannot complete the OAuth flow. Source: #3483.
• V3 API/SDK RFC — Active design discussion on the next SDK surface. Source: #1523.
• LangGraph version floor — Community request to raise composio-langgraph to support langgraph >= 0.3.0. Source: #1448.
• Provider argument normalization — Beta CLI @composio/[email protected] includes fix(providers): normalize string tool-call arguments across all providers (TS + Python). Source: release notes.

See Also

• ts/README.md — TypeScript workspace overview and environment variables.
• python/README.md — Python SDK overview and MCP usage.
• ts/packages/cli/README.md — CLI command reference.
• ts/e2e-tests/README.md — Runtime and pagination e2e layout.

Related Pages

Related topics: Core SDK Models & Authentication, Provider Integrations & Tool Router

CLI, Operations & Troubleshooting

The Composio CLI (@composio/cli) is the primary operator surface for discovering tools, executing actions, managing connected accounts, and generating type stubs. It is a TypeScript-based command-line tool built on the Effect ecosystem, distributed with Bun and tested with Vitest. Source: ts/packages/cli/README.md. This page covers the CLI's role in day-to-day operations, its configuration model, and the troubleshooting patterns that the community has surfaced in recent issues.

Purpose and Scope

The CLI is positioned as a scripting-friendly interface to the Composio platform. It supports root workflows (search, execute, connect accounts) and developer-oriented dev subcommands for project, trigger, log, and connected-account management. Source: ts/packages/cli/README.md. Its companion package @composio/ts-builders is used internally to programmatically generate TypeScript type stubs for toolkits, tools, and triggers. Source: ts/packages/ts-builders/README.md.

A separate, related package — @composio/cli-local-tools — distributes platform-specific native executables and dynamic libraries for first-party local tool integrations (e.g., Beeper iMessage, Peekaboo) and CLI sidecars. Source: ts/packages/cli-local-tools/local-tools-binaries/README.md.

Core Commands and Operations

The CLI ships a focused set of root commands. The most operationally important are summarized below. Source: ts/packages/cli/README.md.

A global --log-level flag accepts all, trace, debug, info, warning, error, fatal, or none. Source: ts/packages/cli/README.md.

flowchart LR
    A[Operator] --> B[composio CLI]
    B --> C[Composio Backend API]
    B --> D[Local user_data.json]
    B --> E[Type stubs<br/>via ts-builders]
    C --> F[Toolkits & Tools]
    C --> G[Connected Accounts]
    C --> H[MCP Servers]

Configuration and Authentication

The CLI supports both environment variables and a JSON session file for persistent configuration. The session file is user_data.json, written to ~/.composio by default; the location can be overridden with COMPOSIO_CACHE_DIR. Source: ts/packages/cli/README.md. The primary variables map to user-JSON fields as follows:

• COMPOSIO_API_KEY — the backend API key (maps to api_key in the JSON file)
• COMPOSIO_BASE_URL — backend base URL (default https://backend.composio.dev)
• COMPOSIO_WEB_URL — dashboard base URL (default https://dashboard.composio.dev/)
• COMPOSIO_CACHE_DIR — overrides the cache directory
• COMPOSIO_LOG_LEVEL — log verbosity

The Python SDK uses its own set of environment variables, including COMPOSIO_API_KEY, COMPOSIO_BASE_URL, COMPOSIO_LOGGING_LEVEL, and per-toolkit version pins like COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>. Source: python/README.md.

For SDK reference generation, the TypeScript core package ships a TypeDoc-based pipeline. pnpm generate:docs extracts JSDoc from ts/packages/core/src/models/*.ts, transforms the AST to MDX, and writes output to docs/content/reference/sdk-reference/typescript/. A CI workflow at .github/workflows/generate-sdk-docs.yml opens a PR when core sources change. Source: ts/packages/core/scripts/README.md.

Troubleshooting Common Issues

Several operational failure modes recur in community reports. The patterns below are derived from those discussions and from the CLI's own configuration surface.

Authentication wedges (HTTP 401/403). When whoami returns a half-populated session with null email/org, or when execute returns 401 and composio login returns 403, the local user_data.json is typically in an inconsistent state. The recovery path is to clear the file under ~/.composio (or COMPOSIO_CACHE_DIR), re-export COMPOSIO_API_KEY, and re-run composio login. A regenerated ck_ consumer key has also been reported as returning 401 against https://connect.composio.dev/mcp, suggesting the new key was not yet propagated on the consumer surface — rotating the key again or waiting for backend propagation typically resolves it. Source: community issue #3482 and #3485.

Account connection failures (e.g., Airtable). When an auth config is created successfully (ac_*) but the connection flow stalls, confirm the toolkit's callback URL is reachable and that the auth config's redirect URIs match the deployment environment. The Python SDK's composio.mcp.create(...) returns a server URL that wraps these configs. Source: python/README.md.

Dashboard reCAPTCHA / CSP blocks. API key creation on dashboard.composio.dev can fail when the page's Content Security Policy blocks the reCAPTCHA script. This is a dashboard-side issue independent of the CLI; the workaround is to generate the key from the CLI via composio login --key <key> or by setting COMPOSIO_API_KEY directly. Source: community issue #3484.

Stale CLI version. The composio upgrade command self-updates the CLI; the --beta flag switches to the beta release channel, which often contains the latest fixes (e.g., vitest security upgrades, authlib bump, MCP/files/realtime route additions). Source: release notes for @composio/[email protected].

Windows incompatibility. The CLI is not yet officially supported on Windows. A formal feature request tracks the scope (PowerShell/CMD install paths, command compatibility, native sidecar handling). Source: community issue #3057.

Type stub regeneration. When tool schemas drift, regenerate stubs with composio generate --output-dir <dir> --toolkits <toolkit>. The underlying @composio/ts-builders package emits .d.ts output via the ConstDeclaration and PropertyValue AST builders. Source: ts/packages/ts-builders/src/ConstDeclaration.ts and ts/packages/ts-builders/src/PropertyValue.ts.

See Also

• Composio TypeScript Core SDK
• Python SDK
• V3 API & SDK RFC
• Composio CLI Releases

Doramagic Pitfall Log

Found 24 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ComposioHQ/composio/issues/3484

2. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ComposioHQ/composio/issues/3590

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: CLI @composio/[email protected]
• User impact: Upgrade or migration may change expected behavior: CLI @composio/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: CLI @composio/[email protected]. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/ComposioHQ/composio/releases/tag/%40composio/cli%400.2.31

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: CLI Beta @composio/[email protected]
• User impact: Upgrade or migration may change expected behavior: CLI Beta @composio/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: CLI Beta @composio/[email protected]. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/ComposioHQ/composio/releases/tag/%40composio/cli%400.2.31-beta.258

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: CLI Beta @composio/[email protected]
• User impact: Upgrade or migration may change expected behavior: CLI Beta @composio/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: CLI Beta @composio/[email protected]. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/ComposioHQ/composio/releases/tag/%40composio/cli%400.2.32-beta.263

6. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: CLI Beta @composio/[email protected]
• User impact: Upgrade or migration may change expected behavior: CLI Beta @composio/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: CLI Beta @composio/[email protected]. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/ComposioHQ/composio/releases/tag/%40composio/cli%400.2.31-beta.252

7. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: CLI Beta @composio/[email protected]
• User impact: Upgrade or migration may change expected behavior: CLI Beta @composio/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: CLI Beta @composio/[email protected]. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/ComposioHQ/composio/releases/tag/%40composio/cli%400.2.32-beta.265

8. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Composio entirely unusable: MCP → 500, CLI whoami null, execute → 401, login → 403
• User impact: Developers may misconfigure credentials, environment, or host setup: Composio entirely unusable: MCP → 500, CLI whoami null, execute → 401, login → 403
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Composio entirely unusable: MCP → 500, CLI whoami null, execute → 401, login → 403. Context: Observed when using macos
• Evidence: failure_mode_cluster:github_issue | https://github.com/ComposioHQ/composio/issues/3482

9. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Post-incident API key creation fails — dashboard CSP blocks reCAPTCHA verification
• User impact: Developers may misconfigure credentials, environment, or host setup: Post-incident API key creation fails — dashboard CSP blocks reCAPTCHA verification
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Post-incident API key creation fails — dashboard CSP blocks reCAPTCHA verification. Context: Observed when using node, windows
• Evidence: failure_mode_cluster:github_issue | https://github.com/ComposioHQ/composio/issues/3484

10. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Question: compact audit artifact for agent tool actions
• User impact: Developers may misconfigure credentials, environment, or host setup: Question: compact audit artifact for agent tool actions
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Question: compact audit artifact for agent tool actions. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/ComposioHQ/composio/issues/3590

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: [Bug]: Can't connect airtable
• User impact: Developers may misconfigure credentials, environment, or host setup: [Bug]: Can't connect airtable
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Can't connect airtable. Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | https://github.com/ComposioHQ/composio/issues/3483

12. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/ComposioHQ/composio

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using composio with real data or production workflows.

• Post-incident API key creation fails — dashboard CSP blocks reCAPTCHA ve - github / github_issue
• [[Bug]: Can't connect airtable](https://github.com/ComposioHQ/composio/issues/3483) - github / github_issue
• Composio entirely unusable: MCP → 500, CLI whoami null, execute → 401, l - github / github_issue
• Question: compact audit artifact for agent tool actions - github / github_issue
• CLI Beta @composio/[email protected] - github / github_release
• CLI Beta @composio/[email protected] - github / github_release
• CLI Beta @composio/[email protected] - github / github_release
• CLI @composio/[email protected] - github / github_release
• CLI Beta @composio/[email protected] - github / github_release
• CLI Beta @composio/[email protected] - github / github_release
• CLI Beta @composio/[email protected] - github / github_release
• CLI Beta @composio/[email protected] - github / github_release