@devries-cameron20 / composio-1 / commits / 16b167c94
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs(cli): document COMPOSIO_BIN_DIR and the install abort contract

COMPOSIO_BIN_DIR was discoverable only by reading the changelog: it is read through a raw ConfigProvider and appeared in no help text. Add it to the README env-var table with its resolution order, and name it in the install command description so `composio install --help` mentions it. No --bin-dir flag: the env var is the right shape for an installer handoff. The changelog entry also picks up the behavior changes it was missing — the non-zero exit on abort and what it means for install.sh's fallback, both abort conditions, the narrowed character set, legacy-block migration, and a note for custom-install-dir users reinstalling without re-specifying COMPOSIO_INSTALL_DIR.

jkomyno committed Aug 4, 2026 at 19:17 UTC 16b167c94a8e24b7b0d21a773886b4b3b6c481f6
2 files changed +33 -10
ts/packages/cli/CHANGELOG.md
+6
@@ -5,6 +5,12 @@
5 ### Minor Changes
6
7 - `composio install` gains a `--shell <zsh|bash|fish>` flag that overrides `$SHELL` detection, in preparation for the mise-style installer rewrite. The bin-dir PATH target now resolves through `COMPOSIO_BIN_DIR`, an existing `~/.local/bin/composio`, or the real binary's own directory, in that order, instead of hardcoding `~/.composio`; rc blocks write only a PATH line (the `export COMPOSIO_INSTALL_DIR=...` line is gone, since that variable identifies the install bundle, not the PATH entry point). Bash now also writes the PATH line to `~/.bash_profile` or `~/.bash_login` when either already exists, so `bash -ilc` picks it up. The restart hint bug is fixed: bash now prints `source ~/.bashrc` instead of the literal string `exec $SHELL`.
8 +- `COMPOSIO_BIN_DIR` is a documented public override: set it to the absolute directory `composio install` should add to `PATH` when the entry point users reach is a shim or symlink rather than the binary itself. See the CLI README for the full resolution order.
9 +- `composio install` now exits non-zero, having written nothing, when it cannot produce a safe PATH line. There are two abort conditions: the resolved bin directory is not absolute, or it contains a character that cannot be embedded in a quoted rc line. A non-zero exit is what makes `install.sh` run its inline PATH fallback, so an aborted run still leaves the user with a working `PATH` — previously the command exited 0 and the fallback never ran.
10 +- The unsafe-character set is narrower than the one first shipped in this entry. The bin dir is only ever written inside double quotes, where `;`, `|`, `&`, `(`, `)`, and `'` are literal — only `` ` ``, `$`, `"`, `\`, newline, carriage return, and the `:` PATH separator abort now. Paths like `/Users/o'brien/.composio` are accepted instead of rejected.
11 +- An rc file that carries the older three-line Composio block (`export COMPOSIO_INSTALL_DIR=...` plus a PATH line derived from it), written by a previous CLI or by `install.sh`'s fallback, is migrated to the current single-line block in place instead of being treated as configured forever. Re-running the command is still idempotent, and a completions block elsewhere in the file is untouched.
12 +- `composio install` no longer skips the rc write when the bin directory happens to be on the invoking process's `$PATH`. That said nothing about future shells — an ad-hoc `export` or a version-manager shim made the command persist nothing and still report success.
13 +- Note for custom install directories: the rc block no longer records `COMPOSIO_INSTALL_DIR`. If you installed to a custom directory with `COMPOSIO_INSTALL_DIR=... curl ... | bash` and later re-run the install script without re-specifying it, the script installs a second copy under `~/.composio` while your rc `PATH` still points at the old one. Re-specify `COMPOSIO_INSTALL_DIR` when reinstalling, or use `composio upgrade`, which replaces the running binary in place.
14
15 ### Patch Changes
16
ts/packages/cli/README.md
+27 -10
@@ -55,16 +55,17 @@ Additionally, for storing and retrieving user session context, a `user_data.json
55
56 By default, this file is stored in `~/.composio`, but you can specify a custom location using the `COMPOSIO_CACHE_DIR` environment variable.
57
58 -| Environment Variable | User JSON config | Description | Default |
59 -| ---------------------- | ---------------- | ------------------------------------------------------------------ | ------------------------------- |
60 -| COMPOSIO_API_KEY | `api_key` | Composio backend API key | None |
61 -| COMPOSIO_BASE_URL | `base_url` | The base URL of the Composio backend API | https://backend.composio.dev |
62 -| COMPOSIO_WEB_URL | `web_url` | The base URL of the Composio web app | https://dashboard.composio.dev/ |
63 -| COMPOSIO_CACHE_DIR | - | The directory where the Composio CLI stores cache files | ~/.composio |
64 -| COMPOSIO_LOG_LEVEL | - | The log level for the Composio CLI | None |
65 -| DEBUG_OVERRIDE_VERSION | - | The version to use when upgrading the Composio CLI (for debugging) | None |
66 -| FORCE_USE_CACHE | - | Whether to force the use of previously cached HTTP responses | None |
67 -| NO_COLOR | - | If set, disables color output in the CLI (https://no-color.org/) | None |
58 +| Environment Variable | User JSON config | Description | Default |
59 +| ---------------------- | ---------------- | ------------------------------------------------------------------ | -------------------------------- |
60 +| COMPOSIO_API_KEY | `api_key` | Composio backend API key | None |
61 +| COMPOSIO_BASE_URL | `base_url` | The base URL of the Composio backend API | https://backend.composio.dev |
62 +| COMPOSIO_WEB_URL | `web_url` | The base URL of the Composio web app | https://dashboard.composio.dev/ |
63 +| COMPOSIO_CACHE_DIR | - | The directory where the Composio CLI stores cache files | ~/.composio |
64 +| COMPOSIO_BIN_DIR | - | The directory `composio install` adds to `PATH` (see below) | Resolved from the running binary |
65 +| COMPOSIO_LOG_LEVEL | - | The log level for the Composio CLI | None |
66 +| DEBUG_OVERRIDE_VERSION | - | The version to use when upgrading the Composio CLI (for debugging) | None |
67 +| FORCE_USE_CACHE | - | Whether to force the use of previously cached HTTP responses | None |
68 +| NO_COLOR | - | If set, disables color output in the CLI (https://no-color.org/) | None |
69
70 Additionally, `composio upgrade` supports the following environment variables:
71
@@ -76,6 +77,22 @@ Additionally, `composio upgrade` supports the following environment variables:
77 | COMPOSIO_GITHUB_TAG | The tag to use when fetching the Composio CLI binary from Github | latest |
78 | COMPOSIO_GITHUB_ACCESS_TOKEN | The access token for the GitHub API. Useful during development to avoid getting rate-limited by Github | None |
79
80 +### Choosing the PATH entry with `COMPOSIO_BIN_DIR`
81 +
82 +`composio install` writes a single `PATH` line into your shell config. The directory it points at is resolved in this order:
83 +
84 +1. `COMPOSIO_BIN_DIR`, when set to an absolute path
85 +2. `~/.local/bin`, when its `composio` entry point resolves to the binary that is running
86 +3. the directory of the running binary
87 +
88 +Set `COMPOSIO_BIN_DIR` when the entry point users should reach is not the binary itself — a shim, a symlink farm, or a version-manager `bin` directory:
89 +
90 +```bash
91 +COMPOSIO_BIN_DIR="$HOME/.local/bin" composio install
92 +```
93 +
94 +The command aborts with a non-zero exit code, writing nothing, when the resolved directory is relative or contains a character that cannot be embedded safely in a quoted rc line (`` ` ``, `$`, `"`, `\`, a newline, or the `:` PATH separator).
95 +
96 ### CLI binary release tags
97
98 CLI binaries are published as GitHub release assets.