Composio CLI

Composio CLI

Preflight: Is The User Logged In?

Before running any toolkit command, confirm the user is logged in. If they are not, stop and tell them to log in — do not improvise.

composio whoami   # exits non-zero when there is no session

If whoami fails (no Composio session), the user is logged out. Stop here. Do not:

• run composio login yourself,
• look for an alternate toolkit, slug, or proxy route,
• ask the user to paste a key, or
• attempt any other workaround.

Respond directly to the user with one message: they need to log in to Composio first, via the "Log in with Composio" action on the Composio app's dashboard. Then end your turn and wait — the request cannot proceed until they have logged in.

Only once whoami succeeds do you continue to the workflow below.

Connection Invariant: One Account Per Toolkit

Rome operates exactly one connected account per toolkit. This is load-bearing because execute, proxy, and run have no flag to choose an account — they act on the toolkit's single connected account, and when more than one exists Composio silently resolves a non-deterministic default. You cannot tell, and cannot control, which account a tool ran as. A second Gmail means a "send email" might go out from the wrong account with no signal.

To keep every tool call deterministic:

• Never create a second account for a toolkit. Do not pass --alias to composio link to add an additional account, and do not enable the multi_account experimental feature. The alias buys you nothing on execution — there is no --alias/--account on execute — it only lets you accumulate ambiguous accounts.
• Check before linking. composio link <toolkit> --list shows existing accounts. If one is ACTIVE, you are connected — retry execute, do not link again.
• If --list shows more than one account for a toolkit, stop and surface it. Tell the user the toolkit has duplicate accounts and tool calls are ambiguous until the extras are removed. Do not guess which one to use.

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.

There is no flag to pick an account — execute uses the toolkit's single connected account (see "Connection Invariant" above). Keep one account per toolkit so this is unambiguous.

• --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 gmail --list          # inspect existing accounts before linking
composio link googlecalendar --no-browser

Key flags:

• --list: List the toolkit's existing connected accounts instead of linking. Run this first — if an account is already ACTIVE, retry execute rather than linking.

• --alias: Names an additional account for a toolkit (requires the multi_account experimental feature). Avoid it — Rome keeps one account per toolkit, and extra accounts make execute ambiguous (see "Connection Invariant").

• Retry the original execute command after linking succeeds.