Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(release): guard and document CLI releases (#3895)
Alberto Schiabel9498679c26c1
diff --git a/.agents/skills/cli-release/SKILL.md b/.agents/skills/cli-release/SKILL.mdnew file mode 100644index 000000000..b6e6537ec--- /dev/null+++ b/.agents/skills/cli-release/SKILL.md@@ -0,0 +1,27 @@+---+name: cli-release+description: Release and recover first-party Composio CLI binaries through Build CLI Binaries, including automatic beta builds, promote-stable dispatches, beta-tag selection, asset and installation verification, and failed release recovery. Use when a contributor asks to build a CLI beta, publish or promote a stable CLI version, choose a release candidate, monitor a CLI release, or diagnose a failed CLI release. Do not use for TypeScript SDK Changesets releases or CLI source implementation.+---++# CLI Release++Use this skill for the GitHub Release that powers the standalone `composio` binary and installer.++Read `references/release-workflow.md` before selecting a candidate or dispatching a workflow.++## Release Contract++- Never add a Changeset for `@composio/cli` or `@composio/cli-local-tools`; both packages are ignored by Changesets and such files wedge `ts.release.yml`.+- Treat a merge to `next` that touches CLI paths as a beta build. Promote a tested beta with the `promote-stable` workflow action for the normal stable-release path.+- Treat a direct CLI `package.json` version bump as a release-owner-only recovery path, not the contributor default.+- Resolve beta tags and workflow state from GitHub immediately before acting. Never invent or reuse a stale candidate from memory.+- A stable promotion is a production write. If the user did not name the exact beta tag, present the resolved candidate and obtain explicit confirmation before dispatching it.+- Follow the release through asset verification, installation tests, and the Homebrew tap update. Do not stop after the dispatch succeeds.++## Execution++1. Classify the request as automatic beta, manual beta, stable promotion, or recovery.+2. Run the playbook's read-only preflight and identify the exact source commit and release tag.+3. Dispatch only the requested workflow action and watch the resulting run to completion.+4. Verify the published release and downstream checks named in the playbook.+5. Report the released tag, source beta or commit, workflow URL, asset state, install-test result, and any remaining follow-up.diff --git a/.agents/skills/cli-release/references/release-workflow.md b/.agents/skills/cli-release/references/release-workflow.mdnew file mode 100644index 000000000..c7b8ff113--- /dev/null+++ b/.agents/skills/cli-release/references/release-workflow.md@@ -0,0 +1,180 @@+# CLI Release Workflow++## Contents++- [Sources Of Truth](#sources-of-truth)+- [Choose The Path](#choose-the-path)+- [Changeset Rule](#changeset-rule)+- [Inspect Candidates](#inspect-candidates)+- [Build A Manual Beta](#build-a-manual-beta)+- [Promote A Beta To Stable](#promote-a-beta-to-stable)+- [Verify Completion](#verify-completion)+- [Failure Recovery](#failure-recovery)++## Sources Of Truth++- `.github/workflows/build-cli-binaries.yml` owns beta and stable GitHub Releases.+- `.github/scripts/cli-release/resolve-release-target.sh` decides the tag and source commit.+- `.github/scripts/cli-release/verify-assets.sh` defines the required asset set.+- `.github/workflows/cli.test-installation.yml` validates installers after publication.+- `.github/workflows/cli.bump-homebrew-tap.yml` updates Homebrew for stable releases.+- `.changeset/config.json` ignores `@composio/cli` and `@composio/cli-local-tools`.++`ts.release.yml` is the TypeScript SDK/npm release train. It is not the normal CLI binary release path.++## Choose The Path++| Goal | Path | Result |+| --- | --- | --- |+| Ship an ordinary CLI change | Merge the reviewed PR to `next` | The push builds a rolling beta automatically. |+| Build a beta from a branch | Dispatch `build-beta` at that branch | A prerelease is built from the branch commit. |+| Publish a stable CLI | Promote an existing tested beta | The beta's source commit is rebuilt and published under the stable tag. |+| Resume a failed promotion | Re-run or re-dispatch the same beta after inspecting the draft | An unpublished draft can be resumed and its assets replaced. |++The resolver also treats a CLI `package.json` version change pushed to `next` as a stable release. Do not use that as the normal contributor procedure. It bypasses beta selection and is reserved for explicit release-owner recovery or migration work.++## Changeset Rule++Never create a `.changeset/*.md` entry for `@composio/cli` or `@composio/cli-local-tools` while those packages remain in `.changeset/config.json#ignore`.++An ignored-package changeset makes `changesets/action` enter version-PR mode, while `changeset version` emits no commit. The action then fails with `No commits between next and changeset-release/next` and blocks unrelated SDK publishing.++If a CLI change needs a human-facing note, update `ts/packages/cli/CHANGELOG.md` directly. Run this guard before handoff:++```bash+pnpm validate:changesets+```++## Inspect Candidates++Use live GitHub state. Do not select a beta from local tags or remembered versions.++```bash+REPOSITORY=ComposioHQ/composio++gh release list \+ --repo "$REPOSITORY" \+ --limit 100 \+ --json tagName,isPrerelease,isDraft,publishedAt \+ --jq '.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease and (.isDraft | not))'+```++For the chosen candidate, require a published prerelease and inspect its commit and assets:++```bash+BETA_TAG='@composio/[email protected]'++gh release view "$BETA_TAG" \+ --repo "$REPOSITORY" \+ --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \+ --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'+```++The beta must have `isDraft: false`, `isPrerelease: true`, and these six assets in `uploaded` state:++- `composio-linux-x64.zip`+- `composio-linux-aarch64.zip`+- `composio-darwin-x64.zip`+- `composio-darwin-aarch64.zip`+- `composio-skill.zip`+- `checksums.txt`++Find the beta workflow run by its target commit and require it to be green, including the reusable installation-test jobs:++```bash+TARGET_COMMIT='replace-with-targetCommitish'++gh run list \+ --repo "$REPOSITORY" \+ --workflow build-cli-binaries.yml \+ --commit "$TARGET_COMMIT" \+ --limit 10+```++If the user asked for a stable release without naming a beta, show the candidate and stop for confirmation before dispatching.++## Build A Manual Beta++Use this only when an explicit beta build is requested. The selected ref supplies both the workflow definition and source commit.++```bash+SOURCE_BRANCH='replace-with-branch'++gh workflow run build-cli-binaries.yml \+ --repo "$REPOSITORY" \+ --ref "$SOURCE_BRANCH" \+ --raw-field action=build-beta+```++Watch the returned run through publication and installation tests. A beta is not a stable release and does not update Homebrew.++## Promote A Beta To Stable++Derive the stable tag by removing the beta suffix, then ensure no published stable release already exists:++```bash+STABLE_TAG="${BETA_TAG%%-beta.*}"++gh release view "$STABLE_TAG" --repo "$REPOSITORY" --json tagName,isDraft,isPrerelease,publishedAt+```++- If the stable tag is absent, promotion may proceed.+- If it is a draft, the promotion can resume it.+- If it is already published, stop. Never overwrite a published release.++Dispatch the current workflow from `next`; `promote-stable` resolves the source commit from the beta release itself:++```bash+gh workflow run build-cli-binaries.yml \+ --repo "$REPOSITORY" \+ --ref next \+ --raw-field action=promote-stable \+ --raw-field beta_tag="$BETA_TAG"+```++Use the returned URL when available. Otherwise identify the new dispatch, verify its creation time and actor, then watch it:++```bash+gh run list \+ --repo "$REPOSITORY" \+ --workflow build-cli-binaries.yml \+ --event workflow_dispatch \+ --branch next \+ --limit 5++gh run watch RUN_ID --repo "$REPOSITORY" --compact --exit-status+```++## Verify Completion++Do not call the release complete until all of these are true:++1. `Build CLI Binaries` completed successfully.+2. The stable release is published with `isDraft: false` and `isPrerelease: false`.+3. All six canonical assets are present and uploaded.+4. The workflow's installation-test matrix passed.+5. `Bump Homebrew Tap` succeeded or reported that the formula was already current.++```bash+gh release view "$STABLE_TAG" \+ --repo "$REPOSITORY" \+ --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \+ --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'++gh run list \+ --repo "$REPOSITORY" \+ --workflow cli.bump-homebrew-tap.yml \+ --event release \+ --limit 5+```++Report the stable tag, promoted beta, target commit, workflow URL, asset count and state, installation result, and Homebrew result.++## Failure Recovery++- **Build matrix failed:** no release should publish. Fix the source, produce a new beta, and promote that candidate.+- **Draft exists, publish did not finish:** inspect the failure, then re-run or re-dispatch the same beta. Draft assets are safely replaced with `--clobber`.+- **Duplicate run says the release is already published:** this is an intentional safety failure. Verify the published release and stop the duplicate.+- **Installation failed after publication:** do not mutate the published tag. Fix forward through a new beta and the next stable patch.+- **Homebrew update failed:** keep the GitHub Release intact, fix the tap credential or workflow issue, then dispatch `cli.bump-homebrew-tap.yml` with the exact stable tag.+- **TS release says there are no commits for the release PR:** remove any pending Changeset that targets an ignored CLI package, preserve its note in the CLI changelog, run `pnpm validate:changesets`, and let the next push retry the SDK release train.diff --git a/.agents/skills/repo-guidance/references/repository-workflow.md b/.agents/skills/repo-guidance/references/repository-workflow.mdindex 8694884a3..39a05b2a0 100644--- a/.agents/skills/repo-guidance/references/repository-workflow.md+++ b/.agents/skills/repo-guidance/references/repository-workflow.md@@ -48,7 +48,7 @@ make build## Changesets- Add a changeset for changes to published TypeScript packages.-- For `@composio/cli`, add a changeset only when intentionally using the stable CLI binary release flow.+- `@composio/cli` and `@composio/cli-local-tools` are ignored by Changesets. Never target them in a changeset while they remain ignored; use the `cli-release` skill for beta builds and stable promotion.- Do not add a changeset for repo guidance, docs-only, tests-only, or validation-only changes unless release metadata changes.## Generated And Vendor Filesdiff --git a/.changeset/whoami-respect-switched-org.md b/.changeset/whoami-respect-switched-org.mddeleted file mode 100644index 6eea99251..000000000--- a/.changeset/whoami-respect-switched-org.md+++ /dev/null@@ -1,5 +0,0 @@-----'@composio/cli': patch------Fix `composio whoami` reporting the wrong organization after `composio orgs switch`. The command resolved session info without the `x-org-id` header, so the backend fell back to the API key's home org and ignored the switch. It now forwards the selected global org, matching how consumer commands resolve org context.diff --git a/.github/workflows/ts.release.yml b/.github/workflows/ts.release.ymlindex 695e79c27..9702efa00 100644--- a/.github/workflows/ts.release.yml+++ b/.github/workflows/ts.release.yml@@ -49,6 +49,9 @@ jobs:- name: Install Dependenciesrun: pnpm install --frozen-lockfile+ - name: Validate Changesets+ run: pnpm validate:changesets+- name: Run Lintingrun: pnpm lintdiff --git a/.github/workflows/ts.test.yml b/.github/workflows/ts.test.ymlindex 3e89d3823..cd3def9f8 100644--- a/.github/workflows/ts.test.yml+++ b/.github/workflows/ts.test.yml@@ -4,20 +4,28 @@ on:push:branches: [master, next]paths:+ - '.changeset/**'- 'ts/**'- '.github/actions/setup-node-pnpm-bun/action.yml'+ - '.github/workflows/ts.release.yml'- '.github/workflows/ts.test.yml'- 'mise.toml'- 'mise.lock'+ - 'package.json'+ - 'test/release-workflow.test.ts'- 'turbo.jsonc'pull_request:branches: [master, next]paths:+ - '.changeset/**'- 'ts/**'- '.github/actions/setup-node-pnpm-bun/action.yml'+ - '.github/workflows/ts.release.yml'- '.github/workflows/ts.test.yml'- 'mise.toml'- 'mise.lock'+ - 'package.json'+ - 'test/release-workflow.test.ts'- 'turbo.jsonc'concurrency:diff --git a/AGENTS.md b/AGENTS.mdindex 3ccb30447..4c9949271 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -26,6 +26,7 @@ Use the smallest relevant skill:- `eve`: durable backend AI agents built with the eve framework.- `typescript-sdk`, `typescript-testing`, `typescript-providers`: TypeScript SDK/core/provider work.- `cli-command`, `cli-e2e`: CLI design/implementation or CLI end-to-end tests.+- `cli-release`: first-party CLI beta builds, stable promotion, release verification, or recovery.- `python-sdk`, `python-testing`, `python-providers`, `python-release`: Python SDK/provider/testing/release work.## Repository Map@@ -85,6 +86,7 @@ make build## Release And Package Notes- TypeScript package releases use Changesets. Add a changeset only when published TypeScript packages change.+- `@composio/cli` and `@composio/cli-local-tools` are excluded from Changesets; use `cli-release` for CLI binaries and never target those packages in a changeset while they remain ignored.- Documentation-only and agent-guidance-only changes do not need a changeset.- Python release metadata lives in `python/pyproject.toml`, `python/setup.py`, and `uv.lock`.- Bumping generated clients is manual. Verify the package version is published before changing pins.diff --git a/mise.lock b/mise.lockindex e06895388..4666d7776 100644--- a/mise.lock+++ b/mise.lock@@ -89,23 +89,23 @@ version = "3.12.13"backend = "core:python"[tools.python."platforms.linux-arm64"]-checksum = "sha256:b85154b9c7ca9de3f85f2c9f032d503151db16ef198de86b885fc61890c075ed"-url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz"+checksum = "sha256:f226576b91491ffa5739aa85726521e9031f4d87f80627d64ed348ac77cb31e9"+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz"provenance = "github-attestations"[tools.python."platforms.linux-x64"]-checksum = "sha256:10a452caac7041357805f0c19a60576df53f1ab06d1abfc9200f1f0157cb3bd1"-url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"+checksum = "sha256:5854aa6ec71cad00334d5065633c210b2e7feb40956767a59a91791cadcf0b79"+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"provenance = "github-attestations"[tools.python."platforms.macos-arm64"]-checksum = "sha256:41df7d3ae4757e84b97874f76d634268456aaa271740d33f968d826374998fb7"-url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-aarch64-apple-darwin-install_only_stripped.tar.gz"+checksum = "sha256:9a1e9e06175c10efd8378b904b07fa21bd791ab3345d7cdffeb4a76c9ff55903"+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-aarch64-apple-darwin-install_only_stripped.tar.gz"provenance = "github-attestations"[tools.python."platforms.macos-x64"]-checksum = "sha256:a6bbea996c5f14eb55ab275889d2df45408deec504b4a7219d7b59c045b2555e"-url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-x86_64-apple-darwin-install_only_stripped.tar.gz"+checksum = "sha256:8e6b7e6533bdf746287008edf91102e7bee0a6ca1d24f16c4514237cafd706c5"+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-x86_64-apple-darwin-install_only_stripped.tar.gz"provenance = "github-attestations"[[tools.uv]]diff --git a/package.json b/package.jsonindex 4675f4fb7..5eaad5b1c 100644--- a/package.json+++ b/package.json@@ -51,6 +51,7 @@"check:peer-deps": "tsx ts/scripts/check-peer-deps.ts","update:peer-deps": "tsx ts/scripts/update-peer-deps.ts","validate:agent-skills": "node ts/scripts/validate-agent-skills.mjs",+ "validate:changesets": "node ts/scripts/validate-changesets.mjs","validate:skill-routing": "node ts/scripts/test-skill-routing.mjs","prepublish": "pnpm run build:packages","changeset": "changeset",@@ -71,6 +72,7 @@"devDependencies": {"@arethetypeswrong/cli": "catalog:","@changesets/cli": "^2.31.0",+ "@changesets/read": "^0.6.7","@composio/anthropic": "workspace:*","@composio/cli-local-tools": "workspace:*","@composio/core": "workspace:*",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 423ab61b8..41a0d86bd 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -126,6 +126,9 @@ importers:'@changesets/cli':specifier: ^2.31.0version: 2.31.0(@types/[email protected])+ '@changesets/read':+ specifier: ^0.6.7+ version: 0.6.7'@composio/anthropic':specifier: workspace:*version: link:ts/packages/providers/anthropicdiff --git a/test/release-workflow.test.ts b/test/release-workflow.test.tsindex 3189fcc12..e75487684 100644--- a/test/release-workflow.test.ts+++ b/test/release-workflow.test.ts@@ -12,6 +12,10 @@ import {import { tmpdir } from 'node:os';import { join } from 'node:path';import { spawnSync } from 'node:child_process';+import {+ findIgnoredChangesetReleases,+ validateChangesets,+} from '../ts/scripts/validate-changesets.mjs';const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));const tsCorePackageJson = JSON.parse(@@ -246,6 +250,76 @@ if (packageJson.scripts?.['changeset:release'] !== 'bash ts/scripts/changeset-rethrow new Error('changeset:release must use the CLI-release filtering script');}+if (packageJson.scripts?.['validate:changesets'] !== 'node ts/scripts/validate-changesets.mjs') {+ throw new Error('validate:changesets must use the ignored-package guard');+}++{+ const violations = findIgnoredChangesetReleases(+ {+ changesets: [+ {+ id: 'ignored-package-fixture',+ releases: [+ { name: '@composio/cli', type: 'patch' },+ { name: '@composio/core', type: 'patch' },+ ],+ },+ ],+ },+ ['@composio/cli']+ );++ if (+ violations.length !== 1 ||+ violations[0].changeset !== 'ignored-package-fixture' ||+ violations[0].package !== '@composio/cli'+ ) {+ throw new Error('changeset validation must identify releases targeting ignored packages');+ }+}++{+ const fixtureDir = mkdtempSync(join(tmpdir(), 'composio-changeset-validation-'));+ const changesetDir = join(fixtureDir, '.changeset');+ const fixturePath = join(changesetDir, 'ignored-package-fixture.md');++ try {+ mkdirSync(changesetDir, { recursive: true });+ writeFileSync(join(changesetDir, 'config.json'), JSON.stringify({ ignore: ['@composio/cli'] }));+ writeFileSync(+ fixturePath,+ '---\n"@composio/cli": patch\n"@composio/core": patch\n---\n\nFixture changeset.\n'+ );++ let validationError = '';+ try {+ await validateChangesets(fixtureDir);+ } catch (error) {+ validationError = error instanceof Error ? error.message : String(error);+ }++ if (!validationError.includes('ignored-package-fixture: @composio/cli')) {+ throw new Error('changeset validation must reject an ignored package outside a git checkout');+ }++ writeFileSync(fixturePath, '---\n"@composio/core": patch\n---\n\nValid fixture changeset.\n');+ await validateChangesets(fixtureDir);+ } finally {+ rmSync(fixtureDir, { recursive: true, force: true });+ }+}++const validateChangesetsIdx = tsReleaseWorkflow.indexOf('run: pnpm validate:changesets');+const changesetsActionIdx = tsReleaseWorkflow.indexOf('uses: changesets/action@');+if (+ validateChangesetsIdx === -1 ||+ changesetsActionIdx === -1 ||+ validateChangesetsIdx > changesetsActionIdx+) {+ throw new Error('ts.release.yml must validate pending changesets before changesets/action');+}+if (changesetConfig.baseBranch !== 'next') {throw new Error('changesets must compare against next, the active release branch');}diff --git a/ts/AGENTS.md b/ts/AGENTS.mdindex 3f7860ed3..202886d44 100644--- a/ts/AGENTS.md+++ b/ts/AGENTS.md@@ -12,6 +12,7 @@ TypeScript workspace guidance for AI agents.- Use `typescript-providers` for packages under `ts/packages/providers/`.- Use `typescript-testing` for Vitest, typecheck, package builds, examples, or runtime E2E test selection.- Use `cli-command` or `cli-e2e` for `ts/packages/cli/` and `ts/e2e-tests/cli/`.+- Use `cli-release` for first-party CLI beta builds, stable promotion, release verification, or recovery.## Commands@@ -33,4 +34,5 @@ pnpm test:e2e:cli- Do not edit `ts/vendor/`; those submodules are read-only references.- Keep generated outputs owned by their generator.- Add changesets only for changes to published TypeScript packages.+- Never add changesets for `@composio/cli` or `@composio/cli-local-tools` while `.changeset/config.json` ignores them; record CLI notes in `ts/packages/cli/CHANGELOG.md` instead.- Prefer focused package tests before broad workspace tests.diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.mdindex 19eed8b13..bf43beeed 100644--- a/ts/packages/cli/AGENTS.md+++ b/ts/packages/cli/AGENTS.md@@ -27,34 +27,34 @@ Errors are captured via the custom `effect-errors/` module (source-mapped stackEach command uses `@effect/cli`'s `Command.make()` pattern. Top-level command files end in `.cmd.ts`; nested command groups live in their own subdirectory with a `<group>.cmd.ts` entry. Current top-level commands:-| Group / Command | Purpose |+| Group / Command | Purpose || -------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |-| `version` | Display CLI version |-| `whoami` | Show logged-in user info (writes raw API key to stdout when piped — see Output Conventions) |-| `login` | Login with browser redirect or direct user/API key (`--no-browser`, `--no-wait`, `--key`, `--user-api-key`, `--org`) |-| `logout` | Clear stored API key |-| `signup` | Create a Composio account |-| `upgrade` | Self-update binary from GitHub releases |-| `init` | Bootstrap a Composio project in the current directory |-| `install` | Install local-tool integrations |-| `generate {ts | py}` | Generate type stubs (auto-detects project language if no subcommand) |-| `agent` | Manage AI agent presets |-| `toolkits` | List / inspect / version toolkits |-| `tools` | List / inspect / `execute` tools |-| `triggers` | List / manage trigger types |-| `auth-configs` | Manage auth-config resources (`ac_*`) |-| `connected-accounts` | Manage connected accounts (`ca_*`) |-| `connections` | Alias / helper for connected-account flows |-| `orgs` | Manage organizations |-| `projects` | Manage projects |-| `local-tools` | Manage local toolkits (via `@composio/cli-local-tools`) |-| `logs` | View tool-execution logs (`logs-cmd/`) |-| `config` | Read/write CLI config |-| `listen` | Listen for events |-| `proxy` | Proxy authenticated API requests |-| `run` | Run a saved script / preset |-| `dev` | Developer-only utilities |-| `artifacts` | Manage generated artifacts |+| `version` | Display CLI version |+| `whoami` | Show logged-in user info (writes raw API key to stdout when piped — see Output Conventions) |+| `login` | Login with browser redirect or direct user/API key (`--no-browser`, `--no-wait`, `--key`, `--user-api-key`, `--org`) |+| `logout` | Clear stored API key |+| `signup` | Create a Composio account |+| `upgrade` | Self-update binary from GitHub releases |+| `init` | Bootstrap a Composio project in the current directory |+| `install` | Install local-tool integrations |+| `generate {ts | py}` | Generate type stubs (auto-detects project language if no subcommand) |+| `agent` | Manage AI agent presets |+| `toolkits` | List / inspect / version toolkits |+| `tools` | List / inspect / `execute` tools |+| `triggers` | List / manage trigger types |+| `auth-configs` | Manage auth-config resources (`ac_*`) |+| `connected-accounts` | Manage connected accounts (`ca_*`) |+| `connections` | Alias / helper for connected-account flows |+| `orgs` | Manage organizations |+| `projects` | Manage projects |+| `local-tools` | Manage local toolkits (via `@composio/cli-local-tools`) |+| `logs` | View tool-execution logs (`logs-cmd/`) |+| `config` | Read/write CLI config |+| `listen` | Listen for events |+| `proxy` | Proxy authenticated API requests |+| `run` | Run a saved script / preset |+| `dev` | Developer-only utilities |+| `artifacts` | Manage generated artifacts |Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation. Feature flags live in `feature-tags.ts` and `experimental-features.ts`.@@ -170,32 +170,17 @@ Outputs land in `recordings/{tapes,svgs,ascii}/<group>/<name>.{tape,svg,ascii}`.## Release Workflow-Two channels: **beta** (automatic) and **stable** (manual promotion via changeset).+Use the repo-local `cli-release` skill before building or publishing first-party CLI binaries.-### Beta (automatic)--Every push to `next` touching `ts/packages/cli/**` triggers `.github/workflows/build-cli-binaries.yml`:--1. Find latest stable `@composio/[email protected]`-2. Compute next patch `X.Y.Z+1`-3. Build cross-platform binaries (linux-x64, linux-aarch64, darwin-x64, darwin-aarch64)-4. Publish GitHub prerelease `@composio/[email protected].(Z+1)-beta.<run_number>`--Also triggerable from any branch via `workflow_dispatch` → `build-beta`. Users install with `composio upgrade --beta`.--### Stable (via changeset)--1. Create a CLI release changeset PR only when intentionally promoting CLI binary behavior through the stable release flow (`.changeset/<name>.md` with `"@composio/cli": patch`). Ordinary CLI source fixes still follow the repo rule: add a changeset only when the release path requires one.-2. Merge into `next`-3. Changeset bot opens "Release: update version" PR bumping `package.json`-4. Merge that PR → push to `next` detects version change → builds **stable** release (`@composio/[email protected]`, marked `latest`)-5. `ts.release.yml` publishes via the repository-controlled `changeset:release` script, which filters `@composio/cli` tag output so only `build-cli-binaries.yml` can create CLI GitHub Releases--Promote an existing beta to stable via `workflow_dispatch` → `promote-stable` with the beta tag (e.g. `@composio/[email protected]`).+- A push to `next` touching CLI paths publishes a rolling beta automatically.+- The normal stable path promotes an existing tested beta through the `promote-stable` workflow action.+- `@composio/cli` and `@composio/cli-local-tools` are ignored by Changesets. Never add a changeset targeting either package; it wedges the TypeScript SDK release action. Put human-facing CLI notes in `CHANGELOG.md` directly.+- A direct `package.json` version bump is supported by the resolver only as an explicit release-owner recovery path, not the contributor default.### Key Workflow Files- `.github/workflows/build-cli-binaries.yml` — binary build + release-- `.github/workflows/ts.release.yml` — changeset bot + npm publish- `.github/workflows/cli.test-installation.yml` — post-release install smoke tests+- `.github/workflows/cli.bump-homebrew-tap.yml` — stable Homebrew formula update+- `.github/scripts/cli-release/resolve-release-target.sh` — beta/stable target resolution- `.changeset/config.json`diff --git a/ts/packages/cli/CHANGELOG.md b/ts/packages/cli/CHANGELOG.mdindex 35fb832f8..e66d312fa 100644--- a/ts/packages/cli/CHANGELOG.md+++ b/ts/packages/cli/CHANGELOG.md@@ -15,6 +15,7 @@### Patch Changes+- 8467efd: Fix `composio whoami` reporting the API key's home organization after `composio orgs switch`. Session info requests now forward the selected global organization.- 5f004ff: Drop `COMPOSIO_UPSERT_RECIPE` and `COMPOSIO_GET_RECIPE` from the CLI meta-tool list. These slugs were removed from `@composio/client` (alpha.74), so listing them broke the type-checked CLI build.- 23f9053: Remove the unused `ansis` dependency from the CLI. Colored output is already handled by `picocolors`, so `ansis` was a dead production dependency that shipped with the package.- 446c6f6: Fix virtual TypeScript file resolution used by CLI type generation so in-memory imports resolve consistently during transpilation and validation.diff --git a/ts/scripts/test-skill-routing.mjs b/ts/scripts/test-skill-routing.mjsindex de3daabc3..6639bda15 100644--- a/ts/scripts/test-skill-routing.mjs+++ b/ts/scripts/test-skill-routing.mjs@@ -47,6 +47,16 @@ const probes = [expect: 'cli-e2e',terms: ['Docker-based', 'end-to-end tests', 'binary invocation', 'fixture isolation'],},+ {+ task: 'promote a tested Composio CLI beta to a stable first-party binary release',+ expect: 'cli-release',+ terms: [+ 'first-party Composio CLI binaries',+ 'promote-stable',+ 'beta-tag selection',+ 'failed release recovery',+ ],+ },{task: 'align TypeScript and Python behavior after a backend API contract change',expect: 'cross-sdk-parity',diff --git a/ts/scripts/validate-agent-skills.mjs b/ts/scripts/validate-agent-skills.mjsindex c4a5738c7..b6310639f 100644--- a/ts/scripts/validate-agent-skills.mjs+++ b/ts/scripts/validate-agent-skills.mjs@@ -14,6 +14,7 @@ const expectedSkills = ['bug-fixing','cli-command','cli-e2e',+ 'cli-release','cross-sdk-parity','docs-decisions','eve',@@ -224,6 +225,7 @@ for (const relativePath of ['docs/decisions/README.md', 'docs/agent-guidance/REAconst ignoredDirs = new Set(['.git',+ '.generated','node_modules','.turbo','.ruff_cache',diff --git a/ts/scripts/validate-changesets.mjs b/ts/scripts/validate-changesets.mjsnew file mode 100644index 000000000..24149cdaa--- /dev/null+++ b/ts/scripts/validate-changesets.mjs@@ -0,0 +1,53 @@+#!/usr/bin/env node++import { readFileSync } from 'node:fs';+import { dirname, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import readChangesets from '@changesets/read';++const scriptPath = fileURLToPath(import.meta.url);+const repositoryRoot = resolve(dirname(scriptPath), '../..');++export function findIgnoredChangesetReleases(changesetStatus, ignoredPackages) {+ const ignored = new Set(ignoredPackages);++ return (changesetStatus.changesets ?? []).flatMap(changeset =>+ (changeset.releases ?? [])+ .filter(release => ignored.has(release.name))+ .map(release => ({ changeset: changeset.id, package: release.name }))+ );+}++export async function validateChangesets(cwd = repositoryRoot) {+ const config = JSON.parse(readFileSync(resolve(cwd, '.changeset/config.json'), 'utf8'));+ const changesets = await readChangesets(cwd);+ const violations = findIgnoredChangesetReleases({ changesets }, config.ignore ?? []);++ if (violations.length > 0) {+ const details = violations+ .map(({ changeset, package: packageName }) => `- ${changeset}: ${packageName}`)+ .join('\n');++ throw new Error(+ [+ 'Pending changesets must not target packages listed in .changeset/config.json#ignore.',+ details,+ '',+ 'An ignored-package changeset makes changesets/action enter version-PR mode, but',+ '`changeset version` emits no commit. The release job then fails while trying to',+ 'open a pull request with no commits. Remove the changeset, or remove the package',+ 'from the ignore list when intentionally restoring its Changesets release flow.',+ ].join('\n')+ );+ }+}++if (resolve(process.argv[1] ?? '') === scriptPath) {+ try {+ await validateChangesets();+ console.log('changeset validation passed');+ } catch (error) {+ console.error(error instanceof Error ? error.message : error);+ process.exitCode = 1;+ }+}