rome-os / 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.

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.

Bundled Scripts

Reusable scripts ship in rome_apps/composio/scripts/ and are invoked via composio run -f.

gmail-parse-markdown.ts — Gmail → Markdown

GMAIL_FETCH_EMAILS returns each body as raw HTML — a single 50-message page is typically ~200k tokens, dominated by HTML markup and tracking URLs. This script fetches messages and converts each body to clean Markdown using @mozilla/readability (with a turndown fallback when readability mis-fires on transactional emails). Cuts a 50-message page to ~3-15k tokens depending on content.

Reach for it any time the user wants Gmail content fed to an LLM, summarized, or otherwise processed as text — not when they need raw HTML.

# One-time setup (deps live alongside the script, not in the workspace):
(cd rome_apps/composio/scripts && npm install)

# Default: drop tracking URLs, keep anchor text, strip images
composio run -f rome_apps/composio/scripts/gmail-parse-markdown.ts -- --max 20

# Keep links inline (use only when downstream needs the URLs)
composio run -f rome_apps/composio/scripts/gmail-parse-markdown.ts -- \
  --query "is:unread newer_than:1d" --max 50 --include-links

Flags:

• --query "<gmail-query>" — Gmail search query (e.g. "is:unread newer_than:1d")
• --max <N> — max_results (default 10, max 500)
• --page-token <token> — pagination cursor from a prior nextPageToken
• --include-links — keep inline links (default strips URLs but preserves anchor text; ~3x token savings)
• --raw — also return the original messageText alongside markdown (debugging only)

Output is JSON on stdout: { messages: [{ messageId, threadId, sender, subject, markdown, bodyFormat, ... }], nextPageToken, resultSizeEstimate, options }.

Auth

composio whoami   # check current session — run this first (see Preflight above)

When whoami fails the user is logged out. **Do not run composio login on
their behalf and do not work around the missing session.** Tell the user to log
in via the dashboard and stop — see "Preflight: Is The User Logged In?" above.

The Composio Rome app reads the key live from the CLI session
(~/.composio/user_data.json) — that session is the single source of truth; the
app stores no copy of its own. Its dashboard exposes Composio login as one
explicit browser action: "Log in with Composio" (or "Re-authorize" once logged
in) opens Composio in a new tab to authorize Rome, which writes the issued key
into the CLI session. The dashboard deliberately hides the CLI mechanics — the
guardian just sees the button.

Because the app reads the CLI session directly, a composio login **you (the
agent)** run in this terminal is picked up automatically — there is no separate
"import" step.