> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Composio CLI

> Use the Composio CLI from Codex, Claude Code, or your terminal for agent workflows and development.

The Composio CLI gives coding agents and terminals a local tool surface. Codex, Claude Code, or a person at the terminal can connect apps, execute tools, inspect schemas, call authenticated APIs, and debug Composio projects. It is also the runtime underneath the native [Composio agent plugins](https://composio-preview.mintlify.site/docs/agent-plugins.md).

Reach for it when you want an agent to act in your connected apps directly, without building an SDK application or configuring MCP.

> [!NOTE]
>
> **Unattended agent authentication**
>
> When no human is available to log in, `composio login --agent` provisions or reuses an agent account without a browser. See [Authenticate an unattended agent](https://composio-preview.mintlify.site/docs/agent-setup/unattended-authentication.md) for constraints, application API key setup, and live-tool verification.

## Install

Install the CLI with one command:

```bash theme={null}
curl -fsSL https://composio.dev/install | sh
```

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 managed `# Composio CLI` block to their startup files. `bash` also gets a login-mode startup file — the first existing of `~/.bash_profile` or `~/.bash_login`, or a newly created `~/.bash_profile` — because a login bash, which macOS Terminal.app starts, never reads `~/.bashrc`. If your shell is not recognized, or shell setup fails, the CLI still installs and the installer prints a runnable command instead. It also installs plugins for detected, supported Codex and Claude Code hosts. Set `COMPOSIO_INSTALL_PLUGINS=0` or pass `--no-plugins` to skip plugin setup. Login remains a separate step. To skip shell configuration entirely, see [Shell setup overrides](#shell-setup-overrides).

Open a new terminal, then log in:

```bash theme={null}
composio login
```

If you skipped plugin setup or installed an agent host later, run:

```bash theme={null}
composio setup --target auto
```

`auto` detects supported agents on your machine. Use `--target codex` or `--target claude` to configure only one. See [Agent plugins](https://composio-preview.mintlify.site/docs/agent-plugins.md) for manual plugin commands and host-specific details.

Setup asks before changing local files. Add `--yes` when you run it from an agent, script, CI job, or another non-interactive shell.

`composio login` installs the standalone `composio-cli` skill for Claude Code by default. For Codex, prefer `composio setup --target codex`; it installs the native plugin, which bundles the CLI skill.

If you explicitly need the standalone skill without the native plugin, install it manually for the agent host:

```bash theme={null}
composio setup skill claude
composio setup skill codex
```

### Backend and Dashboard configuration

The CLI uses the backend recorded by `composio login`. `COMPOSIO_BASE_URL` and `COMPOSIO_ENVIRONMENT` override that backend. If an override sends your stored key to a different backend, the CLI warns on stderr. If your key is rejected, follow the printed command to log in again.

`composio execute` sends single executions, `--parallel` executions, and meta tool calls through the Dashboard recorded with your login. For the default deployment, allow outbound requests to both `dashboard.composio.dev` and `backend.composio.dev`. Other commands, including `composio dev playground-execute`, use the backend API.

For a custom deployment, setting `COMPOSIO_BASE_URL` without `COMPOSIO_WEB_URL` keeps executions on that backend. Set both variables to route executions through your deployment's Dashboard. `COMPOSIO_WEB_URL` must use HTTPS and contain no credentials, query string, or fragment. HTTP is accepted only for `localhost`. An invalid URL causes `composio execute` to fail before sending a request.

### Install with options

Pin a version and skip agent plugin setup:

```bash theme={null}
curl -fsSL https://composio.dev/install \
  | COMPOSIO_INSTALL_VERSION=0.3.1 COMPOSIO_INSTALL_PLUGINS=0 sh
```

You can also pass a stable or beta release tag as the positional argument. The positional value takes precedence over `COMPOSIO_INSTALL_VERSION`:

```bash theme={null}
curl -fsSL https://composio.dev/install | sh -s -- @composio/cli@0.3.1
```

| Variable or argument | Description | Default |
| - | - | - |
| `COMPOSIO_INSTALL_DIR` | Directory that receives the complete CLI bundle and `release-tag.txt`. | `$HOME/.composio` |
| `COMPOSIO_BIN_DIR` | Directory that receives the `composio` entry-point symlink. Set it to `COMPOSIO_INSTALL_DIR` to use the legacy single-directory layout. Treat this as trusted input: anyone who can write to this directory can replace commands that future terminals run. | `$HOME/.local/bin` |
| `COMPOSIO_INSTALL_VERSION` | Stable or beta version to install, with or without the `@composio/cli@` prefix. | Latest stable release |
| `version-tag` | Positional stable or beta version. This overrides `COMPOSIO_INSTALL_VERSION`. | None |
| `COMPOSIO_QUIET` | Set to `1` or `true` to hide progress output. Warnings and errors still print. | Unset |
| `COMPOSIO_DEBUG` | Set to `1` or `true` to print download URLs and temporary paths. | Unset |
| `COMPOSIO_INSTALL_HELP` | Set to `0` to hide normal post-install guidance. Shell-setup failures still warn and print a recovery command to stderr. | `1` |
| `COMPOSIO_INSTALL_PLUGINS` | Runs `composio setup --target auto --yes --if-present` after installation. Set to `0` to skip plugin setup. | `1` |
| `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` |
| `COMPOSIO_GITHUB_OWNER` | GitHub owner used to resolve releases. | `ComposioHQ` |
| `COMPOSIO_GITHUB_REPO` | GitHub repository used to resolve releases. | `composio` |
| `COMPOSIO_GITHUB_URL` | GitHub web and release-download base URL. | `https://github.com` |
| `COMPOSIO_GITHUB_API_BASE_URL` | GitHub API base URL. | Derived from `COMPOSIO_GITHUB_URL` |
| `--agent` | Log in as a Composio agent after installation. | Off |
| `--no-plugins` | Skip agent plugin setup, even when `COMPOSIO_INSTALL_PLUGINS=1`. | Off |

### Shell setup overrides

By default the installer infers your login shell from `$SHELL` and configures it. Set `COMPOSIO_INSTALL_SHELL` to force a specific shell instead:

> [tab] zsh
>
> ```bash theme={null}
> curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh
> ```
>
> This configures `~/.zshrc` and delegates setup to `composio install --shell zsh`.

> [tab] bash
>
> ```bash theme={null}
> curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=bash sh
> ```
>
> This configures `~/.bashrc` and delegates setup to `composio install --shell bash`. It also configures a login-mode startup file so `bash -ilc` can find `composio`: the first active login file (`~/.bash_profile`, then `~/.bash_login`), or a new `~/.bash_profile` that sources your existing `~/.profile` when neither exists.

> [tab] fish
>
> ```bash theme={null}
> curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=fish sh
> ```
>
> This configures `~/.config/fish/config.fish` and delegates setup to `composio install --shell fish`.

Set `COMPOSIO_INSTALL_SHELL=none` to leave shell files unchanged. For an install-only run in CI or Docker, also disable plugin setup:

```bash theme={null}
curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=none COMPOSIO_INSTALL_PLUGINS=0 sh
```

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.

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 the installed CLI predates `composio install --shell`, delegated setup fails, or delegated setup leaves a stale block. Startup-file changes only affect future terminals; in the current one, either open a new terminal or run the absolute path the installer prints.

### Verify the installation

```bash theme={null}
composio --version
which composio
```

The installer supports Linux x64, Linux ARM64, macOS Intel, and macOS Apple Silicon. On Windows, install and run it inside [WSL](https://learn.microsoft.com/windows/wsl/install).

### Update

```bash theme={null}
composio upgrade
```

This replaces the bundle in `~/.composio` in place and leaves the `~/.local/bin/composio` entry point pointing at it. Pass a version to pin a specific release (`composio upgrade 0.3.1`), or `--beta` for the latest prerelease.

### Install manually from GitHub Releases

Download the archive for your platform from [GitHub Releases](https://github.com/ComposioHQ/composio/releases), then install the complete bundle. Keep the support files beside the executable.

```bash theme={null}
bundle=composio-linux-x64
COMPOSIO_INSTALL_DIR=${COMPOSIO_INSTALL_DIR:-"$HOME/.composio"}
COMPOSIO_BIN_DIR=${COMPOSIO_BIN_DIR:-"$HOME/.local/bin"}

unzip "$bundle.zip"
mkdir -p "$COMPOSIO_INSTALL_DIR"
cp -Rp "$bundle"/. "$COMPOSIO_INSTALL_DIR/"
chmod +x "$COMPOSIO_INSTALL_DIR/composio"
mkdir -p "$COMPOSIO_BIN_DIR"
if [ "$COMPOSIO_BIN_DIR" != "$COMPOSIO_INSTALL_DIR" ]; then
  ln -sf "$COMPOSIO_INSTALL_DIR/composio" "$COMPOSIO_BIN_DIR/composio"
fi
export PATH="$COMPOSIO_BIN_DIR:$PATH"
```

### Uninstall

Remove only installer-owned entry points and release artifacts. This keeps your credentials, configuration, and cache data in `~/.composio`. The file list below matches the current release layout; if you installed a different version, compare it against the contents of that release's archive.

```bash theme={null}
install_dir=${COMPOSIO_INSTALL_DIR:-"$HOME/.composio"}
bin_dir=${COMPOSIO_BIN_DIR:-"$HOME/.local/bin"}

rm -f \
  "$bin_dir/composio" \
  "$install_dir/composio" \
  "$install_dir/release-tag.txt" \
  "$install_dir/run-helpers-runtime.mjs" \
  "$install_dir/run-subagent-shared.mjs" \
  "$install_dir/run-subagent-acp.mjs" \
  "$install_dir/run-subagent-legacy.mjs" \
  "$install_dir/run-subagent-output-mcp.mjs" \
  "$install_dir/generation-runtime.mjs" \
  "$install_dir/execute-output-encoder-runtime.mjs"
rm -rf \
  "$install_dir/services" \
  "$install_dir/acp-adapters" \
  "$install_dir/local-tools-binaries"

for file in \
  "$HOME/.zshrc" \
  "$HOME/.bashrc" \
  "$HOME/.bash_profile" \
  "$HOME/.bash_login" \
  "$HOME/.config/fish/config.fish"; do
  [ -f "$file" ] || continue
  tmp=$(mktemp) || continue
  if awk '
    $0 == "# Composio CLI" { in_block = 1; next }
    in_block && (/^export COMPOSIO_INSTALL_DIR=/ || /^set --export COMPOSIO_INSTALL_DIR /) { next }
    in_block && (/^export PATH=/ || /^set --export PATH /) { in_block = 0; next }
    { in_block = 0; print }
  ' "$file" > "$tmp"; then
    if [ "$file" = "$HOME/.bash_profile" ] && ! grep -q '[^[:space:]]' "$tmp"; then
      rm -f "$file"
    else
      cat "$tmp" > "$file"
    fi
  fi
  rm -f "$tmp"
done
```

The loop stages every rewrite in a `mktemp` scratch file — created with an unpredictable name and `0600` permissions, so startup-file contents never pass through a world-readable path — and writes the result back only when `awk` succeeds. A failed or missing `awk` leaves the startup file untouched, and the scratch file is always removed. Writing back with `cat` keeps a symlinked startup file intact: the symlink, its target's inode, owner, and mode all survive. The filter removes the current managed block and the three-line block written by older installers (marker plus `export COMPOSIO_INSTALL_DIR=...` or `set --export COMPOSIO_INSTALL_DIR ...`).

`~/.bash_profile` gets one extra step: when removing the block leaves only blank lines, the file is deleted. The installer creates `~/.bash_profile` on bash systems that had no login startup file, and bash prefers even an empty `~/.bash_profile` over `~/.profile`, so leaving the empty file behind would silently override bash's normal startup-file selection forever. Note the edge case: a `~/.bash_profile` you created yourself but left empty is also removed. If you had a `~/.profile` when you installed, the created `~/.bash_profile` instead keeps a passthrough that sources it, so the file is not blank and survives the loop with only the block removed. It begins with `# Created by the Composio CLI installer.`; delete it too if you want bash to read `~/.profile` directly again.

> [!WARNING]
>
> **Purge all CLI state**
>
> The command below also deletes saved credentials, configuration, and caches. Run it only when you want a complete reset.
>
> ```bash theme={null}
> rm -rf "${COMPOSIO_INSTALL_DIR:-$HOME/.composio}"
> ```

## Agent and terminal workflows

The CLI executes tools, connects accounts, scripts workflows, calls authenticated APIs, and inspects trigger events without you wiring up a custom integration first. Native Codex and Claude Code plugins expose these capabilities to the agent; the same commands work directly in your terminal.

### Search, connect, and execute tools

Use this flow when you or your agent needs to act in one of your connected apps:

```bash theme={null}
# Find the right tool
composio search "summarize my unread gmail"

# Inspect the required input schema
composio execute GMAIL_FETCH_EMAILS --get-schema

# Connect the app if needed
composio link gmail

# Execute the tool
composio execute GMAIL_FETCH_EMAILS \
  -d '{ query: "is:unread newer_than:1d", max_results: 10 }'
```

Use `composio execute <slug> --get-schema` to print the tool's input schema as JSON. `composio execute <slug> --help` now shows command options and examples.

Use `composio execute <slug> --get-schema` to print the tool's input schema as JSON. `composio execute <slug> --help` now shows command options and examples.

The commands you'll reach for most:

| Command | Use it for |
| - | - |
| `composio search` | Find relevant tools by natural language |
| `composio execute` | Execute a known tool slug |
| `composio link` | Connect an app account |
| `composio proxy` | Call provider APIs with Composio-managed auth |

Use `composio proxy` when the agent already knows the provider's API endpoint and just needs Composio to inject auth from your connected account:

```bash theme={null}
composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail
```

### Execution failures and exit codes

`composio execute` exits `1` when a tool reports failure or the Dashboard or backend cannot run it. With `--parallel`, any failed call makes the command exit `1`. Meta tools follow the same rules. Failed tool results include `{"successful": false, ...}` on stdout, with diagnostic messages on stderr. Check the exit code in scripts and agents, even when stdout contains JSON.

Execution requests are sent once, without retries or redirects. After 15 minutes, the CLI stops waiting.

> [!WARNING]
>
> A timed-out tool may still have run. Check the result in the connected app before sending the request again.

Missing required IDs or names for `composio dev auth-configs info`, `composio tools info`, and `composio dev triggers create` or `enable` cause exit `1`. The `--custom-credentials` option for auth config creation and `--trigger-config` option for trigger creation must contain JSON objects. Invalid input prints a message on stderr, leaves stdout empty, and sends no request.

If `--account` matches no connected account, `composio execute` and `composio proxy` print a usage error on stderr and exit `1`. If `composio orgs switch` has no usable stored API key, it exits `1` and asks you to run `composio login`.

### Execution telemetry

When telemetry is enabled, `composio execute` sends the anonymous install ID from `~/.composio/analytics.json` to the Dashboard in the `x-cli-install-id` header. This random UUID is never sent to the backend API. Set `COMPOSIO_CLI_TELEMETRY_DISABLED`, `TELEMETRY_DISABLED`, `COMPOSIO_DISABLE_TELEMETRY`, or `CI` to prevent the header from being sent.

### Run scripts

Reach for `composio run` when the agent needs a multi-step workflow: loops, parallel fan-out, or data transformation. It runs inline TS/JS or a file, with `execute()`, `search()`, `proxy()`, `result.prompt()`, and `z` injected.

If a tool execution fails, `execute()` rejects with the tool's error message and the failed result.

Run a single scripted workflow:

```bash theme={null}
composio run '
const messages = await execute("GMAIL_FETCH_EMAILS", {
  query: "is:unread newer_than:1d",
  max_results: 10,
});
console.log(messages);
'
```

Fan out across multiple tools:

```bash theme={null}
composio run '
const [emails, issues, events] = await Promise.all([
  execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
  execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),
  execute("GOOGLECALENDAR_FIND_EVENT", { calendar_id: "primary" }),
]);
console.log({ emails: emails.data, issues: issues.data, events: events.data });
'
```

Run a checked-in script:

```bash theme={null}
composio run --file ./workflow.ts -- --repo composiohq/composio
```

### Listen to trigger events

Use trigger listening when the agent needs to wait for new events, inspect incoming payloads, or forward events while debugging. Event streaming lives in the developer namespace:

```bash theme={null}
# Compact table view for matching events
composio dev listen --toolkits gmail --table

# Raw JSON payloads, then stop after five events
composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5

# Forward each matching event to a local or hosted webhook
composio dev listen --toolkits github --forward https://example.com/webhook

# Append matching events to a local file for an agent to inspect
composio dev listen --toolkits slack --out ./events.jsonl
```

Filter by toolkit, trigger slug, trigger ID, connected account ID, or userID to focus Claude on a single event source.

## Build on the Composio platform

Use these commands while building on the Composio developer platform. They initialize local project context, create auth configs, manage connected accounts, test tool execution, inspect logs, and debug trigger flows.

### Initialize project context

```bash theme={null}
# Initialize local project context
composio dev init

# Toggle developer mode
composio dev --mode on
composio dev --mode off

# Switch or inspect project scope
composio dev projects list
composio dev projects switch
```

### Inspect toolkits and versions

```bash theme={null}
composio dev toolkits list
composio dev toolkits search "email"
composio dev toolkits info github
composio dev toolkits version github
```

### Create and inspect auth configs

```bash theme={null}
# List existing auth configs
composio dev auth-configs list
composio dev auth-configs list --toolkits github,gmail
composio dev auth-configs info ac_xxx

# Create an auth config from provider credentials
composio dev auth-configs create "GitHub OAuth" \
  --toolkit github \
  --auth-scheme OAUTH2 \
  --scopes "repo,user" \
  --custom-credentials '{ "client_id": "...", "client_secret": "..." }'
```

### Manage connected accounts

Top-level `composio link` is the fastest path for personal knowledge work. Use the developer connected-account commands when you're building against project users, auth configs, and playground flows.

```bash theme={null}
composio dev connected-accounts list
composio dev connected-accounts list --toolkits github --user-id user_123
composio dev connected-accounts list --status ACTIVE --limit 20
composio dev connected-accounts info ca_xxx
composio dev connected-accounts whoami ca_xxx
composio dev connected-accounts link
```

### Execute and inspect logs

```bash theme={null}
# Execute a tool through the developer playground path
composio dev playground-execute GMAIL_SEND_EMAIL \
  -d '{ recipient_email: "you@example.com", subject: "Test", body: "Hello" }'

# Inspect tool and trigger logs
composio dev logs tools --toolkit gmail --limit 20
composio dev logs tools log_xxx
composio dev logs triggers --limit 20
```

### Work with triggers

```bash theme={null}
composio dev triggers list gmail
composio dev triggers info GMAIL_NEW_GMAIL_MESSAGE
composio dev triggers status
composio dev triggers create GMAIL_NEW_GMAIL_MESSAGE
composio dev triggers enable ti_xxx
composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5
```

### Generate type definitions

For legacy direct tool execution projects, generate local TypeScript or Python types from tool schemas:

```bash theme={null}
composio generate
composio generate ts --toolkits github,gmail
composio generate py --toolkits github,gmail
```

Reach for this section when you're debugging auth configs, connected accounts, trigger delivery, or tool execution in a Composio project. For user-facing app development, start with the SDK and session docs and keep the CLI as a local debugging companion.

## Building on top of the CLI

> [!WARNING]
>
> Don't build a production integration on top of the CLI. It's in constant development, and Composio doesn't offer CLI-level SLAs as an application runtime contract. For a stable integration, build on the Composio SDKs and APIs instead.

That said, the CLI works well as a bootstrap or helper layer for agent-native products:

* Use `composio connections list` to inspect which connected accounts are available locally.
* Use `composio run` or `composio proxy` for internal automations where CLI churn is acceptable.

For an example of a product built around CLI-driven agent workflows, see [Houston](https://github.com/gethouston/houston).

## Help

Use `--help` on the root command or any subcommand:

```bash theme={null}
composio --help
composio help
composio execute --help
composio run --help
composio dev projects switch --help
```
