mirror of
https://github.com/ComposioHQ/composio.git
synced 2026-09-22 11:46:35 +08:00
Alberto Schiabel
973de6541d
# fix(cli): rework `composio install` PATH setup ## Why `composio install` hardcoded `~/.composio` as the directory it added to `PATH`, and it wrote the block to `~/.bashrc` only. Two consequences: an installer that puts the entry point somewhere else (a `~/.local/bin` shim, a version manager's `bin`) had no way to say so, and a login-only bash shell — `ssh`, `Terminal.app` — never saw the PATH line at all whenever a `.bash_profile` or `.bash_login` existed to shadow `.profile`. This PR makes the target directory a resolved value rather than a constant, writes to every startup file bash actually reads, and turns the command into something an installer can call and trust: it either configures `PATH` or exits non-zero so the caller's own fallback runs. ## What changed **Bin-dir resolution.** The `PATH` entry now resolves through `COMPOSIO_BIN_DIR` → `~/.local/bin` when its `composio` entry point resolves (through symlinks) to the running executable → the running binary's own directory. A leftover `composio` from another installer no longer wins the `~/.local/bin` step, so shells are never pointed at a foreign program. **`COMPOSIO_BIN_DIR` is public.** It is the user-facing override for the `PATH` target and the CLI-side contract the mise-style installer will use, so it is documented in the CLI README with its full resolution order and named in the `install` command description — `composio install --help` mentions it. Deliberately no `--bin-dir` flag: the env var is the right shape for an installer handoff. **`--shell <zsh|bash|fish>`.** Overrides `$SHELL` detection, for callers that know which shell they are configuring. **Bash login files.** The block also lands in `~/.bash_profile` or `~/.bash_login` when either exists. `.profile` is deliberately not a candidate: when neither override exists, bash reads `.profile` itself, and common `.profile` files already source `.bashrc`. The restart hint now prints `source ~/.bashrc` instead of the literal string `exec $SHELL`, and mentions the login file when one was written. **rc file handling.** Writes go through the file's real target, so a symlinked `.zshrc` keeps its link; the atomic tmp copy is created with the target's mode from the start, so a private rc's contents never sit in a world-readable temp file. Two logical paths that alias one physical file get the block once. **Managed blocks are reconciled, not just detected.** The marker alone no longer means "configured": a file is skipped only when it already contains the exact rendered `PATH` line for the resolved bin dir. Otherwise the existing managed block is spliced in place — which is what migrates the legacy three-line block (`export COMPOSIO_INSTALL_DIR=...` plus a `PATH` line derived from it), written by an older CLI or by `install.sh`'s fallback, to the current single-line form. A completions block elsewhere in the file is untouched, and re-running stays idempotent. **No reachability skip.** The command used to skip the write entirely when the bin dir was already on the invoking process's `$PATH`. That is not evidence about future shells — under an ad-hoc `export` or a mise/direnv shim it exited 0 having persisted nothing. A redundant-but-correct `PATH` line is harmless and the content check already prevents duplicates. The separate early return for "no shell detected *and* already on `$PATH`" stays (there is no rc file to write in that case) with wording that says the conclusion came from the current process. **Abort contract.** `composio install` aborts, writing nothing and exiting non-zero, on two conditions: the resolved bin dir is not absolute, or it contains a character that cannot be embedded safely in a quoted rc line. The non-zero exit is load-bearing — `install.sh` only runs its inline PATH fallback when the CLI fails, so an aborting run still leaves the user with a working `PATH` instead of a green install and `command not found`. **Narrow unsafe-character set.** The bin dir is only ever emitted inside double quotes (`export PATH="<dir>:$PATH"`, `set --export PATH "<dir>" $PATH`), where bash and zsh expand only `` ` ``, `$`, `\`, `"` and fish a subset of those. `;`, `|`, `&`, `(`, `)`, `'` are literal there, so they no longer abort — `/Users/o'brien/.composio` is a legitimate path. Newline/carriage return and `:` remain rejected as structural: one splits the block into extra lines, the other is the PATH separator. **`install.sh` injection fix.** Because an abort now hands PATH setup to `install.sh`'s inline fallback, that writer's escaping matters. It interpolated `COMPOSIO_INSTALL_DIR` raw into the fish and zsh rc lines and escaped only `"` in the bash arm — so a directory the CLI rejects was written unescaped into `~/.zshrc` or `config.fish`, where `$(...)` or a backtick becomes live command substitution at the next shell start. All three arms now escape backslash, backtick, `$`, and `"` before embedding, skipping the backtick for fish (which neither substitutes it nor recognizes `` \` `` inside double quotes). The `$HOME` prefix is re-applied after escaping, so the intended variable reference survives while a user-supplied `$` does not. **CI guard.** `cli.test-installation.yml`'s shell-config check accepted the legacy `install.sh` block on every leg, justified by a comment claiming no leg installs a binary built from this checkout. That was false: `build-cli-binaries.yml` calls the workflow with the tag it just released, so a completely broken `composio install` silently falling through to `install.sh`'s writer still reported success. Callers now declare `built_from_this_checkout`, and those legs must show the CLI-managed line. `promote-stable` keeps the permissive check because it rebuilds the promoted beta's own commit, which can predate the writer. ## Known behavior, documented rather than coded around The rc block no longer records `export COMPOSIO_INSTALL_DIR=`. A user who installed to a custom directory and later re-runs `curl ... | bash` without re-specifying the variable gets a second install under `~/.composio` while their rc `PATH` still resolves the old binary. Reachability is narrow — existing users are unaffected and `composio upgrade`, the documented path, replaces `process.execPath` in place and never consults this. The obvious fix (`command -v composio` + `readlink -f` inside `install.sh`) can misfire on a foreign `composio`, so this is a CHANGELOG note telling custom-dir users to re-specify `COMPOSIO_INSTALL_DIR` or use `composio upgrade`. ## Testing - `ts/packages/cli/test/src/commands/install.cmd.test.ts` — 47 cases covering per-shell rendering (full rendered lines, including fish), bash login-file selection, symlink and mode preservation, legacy-block migration, idempotency, bin-dir resolution order, and both abort conditions. - `test/install-sh-release-resolution.test.sh` — adds a case asserting that an install directory containing `$(...)` lands in `.bashrc` as literal text and does not execute when the file is sourced. Verified locally: `vitest run` for the CLI package (113 files, 1103 passed / 1 skipped), `pnpm run typecheck`, `pnpm run validate:boundaries`, `pnpm run lint`, `bash -n install.sh`, and `bash test/install-sh-release-resolution.test.sh`. ## Notes for reviewers - `@composio/cli` is in `.changeset/config.json`'s ignore list, so this edits `ts/packages/cli/CHANGELOG.md` directly instead of adding a changeset. - No new lint-boundary disables; the two previously registered for this file (`process.env.SHELL`, `process.env.COMPOSIO_INSTALL_DIR`) are gone, since both reads now go through `effect/Config`. - `install.sh` is rewritten wholesale by the follow-up installer PR, so the change here is the minimum that closes the injection. - Follow-up #4042 ships a fuller managed-block reconciler with fixtures; the migration here is its core behavior landed early, without the fixture harness.
composio.dev • Documentation • Quickstart • Changelog
Composio
Composio gives your AI agents 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox, so you can ship agents that turn intent into action.
This is the Composio SDK monorepo. It contains:
@composio/core: TypeScript SDKcomposio: Python SDKcomposioCLI: search, execute, and script tools from your shell- Provider adapters for OpenAI Agents, Claude Agent SDK, Vercel AI SDK, LangChain, and more
Quickstart
Create a session for a user, hand its tools to your agent, and let the agent take action across 1000+ apps. Grab a COMPOSIO_API_KEY from the dashboard first.
TypeScript
npm install @composio/core @composio/openai-agents @openai/agents
@composio/coreintentionally packages its TypeScript source and SDK docs so the installed package is inspectable to coding agents. If you want a smaller install with the same API, use@composio/slim.
import { Composio } from "@composio/core";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { Agent, run } from "@openai/agents";
const composio = new Composio({ provider: new OpenAIAgentsProvider() });
// Each session is scoped to one of your users
const session = await composio.create("user_123");
const tools = await session.tools();
const agent = new Agent({
name: "Personal Assistant",
instructions: "You are a helpful assistant. Use Composio tools to take action.",
tools,
});
const result = await run(agent, "Summarize my emails from today");
console.log(result.finalOutput);
Python
pip install composio composio-openai-agents openai-agents
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner
composio = Composio(provider=OpenAIAgentsProvider())
# Each session is scoped to one of your users
session = composio.create(user_id="user_123")
tools = session.tools()
agent = Agent(
name="Personal Assistant",
instructions="You are a helpful assistant. Use Composio tools to take action.",
tools=tools,
)
result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")
print(result.final_output)
By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store session.session_id and reuse it with composio.use() across turns. See what a session is and configuring sessions for restricting toolkits, auth configs, and connected accounts.
Prefer MCP? Every session also exposes a hosted MCP endpoint. Pass mcp: true to composio.create() and point Claude, Cursor, or any MCP client at session.mcp.url. See sessions via MCP.
CLI
The composio CLI runs Composio from your shell and gives coding agents like Claude Code a local tool surface.
curl -fsSL https://composio.dev/install | bash
composio login
Use composio search to find tools, composio execute to run them, composio link to connect accounts, and composio run to script workflows in TypeScript. See the CLI docs.
Providers
A provider adapts Composio tools to your agent framework's native tool format:
| Provider | TypeScript | Python |
|---|---|---|
| OpenAI | @composio/openai |
composio-openai |
| OpenAI Agents | @composio/openai-agents |
composio-openai-agents |
| Anthropic | @composio/anthropic |
composio-anthropic |
| Claude Agent SDK | @composio/claude-agent-sdk |
composio-claude-agent-sdk |
| Vercel AI SDK | @composio/vercel |
— |
| Google GenAI | @composio/google |
composio-gemini, composio-google |
| Google ADK | — | composio-google-adk |
| LangChain | @composio/langchain |
composio-langchain |
| LangGraph | via @composio/langchain |
composio-langgraph |
| LlamaIndex | @composio/llamaindex |
composio-llamaindex |
| Mastra | @composio/mastra |
— |
| Pi | @composio/experimental* |
— |
| Cloudflare Workers AI | @composio/cloudflare |
— |
| CrewAI | — | composio-crewai |
| AutoGen | — | composio-autogen |
* The Pi provider is experimental and ships from @composio/experimental.
Don't see your framework? Build a custom provider, or skip providers entirely and connect over MCP.
All packages
Everything published from this repo:
| Package | Description |
|---|---|
@composio/core |
TypeScript SDK |
@composio/slim |
@composio/core without packaged source or docs; same API, smaller install |
composio CLI |
Standalone CLI binary: curl -fsSL https://composio.dev/install | bash |
@composio/experimental |
Experimental integrations, including the Pi provider |
@composio/json-schema-to-zod |
JSON Schema to Zod conversion |
@composio/* provider adapters |
OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel, Google, LangChain, LlamaIndex, Mastra, Cloudflare |
composio |
Python SDK |
composio-* provider adapters |
OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Gemini, Google, Google ADK, LangChain, LangGraph, LlamaIndex, CrewAI, AutoGen |
Repository layout
ts/ TypeScript SDK workspace
packages/core/ @composio/core
packages/providers/ Provider adapters
packages/cli/ Composio CLI
python/ Python SDK and provider packages
docs/ Documentation site (docs.composio.dev)
The TypeScript SDK is tested against Node 22+; the Python SDK supports Python 3.10+.
Development
mise install # pinned toolchain (Node, Python, pnpm)
pnpm install
pnpm build
pnpm test
Python commands run from python/; see python/README.md. We welcome contributions to both SDKs; read the contribution guidelines before submitting pull requests.
Support
License
MIT. See LICENSE.