This package defines the Composio CLI used to interact with the Composio platform. It supports root workflows for searching and executing tools, plus developer-oriented dev commands for project, trigger, log, and connected-account management.

Overview

The CLI is built using:

🧑‍💻 Usage

composio [--log-level all|trace|debug|info|warning|error|fatal|none]

Optional Flags

--log-level: Set the log verbosity level. Accepted values: all, trace, debug, info, warning, error, fatal, none
--install-skill [skill-name] <claude|codex|openclaw>: Manually install the composio skill for a supported agent when automatic installation fails. --instal-skill is still accepted as a backward-compatible alias.

🧭 Commands

composio version: Display the current CLI version.
composio whoami: Show the currently logged-in user/account.
composio login [--no-browser] [--no-wait] [--key text] [--user-api-key text] [--org text] [-y, --yes] [--no-skill-install]: Log in to the Composio CLI session.
composio logout: Log out from the Composio CLI session.
composio orgs list|switch: Inspect and switch your default organization context.
composio search <query...> [--toolkits text] [--limit integer] [--human]: Find tools by use case across toolkits/apps.
composio execute <slug> [-d, --data text] [--dry-run] [--get-schema]: Execute a tool by slug, with schema and connection checks.
composio link [<toolkit>] [--no-wait]: Connect an account for a toolkit/app.
composio run <code> [-- ...args] or composio run --file <path> [-- ...args]: Run inline or file-based TS/JS workflows with Composio helpers injected.
composio proxy <url> --toolkit <toolkit> [-X method] [-H header]... [-d data]: Call a toolkit API directly through Composio using a connected account.
composio tools list|info: Inspect available tools and their cached schemas.
composio triggers list <toolkit>|info: Inspect toolkit-scoped trigger types and their schemas.
composio connections list [--toolkit <toolkit>]: Print toolkit connection statuses as JSON.
composio connections remove <account>: Interactively remove a toolkit connection after confirmation.
composio artifacts cwd: Print the cwd-scoped CLI session artifacts directory.
composio dev <subcommand>: Developer workflows for init, playground execution, logs, toolkits, auth configs, accounts, triggers, orgs, and projects.
composio generate [-o, --output-dir <directory>] [--toolkits <toolkit>] [--type-tools]: Auto-detect the project language (Python or TypeScript) and generate type stubs for toolkits, tools, and triggers.
composio generate py [-o, --output-dir <directory>] [--toolkits <toolkit>]: Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
composio generate ts [-o, --output-dir <directory>] [--compact] [--transpiled] [--type-tools] [--toolkits <toolkit>]: Generate TypeScript types for toolkits, tools, and triggers from the Composio API.
composio upgrade [--beta]: Self-update the Composio CLI from the stable channel, or from the beta channel with --beta.
composio --install-skill [skill-name] <claude|codex|openclaw>: Manually install the composio skill for Claude, Codex, or OpenClaw.

Configuration

The Composio CLI supports configuration via environment variables. Additionally, for storing and retrieving user session context, a user_data.json JSON configuration file is used.

By default, this file is stored in ~/.composio, but you can specify a custom location using the COMPOSIO_CACHE_DIR environment variable.

Environment Variable	User JSON config	Description	Default
COMPOSIO_API_KEY	`api_key`	Composio backend API key	None
COMPOSIO_BASE_URL	`base_url`	The base URL of the Composio backend API	https://backend.composio.dev
COMPOSIO_WEB_URL	`web_url`	The base URL of the Composio web app	https://dashboard.composio.dev/
COMPOSIO_CACHE_DIR	-	The directory where the Composio CLI stores cache files	~/.composio
COMPOSIO_LOG_LEVEL	-	The log level for the Composio CLI	None
DEBUG_OVERRIDE_VERSION	-	The version to use when upgrading the Composio CLI (for debugging)	None
FORCE_USE_CACHE	-	Whether to force the use of previously cached HTTP responses	None
NO_COLOR	-	If set, disables color output in the CLI (https://no-color.org/)	None

Additionally, composio upgrade supports the following environment variables:

Environment Variable	Description	Default
COMPOSIO_GITHUB_API_BASE_URL	The base URL for the GitHub API	https://api.github.com
COMPOSIO_GITHUB_OWNER	The owner of the Composio repository on GitHub	ComposioHQ
COMPOSIO_GITHUB_REPO	The repository name for the Composio CLI	composio
COMPOSIO_GITHUB_TAG	The tag to use when fetching the Composio CLI binary from Github	latest
COMPOSIO_GITHUB_ACCESS_TOKEN	The access token for the GitHub API. Useful during development to avoid getting rate-limited by Github	None

CLI binary release tags

CLI binaries are published as GitHub release assets.

Current tag format: @composio/cli@<semver> (for example @composio/cli@0.1.24)
Temporary compatibility: legacy v<semver> tags are also supported during migration
composio upgrade and install.sh can resolve either format during the compatibility window

If you pin upgrades with COMPOSIO_GITHUB_TAG, prefer the package-scoped tag format:

COMPOSIO_GITHUB_TAG='@composio/cli@0.1.24' composio upgrade

To pull from the beta channel instead of the stable channel:

composio upgrade --beta

Caching

The CLI implements a file-based caching system for improved performance and offline capabilities.

Cache Features

Cache-first reads: When FORCE_USE_CACHE=true, the CLI first checks for cached data before making API calls. If you already ran composio generate before, it will work even if you're offline.
Best-effort writes: All successful API responses are automatically cached to disk for future use.
Graceful fallback: If cache files are corrupted or missing, the CLI falls back to making API calls.
Parameter-aware caching: Methods with parameters include those parameters in the cache key.

Cache Structure

Cache files are stored in the directory specified by:

COMPOSIO_CACHE_DIR environment variable (if set)
~/.composio/ directory (default)

The following files are cached:

toolkits.json - Results from toolkit listings
tools-as-enums.json - Results from tool enum listings
tools.json - Results from tool listings
trigger-types-as-enums.json - Results from trigger type enumerations
trigger-types.json - Results from paginated trigger types payloads

Development

Installation

pnpm install

Build TypeScript code

bun run build

Build self-contained executable

bun run build:binary

bun run ./scripts/build-binary.ts

Install self-contained executable

bun run install:binary

bun run ./scripts/install-binary.ts ./dist/composio

By default, the executable will be installed in ~/.composio/composio. You can customize the installation directory by setting the COMPOSIO_INSTALL_DIR environment variable.

Run interactively

bun cli

For instance, to generate type stubs for a TypeScript project, you can run:

bun cli generate ts

Test

bun run test