Composio CLI

The Composio CLI gives Claude Code a local tool surface. From your terminal, Claude can connect apps, execute tools, inspect schemas, call authenticated APIs, and debug Composio projects while it works with you. It's the command-line side of Composio for You.

Reach for it when you want Claude to act in your connected apps directly, instead of pasting API keys, schemas, and one-off scripts into the chat.

Install

curl -fsSL https://composio.dev/install | bash
composio login

Open Claude Code in the project you want to work in. composio login installs the composio-cli skill for Claude Code by default. To install it manually:

composio --install-skill composio-cli claude

Check your local state:

composio whoami
composio --version
composio upgrade

Knowledge work in Claude Code

This is the recommended way to use Composio from inside Claude Code. The CLI executes tools, connects accounts, scripts workflows, calls authenticated APIs, and inspects trigger events, all without you wiring up a custom integration first.

Search, connect, and execute tools

Use this flow when Claude needs to act in one of your connected apps:

# Find the right tool
composio search "summarize my unread gmail"

# Inspect the required input schema
composio execute GMAIL_FETCH_EMAILS --get-schema

# Connect the app if needed
composio link gmail

# Execute the tool
composio execute GMAIL_FETCH_EMAILS \
  -d '{ query: "is:unread newer_than:1d", max_results: 10 }'

The commands you'll reach for most:

Command	Use it for
`composio search`	Find relevant tools by natural language
`composio execute`	Execute a known tool slug
`composio link`	Connect an app account
`composio proxy`	Call provider APIs with Composio-managed auth

Use composio proxy when Claude already knows the provider's API endpoint and just needs Composio to inject auth from your connected account:

composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail

Run scripts and sub-agents

Reach for composio run when Claude needs a multi-step workflow: loops, parallel fan-out, data transformation, or LLM-assisted summarization. It runs inline TS/JS or a file, with execute(), search(), proxy(), experimental_subAgent(), result.prompt(), and z injected.

Run a single scripted workflow:

composio run '
const messages = await execute("GMAIL_FETCH_EMAILS", {
  query: "is:unread newer_than:1d",
  max_results: 10,
});
console.log(messages);
'

Fan out across multiple tools:

composio run '
const [emails, issues, events] = await Promise.all([
  execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
  execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),
  execute("GOOGLECALENDAR_FIND_EVENT", { calendar_id: "primary" }),
]);
console.log({ emails: emails.data, issues: issues.data, events: events.data });
'

Ask a sub-agent to summarize tool output and return structured data:

composio run --logs-off '
const [emails, issues] = await Promise.all([
  execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
  execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),
]);

const brief = await experimental_subAgent(
  `Create a morning brief from these emails and issues.\n\n${emails.prompt()}\n\n${issues.prompt()}`,
  {
    schema: z.object({
      brief: z.string(),
      urgentEmails: z.array(z.string()),
      urgentIssues: z.array(z.string()),
    }),
  }
);

console.log(brief.structuredOutput);
'

Run a checked-in script:

composio run --file ./workflow.ts -- --repo composiohq/composio

Listen to trigger events

Use trigger listening when Claude needs to wait for new events, inspect incoming payloads, or forward events while debugging. Event streaming lives in the developer namespace:

# Compact table view for matching events
composio dev listen --toolkits gmail --table

# Raw JSON payloads, then stop after five events
composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5

# Forward each matching event to a local or hosted webhook
composio dev listen --toolkits github --forward https://example.com/webhook

# Append matching events to a local file for Claude to inspect
composio dev listen --toolkits slack --out ./events.jsonl

Filter by toolkit, trigger slug, trigger ID, connected account ID, or userID to focus Claude on a single event source.

Build on the Composio platform

Use these commands while building on the Composio developer platform. They initialize local project context, create auth configs, manage connected accounts, test tool execution, inspect logs, and debug trigger flows.

Initialize project context

# Initialize local project context
composio dev init

# Toggle developer mode
composio dev --mode on
composio dev --mode off

# Switch or inspect project scope
composio dev projects list
composio dev projects switch

Inspect toolkits and versions

composio dev toolkits list
composio dev toolkits search "email"
composio dev toolkits info github
composio dev toolkits version github

Create and inspect auth configs

# List existing auth configs
composio dev auth-configs list
composio dev auth-configs list --toolkits github,gmail
composio dev auth-configs info ac_xxx

# Create an auth config from provider credentials
composio dev auth-configs create "GitHub OAuth" \
  --toolkit github \
  --auth-scheme OAUTH2 \
  --scopes "repo,user" \
  --custom-credentials '{ "client_id": "...", "client_secret": "..." }'

Manage connected accounts

Top-level composio link is the fastest path for personal knowledge work. Use the developer connected-account commands when you're building against project users, auth configs, and playground flows.

composio dev connected-accounts list
composio dev connected-accounts list --toolkits github --user-id user_123
composio dev connected-accounts list --status ACTIVE --limit 20
composio dev connected-accounts info ca_xxx
composio dev connected-accounts whoami ca_xxx
composio dev connected-accounts link

Execute and inspect logs

# Execute a tool through the developer playground path
composio dev playground-execute GMAIL_SEND_EMAIL \
  -d '{ recipient_email: "you@example.com", subject: "Test", body: "Hello" }'

# Inspect tool and trigger logs
composio dev logs tools --toolkit gmail --limit 20
composio dev logs tools log_xxx
composio dev logs triggers --limit 20

Work with triggers

composio dev triggers list gmail
composio dev triggers info GMAIL_NEW_GMAIL_MESSAGE
composio dev triggers status
composio dev triggers create
composio dev triggers enable ti_xxx
composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5

Generate type definitions

For legacy direct tool execution projects, generate local TypeScript or Python types from tool schemas:

composio generate
composio generate ts --toolkits github,gmail
composio generate py --toolkits github,gmail

Reach for this section when you're debugging auth configs, connected accounts, trigger delivery, or tool execution in a Composio project. For user-facing app development, start with the SDK and session docs and keep the CLI as a local debugging companion.

Building on top of the CLI

Don't build a production integration on top of the CLI. It's in constant development, and Composio doesn't offer CLI-level SLAs as an application runtime contract. For a stable integration, build on the Composio SDKs and APIs instead.

That said, the CLI works well as a bootstrap or helper layer for agent-native products:

Use composio connections list to inspect which connected accounts are available locally.
Use composio run or composio proxy for internal automations where CLI churn is acceptable.

For an example of a product built around CLI-driven agent workflows, see Houston.

Help

Use --help on the root command or any subcommand:

composio --help
composio --help full
composio execute --help full
composio run --help full
composio dev --help full

Edit this page on GitHub

On this page