Unattended agent authenticationWhen no human is available to log in,
composio login --agent provisions or reuses an agent account without a browser. See Authenticate an unattended agent for constraints, application API key setup, and live-tool verification.Install
Install the CLI with one command:~/.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.
Open a new terminal, then log in:
auto detects supported agents on your machine. Use --target codex or --target claude to configure only one. See Agent plugins 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:
Backend and Dashboard configuration
The CLI uses the backend recorded bycomposio 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:COMPOSIO_INSTALL_VERSION:
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:
- zsh
- bash
- fish
~/.zshrc and delegates setup to composio install --shell zsh.COMPOSIO_INSTALL_SHELL=none to leave shell files unchanged. For an install-only run in CI or Docker, also disable plugin setup:
zsh.sh, bash.sh, and fish.sh in the repository’s install/ directory) 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
Update
~/.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, then install the complete bundle. Keep the support files beside the executable.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.
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.
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: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:
Use
composio proxy when the agent already knows the provider’s API endpoint and just needs Composio to inject auth from your connected account:
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.
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 forcomposio 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:
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: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
Inspect toolkits and versions
Create and inspect auth configs
Manage connected accounts
Top-levelcomposio 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.
Execute and inspect logs
Work with triggers
Generate type definitions
For legacy direct tool execution projects, generate local TypeScript or Python types from tool schemas:Building on top of the CLI
That said, the CLI works well as a bootstrap or helper layer for agent-native products:- Use
composio connections listto inspect which connected accounts are available locally. - Use
composio runorcomposio proxyfor internal automations where CLI churn is acceptable.
Help
Use--help on the root command or any subcommand: