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): describe automatic shell setup as the installer default
jkomyno committed
Aug 3, 2026 at 16:52 UTC
bd6582a266364ef85e9a0ac90c291a62a553c357
6 files changed
+41
-22
INSTALL.md
+16
-5
@@ -6,15 +6,26 @@ Install the CLI bundle in `~/.composio` and its entry point in `~/.local/bin`:
6
curl -fsSL https://composio.dev/install | sh
7
```
8
9
-The default installer changes no shell files and installs no agent plugins. If it reports that `~/.local/bin` is not available on `PATH`, run the shell-specific command it prints:
9
+The installer also configures your shell. It infers your login shell from `$SHELL` (`zsh`, `bash`, or `fish`) and writes a single managed `# Composio CLI` PATH block to the matching startup file so future terminals find `composio`. Open a new terminal, then run `composio login`.
10
+
11
+If your shell is not recognized, or shell setup fails, the binary install still succeeds and the installer prints a runnable command instead. The installer never installs agent plugins.
12
+
13
+## Choose or skip shell setup
14
+
15
+Set `COMPOSIO_INSTALL_SHELL` to force a specific shell, or to skip shell configuration entirely:
16
17
```bash
18
curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh
19
curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=bash sh
20
curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=fish sh
21
+curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=none sh
22
```
23
17
-Shell setup delegates to `composio install --shell <shell>` and falls back to writing the same `# Composio CLI` PATH block inline when the installed CLI release predates that flag.
24
+Use `none` for an install-only run that changes no shell files. Reach for it in CI, Docker images, or when a dotfile manager owns your startup files.
25
+
26
+Shell-specific installer variants ([`install/zsh.sh`](install/zsh.sh), [`install/bash.sh`](install/bash.sh), [`install/fish.sh`](install/fish.sh)) pin `COMPOSIO_INSTALL_SHELL` to their shell before delegating to the base installer.
27
+
28
+Shell setup is idempotent: repeated installs keep exactly one managed PATH block per startup file and reconcile it when the bin directory changes. Setup delegates to `composio install --shell <shell>` and falls back to writing the same `# Composio CLI` PATH block inline when the installed CLI release predates that flag.
29
30
Pin a stable or beta release with `COMPOSIO_INSTALL_VERSION`, or pass the tag as a positional argument:
31
@@ -28,13 +39,13 @@ The positional argument takes precedence over `COMPOSIO_INSTALL_VERSION`.
39
| Variable or argument | Description | Default |
40
|---|---|---|
41
| `COMPOSIO_INSTALL_DIR` | Complete CLI bundle directory. | `$HOME/.composio` |
31
-| `COMPOSIO_BIN_DIR` | `composio` entry-point directory. | `$HOME/.local/bin` |
42
+| `COMPOSIO_BIN_DIR` | `composio` entry-point directory. Trusted input: anyone with write access to this directory can replace commands that future terminals run. | `$HOME/.local/bin` |
43
| `COMPOSIO_INSTALL_VERSION` | Stable or beta version, with or without the package prefix. | Latest stable release |
44
| `COMPOSIO_QUIET` | Set to `1` or `true` to hide progress output. | Unset |
45
| `COMPOSIO_DEBUG` | Set to `1` or `true` to print installer traces. | Unset |
46
| `COMPOSIO_INSTALL_HELP` | Set to `0` to hide post-install guidance. | `1` |
47
| `COMPOSIO_INSTALL_PLUGINS` | Set to `1` to install plugins for detected agent hosts. | `0` |
37
-| `COMPOSIO_INSTALL_SHELL` | Configure the requested shell (`zsh`, `bash`, or `fish`) after installation. | Unset |
48
+| `COMPOSIO_INSTALL_SHELL` | Shell setup mode: `auto` infers your login shell from `$SHELL`, `zsh`, `bash`, or `fish` force a specific shell, and `none` skips shell configuration. | `auto` |
49
| `--agent` | Log in as a Composio agent after installation. | Off |
50
| `--no-plugins` | Skip plugin setup. Kept for compatibility. | Off |
51
@@ -95,7 +106,7 @@ rm -rf \
106
"$install_dir/local-tools-binaries"
107
```
108
98
-Remove `# Composio CLI` PATH blocks from `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.bash_login`, or `~/.config/fish/config.fish` if you used a shell-specific installer. Blocks written by older installers contain an extra `export COMPOSIO_INSTALL_DIR=...` line after the marker; remove that line too.
109
+Remove the managed `# Composio CLI` PATH block from `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.bash_login`, or `~/.config/fish/config.fish`. Blocks written by older installers contain an extra `export COMPOSIO_INSTALL_DIR=...` line after the marker; remove that line too.
110
111
To purge credentials, configuration, caches, and every other CLI file, run `rm -rf "${COMPOSIO_INSTALL_DIR:-$HOME/.composio}"`. This is a complete reset and cannot be undone.
112
README.md
+2
-1
@@ -103,9 +103,10 @@ The `composio` CLI runs Composio from your shell and gives coding agents like Cl
103
104
```bash
105
curl -fsSL https://composio.dev/install | sh
106
-composio login
106
```
107
108
+The installer puts `composio` on your `PATH` for future terminals. Open a new terminal, then run `composio login`. See [INSTALL.md](INSTALL.md) for shell setup overrides, including `COMPOSIO_INSTALL_SHELL=none` for install-only runs.
109
+
110
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](https://docs.composio.dev/docs/cli).
111
112
## Providers
docs/content/changelog/07-31-26-installer.mdx
+5
-4
@@ -1,15 +1,16 @@
1
---
2
title: "Install the Composio CLI with a POSIX shell"
3
-description: "The CLI installer now runs on POSIX sh, keeps the release bundle separate from the entry point, and makes shell configuration opt-in."
3
+description: "The CLI installer now runs on POSIX sh, keeps the release bundle separate from the entry point, and configures your shell automatically."
4
date: "2026-07-31"
5
---
6
7
-The Composio CLI installer now separates the release bundle from the command you run, works with POSIX `sh`, and leaves shell configuration opt-in.
7
+The Composio CLI installer now separates the release bundle from the command you run, works with POSIX `sh`, and puts `composio` on `PATH` for future terminals automatically.
8
9
### What's new
10
11
- `curl -fsSL https://composio.dev/install | sh` installs the verified release bundle in `~/.composio` and creates `~/.local/bin/composio`.
12
-- The default flow does not edit shell files, install agent plugins, or log you in.
13
-- `COMPOSIO_INSTALL_SHELL=zsh|bash|fish` configures the requested shell explicitly, for example `curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh`.
12
+- The default flow infers your shell from `$SHELL` and configures `PATH` for future terminals; set `COMPOSIO_INSTALL_SHELL=none` for an install-only run.
13
+- The installer does not install agent plugins or log you in.
14
+- `COMPOSIO_INSTALL_SHELL=zsh|bash|fish` forces a specific shell, for example `curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh`.
15
- `COMPOSIO_INSTALL_VERSION`, `COMPOSIO_BIN_DIR`, `COMPOSIO_QUIET`, and `COMPOSIO_DEBUG` give you control over version, layout, and output.
16
- Existing `COMPOSIO_INSTALL_DIR` configurations keep their bundle-directory meaning.
docs/content/docs/claude-code-plugin.mdx
+1
-1
@@ -44,7 +44,7 @@ The first time, Claude installs the Composio CLI if it's missing, signs you in w
44
</Steps>
45
46
<Callout>
47
-Prefer to set things up ahead of time? Run `curl -fsSL https://composio.dev/install | sh`, then `composio login`.
47
+Prefer to set things up ahead of time? Run `curl -fsSL https://composio.dev/install | sh` to install the CLI and configure your shell, then open a new terminal and run `composio login`.
48
</Callout>
49
50
## What you can do
docs/content/docs/cli.mdx
+16
-10
@@ -10,17 +10,15 @@ Reach for it when you want Claude to act in your connected apps directly, instea
10
11
## Install
12
13
-Install the CLI with the POSIX shell installer:
13
+Install the CLI with one command:
14
15
```bash
16
curl -fsSL https://composio.dev/install | sh
17
```
18
19
-The installer downloads and verifies the release bundle in `~/.composio`, then creates the `~/.local/bin/composio` entry point. It does not edit shell files, install agent plugins, or log you in.
19
+The installer downloads and verifies the release bundle in `~/.composio`, creates the `~/.local/bin/composio` entry point, and configures your shell so future terminals find `composio` on `PATH`. It recognizes `zsh`, `bash`, and `fish` login shells from `$SHELL` and writes a single managed `# Composio CLI` block to the matching startup file. If your shell is not recognized, or shell setup fails, the CLI still installs and the installer prints a runnable command instead. It does not install agent plugins or log you in. To skip shell configuration entirely, see [Shell setup overrides](#shell-setup-overrides).
20
21
-If the installer reports that `~/.local/bin` is not on your `PATH`, run the command it prints for your shell — see [Configure your shell](#configure-your-shell) — and start a new shell.
22
-
23
-Log in after `composio` is available:
21
+Open a new terminal, then log in:
22
23
```bash
24
composio login
@@ -50,14 +48,14 @@ curl -fsSL https://composio.dev/install | sh -s -- @composio/cli@0.3.1
48
| Variable or argument | Description | Default |
49
|---|---|---|
50
| `COMPOSIO_INSTALL_DIR` | Directory that receives the complete CLI bundle and `release-tag.txt`. | `$HOME/.composio` |
53
-| `COMPOSIO_BIN_DIR` | Directory that receives the `composio` entry-point symlink. Set it to `COMPOSIO_INSTALL_DIR` to use the legacy single-directory layout. | `$HOME/.local/bin` |
51
+| `COMPOSIO_BIN_DIR` | Directory that receives the `composio` entry-point symlink. Set it to `COMPOSIO_INSTALL_DIR` to use the legacy single-directory layout. Trusted input: anyone with write access to this directory can replace commands that future terminals run. | `$HOME/.local/bin` |
52
| `COMPOSIO_INSTALL_VERSION` | Stable or beta version to install, with or without the `@composio/cli@` prefix. | Latest stable release |
53
| `version-tag` | Positional stable or beta version. This overrides `COMPOSIO_INSTALL_VERSION`. | None |
54
| `COMPOSIO_QUIET` | Set to `1` or `true` to hide progress output. Warnings and errors still print. | Unset |
55
| `COMPOSIO_DEBUG` | Set to `1` or `true` to print download URLs and temporary paths. | Unset |
56
| `COMPOSIO_INSTALL_HELP` | Set to `0` to hide post-install guidance. | `1` |
57
| `COMPOSIO_INSTALL_PLUGINS` | Set to `1` to run `composio setup --target auto --yes --if-present` after installation. | `0` |
60
-| `COMPOSIO_INSTALL_SHELL` | Configure the requested shell (`zsh`, `bash`, or `fish`) after installation. See [Configure your shell](#configure-your-shell). | Unset |
58
+| `COMPOSIO_INSTALL_SHELL` | Shell setup mode: `auto` infers your login shell from `$SHELL`, `zsh`, `bash`, or `fish` force a specific shell, and `none` skips shell configuration. See [Shell setup overrides](#shell-setup-overrides). | `auto` |
59
| `COMPOSIO_GITHUB_OWNER` | GitHub owner used to resolve releases. | `ComposioHQ` |
60
| `COMPOSIO_GITHUB_REPO` | GitHub repository used to resolve releases. | `composio` |
61
| `COMPOSIO_GITHUB_URL` | GitHub web and release-download base URL. | `https://github.com` |
@@ -65,9 +63,9 @@ curl -fsSL https://composio.dev/install | sh -s -- @composio/cli@0.3.1
63
| `--agent` | Log in as a Composio agent after installation. | Off |
64
| `--no-plugins` | Skip agent plugin setup. Kept for compatibility and now matches the default. | Off |
65
68
-### Configure your shell
66
+### Shell setup overrides
67
70
-Set `COMPOSIO_INSTALL_SHELL` when `~/.local/bin` is not already on `PATH`, or when you want the CLI to configure the requested shell explicitly.
68
+By default the installer infers your login shell from `$SHELL` and configures it. Set `COMPOSIO_INSTALL_SHELL` to force a specific shell instead:
69
70
<Tabs groupId="shell" items={['zsh','bash','fish']} persist>
71
<Tab value="zsh">
@@ -93,7 +91,15 @@ This configures `~/.config/fish/config.fish` and delegates setup to `composio in
91
</Tab>
92
</Tabs>
93
96
-Shell setup is idempotent. It falls back to writing the same PATH block inline when you pin an older CLI release that does not support `composio install --shell`.
94
+Set `COMPOSIO_INSTALL_SHELL=none` for an install-only run that changes no shell files. Use it in CI, Docker images, or when a dotfile manager owns your startup files:
95
+
96
+```bash
97
+curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=none sh
98
+```
99
+
100
+Shell-specific installer variants (`zsh.sh`, `bash.sh`, and `fish.sh` in the repository's [`install/` directory](https://github.com/ComposioHQ/composio/tree/next/install)) pin `COMPOSIO_INSTALL_SHELL` to their shell before delegating to the base installer.
101
+
102
+Shell setup is idempotent: repeated installs keep exactly one managed PATH block per startup file and reconcile it when the bin directory changes. Setup falls back to writing the same PATH block inline when you pin an older CLI release that does not support `composio install --shell`. Startup-file changes only affect future terminals; in the current one, either open a new terminal or run the absolute path the installer prints.
103
104
### Verify the installation
105
ts/packages/cli/AGENTS.md
+1
-1
@@ -38,7 +38,7 @@ Each command uses `@effect/cli`'s `Command.make()` pattern. Top-level command fi
38
| `signup` | Create a Composio account |
39
| `upgrade` | Self-update binary from GitHub releases |
40
| `init` | Bootstrap a Composio project in the current directory |
41
-| `install` | Install local-tool integrations |
41
+| `install` | Set up shell integration (PATH and completions) |
42
| `generate {ts | py}` | Generate type stubs (auto-detects project language if no subcommand) |
43
| `agent` | Manage AI agent presets |
44
| `toolkits` | List / inspect / version toolkits |