Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 Files
diff --git a/.changeset/whoami-respect-switched-org.md b/.changeset/whoami-respect-switched-org.md
deleted file mode 100644
index 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.yml
index 695e79c27..9702efa00 100644
--- a/.github/workflows/ts.release.yml
+++ b/.github/workflows/ts.release.yml
@@ -49,6 +49,9 @@ jobs:
- name: Install Dependencies
run: pnpm install --frozen-lockfile
+ - name: Validate Changesets
+ run: pnpm validate:changesets
+
- name: Run Linting
run: pnpm lint
diff --git a/.github/workflows/ts.test.yml b/.github/workflows/ts.test.yml
index 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.md
index 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.lock
index 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.json
index 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.yaml
index 423ab61b8..41a0d86bd 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -126,6 +126,9 @@ importers:
'@changesets/cli':
specifier: ^2.31.0
version: 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/anthropic
diff --git a/test/release-workflow.test.ts b/test/release-workflow.test.ts
index 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-re
throw 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.md
index 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.md
index 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 stack
Each 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.md
index 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.mjs
index 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.mjs
index 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/REA
const ignoredDirs = new Set([
'.git',
+ '.generated',
'node_modules',
'.turbo',
'.ruff_cache',
diff --git a/ts/scripts/validate-changesets.mjs b/ts/scripts/validate-changesets.mjs
new file mode 100644
index 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;
+ }
+}