composio-cli

name: composio-cli description: Help users operate the published Composio CLI to find the right tool, connect accounts, inspect schemas, execute tools, subscribe to trigger events with composio listen, script workflows with composio run, and call authenticated app APIs with composio proxy. Use when the user asks how to do something with composio, wants to run a known tool slug, needs to discover a slug with composio search, fix a missing connection with composio link, inspect tool inputs with --get-schema or --dry-run, troubleshoot top-level CLI flows, or explicitly needs composio dev guidance.

Composio CLI

Default Workflow

1. Start with composio execute <slug> whenever the slug is known.
2. If several independent tool calls must happen at once, use composio execute -p/--parallel with repeated <slug> -d <json> groups.
3. If execute says the toolkit is not connected, run composio link <toolkit> and retry.
4. If the arguments are unclear, run composio execute <slug> --get-schema or --dry-run before guessing.
5. Reach for composio search "<task>" only when the slug is unknown. search accepts one or more queries, so batch related discovery work into a single command when useful.

execute - Run A Tool

Use execute when the tool slug is already known.

composio execute GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'

Inspect required inputs without executing:

composio execute GITHUB_CREATE_AN_ISSUE --get-schema

Preview safely:

composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'

Pass data from a file or stdin:

composio execute GITHUB_CREATE_AN_ISSUE -d @issue.json
cat issue.json | composio execute GITHUB_CREATE_AN_ISSUE -d -

Upload a local file:

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

Run independent tool calls in parallel:

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

Key flags:

• --get-schema: Inspect required arguments without executing the tool.

• --dry-run: Preview the request shape without performing the action.

• --file: Inject a local file path into a tool that exposes exactly one uploadable file argument.

• --parallel: Execute multiple independent tool calls in the same invocation.

• --account: Select which connected account to use by alias, word_id, or account id when multiple accounts exist for the same toolkit.

• --file only works when the tool exposes a single uploadable file input. Otherwise use explicit -d JSON.

search - Find The Slug

Use search only when the tool slug is not already known.

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

• Batch related discovery work into one search invocation, then move back to execute once the correct slugs are known.

link - Connect An Account

Use link when execute reports that a toolkit is not connected, or when the user explicitly wants to authorize an account.

composio link gmail
composio link googlecalendar --no-browser

Key flags:

• --alias: Assign an alias to the connected account. Required when creating an additional account for the same toolkit.

• Retry the original execute command after linking succeeds.

proxy - Raw API Access

Use proxy when a toolkit supports a raw API operation that is easier than finding a dedicated tool slug.

composio proxy https://api.github.com/user --toolkit github --method GET </dev/null

run - Scripting, LLMs, and Programmatic Workflows

For programmatic calls, loops, output plumbing, or anything beyond a single tool call, prefer composio run.

composio run executes an inline ESM JavaScript/TypeScript snippet with authenticated execute(), search(), proxy(), and the experimental experimental_subAgent() helper pre-injected. No SDK setup required.

Chain multiple tools:

composio run '
  const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");
  const emails = await execute("GMAIL_FETCH_EMAILS", { max_results: 1 });
  console.log({ login: me.data.login, fetchedEmails: !!emails.data });
'

Fan out with Promise.all:

composio run '
  const [me, emails] = await Promise.all([
    execute("GITHUB_GET_THE_AUTHENTICATED_USER"),
    execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
  ]);
  console.log({ login: me.data.login, emailCount: emails.data.messages?.length });
'

Feed tool output into an LLM and get structured JSON back:

composio run --logs-off '
  const emails = await execute("GMAIL_FETCH_EMAILS", { max_results: 5 });
  const brief = await experimental_subAgent(
    `Summarize these emails and count them.\n\n${emails.prompt()}`,
    { schema: z.object({ summary: z.string(), count: z.number() }) }
  );
  console.log(brief.structuredOutput);
'

• Use top-level execute --parallel instead when the user only needs a few independent tool calls and does not need script logic.

Auth

composio whoami   # check current session
composio login    # authenticate if whoami fails

Escalate Only When Needed

If the user is stuck on top-level commands or needs fallback inspection commands, load references/troubleshooting.md.

If the user explicitly asks about developer projects, auth configs, connected accounts, triggers, logs, orgs, or projects, load references/composio-dev.md. composio dev is not the default end-user path.