Composio CLI

The Composio CLI is primarily the command-line surface for Composio for You. It is meant to be installed in your terminal and used from inside Claude Code, so Claude can connect apps, execute tools, inspect schemas, call authenticated APIs, and debug Composio projects while it works with you.

Use the CLI directly when you want to give Claude Code a reliable local tool surface instead of copying API keys, schemas, and one-off scripts into chat.

Install

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

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

composio --install-skill composio-cli claude

Check your local state:

composio whoami
composio --version
composio upgrade

1. Using Composio CLI for knowledge work

This is the recommended way to use Composio from inside Claude Code. The CLI can execute tools for you, connect accounts, script workflows, call authenticated APIs, and inspect trigger events without you wiring a custom integration first.

1.1 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 }'

Useful commands:

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 API endpoint and wants Composio to inject auth from your connected account:

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

1.2 Run scripts and sub-agents

Use 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

1.3 Listen to trigger events

Use trigger listening when Claude needs to wait for new events, inspect incoming payloads, or forward events while debugging. In the current CLI, trigger event streaming is exposed through 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 user ID when you want Claude to focus on one event source.

2. Using Composio CLI to build on Composio

Use the CLI while building on the Composio developer platform. These commands help 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 developer connected-account commands when you are 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

Use this section when you are debugging auth configs, connected accounts, trigger delivery, or tool execution in a Composio project. For general user-facing app development, prefer the SDK/session docs first and use the CLI as a local debugging companion.

3. Building directly on top of the CLI

Building products directly on top of the CLI is not recommended. The CLI is in constant development and Composio does not provide CLI-level SLAs as an application runtime contract.

If you need a stable production integration, build on top of the Composio SDKs and APIs instead.

That said, the CLI can be useful as a bootstrap or helper layer for agent-native products:

Use Signing up as an agent when an agent needs to programmatically create or reuse a Composio identity.
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