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

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

Getting started

# 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.

# 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:

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:

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.

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:

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.

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

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:

# 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.

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.

# 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 <command> --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

Environment variables

Generate type definitions

Generate TypeScript or Python type definitions for Composio tools. These types provide autocomplete and type safety when using direct tool execution (composio.tools.execute()).

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.

composio generate ts

composio generate py