Composio CLI 完全指南工具发现、执行、账户连接与类型生成的开发者工作台【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读composio/cli是 Composio 平台的官方命令行工具集工具搜索、工具执行、账户连接、脚本化工作流与类型桩type stub生成于一身。本文以 ts/packages/cli/README.md 为骨架结合仓库内 src/commands 与 src/services 等目录的源码实现完整覆盖 CLI 的全局用法、全部子命令、环境变量配置体系、缓存机制以及开发构建流程。读完本文你将能够熟练使用composio完成登录、搜索与执行工具、连接账户、运行 TS/JS 工作流、生成 Python/TypeScript 类型桩并理解其底层实现原理。CLI 概览基于 Effect 生态的命令行工作台根据 ts/packages/cli/README.md 的定义该 CLI 支持两类工作流根级工作流root workflows搜索并执行工具search/execute开发者导向的dev命令管理项目init、触发器triggers、日志logs、工具包toolkits、认证配置auth configs、账户accounts、组织orgs与项目projects。技术栈如下见 ts/packages/cli/package.json 的dependencies与devDependencies技术在 CLI 中的角色TypeScript全部源码语言类型系统贯穿命令定义与配置解析Effect 生态effect、effect/unstable/cli命令树构建、参数解析、依赖注入Layer、错误处理与重试调度Bun运行时与构建工具bun run build、bun run build:binaryVitest测试运行器bun run test会先执行技能/边界校验再跑 vitest从源码入口看CLI 的启动分为两步src/bin.ts 只负责读取一次process.argv剥离--telemetry-debug调试标志然后动态导入 src/cli-main.ts 中的runClicli-main通过Layer.mergeAll组装了文件系统、HTTP 客户端、用户上下文、会话仓库、工具包仓库、工具执行器等二十余个服务层最终交给effect/unstable/cli的Command.runWith驱动根命令。值得一提的细节是 src/commands/index.ts 中normalizeVersionFlag会把composio --version/composio -v统一改写为version命令保证三种拼写输出逐字节一致。全局用法与可选 Flagscomposio [--log-level All|Trace|Debug|Info|Warn|Error|Fatal|None]--log-level设置日志详细级别。可接受的值大小写敏感All、Trace、Debug、Info、Warn、Error、Fatal、None。在源码层面该 flag 通过 src/commands/$default.cmd.ts 的withRootLogLevel挂载到根命令日志级别也可通过环境变量COMPOSIO_LOG_LEVEL配置见下文配置章节两者最终都会影响 Effect 运行时的MinimumLogLevel见 src/services/config.ts 中的LoggerFromConfigLive。--install-skill [skill-name] claude|codex|openclaw当自动安装失败时手动为受支持的 Agent 安装 Composio 技能。--instal-skill拼写错误的历史别名仍被接受以保证向后兼容。对应实现位于 src/commands/index.tsROOT_INSTALL_SKILL_FLAGS同时收录了--install-skill与--instal-skill两种拼写SKILL_INSTALL_TARGETS定义了三种合法目标claude、codex、openclaw。解析失败缺目标、目标非法、参数过多会返回带明确用法提示的RootCommandError。命令参考身份与会话管理composio version等价composio --version/composio -v显示当前 CLI 版本。版本来源见 src/constants.ts 的APP_VERSION发布构建会将__COMPOSIO_CLI_RELEASE_VERSION__替换为 GitHub release 的精确版本未发布构建回退到package.json的私有版本号仅作源码/开发回退绝不用于二进制发布选择。composio whoami显示当前登录用户/账户。composio login [--no-browser] [--no-wait] [--key text] [--user-api-key text] [--org text] [-y, --yes] [--no-skill-install]登录 Composio CLI 会话。composio logout登出当前 CLI 会话。composio orgs list|switch查看并切换默认组织上下文。登录完成后输出的提示中也包含composio orgs switch --org-id org_id用法见 src/commands/login.cmd.ts。login 源码细节登录命令的完整实现位于 src/commands/login.cmd.ts支持多种登录路径参数含义备注--no-browser不自动打开浏览器改为打印登录 URL非交互环境推荐--no-wait打印登录 URL 与会话信息后立即退出不等待隐式等价于--no-browser--key key使用composio login --no-wait产生的会话 key 完成登录不带--no-wait时轮询至 linked带--no-wait时只检查一次--user-api-key uak直接使用 Composio 用户 API key 登录跳过浏览器流程可与--org组合指定组织--org org指定当前组织 ID 或名称仅当配合--user-api-key时合法-y, --yes跳过组织选择器使用当前组织--no-skill-install跳过为 Claude Code 安装 composio-cli 技能--agent使用 Composio agent 身份注册/登录适合无人值守场景源码中有明确警告有人在场时勿用--poll轮询最近一次待完成的浏览器登录不能与浏览器/会话/直登/agent 类 flag 组合参数之间的互斥校验如--key与--user-api-key不能同时使用、--org必须配合--user-api-key、--agent不能与浏览器类 flag 组合均在 handler 开头强制执行。登录采用浏览器 OAuth 流程先创建 CLI session打开浏览器失败则回退为打印 URL随后以指数退避 5 秒间隔的调度最多 15 次轮询直到 session 状态变为linked再用拿到的 UAK形如uak_b813ydmoEYdB_xBxGHeW调用session/info丰富组织/项目元数据并落盘。待办登录会话会写入缓存目录下的pending-login-session.jsonTTL 为 10 分钟。工具发现与执行composio search query... [--toolkits text] [--limit integer] [--human]按用例跨工具包/应用查找工具。实现见 src/commands/tools/commands/tools.search.cmd.ts。composio execute slug [-d, --data text] [--dry-run] [--get-schema]按 slug 执行工具执行前做 schema 与连接检查。实现见 src/commands/tools/commands/tools.execute.cmd.ts该文件还支持tools execute的并行执行入口runParallelToolsExecuteFromArgv。composio link [toolkit] [--no-wait]为工具包/应用连接账户。实现见 src/commands/connected-accounts/commands/connected-accounts.link.cmd.ts。composio tools list|info查看可用工具及其缓存 schema。命令树定义见 src/commands/tools/tools.cmd.ts。composio triggers list toolkit|info查看工具包范围内的触发器类型及 schema见 src/commands/triggers/root-triggers.cmd.ts。工作流运行与代理composio run code [-- ...args]或composio run --file path [-- ...args]以行内或文件方式运行 TS/JS 工作流并注入 Composio helpers如execute()。run命令的实现细节非常值得展开见 src/commands/run.cmd.tsFlag含义--file,-f path运行 TS/JS 文件而非行内代码--dry-run只预览execute()调用不真正执行--debug脚本运行时输出 helper 步骤日志--logs-off隐藏 helper 流式日志仅保留在运行日志文件中--skip-connection-check跳过 connected-account 检查--skip-tool-params-check跳过对缓存 schema 的输入校验--skip-checks同时跳过连接检查与输入校验composio run会把--之后的所有参数原样透传给用户脚本。由于effect/unstable/cli的词法解析器会把所有-前缀 token 当作选项候选src/commands/index.ts 中的splitRunPassthroughArgs在交给 CLI 解析器之前就先把透传参数从 argv 中剥离出来通过RunPassthroughArgsContext 引用以带外out-of-band方式传给 handler从而保证脚本参数包括后续的--逐字到达脚本。composio proxy url --toolkit toolkit [-X method] [-H header]... [-d data]通过已连接账户直接调用工具包的 API等价于以 curl 风格访问 toolkit API见 src/commands/proxy.cmd.ts。连接与产物管理composio connections list [--toolkit toolkit]以 JSON 形式打印工具包连接状态见 src/commands/connections/connections.cmd.ts。composio connections remove account确认后交互式移除工具包连接。composio artifacts cwd打印当前工作目录cwd作用域的 CLI 会话产物目录实现见 src/commands/artifacts.cmd.ts 与 src/services/cli-session-artifacts.ts。开发者命令composio dev subcommand开发者工作流覆盖 init、playground 执行、日志、工具包、认证配置、账户、触发器、组织与项目。命令树构建见 src/commands/dev.cmd.ts各子命令位于 src/commands 下的auth-configs/、logs-cmd/、toolkits/、triggers/、orgs/、projects/、connected-accounts/等目录。值得注意的安全设计见 src/commands/index.tsdev命令默认要求开发者模式开启否则提示Run \composio dev --mode on其中dev triggers disable被标记为危险命令需要配置developer.destructive_actions为true位于~/.composio/config.json且显式追加--dangerously-allow 才会执行。composio generate [-o, --output-dir directory] [--toolkits toolkit] [--type-tools]自动探测项目语言Python 或 TypeScript为工具包、工具和触发器生成类型桩。入口见 src/commands/generate/generate.cmd.ts生成逻辑在 src/generation 目录python/与typescript/两个子目录分别实现两种语言。composio generate py [-o, --output-dir directory] [--toolkits toolkit]从 Composio API 生成 Python 类型桩。composio generate ts [-o, --output-dir directory] [--compact] [--transpiled] [--type-tools] [--toolkits toolkit]从 Composio API 生成 TypeScript 类型。自升级composio upgrade [--beta]从稳定渠道自更新 CLI--beta别名-b从 beta 渠道更新。实现见 src/commands/upgrade.cmd.ts除了--beta还支持可选版本参数如0.13.1、0.13.1-beta.42或完整 tagcomposio/cli0.13.1版本号会被normalizeReleaseTag归一化为composio/clisemver格式升级完成后还会顺带安全安装配套技能installSkillSafe。配置体系环境变量与 JSON 配置CLI 支持通过环境变量配置。认证用户上下文存放在user_data.json通用 CLI 设置存放在config.json对应文件名常量见 src/constants.ts 的USER_CONFIG_FILE_NAME与CLI_CONFIG_FILE_NAME。默认情况下两个文件都存放在~/.composio可用COMPOSIO_CACHE_DIR环境变量指定自定义位置。核心环境变量环境变量JSON 配置说明默认值COMPOSIO_USER_API_KEYuser_data.json:api_keyComposio 用户 API keyNoneCOMPOSIO_ENVIRONMENT-选择生产或 staging URL 默认值productionCOMPOSIO_BASE_URLuser_data.json:base_urlComposio 后端 API 的 base URLhttps://backend.composio.devCOMPOSIO_WEB_URLuser_data.json:web_urlComposio Web 应用的 base URLhttps://dashboard.composio.dev/COMPOSIO_CACHE_DIR-CLI 存储缓存文件的目录~/.composioCOMPOSIO_SESSION_DIRconfig.json:artifact_directoryCLI 会话产物的根目录COMPOSIO_CACHE_DIR其次artifact_directory最后$TMPDIR/composioCOMPOSIO_BIN_DIR-composio install加入PATH的目录见下文由正在运行的二进制解析COMPOSIO_LOG_LEVEL-CLI 日志级别大小写敏感All, Trace, Debug, Info, Warn, Error, Fatal, NoneNoneCOMPOSIO_ORG_ID-项目级命令使用的组织 ID当前项目COMPOSIO_PROJECT_ID-项目级命令使用的项目 ID当前项目COMPOSIO_AGENTS_BASE_URL-Composio agents 服务的 base URLhttps://agents.composio.devCOMPOSIO_WEBHOOK_SECRET-composio dev triggers listen转发事件的签名密钥为当前会话生成COMPOSIO_DISABLE_CONNECTED_ACCOUNT_CACHE-禁用 connected-account 缓存trueCOMPOSIO_PERF_DEBUG-设为1时写入性能诊断0COMPOSIO_TOOL_DEBUG-设为1时写入工具诊断0DEBUG_OVERRIDE_VERSION-升级 CLI 时使用的版本调试用NoneFORCE_USE_CACHE-是否强制使用先前缓存的 HTTP 响应NoneNO_COLOR-设置后禁用 CLI 彩色输出遵循 no-color.org 约定None源码级解读配置读取基于 Effect 的ConfigProvider。src/services/config.ts 中的getBaseConfigProvider()每次调用都从当前进程环境新建ConfigProvider.fromEnv()快照避免模块级常量冻结环境extendConfigProvider负责给配置 key 统一加上COMPOSIO_前缀DEBUG_OVERRIDE_与FORCE_开头的 key 除外。也就是说源码里用Config.string(USER_API_KEY)读取实际生效的环境变量就是COMPOSIO_USER_API_KEY。staging 环境的 URL 常量https://staging-backend.composio.dev与https://staging-dashboard.composio.dev/定义在 src/constants.ts。CLI 内部协调变量以下变量由 CLI 及其安装器用于协调嵌套命令不用于手动配置环境变量说明默认值COMPOSIO_CLI_INVOCATION_ORIGIN标识是否由另一个 CLI 表面如composio run调用cliCOMPOSIO_CLI_PARENT_RUN_ID复用父级 run ID 用于嵌套命令遥测NoneCOMPOSIO_RUN_ACP_ONLY设为1时禁用旧版子代理回退0COMPOSIO_RUN_OUTPUT_DIR让嵌套的composio run命令共享同一个产物目录Nonecomposio upgrade专用环境变量环境变量说明默认值COMPOSIO_GITHUB_API_BASE_URLGitHub API 的 base URLhttps://api.github.comCOMPOSIO_GITHUB_OWNERGitHub 上 Composio 仓库的 ownerComposioHQCOMPOSIO_GITHUB_REPOComposio CLI 的仓库名composioCOMPOSIO_GITHUB_TAG拉取 Composio CLI 二进制时使用的 taglatestCOMPOSIO_GITHUB_ACCESS_TOKENGitHub API 访问令牌开发时避免被 GitHub 限流None对应仓库元信息常量定义在 src/constants.ts 的GITHUB_REPO。用COMPOSIO_BIN_DIR指定 PATH 条目composio install会在 shell 配置中写入一行PATH配置。该目录按以下顺序解析设置了COMPOSIO_BIN_DIR且为绝对路径时使用它~/.local/bin中的composio入口解析到正在运行的二进制时使用它否则使用正在运行二进制所在目录。当用户需要触达的入口点不是二进制本身而是 shim、符号链接农场或版本管理器的bin目录时设置COMPOSIO_BIN_DIRCOMPOSIO_BIN_DIR$HOME/.local/bin composio install当解析出的目录是相对路径或包含无法安全嵌入带引号 rc 行的字符、$、、\、换行符或:PATH 分隔符时命令会以非零退出码中止且不写入任何内容。CLI 二进制发布标签CLI 二进制以 GitHub release 资产形式发布当前 tag 格式composio/clisemver例如composio/cli0.1.24临时兼容迁移期间旧式vsemvertag 也受支持兼容窗口期内composio upgrade与install.sh均可解析两种格式。如需用COMPOSIO_GITHUB_TAG固定升级版本推荐使用包作用域 tag 格式COMPOSIO_GITHUB_TAGcomposio/cli0.1.24 composio upgrade从 beta 渠道拉取替代稳定渠道composio upgrade --beta插件安装的发布依赖composio setup从以下公开市场仓库安装插件Claude CodeComposioHQ/composio-plugin-ccCodexComposioHQ/composio-plugin-openai发布一个宣传自动插件安装的 CLI 版本前两个仓库都必须公开可访问且包含composiocomposio入口。CLI release 还必须包含composio-skill.zipClaude 安装会使用该独立技能而 Codex 插件自带一份副本。对应的安装器实现可参考 src/commands/setup.cmd.ts、src/commands/install.cmd.ts 与 src/services/setup-skill-installer.ts。缓存系统面向离线与性能的文件缓存CLI 实现了基于文件的缓存系统用于提升性能与离线可用性。缓存特性Cache-first 读取当FORCE_USE_CACHEtrue时CLI 在发起 API 调用前先检查缓存。如果你之前运行过composio generate即使离线也能正常工作。Best-effort 写入所有成功的 API 响应都会自动落盘缓存供后续使用。写入是原子的——写入中途被中断不会留下截断文件而是保留之前的完整缓存。优雅回退缓存文件损坏或缺失时CLI 回退为发起 API 调用。参数感知缓存带参数的调用方法会把参数纳入缓存 key。缓存结构缓存文件存放在COMPOSIO_CACHE_DIR环境变量指定的目录若设置否则是~/.composio/。被缓存的文件包括文件内容toolkits.json工具包列表结果tools-as-enums.json工具枚举列表结果tools.json工具列表结果trigger-types-as-enums.json触发器类型枚举结果trigger-types.json分页触发器类型 payload 结果文件名常量同样定义在 src/constants.ts 的CACHE_FILENAMESsession.json、toolkits.json、tools.json、trigger-types.json带缓存的客户端实现见 src/services/composio-clients-cached.ts。known-toolkit-slugs.jsonknown-toolkit-slugs.json也位于缓存目录但它不属于上述 API 响应缓存文件。执行工具意味着要知道它属于哪个工具包而工具 slug 本身并不能说明GOOGLE_ANALYTICS_RUN_REPORT属于google_analytics而非google。CLI 内置了构建时存在的工具包 slug 列表之后学习到的新 slug 会记录在该文件中因此解析工具包只需一次小型本地读取无需下载整个目录。它是派生数据而非保存的 API 响应因此无论FORCE_USE_CACHE如何设置每次运行都会读取——该变量保持选择重放先前缓存的 API 响应的语义。删除该文件是安全的CLI 会重新学习所需内容。过期也是安全的后端永远不会移除工具包文件里没见过的 slug 只会多花一次目录拉取之后被记住并在后台每周刷新。相关实现见 src/services/known-toolkit-slugs.ts、src/services/toolkit-slug-catalog.ts 与生成脚本 ts/packages/cli/scripts/generate-toolkit-slugs.ts。从源码构建与开发以下命令均在 ts/packages/cli 目录下执行。安装依赖pnpm install构建 TypeScript 代码bun run build内部等价于tsdown bun run ./scripts/copy-local-tools-assets.ts ./dist见 package.json 的build脚本构建前会自动执行类型检查prebuild。构建自包含可执行文件bun run build:binary或bun run ./scripts/build-binary.ts安装自包含可执行文件bun run install:binary或bun run ./scripts/install-binary.ts ./dist/composio默认安装到~/.composio/composio。可通过COMPOSIO_INSTALL_DIR环境变量自定义安装目录。交互式运行bun cli内部等价于bun run src/bin.ts。例如为 TypeScript 项目生成类型桩bun cli generate ts测试bun run testtest脚本会依次执行validate:skills技能校验、validate:boundarieslint 边界校验与vitest run。测试源码位于 ts/packages/cli/test覆盖命令解析、Effect 服务层与生成逻辑test/__mocks__中的toolkits.json、tools.json、trigger-types.json等 fixture 与缓存文件一一对应test/__fixtures__则准备了 Python/TypeScript/bun/pnpm monorepo 等多种项目形态用于生成功能测试。源码结构速览src/bin.ts进程入口剥离遥测调试 flag分发后台 worker 与主命令。src/cli-main.tsEffect 层组装、根命令运行、退出码与错误渲染文件头注释详细记录了 v4 runner 的设计决策。src/commands全部子命令定义login、run、proxy、generate、dev、tools、triggers、connections、orgs、projects、auth-configs、logs-cmd、local-tools等。src/services业务服务层会话、用户上下文、工具包目录、工具执行器、升级二进制、运行时 flag 等。src/generationPython/TypeScript 类型桩生成器。src/effects可复用的 Effect 组合子版本解析、技能安装、工具包解析、原子写文件等。src/constants.tsURL、缓存文件名、GitHub 仓库元信息等常量。scripts构建二进制、生成 checksum、录制终端演示等开发脚本。test命令与服务的单元/集成测试。总结composio/cli是一个把发现工具 → 连接账户 → 执行动作 → 沉淀产物串成一条流水线的开发者工具。它继承了 Effect 生态的类型安全与依赖注入能力通过search/execute覆盖工具生命周期通过login/link/connections管理认证状态通过run/proxy支撑脚本化工作流与直接 API 调用通过generate为 Python/TypeScript 项目产出类型桩并依靠一套参数感知的原子文件缓存保障离线可用性。无论是交互式探索工具还是在 CI 中自动化生成类型掌握上述命令与环境变量配置即可充分发挥该 CLI 的能力。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考