CLI

The Composio CLI connects AI agents to 1000+ external apps from the terminal. Use it to discover tools, execute known tool slugs, connect accounts, stream trigger events, call raw APIs through connected accounts, and script multi-step workflows.

The default workflow is:

If you know the tool slug, start with composio execute.
If you do not know the slug, use composio search.
If the inputs are unclear, use composio execute --get-schema or --dry-run.
If execution says the toolkit is not connected, run composio link <toolkit> and retry.
Use composio run for scripts, composio listen for temporary trigger subscriptions, and composio proxy for raw authenticated API requests.

Installation

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

Check the installed version and upgrade when needed:

composio --version
composio upgrade

Set up shell integration after installing or moving the binary:

composio install --completions

Help modes

Use --help on the root command or any subcommand. The root help supports simple, default, and full modes.

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

composio help is not a subcommand. Use composio --help or composio <command> --help.

For a normal human-owned account, start with browser login:

composio login
composio whoami

Useful login options:

# Print a login URL/session and exit without waiting
composio login --no-wait

# Complete login with the key from a no-wait session
composio login --key "session_key"

# Login non-interactively with a user API key and organization
composio login --user-api-key "uak_..." --org "org_or_name"

# Skip the organization picker and use the session default
composio login -y

Manage your default organization context:

composio orgs list
composio orgs switch --org-id "org_xxx"

Log out when you want to clear local auth state:

composio logout

Agents can create and reuse a Composio identity without a human signing up first. The CLI wraps the agent signup APIs documented in Signing up as an agent.

# Sign up as an agent and log the CLI in when credentials are ready
composio signup

# Start signup and exit without waiting for credentials
composio signup --no-wait

# Create or verify the agent identity without logging the CLI in
composio signup --no-login

# Force a new agent identity even if one already exists locally
composio signup --force

You can also manage agent identity through the agent namespace:

composio agent signup
composio agent login "composio_agent_key_..."
composio agent whoami
composio agent inbox --limit 20
composio agent claim human@example.com

Agent identity is stored separately from the normal CLI login flow, so a background agent can bootstrap itself and later hand the organization to a human admin.

Search for tools

Use composio search when you do not know the tool slug. It accepts one or more semantic queries and returns JSON by default.

composio search "send an email"
composio search "send an email" "create github issue"
composio search "my emails" "my github issues" --toolkits gmail,github
composio search "list calendar events" --toolkits google_calendar --limit 5

Use --human for readable terminal output:

composio search "create a github issue" --human

Once you have a slug, switch back to composio execute.

Execute tools

composio execute runs a tool by slug. It validates inputs against the cached schema and checks the required connected account before running the remote action.

composio execute GITHUB_CREATE_ISSUE \
  -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'

The -d / --data flag accepts JSON, JS-style object literals, files, or stdin:

composio execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'
composio execute GITHUB_CREATE_ISSUE -d @issue.json
cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -

Inspect the schema or preview a call without executing it:

composio execute GITHUB_CREATE_ISSUE --get-schema
composio execute GITHUB_CREATE_ISSUE --dry-run \
  -d '{ owner: "acme", repo: "app", title: "Bug" }'

Use the validation escape hatches only when you know what you are doing:

composio execute GITHUB_CREATE_ISSUE --skip-connection-check -d @issue.json
composio execute GITHUB_CREATE_ISSUE --skip-tool-params-check -d @issue.json
composio execute GITHUB_CREATE_ISSUE --skip-checks -d @issue.json

Upload a local file when the tool exposes exactly one uploadable file input:

composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \
  --file ./image.png \
  -d '{ channels: "C123" }'

Run independent tool calls concurrently with -p / --parallel:

composio execute -p \
  GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi", body: "Hello" }' \
  GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'

If output is too large for the terminal, the CLI stores it in the session artifact directory. Use composio artifacts cwd to find that directory.

Connect and manage accounts

composio link connects an external account for a toolkit such as GitHub, Gmail, Slack, or Google Calendar.

composio link github
composio link gmail --alias work

Useful link options:

# Print link info and exit without waiting for browser authorization
composio link github --no-wait

# List existing connected accounts for a toolkit
composio link github --list

The normal flow is to try execute first. If the CLI reports that no account is connected, run link and retry the same execute command.

Inspect or remove connected accounts with connections:

composio connections list
composio connections list --toolkit github
composio connections remove github
composio connections remove work

Aliases for duplicate toolkit accounts require the multi_account experimental feature:

composio config experimental multi_account on

Inspect tools and triggers

Use tools and triggers when you already know the toolkit or slug and want a compact summary.

# Tools
composio tools list gmail
composio tools list gmail --query "send" --tags important --limit 20
composio tools info GMAIL_SEND_EMAIL

# Trigger types
composio triggers list gmail
composio triggers list gmail --limit 20
composio triggers info GMAIL_NEW_GMAIL_MESSAGE

For execution arguments, composio execute <slug> --get-schema is usually the most direct schema view.

Listen to trigger events

composio listen creates a temporary subscription for consumer-project trigger events and writes each payload into the session artifact folder. Use it when an agent needs to consume new emails, Slack messages, or other events during a run.

composio listen GMAIL_NEW_GMAIL_MESSAGE
composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 5m
composio listen GMAIL_NEW_GMAIL_MESSAGE --max-events 5

Pass trigger creation params as JSON, JS-style object literals, @file, or stdin:

composio listen SLACK_RECEIVE_MESSAGE \
  -p '{ trigger_config: { channel: "C123" } }' \
  --max-events 10

composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream

Use --stream to also print each payload inline. You can pass a jq-like path to stream one field:

composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 1hr --stream '.data.threadId'

See where payload artifacts are stored:

composio artifacts cwd

Script workflows with run

Use composio run for multi-step workflows, loops, conditionals, parallel fan-out, or LLM-assisted summarization. It runs inline TS/JS or a file with injected helpers.

Injected helpers:

Helper	Description
`execute(slug, data?)`	Run a tool, like `composio execute`, and return parsed JSON
`search(query, opts?)`	Find tools, like `composio search`
`proxy(toolkit)`	Return a `fetch()` bound to a connected account for that toolkit
`experimental_subAgent(prompt, opts?)`	Ask a Claude/Codex sub-agent, optionally with structured output
`result.prompt()`	Serialize any helper result into an LLM-friendly string
`z`	Global Zod instance for structured output schemas

Examples:

# Inline workflow
composio run '
  const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");
  console.log(me);
'

# Sequential actions across services
composio run '
  const issue = await execute("GITHUB_CREATE_ISSUE", {
    owner: "acme",
    repo: "app",
    title: "Deploy v2"
  });
  await execute("SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL", {
    channel: "eng",
    text: "Created: " + issue.data.html_url
  });
'

# Run a file and pass script args after --
composio run --file ./workflow.ts -- --repo acme/app

Debug or preview scripts:

composio run --dry-run 'await execute("GMAIL_SEND_EMAIL", { recipient_email: "a@b.com" })'
composio run --debug --file ./workflow.ts
composio run --logs-off '/* hide experimental_subAgent streaming logs */'

Use top-level composio execute -p instead when you only need a few independent tool calls and no script logic.

Call raw APIs with proxy

Use composio proxy when you already know the API endpoint and want Composio to inject auth from a connected account. Pass the full API URL and the toolkit slug.

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":"..."}}'

-d accepts raw text, JSON, @file, or - for stdin. Use --skip-connection-check only when you need to bypass the connected-account preflight.

You can also use proxy() inside composio run:

composio run '
  const gmail = await proxy("gmail");
  const profile = await gmail("https://gmail.googleapis.com/gmail/v1/users/me/profile");
  console.log(profile);
'

Generate type definitions

Generate TypeScript or Python type stubs for selected toolkits, tools, and triggers. The current CLI requires at least one --toolkits value.

# Auto-detect TypeScript or Python from the project
composio generate --toolkits github gmail

# TypeScript
composio generate ts --toolkits github gmail
composio generate ts --toolkits github --output-dir ./src/composio-types
composio generate ts --toolkits github --compact
composio generate ts --toolkits github --transpiled
composio generate ts --toolkits github --type-tools

# Python
composio generate py --toolkits github gmail
composio generate py --toolkits github --output-dir ./composio_types

Type generation is most useful when you are using direct tool execution. If you use sessions with meta tools, you usually do not need generated stubs.

Local files, artifacts, and config

Show where the CLI stores local data:

composio files
composio artifacts cwd

Important locations:

Path	Purpose
`~/.composio/`	CLI auth, config, cached tool/toolkit definitions, trigger types, analytics ID, and per-org consumer caches
`$TMPDIR/composio/`	Session artifacts, large outputs, downloaded files, and run/execute history
`.composio/`	Optional per-project config such as `.env` and `project.json`

Useful path environment variables:

Variable	Description
`COMPOSIO_SESSION_DIR`	Override the session artifacts root
`COMPOSIO_CACHE_DIR`	Override the cache directory and artifact fallback location

View or toggle experimental CLI features:

composio config experimental
composio config experimental listen
composio config experimental multi_account on
composio config experimental multi_account off

Developer project commands

Use the dev namespace when you are building an app or agent with Composio's SDK and need developer-scoped project setup, playground execution, logs, toolkits, auth configs, connected accounts, triggers, and projects.

# Initialize this directory with a developer project
composio dev init

# Turn developer mode on or off
composio dev --mode on
composio dev --mode off

# Execute a tool against a developer playground user
composio dev playground-execute GMAIL_SEND_EMAIL \
  --user-id demo-user \
  -d '{ recipient_email: "a@b.com", subject: "Hello" }'

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

# Stream developer-project trigger events
composio dev listen --toolkits gmail --table
composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5
composio dev listen --toolkits github --forward https://example.com/webhook

Common dev groups:

Group	Examples
Project	`dev init`, `dev projects list`, `dev projects switch`
Execution	`dev playground-execute`, `dev listen`, `dev logs tools`, `dev logs triggers`
Toolkits	`dev toolkits list`, `dev toolkits info`, `dev toolkits search`, `dev toolkits version`
Auth configs	`dev auth-configs list`, `dev auth-configs info`, `dev auth-configs create`
Connected accounts	`dev connected-accounts link`, `list`, `info`, `whoami`
Triggers	`dev triggers list`, `info`, `status`, `create`, `enable`, `disable`

Disabling trigger instances is guarded. It requires developer.destructive_actions: true in ~/.composio/config.json and --dangerously-allow on the command line.

Agent skill installation

The CLI can install Composio skills into supported coding agents when auto-installation fails or you want to install manually.

composio --install-skill claude
composio --install-skill composio-cli codex
composio --install-skill composio-cli openclaw

composio login installs the composio-cli skill for Claude Code by default. Pass --no-skill-install to skip it.

Command summary

Command	Use it for
`composio search`	Find tool slugs by use case
`composio execute`	Run a known tool slug, inspect schemas, dry-run, or parallelize tool calls
`composio link`	Connect an account for a toolkit
`composio connections`	List or remove connected accounts
`composio tools`	List tools for a toolkit or inspect a known tool
`composio triggers`	List or inspect trigger types
`composio listen`	Create temporary consumer-project trigger subscriptions
`composio run`	Script multi-step workflows with injected helpers
`composio proxy`	Call raw toolkit APIs with Composio-managed auth
`composio signup` / `composio agent`	Bootstrap and manage an agent-owned Composio identity
`composio generate`	Generate TypeScript or Python stubs for selected toolkits
`composio dev`	Manage developer-project workflows
`composio artifacts` / `composio files`	Inspect local artifact and config/cache paths
`composio orgs` / `composio config`	Manage organization context and CLI config
`composio version` / `composio upgrade`	Check and update the CLI

Environment variables

Variable	Description
`COMPOSIO_API_KEY`	Composio project API key for API and SDK usage
`COMPOSIO_BASE_URL`	Custom Composio API base URL
`COMPOSIO_WEB_URL`	Custom Composio dashboard URL
`COMPOSIO_SESSION_DIR`	Override the CLI session artifact root
`COMPOSIO_CACHE_DIR`	Override the CLI cache directory
`COMPOSIO_LOG_LEVEL`	Default logging level
`COMPOSIO_DISABLE_TELEMETRY`	Set to `"true"` to disable telemetry
`COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}`	Override a toolkit version, for example `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`
`COMPOSIO_WEBHOOK_SECRET`	Signing secret for trigger webhook forwarding
`COMPOSIO_ORG_ID`	Per-project or environment organization override
`COMPOSIO_PROJECT_ID`	Per-project or environment project override
`FORCE_USE_CACHE`	Force cache-first reads for generated toolkit and tool metadata
`DEBUG_OVERRIDE_VERSION`	Override target CLI version during upgrade debugging

On this page