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

Install the CLI with one command:

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

The installer downloads and verifies the release bundle in ~/.composio, creates the ~/.local/bin/composio entry point, and configures your shell so future terminals find composio on PATH. It recognizes zsh, bash, and fish login shells from $SHELL and writes a managed # Composio CLI block to their startup files. bash also gets a login-mode startup file — the first existing of ~/.bash_profile or ~/.bash_login, or a newly created ~/.bash_profile — because a login bash, which macOS Terminal.app starts, never reads ~/.bashrc. If your shell is not recognized, or shell setup fails, the CLI still installs and the installer prints a runnable command instead. It does not install agent plugins or log you in unless you ask it to. To skip shell configuration entirely, see Shell setup overrides.

Open a new terminal, then log in:

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

Install with options

Pin a version and opt in to agent plugin setup:

curl -fsSL https://composio.dev/install \
  | COMPOSIO_INSTALL_VERSION=0.3.1 COMPOSIO_INSTALL_PLUGINS=1 sh

You can also pass a stable or beta release tag as the positional argument. The positional value takes precedence over COMPOSIO_INSTALL_VERSION:

curl -fsSL https://composio.dev/install | sh -s -- @composio/cli@0.3.1

Shell setup overrides

By default the installer infers your login shell from $SHELL and configures it. Set COMPOSIO_INSTALL_SHELL to force a specific shell instead:

curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh

Set COMPOSIO_INSTALL_SHELL=none for an install-only run that changes no shell files. Use it in CI, Docker images, or when a dotfile manager owns your startup files:

curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=none sh

Shell-specific installer variants (zsh.sh, bash.sh, and fish.sh in the repository's install/ directory) pin COMPOSIO_INSTALL_SHELL to their shell before delegating to the base installer.

Shell setup is idempotent: repeated installs keep exactly one managed PATH block per startup file and reconcile it when the bin directory changes. Setup falls back to writing the same PATH block inline when the installed CLI predates composio install --shell, delegated setup fails, or delegated setup leaves a stale block. Startup-file changes only affect future terminals; in the current one, either open a new terminal or run the absolute path the installer prints.

Verify the installation

composio --version
which composio

The installer supports Linux x64, Linux ARM64, macOS Intel, and macOS Apple Silicon. On Windows, install and run it inside WSL.

Update

composio upgrade

This replaces the bundle in ~/.composio in place and leaves the ~/.local/bin/composio entry point pointing at it. Pass a version to pin a specific release (composio upgrade 0.3.1), or --beta for the latest prerelease.

Install manually from GitHub Releases

Download the archive for your platform from GitHub Releases, then install the complete bundle. Keep the support files beside the executable.

bundle=composio-linux-x64
COMPOSIO_INSTALL_DIR=${COMPOSIO_INSTALL_DIR:-"$HOME/.composio"}
COMPOSIO_BIN_DIR=${COMPOSIO_BIN_DIR:-"$HOME/.local/bin"}

unzip "$bundle.zip"
mkdir -p "$COMPOSIO_INSTALL_DIR"
cp -Rp "$bundle"/. "$COMPOSIO_INSTALL_DIR/"
chmod +x "$COMPOSIO_INSTALL_DIR/composio"
mkdir -p "$COMPOSIO_BIN_DIR"
if [ "$COMPOSIO_BIN_DIR" != "$COMPOSIO_INSTALL_DIR" ]; then
  ln -sf "$COMPOSIO_INSTALL_DIR/composio" "$COMPOSIO_BIN_DIR/composio"
fi
export PATH="$COMPOSIO_BIN_DIR:$PATH"

Uninstall

Remove only installer-owned entry points and release artifacts. This keeps your credentials, configuration, and cache data in ~/.composio. The file list below matches the current release layout; if you installed a different version, compare it against the contents of that release's archive.

install_dir=${COMPOSIO_INSTALL_DIR:-"$HOME/.composio"}
bin_dir=${COMPOSIO_BIN_DIR:-"$HOME/.local/bin"}

rm -f \
  "$bin_dir/composio" \
  "$install_dir/composio" \
  "$install_dir/release-tag.txt" \
  "$install_dir/run-helpers-runtime.mjs" \
  "$install_dir/run-subagent-shared.mjs" \
  "$install_dir/run-subagent-acp.mjs" \
  "$install_dir/run-subagent-legacy.mjs" \
  "$install_dir/run-subagent-output-mcp.mjs"
rm -rf \
  "$install_dir/services" \
  "$install_dir/acp-adapters" \
  "$install_dir/local-tools-binaries"

for file in \
  "$HOME/.zshrc" \
  "$HOME/.bashrc" \
  "$HOME/.bash_profile" \
  "$HOME/.bash_login" \
  "$HOME/.config/fish/config.fish"; do
  [ -f "$file" ] || continue
  tmp=$(mktemp) || continue
  if awk '
    $0 == "# Composio CLI" { in_block = 1; next }
    in_block && (/^export COMPOSIO_INSTALL_DIR=/ || /^set --export COMPOSIO_INSTALL_DIR /) { next }
    in_block && (/^export PATH=/ || /^set --export PATH /) { in_block = 0; next }
    { in_block = 0; print }
  ' "$file" > "$tmp"; then
    if [ "$file" = "$HOME/.bash_profile" ] && ! grep -q '[^[:space:]]' "$tmp"; then
      rm -f "$file"
    else
      cat "$tmp" > "$file"
    fi
  fi
  rm -f "$tmp"
done

The loop stages every rewrite in a mktemp scratch file — created with an unpredictable name and 0600 permissions, so startup-file contents never pass through a world-readable path — and writes the result back only when awk succeeds. A failed or missing awk leaves the startup file untouched, and the scratch file is always removed. Writing back with cat keeps a symlinked startup file intact: the symlink, its target's inode, owner, and mode all survive. The filter removes the current managed block and the three-line block written by older installers (marker plus export COMPOSIO_INSTALL_DIR=... or set --export COMPOSIO_INSTALL_DIR ...).

~/.bash_profile gets one extra step: when removing the block leaves only blank lines, the file is deleted. The installer creates ~/.bash_profile on bash systems that had no login startup file, and bash prefers even an empty ~/.bash_profile over ~/.profile, so leaving the empty file behind would silently override bash's normal startup-file selection forever. Note the edge case: a ~/.bash_profile you created yourself but left empty is also removed. If you had a ~/.profile when you installed, the created ~/.bash_profile instead keeps a passthrough that sources it, so the file is not blank and survives the loop with only the block removed. It begins with # Created by the Composio CLI installer.; delete it too if you want bash to read ~/.profile directly again.

rm -rf "${COMPOSIO_INSTALL_DIR:-$HOME/.composio}"

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:

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

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