Toolkit Versions

Pin specific toolkit versions using environment variables

The Composio CLI supports pinning specific toolkit versions using environment variables. This allows you to control which version of each toolkit is used when generating type definitions.

Overview

Toolkit versions determine the available tools and their schemas for each integration. By default, the CLI uses the latest version for all toolkits. You can override this behavior to:

• Pin specific versions for reproducible builds
• Test against older versions for compatibility
• Preview new features in specific toolkit versions

Toolkit version overrides only apply when using the --type-tools flag with composio generate or composio ts generate.

Environment Variable Format

To override a toolkit version, set an environment variable:

COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_SLUG>=<version>

Format:

• <TOOLKIT_SLUG> - Uppercase toolkit name (e.g., GMAIL, GITHUB, SLACK)
• <version> - Version identifier or latest

Examples

Pin a Single Toolkit

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
composio generate --type-tools

Generates types using Gmail toolkit version 20250901_00 and latest for all others.

Pin Multiple Toolkits

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
export COMPOSIO_TOOLKIT_VERSION_GITHUB=20241215_00
export COMPOSIO_TOOLKIT_VERSION_SLACK=20250115_00
composio generate --type-tools --toolkits gmail --toolkits github --toolkits slack

Use Latest Version Explicitly

export COMPOSIO_TOOLKIT_VERSION_GMAIL=latest
composio generate --type-tools --toolkits gmail

Explicitly uses the latest version (same as not setting the variable).

Mixed Versions

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00    # Specific version
export COMPOSIO_TOOLKIT_VERSION_GITHUB=latest        # Latest version
composio generate --type-tools

Version Discovery

To find available versions for a toolkit:

composio toolkits version <toolkit-slug>

Example:

composio toolkits version gmail

Output:

┌─────────────────────────────────────────────────────┐
│ Gmail Toolkit Versions                              │
├─────────────────────────────────────────────────────┤
│ - 20250901_00 (latest)                              │
│ - 20250815_00                                       │
│ - 20250701_00                                       │
│ - 20250615_00                                       │
└─────────────────────────────────────────────────────┘

Validation

The CLI validates toolkit version overrides before fetching data:

1. Detects overrides from environment variables
2. Logs detected versions for transparency
3. Validates against API to ensure versions exist
4. Warns about unused overrides when using --toolkits filter

Example output:

◇  Toolkit version overrides detected:
│  - gmail: 20250901_00
│  - github: 20241215_00
│
◇  Validating toolkit versions...
│
◆  Warning: Toolkit version override for 'slack' is not used (not in --toolkits filter)

Behavior with —type-tools

With —type-tools (Versions Apply)

When using --type-tools, the CLI fetches full tool schemas with version support:

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
composio generate --type-tools --toolkits gmail

What happens:

1. Fetches Gmail toolkit version 20250901_00
2. Generates full type definitions for tools in that version
3. Includes input/output schemas

Without —type-tools (Versions Ignored)

Without --type-tools, the CLI only fetches tool names (not full schemas), so versions don’t apply:

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
composio generate --toolkits gmail
# Version override is ignored

What happens:

1. Fetches Gmail toolkit metadata (no version)
2. Generates tool name enums only (e.g., GMAIL_SEND_EMAIL)
3. No input/output schemas

Toolkit version overrides are only meaningful when using --type-tools. Without it, all toolkits use the latest version implicitly.

Version Map Output

When version overrides are applied, the generated code includes a version map:

TypeScript output:

export const ToolkitVersions = {
  gmail: "20250901_00",
  github: "20241215_00",
} as const;

This allows you to track which versions were used during generation.

Use Cases

Reproducible Builds

Pin toolkit versions in CI/CD for consistent builds:

# .env.production
export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
export COMPOSIO_TOOLKIT_VERSION_GITHUB=20241215_00
export COMPOSIO_TOOLKIT_VERSION_SLACK=20250115_00

# CI script
source .env.production
composio generate --type-tools

Testing Against Older Versions

Test compatibility with a previous toolkit version:

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250701_00
composio generate --type-tools --toolkits gmail
npm test

Preview New Features

Test new toolkit features before they’re widely available:

export COMPOSIO_TOOLKIT_VERSION_GMAIL=latest
composio generate --type-tools --toolkits gmail

Version Lock File

Create a version lock file for your project:

# toolkit-versions.env
COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
COMPOSIO_TOOLKIT_VERSION_GITHUB=20241215_00
COMPOSIO_TOOLKIT_VERSION_SLACK=20250115_00
COMPOSIO_TOOLKIT_VERSION_NOTION=20250120_00

Load it before generation:

source toolkit-versions.env
composio generate --type-tools

Filtering and Versions

When using --toolkits to filter generation, the CLI warns about unused version overrides:

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
export COMPOSIO_TOOLKIT_VERSION_SLACK=20250115_00
composio generate --type-tools --toolkits gmail

Output:

◇  Toolkit version overrides detected:
│  - gmail: 20250901_00
│  - slack: 20250115_00
│
◆  Warning: Toolkit version override for 'slack' is not used (not in --toolkits filter)
│
◇  Fetching data for 1 toolkit(s): gmail...

The slack override is ignored because slack is not in the --toolkits filter.

Version Naming Convention

Composio toolkit versions follow the format:

YYYYMMDD_NN

• YYYYMMDD - Release date (e.g., 20250901 = September 1, 2025)
• NN - Revision number (e.g., 00, 01)

Examples:

• 20250901_00 - First release on September 1, 2025
• 20250901_01 - Second release on September 1, 2025
• latest - Most recent version

Troubleshooting

Invalid Version

If you specify a non-existent version:

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20990101_00
composio generate --type-tools --toolkits gmail

Error:

Error: Toolkit version '20990101_00' not found for toolkit 'gmail'.
Available versions: 20250901_00, 20250815_00, 20250701_00

Solution: Use composio toolkits version gmail to list available versions.

Version Override Ignored

If your version override doesn’t apply:

export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
composio generate --toolkits gmail
# No error, but version is not used

Reason: --type-tools flag is missing.

Solution: Add --type-tools:

composio generate --type-tools --toolkits gmail

Case Sensitivity

Environment variable names are case-sensitive:

# Wrong (lowercase)
export composio_toolkit_version_gmail=20250901_00

# Correct (uppercase)
export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00

Related Commands

• composio generate - Generate types with version control

Next Steps

Environment Variables

Configure the CLI

Generate Command

Generate type-safe code