Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import * as fs from 'node:fs'; |
| 2 | import * as path from 'node:path'; |
| 3 | import { CLI_EXPERIMENTAL_FEATURES } from '../../src/experimental-features'; |
| 4 | import { composioDevReference } from './references/composio-dev'; |
| 5 | import { powerUserExamplesReference } from './references/power-user-examples'; |
| 6 | import { troubleshootingReference } from './references/troubleshooting'; |
| 7 | import { |
| 8 | isEnabledForBuild, |
| 9 | renderReferenceDocument, |
| 10 | resolveSkillBuildContext, |
| 11 | validateReferenceDocument, |
| 12 | type SkillBuildContext, |
| 13 | type SkillFeatureFlag, |
| 14 | type SkillReleaseChannel, |
| 15 | } from './reference-schema'; |
| 16 | |
| 17 | // Re-exported for scripts/build-skills.ts, which maps the --channel CLI |
| 18 | // flag onto the build pipeline's channel type. |
| 19 | export type { SkillReleaseChannel }; |
| 20 | |
| 21 | type SkillFlag = { |
| 22 | description: string; |
| 23 | name: string; |
| 24 | features?: SkillFeatureFlag[]; |
| 25 | }; |
| 26 | |
| 27 | type SkillExample = { |
| 28 | code: string; |
| 29 | description?: string; |
| 30 | features?: SkillFeatureFlag[]; |
| 31 | }; |
| 32 | |
| 33 | type SkillCommand = { |
| 34 | id: string; |
| 35 | title: string; |
| 36 | summary?: string; |
| 37 | features?: SkillFeatureFlag[]; |
| 38 | intro?: string[]; |
| 39 | flags?: SkillFlag[]; |
| 40 | examples?: SkillExample[]; |
| 41 | notes?: string[]; |
| 42 | extraBody?: Array<{ |
| 43 | features?: SkillFeatureFlag[]; |
| 44 | markdown: string; |
| 45 | }>; |
| 46 | }; |
| 47 | |
| 48 | const sourceAssetsDir = path.resolve(import.meta.dirname, './assets'); |
| 49 | |
| 50 | const frontmatter = { |
| 51 | name: 'composio-cli', |
| 52 | description: |
| 53 | 'Help users operate the published Composio CLI to find the right tool, connect accounts, inspect schemas, execute tools, subscribe to trigger events with `composio listen`, script workflows with `composio run`, and call authenticated app APIs with `composio proxy`. Use when the user asks how to do something with `composio`, wants to run a known tool slug, needs to discover a slug with `composio search`, fix a missing connection with `composio link`, inspect tool inputs with `--get-schema` or `--dry-run`, troubleshoot top-level CLI flows, or explicitly needs `composio dev` guidance.', |
| 54 | }; |
| 55 | |
| 56 | const commands: SkillCommand[] = [ |
| 57 | { |
| 58 | id: 'execute', |
| 59 | title: '`execute` - Run A Tool', |
| 60 | summary: 'Use `execute` when the tool slug is already known.', |
| 61 | flags: [ |
| 62 | { |
| 63 | name: '`--get-schema`', |
| 64 | description: 'Inspect required arguments without executing the tool.', |
| 65 | }, |
| 66 | { |
| 67 | name: '`--dry-run`', |
| 68 | description: 'Preview the request shape without performing the action.', |
| 69 | }, |
| 70 | { |
| 71 | name: '`--file`', |
| 72 | description: |
| 73 | 'Inject a local file path into a tool that exposes exactly one uploadable file argument.', |
| 74 | }, |
| 75 | { |
| 76 | name: '`--parallel`', |
| 77 | description: 'Execute multiple independent tool calls in the same invocation.', |
| 78 | }, |
| 79 | { |
| 80 | name: '`--account`', |
| 81 | description: |
| 82 | 'Select which connected account to use by alias, word_id, or account id when multiple accounts exist for the same toolkit.', |
| 83 | }, |
| 84 | ], |
| 85 | examples: [ |
| 86 | { |
| 87 | code: "composio execute GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'", |
| 88 | }, |
| 89 | { |
| 90 | description: 'Inspect required inputs without executing', |
| 91 | code: 'composio execute GITHUB_CREATE_AN_ISSUE --get-schema', |
| 92 | }, |
| 93 | { |
| 94 | description: 'Preview safely', |
| 95 | code: 'composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d \'{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }\'', |
| 96 | }, |
| 97 | { |
| 98 | description: 'Pass data from a file or stdin', |
| 99 | code: 'composio execute GITHUB_CREATE_AN_ISSUE -d @issue.json\ncat issue.json | composio execute GITHUB_CREATE_AN_ISSUE -d -', |
| 100 | }, |
| 101 | { |
| 102 | description: 'Upload a local file', |
| 103 | code: 'composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \\\n --file ./image.png \\\n -d \'{ channels: "C123" }\'', |
| 104 | }, |
| 105 | { |
| 106 | description: 'Run independent tool calls in parallel', |
| 107 | code: 'composio execute --parallel \\\n GMAIL_SEND_EMAIL -d \'{ recipient_email: "a@b.com", subject: "Hi" }\' \\\n GITHUB_CREATE_AN_ISSUE -d \'{ owner: "acme", repo: "app", title: "Bug" }\'', |
| 108 | }, |
| 109 | ], |
| 110 | notes: [ |
| 111 | '`--file` only works when the tool exposes a single uploadable file input. Otherwise use explicit `-d` JSON.', |
| 112 | ], |
| 113 | }, |
| 114 | { |
| 115 | id: 'search', |
| 116 | title: '`search` - Find The Slug', |
| 117 | summary: 'Use `search` only when the tool slug is not already known.', |
| 118 | examples: [ |
| 119 | { |
| 120 | code: 'composio search "create a github issue"\ncomposio search "send an email" --toolkits gmail\ncomposio search "send an email" "create a github issue"\ncomposio search "my emails" "my github issues" --toolkits gmail,github', |
| 121 | }, |
| 122 | ], |
| 123 | notes: [ |
| 124 | 'Batch related discovery work into one `search` invocation, then move back to `execute` once the correct slugs are known.', |
| 125 | ], |
| 126 | }, |
| 127 | { |
| 128 | id: 'link', |
| 129 | title: '`link` - Connect An Account', |
| 130 | summary: |
| 131 | 'Use `link` when `execute` reports that a toolkit is not connected, or when the user explicitly wants to authorize an account.', |
| 132 | examples: [ |
| 133 | { |
| 134 | code: 'composio link gmail\ncomposio link googlecalendar --no-browser --no-wait', |
| 135 | }, |
| 136 | ], |
| 137 | flags: [ |
| 138 | { |
| 139 | name: '`--no-wait`', |
| 140 | description: |
| 141 | 'Print the authorization URL as JSON (`redirect_url`) and return at once instead of waiting for the authorization.', |
| 142 | }, |
| 143 | { |
| 144 | name: '`--alias`', |
| 145 | description: |
| 146 | 'Assign an alias to the connected account. Required when creating an additional account for the same toolkit.', |
| 147 | }, |
| 148 | ], |
| 149 | notes: [ |
| 150 | "When the user has to open the page themselves, run `link` with `--no-wait`, show them the `redirect_url`, and wait for them to say they approved. Without `--no-wait` the command blocks until the authorization completes, so the URL reaches the user only if they can see the command's output.", |
| 151 | 'Retry the original `execute` command after linking succeeds.', |
| 152 | ], |
| 153 | }, |
| 154 | { |
| 155 | id: 'listen', |
| 156 | title: '`listen` - Subscribe To Trigger Events', |
| 157 | features: [CLI_EXPERIMENTAL_FEATURES.LISTEN], |
| 158 | summary: |
| 159 | 'Use `listen` for temporary trigger subscriptions in consumer projects, especially when background agents should consume new event payloads from artifact files.', |
| 160 | examples: [ |
| 161 | { |
| 162 | code: "composio listen GMAIL_NEW_GMAIL_MESSAGE\ncomposio listen SLACK_CHANNEL_MESSAGE_RECEIVED -p '{ trigger_config: { channel_id: \"C123\" } }'\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE --stream\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE --stream '.data.threadId'\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 5m\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --max-events 5", |
| 163 | }, |
| 164 | ], |
| 165 | flags: [ |
| 166 | { |
| 167 | name: '`-p/--params`', |
| 168 | description: |
| 169 | 'Provide only trigger config fields; connected account resolution is automatic.', |
| 170 | }, |
| 171 | { |
| 172 | name: '`--stream`', |
| 173 | description: 'Print events inline, optionally narrowed to a JSON path.', |
| 174 | }, |
| 175 | { |
| 176 | name: '`--timeout` and `--max-events`', |
| 177 | description: 'Stop long-running listeners cleanly.', |
| 178 | }, |
| 179 | { |
| 180 | name: '`--fail-fast`', |
| 181 | description: |
| 182 | 'Stop at the first event that fails to save and exit 1, so a bounded run that lost events is not a success.', |
| 183 | }, |
| 184 | { |
| 185 | name: '`--account`', |
| 186 | description: 'Select which connected account to use by alias, word_id, or account id.', |
| 187 | }, |
| 188 | ], |
| 189 | notes: [ |
| 190 | '`composio artifacts cwd` shows the current artifact root when saved payloads need inspection.', |
| 191 | ], |
| 192 | }, |
| 193 | { |
| 194 | id: 'proxy', |
| 195 | title: '`proxy` - Raw API Access', |
| 196 | summary: |
| 197 | 'Use `proxy` when a toolkit supports a raw API operation that is easier than finding a dedicated tool slug.', |
| 198 | examples: [ |
| 199 | { |
| 200 | code: 'composio proxy https://api.github.com/user --toolkit github --account work --method GET </dev/null', |
| 201 | }, |
| 202 | ], |
| 203 | flags: [ |
| 204 | { |
| 205 | name: '`--account`', |
| 206 | description: 'Select which connected account to use by alias, word_id, or account id.', |
| 207 | }, |
| 208 | ], |
| 209 | }, |
| 210 | { |
| 211 | id: 'run', |
| 212 | title: '`run` - Scripting and Programmatic Workflows', |
| 213 | summary: |
| 214 | 'For programmatic calls, loops, output plumbing, or anything beyond a single tool call, prefer `composio run`.', |
| 215 | intro: [ |
| 216 | '`composio run` executes an inline ESM JavaScript/TypeScript snippet with authenticated `execute()`, `search()`, and `proxy()` pre-injected. No SDK setup required.', |
| 217 | ], |
| 218 | examples: [ |
| 219 | { |
| 220 | description: 'Chain multiple tools', |
| 221 | code: 'composio run \'\n const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");\n const emails = await execute("GMAIL_FETCH_EMAILS", { max_results: 1 });\n console.log({ login: me.data.login, fetchedEmails: !!emails.data });\n\'', |
| 222 | }, |
| 223 | { |
| 224 | description: 'Fan out with Promise.all', |
| 225 | code: 'composio run \'\n const [me, emails] = await Promise.all([\n execute("GITHUB_GET_THE_AUTHENTICATED_USER"),\n execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),\n ]);\n console.log({ login: me.data.login, emailCount: emails.data.messages?.length });\n\'', |
| 226 | }, |
| 227 | ], |
| 228 | notes: [ |
| 229 | 'Use top-level `execute --parallel` instead when the user only needs a few independent tool calls and does not need script logic.', |
| 230 | ], |
| 231 | }, |
| 232 | { |
| 233 | id: 'auth', |
| 234 | title: 'Auth', |
| 235 | examples: [ |
| 236 | { |
| 237 | code: 'composio whoami # check current session\ncomposio login # authenticate if whoami fails', |
| 238 | }, |
| 239 | ], |
| 240 | }, |
| 241 | ]; |
| 242 | |
| 243 | const defaultWorkflow = (build: SkillBuildContext) => { |
| 244 | const lines = [ |
| 245 | '1. Start with `composio execute <slug>` whenever the slug is known.', |
| 246 | '2. If several independent tool calls must happen at once, use `composio execute -p/--parallel` with repeated `<slug> -d <json>` groups.', |
| 247 | '3. If `execute` says the toolkit is not connected, run `composio link <toolkit>` and retry.', |
| 248 | '4. If the arguments are unclear, run `composio execute <slug> --get-schema` or `--dry-run` before guessing.', |
| 249 | '5. Reach for `composio search "<task>"` only when the slug is unknown. `search` accepts one or more queries, so batch related discovery work into a single command when useful.', |
| 250 | '6. If a command exits 75, the failure was temporary and running it again cannot act twice: wait a moment and run the same command again. If a failed `execute` result has `"retry": "check-first"`, the tool may already have run: check before running it again.', |
| 251 | ]; |
| 252 | |
| 253 | if (build.experimentalFeatures[CLI_EXPERIMENTAL_FEATURES.LISTEN]) { |
| 254 | lines.push( |
| 255 | '7. If the CLI build enables the experimental `listen` feature, use it for temporary consumer-project trigger subscriptions.' |
| 256 | ); |
| 257 | } |
| 258 | |
| 259 | return lines; |
| 260 | }; |
| 261 | |
| 262 | const referenceDocuments = [ |
| 263 | composioDevReference, |
| 264 | powerUserExamplesReference, |
| 265 | troubleshootingReference, |
| 266 | ] as const; |
| 267 | |
| 268 | const renderExample = (example: SkillExample) => { |
| 269 | const lines = []; |
| 270 | |
| 271 | if (example.description) { |
| 272 | lines.push(example.description + ':'); |
| 273 | } |
| 274 | |
| 275 | lines.push('```bash', example.code, '```'); |
| 276 | return lines.join('\n'); |
| 277 | }; |
| 278 | |
| 279 | const renderCommand = (build: SkillBuildContext, command: SkillCommand) => { |
| 280 | const lines: string[] = [`## ${command.title}`]; |
| 281 | |
| 282 | if (command.summary) { |
| 283 | lines.push('', command.summary); |
| 284 | } |
| 285 | |
| 286 | for (const intro of command.intro ?? []) { |
| 287 | lines.push('', intro); |
| 288 | } |
| 289 | |
| 290 | const examples = (command.examples ?? []).filter(example => isEnabledForBuild(build, example)); |
| 291 | if (examples.length > 0) { |
| 292 | for (const example of examples) { |
| 293 | lines.push('', renderExample(example)); |
| 294 | } |
| 295 | } |
| 296 | |
| 297 | const flags = (command.flags ?? []).filter(flag => isEnabledForBuild(build, flag)); |
| 298 | if (flags.length > 0) { |
| 299 | lines.push('', 'Key flags:'); |
| 300 | for (const flag of flags) { |
| 301 | lines.push(`- ${flag.name}: ${flag.description}`); |
| 302 | } |
| 303 | } |
| 304 | |
| 305 | for (const note of command.notes ?? []) { |
| 306 | lines.push('', `- ${note}`); |
| 307 | } |
| 308 | |
| 309 | for (const extra of (command.extraBody ?? []).filter(block => isEnabledForBuild(build, block))) { |
| 310 | lines.push('', extra.markdown); |
| 311 | } |
| 312 | |
| 313 | return lines.join('\n'); |
| 314 | }; |
| 315 | |
| 316 | export const renderComposioCliSkill = ( |
| 317 | channel: SkillReleaseChannel, |
| 318 | featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>> |
| 319 | ) => { |
| 320 | const build = resolveSkillBuildContext(channel, featureOverrides); |
| 321 | const lines: string[] = [ |
| 322 | '---', |
| 323 | `name: ${frontmatter.name}`, |
| 324 | `description: ${frontmatter.description}`, |
| 325 | '---', |
| 326 | '', |
| 327 | '<!-- AUTO-GENERATED: edit skills-src/composio-cli/index.ts and rebuild -->', |
| 328 | `<!-- release-channel: ${channel} -->`, |
| 329 | '', |
| 330 | '# Composio CLI', |
| 331 | '', |
| 332 | '## Default Workflow', |
| 333 | '', |
| 334 | ...defaultWorkflow(build), |
| 335 | ]; |
| 336 | |
| 337 | const enabledCommands = commands.filter(command => isEnabledForBuild(build, command)); |
| 338 | for (const command of enabledCommands) { |
| 339 | lines.push('', renderCommand(build, command)); |
| 340 | } |
| 341 | |
| 342 | lines.push( |
| 343 | '', |
| 344 | '## Escalate Only When Needed', |
| 345 | '', |
| 346 | 'If the user is stuck on top-level commands or needs fallback inspection commands, load [references/troubleshooting.md](references/troubleshooting.md).', |
| 347 | '', |
| 348 | 'If the user explicitly asks about developer projects, auth configs, connected accounts, triggers, logs, orgs, or projects, load [references/composio-dev.md](references/composio-dev.md). `composio dev` is not the default end-user path. In a developer project, run tools with `composio dev playground-execute`, not `composio execute`.' |
| 349 | ); |
| 350 | |
| 351 | return lines.join('\n') + '\n'; |
| 352 | }; |
| 353 | |
| 354 | export const renderReferenceFiles = ( |
| 355 | channel: SkillReleaseChannel, |
| 356 | featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>> |
| 357 | ) => { |
| 358 | const build = resolveSkillBuildContext(channel, featureOverrides); |
| 359 | return Object.fromEntries( |
| 360 | referenceDocuments.map(document => [ |
| 361 | `${document.slug}.md`, |
| 362 | renderReferenceDocument(document, build), |
| 363 | ]) |
| 364 | ); |
| 365 | }; |
| 366 | |
| 367 | export const validateSkillSources = () => referenceDocuments.flatMap(validateReferenceDocument); |
| 368 | |
| 369 | const copyDir = (sourceDir: string, targetDir: string) => { |
| 370 | fs.mkdirSync(targetDir, { recursive: true }); |
| 371 | for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) { |
| 372 | const sourcePath = path.join(sourceDir, entry.name); |
| 373 | const targetPath = path.join(targetDir, entry.name); |
| 374 | |
| 375 | if (entry.isDirectory()) { |
| 376 | copyDir(sourcePath, targetPath); |
| 377 | continue; |
| 378 | } |
| 379 | |
| 380 | fs.copyFileSync(sourcePath, targetPath); |
| 381 | } |
| 382 | }; |
| 383 | |
| 384 | export const buildComposioCliSkill = ({ |
| 385 | channel, |
| 386 | outputRoot, |
| 387 | featureOverrides, |
| 388 | }: { |
| 389 | channel: SkillReleaseChannel; |
| 390 | outputRoot: string; |
| 391 | featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>>; |
| 392 | }) => { |
| 393 | const skillOutputDir = path.join(outputRoot, 'composio-cli'); |
| 394 | fs.rmSync(skillOutputDir, { recursive: true, force: true }); |
| 395 | fs.mkdirSync(skillOutputDir, { recursive: true }); |
| 396 | |
| 397 | fs.writeFileSync( |
| 398 | path.join(skillOutputDir, 'SKILL.md'), |
| 399 | renderComposioCliSkill(channel, featureOverrides), |
| 400 | 'utf8' |
| 401 | ); |
| 402 | |
| 403 | const agentsSourceDir = path.join(sourceAssetsDir, 'agents'); |
| 404 | if (fs.existsSync(agentsSourceDir)) { |
| 405 | copyDir(agentsSourceDir, path.join(skillOutputDir, 'agents')); |
| 406 | } |
| 407 | |
| 408 | const referencesOutputDir = path.join(skillOutputDir, 'references'); |
| 409 | fs.mkdirSync(referencesOutputDir, { recursive: true }); |
| 410 | for (const [fileName, markdown] of Object.entries( |
| 411 | renderReferenceFiles(channel, featureOverrides) |
| 412 | )) { |
| 413 | fs.writeFileSync(path.join(referencesOutputDir, fileName), markdown, 'utf8'); |
| 414 | } |
| 415 | |
| 416 | return skillOutputDir; |
| 417 | }; |