Skip to content

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

fix(install): stop swallowing the CLI's PATH guidance (#3951)

Alberto Schiabel27706a508127
diff --git a/install.sh b/install.sh
index 8cade2fec..da363165f 100755
--- a/install.sh
+++ b/install.sh
@@ -306,12 +306,18 @@ success "Composio CLI was installed successfully to $Bold_Green$(tildify "$exe")
# - Idempotent PATH setup in the correct rc file
# - Shell completions installation
# If the binary can't run (e.g. missing runtime), fall back to inline setup.
+#
+# Run it with stderr left on the terminal. `composio install` reports which rc
+# file it changed and how to reload the shell, and it treats a redirected stderr
+# as "nobody is watching" — capturing that stream, even to replay it later, is
+# what makes the PATH guidance disappear. The version probe keeps a binary that
+# cannot run at all from spilling loader errors before the fallback takes over.
echo
-install_err=$(mktemp)
-if COMPOSIO_INSTALL_DIR="$COMPOSIO_INSTALL_DIR" "$exe" install 2>"$install_err"; then
- cat "$install_err" >&2 # Show CLI's TerminalUI output on success
+if "$exe" --version >/dev/null 2>&1 &&
+ COMPOSIO_INSTALL_DIR="$COMPOSIO_INSTALL_DIR" "$exe" install; then
+ : # the CLI printed its own shell-integration guidance
else
info "Setting up shell integration..."
@@ -402,7 +408,6 @@ else
esac
fi
-rm -f "$install_err"
if [[ $install_plugins = true ]]; then
echo
@@ -421,8 +426,11 @@ if [[ $install_agent = true ]]; then
fi
echo
-info "Composio was added to your PATH — restart your shell (or open a new terminal) for it to take effect."
-info "Then, to get started, run:"
+# No PATH claim here: whichever branch ran above already reported what it did to
+# which file, and whether a reload is needed. Restating it unconditionally would
+# promise a configured PATH even on the branches that only printed manual
+# instructions.
+info "To get started, run:"
echo
if [[ ${refresh_command:-} ]]; then
diff --git a/test/install-sh-release-resolution.test.sh b/test/install-sh-release-resolution.test.sh
index 1fcc5fe2d..6b076d0fb 100755
--- a/test/install-sh-release-resolution.test.sh
+++ b/test/install-sh-release-resolution.test.sh
@@ -151,6 +151,9 @@ printf '%s\n' "$*" >> "$TEST_COMPOSIO_LOG"
case "${1:-}" in
install)
+ if [[ -n "${TEST_INSTALL_STDERR:-}" ]]; then
+ printf '%s\n' "$TEST_INSTALL_STDERR" >&2
+ fi
exit 0
;;
setup)
@@ -161,8 +164,11 @@ setup)
exit "${TEST_SETUP_EXIT:-0}"
;;
--version|version)
+ if [[ -n "${TEST_VERSION_STDERR:-}" ]]; then
+ printf '%s\n' "$TEST_VERSION_STDERR" >&2
+ fi
echo 'composio fake 98.0.0'
- exit 0
+ exit "${TEST_VERSION_EXIT:-0}"
;;
*)
exit 0
@@ -207,11 +213,15 @@ run_installer() {
COMPOSIO_GITHUB_API_BASE_URL="$api_base" \
COMPOSIO_GITHUB_OWNER='FakeOwner' \
COMPOSIO_GITHUB_REPO='fake-repo' \
+ TEST_INSTALL_STDERR="${TEST_INSTALL_STDERR:-}" \
TEST_SETUP_EXIT="${TEST_SETUP_EXIT:-0}" \
+ TEST_VERSION_EXIT="${TEST_VERSION_EXIT:-0}" \
+ TEST_VERSION_STDERR="${TEST_VERSION_STDERR:-}" \
bash "$repo_root/install.sh" "$@"
}
-output=$(run_installer "$home_dir" "$install_dir" 2>&1)
+install_guidance='shell integration guidance from composio install'
+output=$(TEST_INSTALL_STDERR="$install_guidance" run_installer "$home_dir" "$install_dir" 2>&1)
printf '%s\n' "$output"
@@ -247,6 +257,24 @@ if grep -q "$tag_without_release" "$curl_log"; then
exit 1
fi
+if ! grep -qxF -- '--version' "$composio_log"; then
+ echo 'Expected installer to probe the downloaded CLI with --version.' >&2
+ cat "$composio_log" >&2
+ exit 1
+fi
+
+if ! grep -qxF 'install' "$composio_log"; then
+ echo 'Expected installer to delegate shell integration to composio install.' >&2
+ cat "$composio_log" >&2
+ exit 1
+fi
+
+if ! grep -qF "$install_guidance" <<<"$output"; then
+ echo 'Expected composio install stderr guidance to remain visible.' >&2
+ printf '%s\n' "$output" >&2
+ exit 1
+fi
+
expected_setup='setup --target auto --yes --if-present'
if ! grep -qxF "$expected_setup" "$composio_log"; then
echo "Expected installer to invoke: composio $expected_setup" >&2
@@ -254,6 +282,38 @@ if ! grep -qxF "$expected_setup" "$composio_log"; then
exit 1
fi
+failed_probe_home="$tmpdir/home-failed-probe"
+failed_probe_install="$tmpdir/install-failed-probe"
+mkdir -p "$failed_probe_home" "$failed_probe_install"
+: > "$failed_probe_home/.bashrc"
+: > "$composio_log"
+loader_error='loader error from an unusable composio binary'
+failed_probe_output=$(
+ TEST_VERSION_EXIT=126 \
+ TEST_VERSION_STDERR="$loader_error" \
+ run_installer "$failed_probe_home" "$failed_probe_install" --no-plugins 2>&1
+)
+if grep -qF "$loader_error" <<<"$failed_probe_output"; then
+ echo 'Expected the failed binary probe to suppress loader errors.' >&2
+ printf '%s\n' "$failed_probe_output" >&2
+ exit 1
+fi
+if grep -qxF 'install' "$composio_log"; then
+ echo 'Expected a failed binary probe to skip composio install.' >&2
+ cat "$composio_log" >&2
+ exit 1
+fi
+if ! grep -qF 'Setting up shell integration...' <<<"$failed_probe_output"; then
+ echo 'Expected a failed binary probe to select inline shell integration.' >&2
+ printf '%s\n' "$failed_probe_output" >&2
+ exit 1
+fi
+if ! grep -qxF '# Composio CLI' "$failed_probe_home/.bashrc"; then
+ echo 'Expected inline shell integration to update .bashrc.' >&2
+ cat "$failed_probe_home/.bashrc" >&2
+ exit 1
+fi
+
no_plugins_home="$tmpdir/home-no-plugins"
no_plugins_install="$tmpdir/install-no-plugins"
mkdir -p "$no_plugins_home" "$no_plugins_install"
@@ -290,4 +350,4 @@ if ! grep -q 'Composio CLI was installed, but agent plugin setup failed' <<<"$fa
exit 1
fi
-printf 'install.sh release fallback and plugin setup tests passed\n'
+printf 'install.sh release fallback, shell integration, and plugin setup tests passed\n'
diff --git a/ts/packages/cli/CHANGELOG.md b/ts/packages/cli/CHANGELOG.md
index 12f229fe6..553e41af1 100644
--- a/ts/packages/cli/CHANGELOG.md
+++ b/ts/packages/cli/CHANGELOG.md
@@ -19,6 +19,7 @@
- Preserve the original CLI diagnostic when an adjacent source map is malformed or unusable instead of letting optional source-map enrichment abort error capture. Source-map enrichment is now best-effort end to end: a malformed, invalid, or unreadable `.map`, and a valid map pointing at an original source that was never shipped, all degrade to the raw stack location. `captureErrors` can no longer fail.
- Fix source-map resolution on Windows: original source paths are now resolved with the platform path separator instead of a hardcoded `/`, and the `node_modules` filter no longer mistakes directories such as `node_modules_local` for real dependency paths.
- Make `composio version --check` report `checkStatus: "unknown"` when GitHub cannot confirm the latest stable release, preserve the last successful cache on failed refreshes, and avoid racing the command with the startup update check.
+- Keep `composio install` guidance visible when its output is captured. The command reports which rc file it changed and how to reload the shell, but suppressed all of it when stderr was not a terminal — so installers, containers, and CI logs saw nothing and users were left with `command not found`. Those lines now fall back to plain, undecorated output.
- Make multi-account selection a stable CLI feature: `execute`, `listen`, and `link --alias` no longer honor the old experimental toggle; `proxy` now accepts `--account <alias|word_id|connected-account-id>`; and duplicate-alias link errors explain how to select the existing account.
- 8467efd: Fix `composio whoami` reporting the API key's home organization after `composio orgs switch`. Session info requests now forward the selected global organization.
- 5f004ff: Drop `COMPOSIO_UPSERT_RECIPE` and `COMPOSIO_GET_RECIPE` from the CLI meta-tool list. These slugs were removed from `@composio/client` (alpha.74), so listing them broke the type-checked CLI build.
diff --git a/ts/packages/cli/src/commands/install.cmd.ts b/ts/packages/cli/src/commands/install.cmd.ts
index b0e6f0fb3..cd91af522 100644
--- a/ts/packages/cli/src/commands/install.cmd.ts
+++ b/ts/packages/cli/src/commands/install.cmd.ts
@@ -169,6 +169,20 @@ export const installShellIntegration = (params: {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
+ // Everything this command prints is a report of what it changed on disk, so
+ // it has to reach the user even when stderr is not a terminal: install.sh
+ // runs it as a subprocess, and container/CI installs pipe the whole session
+ // to a build log. Decoration stays the interactive default; `ui.error`
+ // writes the same text unformatted when there is nothing to decorate.
+ const { canDecorate } = yield* ui.capabilities;
+ const plain = (prefix: string) => (message: string) => ui.error(`${prefix}${message}`);
+ const step = canDecorate ? ui.log.step : ui.error;
+ const success = canDecorate ? ui.log.success : ui.error;
+ const warn = canDecorate ? ui.log.warn : plain('warning: ');
+ const failure = canDecorate ? ui.log.error : plain('error: ');
+ const note = (body: string, title: string) =>
+ canDecorate ? ui.note(body, title) : ui.error(`${title}:\n${body}`);
+
yield* ui.intro('composio install');
// Detect install directory — either from env or default ~/.composio
@@ -176,7 +190,7 @@ export const installShellIntegration = (params: {
const installDir = process.env.COMPOSIO_INSTALL_DIR ?? path.join(os.homedir, '.composio');
if (isUnsafePath(installDir)) {
- yield* ui.log.error(
+ yield* failure(
'COMPOSIO_INSTALL_DIR contains unsafe characters and cannot be written to shell config.'
);
yield* ui.outro('Aborted.');
@@ -186,10 +200,8 @@ export const installShellIntegration = (params: {
// Detect user shell
const shell = detectShell(path);
if (!shell) {
- yield* ui.log.warn(
- 'Could not detect your shell. Manually add the following to your shell config:'
- );
- yield* ui.note(
+ yield* warn('Could not detect your shell. Manually add the following to your shell config:');
+ yield* note(
`export COMPOSIO_INSTALL_DIR="${installDir}"\nexport PATH="$COMPOSIO_INSTALL_DIR:$PATH"`,
'PATH setup'
);
@@ -197,7 +209,7 @@ export const installShellIntegration = (params: {
return;
}
- yield* ui.log.step(`Detected shell: ${shell}`);
+ yield* step(`Detected shell: ${shell}`);
// Generate completions script if requested.
// Lazy-import the root command to avoid a circular dependency
@@ -239,28 +251,28 @@ export const installShellIntegration = (params: {
const existingPathFile = existingByFile.get(config.pathFile) ?? '';
if (!fileContains(existingPathFile, MARKER)) {
pushBlock(config.pathFile, config.pathBlock);
- yield* ui.log.step(`PATH: will add ${tildify(installDir, os.homedir)} to $PATH`);
+ yield* step(`PATH: will add ${tildify(installDir, os.homedir)} to $PATH`);
} else {
- yield* ui.log.step('PATH: already configured');
+ yield* step('PATH: already configured');
}
if (shell === 'zsh') {
- yield* ui.log.step('Completions: skipped for zsh');
+ yield* step('Completions: skipped for zsh');
} else if (!params.completions) {
- yield* ui.log.step('Completions: skipped by default (pass --completions to enable)');
+ yield* step('Completions: skipped by default (pass --completions to enable)');
} else if (!config.completionBlock) {
- yield* ui.log.step('Completions: not available for this shell');
+ yield* step('Completions: not available for this shell');
} else {
const existingCompletionFile = existingByFile.get(config.completionFile) ?? '';
if (!fileContains(existingCompletionFile, COMPLETIONS_MARKER)) {
pushBlock(config.completionFile, config.completionBlock);
- yield* ui.log.step(
+ yield* step(
config.shell === 'fish'
? `Completions: will install fish completions to ${tildify(config.completionFile, os.homedir)}`
: 'Completions: will install shell completions'
);
} else {
- yield* ui.log.step('Completions: already configured');
+ yield* step('Completions: already configured');
}
}
@@ -286,14 +298,14 @@ export const installShellIntegration = (params: {
yield* fs.writeFileString(tmpPath, existingContents + appendContent);
yield* fs.rename(tmpPath, writeTarget);
- yield* ui.log.success(`Updated ${tildify(filePath, os.homedir)}`);
+ yield* success(`Updated ${tildify(filePath, os.homedir)}`);
}
} else {
- yield* ui.log.success('Shell integration already configured — nothing to do.');
+ yield* success('Shell integration already configured — nothing to do.');
}
if (blocksByFile.size > 0) {
- yield* ui.note(
+ yield* note(
shell === 'fish'
? 'exec fish'
: shell === 'zsh'
diff --git a/ts/packages/cli/test/src/commands/install.cmd.test.ts b/ts/packages/cli/test/src/commands/install.cmd.test.ts
index b0afb1990..127c78766 100644
--- a/ts/packages/cli/test/src/commands/install.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/install.cmd.test.ts
@@ -1,12 +1,33 @@
import path from 'node:path';
import process from 'node:process';
+import { Writable } from 'node:stream';
import { beforeEach, afterEach } from 'vitest';
import { describe, expect, layer } from '@effect/vitest';
import { Effect } from 'effect';
import { FileSystem } from '@effect/platform';
import { NodeOs } from 'src/services/node-os';
+import { makeTerminalUI } from 'src/services/terminal-ui';
import { cli, TestLive, MockConsole } from 'test/__utils__';
+const makeSink = (isTTY: boolean) => {
+ const chunks: string[] = [];
+ const sink = new Writable({
+ write(chunk, _encoding, callback) {
+ chunks.push(String(chunk));
+ callback();
+ },
+ });
+ return Object.assign(sink, { isTTY, chunks });
+};
+
+const capturedStdout = makeSink(true);
+const capturedStderr = makeSink(false);
+const capturedStderrUI = makeTerminalUI({
+ stdin: { isTTY: true },
+ stdout: capturedStdout,
+ stderr: capturedStderr,
+});
+
describe('CLI: composio install', () => {
let savedShell: string | undefined;
let savedInstallDir: string | undefined;
@@ -14,6 +35,8 @@ describe('CLI: composio install', () => {
beforeEach(() => {
savedShell = process.env.SHELL;
savedInstallDir = process.env.COMPOSIO_INSTALL_DIR;
+ capturedStdout.chunks.length = 0;
+ capturedStderr.chunks.length = 0;
});
afterEach(() => {
@@ -374,6 +397,38 @@ describe('CLI: composio install', () => {
});
});
+ describe('[When] stderr is captured rather than a terminal', () => {
+ layer(TestLive({ terminalUI: capturedStderrUI }))(it => {
+ it.scoped('[Then] still reports the rc file and how to reload the shell', () =>
+ Effect.gen(function* () {
+ const os = yield* NodeOs;
+ process.env.SHELL = '/bin/zsh';
+ process.env.COMPOSIO_INSTALL_DIR = path.join(os.homedir, '.composio');
+
+ yield* cli(['install']);
+
+ const output = capturedStderr.chunks.join('');
+ expect(output).toContain('PATH: will add');
+ expect(output).toContain('Updated ~/.zshrc');
+ expect(output).toContain('Restart your shell to apply changes');
+ expect(output).toContain('source ~/.zshrc');
+ })
+ );
+
+ it.scoped('[Then] still shows manual setup instructions for an unknown shell', () =>
+ Effect.gen(function* () {
+ process.env.SHELL = '';
+
+ yield* cli(['install']);
+
+ const output = capturedStderr.chunks.join('');
+ expect(output).toContain('Could not detect your shell');
+ expect(output).toContain('export PATH="$COMPOSIO_INSTALL_DIR:$PATH"');
+ })
+ );
+ });
+ });
+
describe('[When] COMPOSIO_INSTALL_DIR is not set', () => {
layer(TestLive())(it => {
it.scoped('[Then] defaults to ~/.composio', () =>