Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(cli): route consumer `composio execute` through the Dashboard (#4754)
> [!NOTE] > The Dashboard endpoints (`POST /api/cli/trpc/execute`, `POST /api/cli/trpc/executeMeta`) are live in production since ComposioHQ/dashboard#1769 merged on 2026-10-16. A merge to `next` publishes a rolling CLI beta that uses them for every consumer `composio execute`. This PR: - is the CLI side of the change. The backend side merged on 2026-10-15 (ComposioHQ/platform#13603, #13849, #13855, private repos) and the Dashboard side on 2026-10-16 (ComposioHQ/dashboard#1769) - includes the refactor from #4849 unchanged (the session-context split and the named executor stages); #4849 was closed in favor of this PR - picks the transport from the command surface: root `execute` (the consumer surface, which `composio run` also spawns) goes to the Dashboard, `composio dev playground-execute` stays on the backend - sends the execution step of consumer `composio execute` (single, `--parallel`, meta slugs) to the Composio Dashboard through a new `DashboardToolExecution` service; the CLI creates no Tool Router session on this path, the Dashboard creates and owns it - sends the connected account the CLI resolved with each `execute` call, since the session can no longer be pinned from the CLI - keeps connection lookups, the permission gate and file uploads on the backend client, and keeps `composio dev playground-execute`, developer projects and every other command on the backend - keeps the backend transport when `COMPOSIO_BASE_URL` is overridden and `COMPOSIO_WEB_URL` is not, so a key for one deployment is never sent to another deployment's Dashboard; `composio run` stops forwarding a web URL to its child CLI in that case - fails a relayed backend failure with the same `@composio/client/effect` status error the backend transport fails with (`@composio/client/PermissionDeniedError`, …), so error mapping, connection tips, `--json` output and telemetry take the existing path - sends each execution once: no retry, `redirect: 'error'`, one 15-minute deadline, no fallback to the backend, and fiber interruption aborts the request - names the Dashboard in `ts/packages/cli/AGENTS.md` as the one first-party host called without `@composio/client`, and adds two notes to the CLI changelog (no changeset: `@composio/cli` is ignored by Changesets) Ticket: PLEN-4353. ## Context ComposioHQ/platform#13603 first refused Instant (Composio-managed credential) executions on consumer projects unless they came through the Dashboard (error `6606`). ComposioHQ/platform#13988, deployed on 2026-10-17, removed that check: any caller with a user API key, including released CLIs, runs Instant tools again, metered and wallet-checked as before. So this PR is not needed to unblock Instant tools; it moves consumer execution onto the Dashboard, which owns the consumer session, its tool policy and the Instant charge. Once this CLI is released and the Dashboard path has proven itself, Apollo can redirect the older CLIs' direct calls. #4774, written to record a 0.4.3 entry, was closed: 0.4.3 shipped without this change, and its changelog entries sit under `## Unreleased` here. ## User-visible behavior None for standard tools: the same output, exit codes, error details, connection tips and `--json` shapes. No new login or configuration. These differences exist by design: - a Dashboard-level failure (unreachable, non-JSON reply, rejected credentials, backend outage) prints the Dashboard's message and has no "Error details" note; rejected credentials suggest `composio login` - there is no fallback to the backend when the Dashboard is unreachable - a `COMPOSIO_WEB_URL` that is not `https://` (or `http://` on localhost), or that carries credentials, a query string or a fragment, makes `composio execute` fail before anything is sent - a request with no complete answer after 15 minutes fails with a message that the tool may still have run - the session is the Dashboard's, not the CLI's: the CLI's auth-config choices and the enhanced link URL are no longer applied on this path, and the account selection travels with each call instead of being pinned on the session ## Contract the CLI speaks Request, for `execute` and `executeMeta` under `<COMPOSIO_WEB_URL>/api/cli/trpc/`: ``` POST /api/cli/trpc/execute Authorization: Bearer <user API key> x-org-id: <org id> content-type: application/json { "json": { "tool_slug": string, "arguments": object, "account"?: string } } ``` `executeMeta` takes `"slug"` in place of `"tool_slug"` and has no `account`. The CLI sends no session settings and no user id. `account` is the connected account the CLI resolved for the tool's toolkit: the `--account` selection (alias, word id or id), else the account aliased `default`, else the newest. It is sent only when there is one. Response 200: ``` { "result": { "data": { "json": { "ok": true, "response": { "result_type": "completed" | "failed" | "input_required", ... } } | { "ok": false, "status": number, "error": { "message": string, "code"?: number, "slug"?: string, "status"?: number, "request_id"?: string, "suggested_fix"?: string } } } } } ``` `response` is the backend's execute answer, relayed as is (`data`, `error`, `log_id`, and `instant_charge` when the Dashboard's session asked for it). The CLI checks only `result_type`, the same as the backend transport: the tool has already run, so a missing field does not turn its result into an error. Dashboard-level failures use the tRPC error envelope `{ "error": { "json": { "message": string, "data": { "code": string, "httpStatus": number } } } }`. The envelopes are decoded with `effect/Schema`. The Instant charge line (#4857) appears on this path because the Dashboard creates its sessions with `instant: { return_instant_charge: true }` (dashboard#1769); the production run below shows it. ## Security hardening - **Clear-text key.** The Dashboard base URL is validated before the user API key is attached: `https:` is required, and `http:` is accepted only for `localhost`, `127.0.0.1` and `[::1]`. A violation fails with a fixed message and sends nothing. - **Secrets in the URL.** A URL with userinfo, a query string or a fragment is rejected by the same check. The message never echoes the configured value, and the remaining transport, response and timeout messages name only the origin. - **Deadline.** One 15-minute timeout (`DASHBOARD_REQUEST_TIMEOUT`) covers the POST and the body read. Expiry aborts the request, does not resend it, and tells the user the tool may still have run and to check before running it again. - **Stored URLs.** `base_url` and `web_url` in `~/.composio/user_data.json` never take effect: the backend client, the Dashboard request and the transport choice all read the environment (or the defaults), so they cannot disagree. Four command-level tests pin this; no production change was needed. ## Analytics While telemetry is enabled, the two Dashboard execution requests also carry `x-cli-install-id: <install_id>`: the random UUID already stored in `~/.composio/analytics.json`, sent verbatim, so Dashboard-side product analytics can be joined with the CLI's own events. The header is gated by the same predicate as the CLI's own events, so it is omitted under `COMPOSIO_CLI_TELEMETRY_DISABLED`, `TELEMETRY_DISABLED`, `COMPOSIO_DISABLE_TELEMETRY`, `CI`, or `NODE_ENV=test`. It is also omitted when no install ID is stored or the state file is unreadable; the read never creates an ID and never fails or delays an execution. It is not sent to the backend API and is not part of `cliRequestHeaders()`. ## How Has This Been Tested? ### Automated On the current head (`def340f14`, rebased onto `next` on 2026-10-19, `@composio/client` rc.19), Node 24.17.0, re-run on 2026-10-20: - `pnpm test` in `ts/packages/cli`: 162 files, 1966 passed, 1 skipped; `validate:command-tests` reports 15 exemptions (unchanged) - `pnpm typecheck` from the repo root: 14/14 tasks - `pnpm --filter @composio/cli run lint:effect`: 0 diagnostics; oxlint and prettier clean on the touched files Rebasing onto `next` rebuilt the transport on the Effect client: the old promise client's `APIError.generate` and `maxRetries: 0` are gone (the Effect client sends an execution once unless the call passes `idempotent`), and the tests' `for` loops became `describe.each`, per the oxlint ban from #4897. #4849's ordering test now runs on both transports: the backend creates the session before the permission gate, and a denied tool reaches neither the backend nor the Dashboard. New tests: - `test/src/services/dashboard-tool-execution.test.ts` (38): URL, headers and body for both procedures; trailing-slash normalization; the client's status error from an `ok: false` reply; tRPC `UNAUTHORIZED` and other Dashboard errors; network failure and non-JSON reply name the Dashboard and send one request; `redirect: 'error'` reaches `fetch`; interruption aborts the in-flight request; the transport choice for each URL-override combination; rejected URLs (remote `http`, userinfo, query, fragment, other scheme, unparseable) send nothing and keep the value out of the message; loopback `http` is allowed; the deadline fires under the test clock with one request, aborted; the install ID header is present on both procedures with telemetry on, absent for each opt-out, absent with no stored ID (and none is created), and an unreadable analytics state does not break execution - `test/src/commands/tools/tools.execute.transport.test.ts` (26), through the real command and executor: one POST and no backend session for a standard tool, with printed lines equal to the backend transport's; meta slug; three parallel tools with one failing; `dev playground-execute` on the backend; project resolution and file upload before the Dashboard call; a denied permission gate sends nothing; a relayed 402 prints the same lines as the backend transport; the `composio link` tip for code 4302; `composio login` hint; no resend and no backend fallback on transport failure; both URL-override cases; stored URLs cannot split the transport; an unsafe web URL sends nothing and the secret appears in neither the printed lines nor the JSON summary; a timeout is reported once with no backend call - `test/src/commands/run.cmd.test.ts`: the web URL is forwarded to run helpers only when this process uses the Dashboard transport `test/__utils__/layers/dashboard.ts` adds a test Dashboard (`DashboardToolExecutionTest`, wired into `TestLive`) that runs the real service over a stub `HttpClient`, rejects any `session` key, forwards `account` to the mock Tool Router's execute call, and relays its answers, so the existing execute tests exercise the new request and reply decoding. The account-selection tests in `tools.execute.cmd.test.ts` now assert the `account` sent with the call. Earlier local runs, before the rebase onto `next`: - On an earlier commit of this branch, Node 24.17.0, all passing: `pnpm typecheck` from the repo root (14/14 tasks); `pnpm test` in `ts/packages/cli` (`validate:skills`, `validate:boundaries`, `vitest run`) with 134 files, 1513 passed, 1 skipped and `lint boundaries OK: 4 registered disables` (no new `eslint-disable`); `oxlint ts/packages/cli` with no errors. - On `e15273a3a`, Node 22.23.2 (so with an engine warning): `tsc --noEmit` clean, and `pnpm test` in `ts/packages/cli` with 134 files, 1513 passed, 1 skipped, 1 failed. The failure is `analytics.dispatch.test.ts > uses one install_id across concurrent first-run events`, which passes when run alone (4 of 4 runs, with and without this change) and failed only inside the full run. ### Production run, 2026-10-20 CLI from this branch at `def340f14` (run from source with Bun, no URL overrides), against the production Dashboard (dashboard#1769) and production Apollo, which runs platform#13988. Existing login, consumer project of the `composio_team` org. A fetch trace confirmed the execution is a single `POST https://dashboard.composio.dev/api/cli/trpc/execute`, after the backend calls for project resolve, connected accounts, the tool version and consumer config, and with no Tool Router session created by the CLI. | Case | Result | |---|---| | `COMPOSIO_SEARCH_TOOLS` (meta, `executeMeta`) | `successful: true` (5 s) | | `TELEGRAM_GET_ME --account first`, then `second` | `successful: true`, a different bot each time | | `TELEGRAM_GET_ME --account nope` | "No connected account matched", both accounts listed, exit 1, no request | | `GITHUB_GET_THE_AUTHENTICATED_USER` | `successful: true` | | `EXA_SEARCH` (Instant) | `successful: true` with `instantCharge: { amount: "0.007000", currency: "USD", chargedBy: "composio" }` | | `--parallel TELEGRAM_GET_ME EXA_SEARCH` | both `successful: true`, the charge on the Exa result | `--account` ownership, sent straight to the production Dashboard route (the CLI itself refuses an id it did not list), `SLACK_FETCH_TEAM_INFO` in `composio_team`: | `account` | Result | |---|---| | the caller's own Slack account in this org | `ok: true`, the team info | | the same user's Slack account in another org (`alberto_workspace`) | `ok: false`, 400 `ToolRouterV2_BadRequest` (4300) "No account found matching …" | | a made-up `ca_*` id | the same 400, so the reply does not reveal whether the id exists | Not run: another member's account in the same org, and `composio run` (needs the compiled binary). ### Live run, 2026-10-16 This run predates ComposioHQ/platform#13988: the two `ManagedCredential_DashboardOriginRequired` rows no longer apply, since that check is gone. CLI built from this branch at `7cfb86de8` (run from source with Bun), against the dashboard#1769 preview at `dda5f1bdf` (`dashboard-git-feat-cli-execute-via-dashboard.preview.composio.dev`) and staging Apollo, which runs platform#13603, #13849 and #13855. Fresh browser-approved login, consumer project of org `ok_ZZCb3s6ETg_7`. "0.4.5" is the released binary, calling Apollo directly with the same key. | Case | Result | |---|---| | `COMPOSIO_SEARCH_TOOLS` (meta, `executeMeta`) | `successful: true` (20 s on the idle preview) | | `GMAIL_FETCH_EMAILS`, no connection | `ToolRouterV2_NoActiveConnection` with the `composio link gmail` tip | | `TELEGRAM_GET_ME --account first`, then `second` | `successful: true`, a different bot each time | | `TELEGRAM_GET_ME --account nope` | "No connected account matched", both accounts listed, exit 1, no request | | `EXA_SEARCH`, Instant off | `ToolRouterV2_NoActiveConnection` (same on 0.4.5) | | `EXA_SEARCH`, Instant on | `successful: true` with `instantCharge: { amount: "0.007000", currency: "USD", chargedBy: "composio" }` | | `--parallel EXA_SEARCH TELEGRAM_GET_ME`, Instant on | both `successful: true`, the charge on the Exa result | | Same build, only `COMPOSIO_BASE_URL` overridden (backend transport), `EXA_SEARCH`, Instant on | `ManagedCredential_DashboardOriginRequired`, the upgrade message | | 0.4.5 `TELEGRAM_GET_ME` | `successful: true` | | 0.4.5 `EXA_SEARCH`, Instant on | `ManagedCredential_DashboardOriginRequired`, the upgrade message | Instant was switched on for the Instant rows and off again afterwards. Not run: `composio run` (needs the compiled binary), Apollo 5xx and timeouts, production. ### Earlier live runs These predate the rebase onto `next` and platform#13988, so every refusal below is the since-removed origin check. Run by the author on 2026-10-07 with a build of this branch, against deployed previews of the Dashboard and backend PRs on staging data, after a fresh browser-approved login: - **Success.** A no-auth tool and a tool on Composio-managed credentials (`EXA_SEARCH`) succeeded. - **Backend errors.** A missing tool, a missing connection and a tool disabled for the session each printed the backend's message. - **`--account`.** With two connected Telegram accounts aliased `first` and `second`: `--account first` and `--account second`, the word id and the `ca_` id each reached the matching account. No `--account` picked the newest. An unknown selector failed in the CLI with "No connected account matched", exit code 1, before any request. - **Backend transport.** With `COMPOSIO_BASE_URL` set to the preview backend and `COMPOSIO_WEB_URL` unset, the CLI called the backend directly and was refused on the managed-credential tool with the upgrade message. - **Released CLIs.** 0.4.2, 0.2.32 and 0.2.31 were refused on the managed-credential tool and still worked on a standard tool. Repeated on 2026-10-08 with a build of the current head (`4ddc26698`), against fresh previews of the Dashboard and backend PRs: every case above gave the same result. Two additions: - **Blocked tool.** A tool on the Dashboard's blocked list printed the Dashboard's marketplace-policy message naming the CLI. - **Managed credentials switched off.** With Composio-managed credentials turned off for the project, the backend now answers a managed-credential tool with an error of its own, saying they are turned off and how to proceed. This branch and released 0.4.2 both printed it in full, because it does not arrive as a missing-connection error, which the CLI would replace with its `composio link` tip. A tool with no managed credential still got that tip. Earlier, on 2026-10-06 and 2026-10-07, the success and backend-error cases were also run against a locally running Dashboard branch and a preview backend on staging data. These runs did not cover production (see the production run above) or `composio run` from this branch (the source build cannot run it; only the compiled binary can). ## Known limits - A reply whose envelope deviates from the contract above, or whose `response` has no valid `result_type`, is reported as an unexpected response. - A failed execution (`"successful": false`, including the backend's refusal) exits 0 on this branch, as on released CLIs. Tracked in #4768, out of scope here. No VHS recording: the command surface and its output are unchanged.