1
+---
2
+description: Trigger a CI binary build via workflow dispatch, monitor it, download the artifact, and test the CLI binary locally.
3
+---
4
+
5
+# CLI Test with Bundling (CI)
6
+
7
+Trigger the `Build CLI Binaries` workflow on GitHub Actions, wait for it to complete, download the built binary for the current platform, and test it locally.
8
+
9
+## Prerequisites
10
+
11
+- `gh` CLI authenticated with access to `ComposioHQ/composio`
12
+- Current branch pushed to the remote
13
+
14
+## Step 1: Determine the version
15
+
16
+Read the version from `ts/packages/cli/package.json`:
17
+
18
+```bash
19
+jq -r .version ts/packages/cli/package.json
20
+```
21
+
22
+## Step 2: Trigger the workflow
23
+
24
+```bash
25
+gh workflow run build-cli-binaries.yml \
26
+ --repo ComposioHQ/composio \
27
+ --ref "$(git rev-parse --abbrev-ref HEAD)" \
28
+ --field version="<version-from-step-1>"
29
+```
30
+
31
+## Step 3: Find and monitor the run
32
+
33
+After triggering, wait a few seconds then find the run:
34
+
35
+```bash
36
+gh run list \
37
+ --repo ComposioHQ/composio \
38
+ --workflow build-cli-binaries.yml \
39
+ --limit 1 \
40
+ --json databaseId,status,headBranch
41
+```
42
+
43
+Then watch it until completion:
44
+
45
+```bash
46
+gh run watch <run-id> --repo ComposioHQ/composio
47
+```
48
+
49
+Alternatively, use `/loop 5m gh run view <run-id> --repo ComposioHQ/composio` to poll the workflow status every 5 minutes while you continue other work.
50
+
51
+## Step 4: Download and install the binary
52
+
53
+Once the run succeeds, determine the platform artifact name:
54
+
55
+| Platform | Artifact name |
56
+|-----------------|--------------------------|
57
+| macOS ARM64 | composio-darwin-aarch64 |
58
+| macOS x64 | composio-darwin-x64 |
59
+| Linux x64 | composio-linux-x64 |
60
+| Linux ARM64 | composio-linux-aarch64 |
61
+
62
+Detect the right one automatically:
63
+
64
+```bash
65
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
66
+ARCH=$(uname -m)
67
+case "$ARCH" in
68
+ arm64|aarch64) ARCH="aarch64" ;;
69
+ x86_64) ARCH="x64" ;;
70
+esac
71
+ARTIFACT="composio-${OS}-${ARCH}"
72
+```
73
+
74
+Then download from the release. The workflow creates a GitHub release tagged `@composio/cli@<version>`:
75
+
76
+```bash
77
+VERSION="<version-from-step-1>"
78
+TAG="@composio/cli@${VERSION}"
79
+ENCODED_TAG=$(python3 -c "import urllib.parse; print(urllib.parse.quote('${TAG}', safe=''))")
80
+
81
+mkdir -p /tmp/composio-prerelease-test && cd /tmp/composio-prerelease-test \
82
+ && curl -L -o "${ARTIFACT}.zip" \
83
+ "https://github.com/ComposioHQ/composio/releases/download/${ENCODED_TAG}/${ARTIFACT}.zip" \
84
+ && unzip -o "${ARTIFACT}.zip" \
85
+ && ./${ARTIFACT}/composio --version
86
+```
87
+
88
+Alternatively, download the artifact directly from the workflow run (doesn't require waiting for the release job):
89
+
90
+```bash
91
+gh run download <run-id> \
92
+ --repo ComposioHQ/composio \
93
+ --name "${ARTIFACT}" \
94
+ --dir /tmp/composio-prerelease-test
95
+
96
+cd /tmp/composio-prerelease-test && unzip -o "${ARTIFACT}.zip" && ./${ARTIFACT}/composio --version
97
+```
98
+
99
+## Step 5: Test the binary
100
+
101
+Run commands against the downloaded binary:
102
+
103
+```bash
104
+BINARY="/tmp/composio-prerelease-test/${ARTIFACT}/composio"
105
+
106
+$BINARY version
107
+$BINARY whoami
108
+$BINARY --help
109
+```
110
+
111
+### Critical: Test `run` and `subAgent`
112
+
113
+`composio run` and `experimental_subAgent()` inside `run` have complex bundling — they spawn child Bun processes using companion modules that live outside the compiled binary. These are the most likely commands to break in a bundled build. Always test them explicitly:
114
+
115
+```bash
116
+# Test composio run with a simple inline script
117
+$BINARY run 'console.log("hello from composio run")'
118
+
119
+# Test composio run with subAgent (requires OPENAI_API_KEY or similar)
120
+$BINARY run 'const result = await experimental_subAgent({ goal: "What is 2+2?", toolNames: [] }); console.log(result)'
121
+```
122
+
123
+If either of these fails, the companion module bundling is broken — check `ts/packages/cli/scripts/build-binary.ts` and the `buildCompanionModules` function.
124
+
125
+### Auth
126
+
127
+By default, the binary uses your existing Composio CLI auth (stored in `~/.composio/user-config.json`). No extra setup needed.
128
+
129
+### Testing against staging or preview environments
130
+
131
+To test against staging:
132
+
133
+```bash
134
+export COMPOSIO_BASE_URL=https://staging-backend.composio.dev
135
+export COMPOSIO_WEB_URL=https://staging-platform.composio.dev
136
+```
137
+
138
+Or shorthand:
139
+
140
+```bash
141
+export COMPOSIO_ENVIRONMENT=staging
142
+```
143
+
144
+For a preview environment, set the URLs to the preview backend and dashboard:
145
+
146
+```bash
147
+export COMPOSIO_BASE_URL=<preview-backend-url>
148
+export COMPOSIO_WEB_URL=<preview-dashboard-url>
149
+```
150
+
151
+Then authenticate against that environment:
152
+
153
+```bash
154
+$BINARY login
155
+```
156
+
157
+## Step 6: Post results to the PR
158
+
159
+This test should be run on PRs that touch CLI code. After testing, leave a PR comment summarizing the results and how to reproduce. Use `gh pr comment`:
160
+
161
+```bash
162
+gh pr comment <pr-number> --repo ComposioHQ/composio --body "$(cat <<'EOF'
163
+## Binary bundle test results
164
+
165
+| Command | Result |
166
+|---|---|
167
+| `composio version` | ✅ / ❌ |
168
+| `composio whoami` | ✅ / ❌ |
169
+| `composio run '...'` | ✅ / ❌ |
170
+| `composio run` with `experimental_subAgent()` | ✅ / ❌ |
171
+
172
+<details>
173
+<summary>Reproduce locally</summary>
174
+
175
+```sh
176
+mkdir -p /tmp/composio-prerelease-test && cd /tmp/composio-prerelease-test \
177
+ && curl -L -o <ARTIFACT>.zip '<RELEASE_URL>' \
178
+ && unzip -o <ARTIFACT>.zip \
179
+ && ./<ARTIFACT>/composio version
180
+```
181
+
182
+</details>
183
+EOF
184
+)"
185
+```
186
+
187
+Fill in the actual results, artifact name, and release URL. Keep the comment concise — the details block lets anyone reproduce without cluttering the PR.
188
+
189
+## Reference Files
190
+
191
+| File | Purpose |
192
+|---|---|
193
+| `.github/workflows/build-cli-binaries.yml` | CI workflow that builds binaries |
194
+| `ts/packages/cli/package.json` | Source of CLI version |
195
+| `ts/packages/cli/scripts/build-binary.ts` | Local binary build script |
196
+| `ts/packages/cli/scripts/build-binary-cross.ts` | Cross-platform build script |