@thinkrun/cli 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/README.md +349 -0
  2. package/dist/bin/thinkrun.d.ts +6 -0
  3. package/dist/bin/thinkrun.d.ts.map +1 -0
  4. package/dist/bin/thinkrun.js +124 -0
  5. package/dist/bin/thinkrun.js.map +1 -0
  6. package/dist/scripts/browse.sh +1107 -0
  7. package/dist/src/adapters/cloud.d.ts +79 -0
  8. package/dist/src/adapters/cloud.d.ts.map +1 -0
  9. package/dist/src/adapters/cloud.js +637 -0
  10. package/dist/src/adapters/cloud.js.map +1 -0
  11. package/dist/src/adapters/index.d.ts +47 -0
  12. package/dist/src/adapters/index.d.ts.map +1 -0
  13. package/dist/src/adapters/index.js +211 -0
  14. package/dist/src/adapters/index.js.map +1 -0
  15. package/dist/src/adapters/local-command-retry.d.ts +12 -0
  16. package/dist/src/adapters/local-command-retry.d.ts.map +1 -0
  17. package/dist/src/adapters/local-command-retry.js +224 -0
  18. package/dist/src/adapters/local-command-retry.js.map +1 -0
  19. package/dist/src/adapters/local.d.ts +136 -0
  20. package/dist/src/adapters/local.d.ts.map +1 -0
  21. package/dist/src/adapters/local.js +1273 -0
  22. package/dist/src/adapters/local.js.map +1 -0
  23. package/dist/src/adapters/types.d.ts +45 -0
  24. package/dist/src/adapters/types.d.ts.map +1 -0
  25. package/dist/src/adapters/types.js +6 -0
  26. package/dist/src/adapters/types.js.map +1 -0
  27. package/dist/src/commands/actions.d.ts +135 -0
  28. package/dist/src/commands/actions.d.ts.map +1 -0
  29. package/dist/src/commands/actions.js +2207 -0
  30. package/dist/src/commands/actions.js.map +1 -0
  31. package/dist/src/commands/agent-init.d.ts +16 -0
  32. package/dist/src/commands/agent-init.d.ts.map +1 -0
  33. package/dist/src/commands/agent-init.js +222 -0
  34. package/dist/src/commands/agent-init.js.map +1 -0
  35. package/dist/src/commands/analyze.d.ts +11 -0
  36. package/dist/src/commands/analyze.d.ts.map +1 -0
  37. package/dist/src/commands/analyze.js +238 -0
  38. package/dist/src/commands/analyze.js.map +1 -0
  39. package/dist/src/commands/cache.d.ts +6 -0
  40. package/dist/src/commands/cache.d.ts.map +1 -0
  41. package/dist/src/commands/cache.js +147 -0
  42. package/dist/src/commands/cache.js.map +1 -0
  43. package/dist/src/commands/cloud.d.ts +6 -0
  44. package/dist/src/commands/cloud.d.ts.map +1 -0
  45. package/dist/src/commands/cloud.js +332 -0
  46. package/dist/src/commands/cloud.js.map +1 -0
  47. package/dist/src/commands/config.d.ts +7 -0
  48. package/dist/src/commands/config.d.ts.map +1 -0
  49. package/dist/src/commands/config.js +208 -0
  50. package/dist/src/commands/config.js.map +1 -0
  51. package/dist/src/commands/doctor.d.ts +127 -0
  52. package/dist/src/commands/doctor.d.ts.map +1 -0
  53. package/dist/src/commands/doctor.js +684 -0
  54. package/dist/src/commands/doctor.js.map +1 -0
  55. package/dist/src/commands/evaluate-helpers.d.ts +6 -0
  56. package/dist/src/commands/evaluate-helpers.d.ts.map +1 -0
  57. package/dist/src/commands/evaluate-helpers.js +13 -0
  58. package/dist/src/commands/evaluate-helpers.js.map +1 -0
  59. package/dist/src/commands/install.d.ts +118 -0
  60. package/dist/src/commands/install.d.ts.map +1 -0
  61. package/dist/src/commands/install.js +975 -0
  62. package/dist/src/commands/install.js.map +1 -0
  63. package/dist/src/commands/release.d.ts +7 -0
  64. package/dist/src/commands/release.d.ts.map +1 -0
  65. package/dist/src/commands/release.js +123 -0
  66. package/dist/src/commands/release.js.map +1 -0
  67. package/dist/src/commands/reset-connection.d.ts +17 -0
  68. package/dist/src/commands/reset-connection.d.ts.map +1 -0
  69. package/dist/src/commands/reset-connection.js +141 -0
  70. package/dist/src/commands/reset-connection.js.map +1 -0
  71. package/dist/src/commands/session-debug.d.ts +23 -0
  72. package/dist/src/commands/session-debug.d.ts.map +1 -0
  73. package/dist/src/commands/session-debug.js +267 -0
  74. package/dist/src/commands/session-debug.js.map +1 -0
  75. package/dist/src/commands/setup.d.ts +53 -0
  76. package/dist/src/commands/setup.d.ts.map +1 -0
  77. package/dist/src/commands/setup.js +249 -0
  78. package/dist/src/commands/setup.js.map +1 -0
  79. package/dist/src/config/store.d.ts +39 -0
  80. package/dist/src/config/store.d.ts.map +1 -0
  81. package/dist/src/config/store.js +290 -0
  82. package/dist/src/config/store.js.map +1 -0
  83. package/dist/src/daemon/access.d.ts +53 -0
  84. package/dist/src/daemon/access.d.ts.map +1 -0
  85. package/dist/src/daemon/access.js +87 -0
  86. package/dist/src/daemon/access.js.map +1 -0
  87. package/dist/src/daemon/bridge-envelope.d.ts +96 -0
  88. package/dist/src/daemon/bridge-envelope.d.ts.map +1 -0
  89. package/dist/src/daemon/bridge-envelope.js +235 -0
  90. package/dist/src/daemon/bridge-envelope.js.map +1 -0
  91. package/dist/src/daemon/utils.d.ts +43 -0
  92. package/dist/src/daemon/utils.d.ts.map +1 -0
  93. package/dist/src/daemon/utils.js +134 -0
  94. package/dist/src/daemon/utils.js.map +1 -0
  95. package/dist/src/errors.d.ts +60 -0
  96. package/dist/src/errors.d.ts.map +1 -0
  97. package/dist/src/errors.js +87 -0
  98. package/dist/src/errors.js.map +1 -0
  99. package/dist/src/local-bridge-timing.d.ts +31 -0
  100. package/dist/src/local-bridge-timing.d.ts.map +1 -0
  101. package/dist/src/local-bridge-timing.js +41 -0
  102. package/dist/src/local-bridge-timing.js.map +1 -0
  103. package/dist/src/obstacle-recovery/classify-script.d.ts +16 -0
  104. package/dist/src/obstacle-recovery/classify-script.d.ts.map +1 -0
  105. package/dist/src/obstacle-recovery/classify-script.js +53 -0
  106. package/dist/src/obstacle-recovery/classify-script.js.map +1 -0
  107. package/dist/src/obstacle-recovery/obstacle-classifier.d.ts +21 -0
  108. package/dist/src/obstacle-recovery/obstacle-classifier.d.ts.map +1 -0
  109. package/dist/src/obstacle-recovery/obstacle-classifier.js +37 -0
  110. package/dist/src/obstacle-recovery/obstacle-classifier.js.map +1 -0
  111. package/dist/src/obstacle-recovery/state-fingerprint.d.ts +26 -0
  112. package/dist/src/obstacle-recovery/state-fingerprint.d.ts.map +1 -0
  113. package/dist/src/obstacle-recovery/state-fingerprint.js +85 -0
  114. package/dist/src/obstacle-recovery/state-fingerprint.js.map +1 -0
  115. package/dist/src/obstacle-recovery/types.d.ts +44 -0
  116. package/dist/src/obstacle-recovery/types.d.ts.map +1 -0
  117. package/dist/src/obstacle-recovery/types.js +16 -0
  118. package/dist/src/obstacle-recovery/types.js.map +1 -0
  119. package/dist/src/output/formatter.d.ts +55 -0
  120. package/dist/src/output/formatter.d.ts.map +1 -0
  121. package/dist/src/output/formatter.js +55 -0
  122. package/dist/src/output/formatter.js.map +1 -0
  123. package/dist/src/output/mode.d.ts +11 -0
  124. package/dist/src/output/mode.d.ts.map +1 -0
  125. package/dist/src/output/mode.js +16 -0
  126. package/dist/src/output/mode.js.map +1 -0
  127. package/dist/src/protected-flow/detector.d.ts +26 -0
  128. package/dist/src/protected-flow/detector.d.ts.map +1 -0
  129. package/dist/src/protected-flow/detector.js +75 -0
  130. package/dist/src/protected-flow/detector.js.map +1 -0
  131. package/dist/src/protected-flow/types.d.ts +24 -0
  132. package/dist/src/protected-flow/types.d.ts.map +1 -0
  133. package/dist/src/protected-flow/types.js +28 -0
  134. package/dist/src/protected-flow/types.js.map +1 -0
  135. package/dist/src/session/agent-identity.d.ts +65 -0
  136. package/dist/src/session/agent-identity.d.ts.map +1 -0
  137. package/dist/src/session/agent-identity.js +133 -0
  138. package/dist/src/session/agent-identity.js.map +1 -0
  139. package/dist/src/session/cli-session-sync.d.ts +72 -0
  140. package/dist/src/session/cli-session-sync.d.ts.map +1 -0
  141. package/dist/src/session/cli-session-sync.js +244 -0
  142. package/dist/src/session/cli-session-sync.js.map +1 -0
  143. package/dist/src/session/context.d.ts +24 -0
  144. package/dist/src/session/context.d.ts.map +1 -0
  145. package/dist/src/session/context.js +165 -0
  146. package/dist/src/session/context.js.map +1 -0
  147. package/dist/src/session/continuity.d.ts +33 -0
  148. package/dist/src/session/continuity.d.ts.map +1 -0
  149. package/dist/src/session/continuity.js +179 -0
  150. package/dist/src/session/continuity.js.map +1 -0
  151. package/dist/src/session/errors.d.ts +9 -0
  152. package/dist/src/session/errors.d.ts.map +1 -0
  153. package/dist/src/session/errors.js +31 -0
  154. package/dist/src/session/errors.js.map +1 -0
  155. package/dist/src/session/local-continuity.d.ts +16 -0
  156. package/dist/src/session/local-continuity.d.ts.map +1 -0
  157. package/dist/src/session/local-continuity.js +146 -0
  158. package/dist/src/session/local-continuity.js.map +1 -0
  159. package/dist/src/session/signal-handler.d.ts +24 -0
  160. package/dist/src/session/signal-handler.d.ts.map +1 -0
  161. package/dist/src/session/signal-handler.js +35 -0
  162. package/dist/src/session/signal-handler.js.map +1 -0
  163. package/dist/src/shared/local-recovery-policy.d.ts +40 -0
  164. package/dist/src/shared/local-recovery-policy.d.ts.map +1 -0
  165. package/dist/src/shared/local-recovery-policy.js +59 -0
  166. package/dist/src/shared/local-recovery-policy.js.map +1 -0
  167. package/dist/src/shared/recovery-state.d.ts +3 -0
  168. package/dist/src/shared/recovery-state.d.ts.map +1 -0
  169. package/dist/src/shared/recovery-state.js +9 -0
  170. package/dist/src/shared/recovery-state.js.map +1 -0
  171. package/dist/src/types.d.ts +131 -0
  172. package/dist/src/types.d.ts.map +1 -0
  173. package/dist/src/types.js +5 -0
  174. package/dist/src/types.js.map +1 -0
  175. package/dist/src/utils.d.ts +50 -0
  176. package/dist/src/utils.d.ts.map +1 -0
  177. package/dist/src/utils.js +147 -0
  178. package/dist/src/utils.js.map +1 -0
  179. package/dist/src/working-location.d.ts +107 -0
  180. package/dist/src/working-location.d.ts.map +1 -0
  181. package/dist/src/working-location.js +651 -0
  182. package/dist/src/working-location.js.map +1 -0
  183. package/package.json +65 -0
package/README.md ADDED
@@ -0,0 +1,349 @@
1
+ # @thinkrun/cli
2
+
3
+ CLI for ThinkRun browser automation.
4
+
5
+ `thinkrun` is the single CLI for controlling browsers via ThinkRun cloud and local (native host) infrastructure.
6
+
7
+ ## Requirements
8
+
9
+ - Node.js 18+ (uses native `fetch`)
10
+
11
+ ## OS Support
12
+
13
+ - macOS, Linux, Windows
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ npm install -g @thinkrun/cli # works with npm, bun, pnpm, yarn
19
+ thinkrun setup # download native host + register the ThinkRun browser extension
20
+ ```
21
+
22
+ Install directly from this repository on your machine:
23
+
24
+ ```bash
25
+ npm install -g /path/to/mech-browse/packages/cli
26
+ thinkrun setup
27
+ ```
28
+
29
+ ## Quick Start
30
+
31
+ ```bash
32
+ # 1. Install native host and configure API key
33
+ thinkrun setup
34
+
35
+ # 2. Configure API key (if not done during setup)
36
+ thinkrun config set-key tb_your_api_key_here
37
+
38
+ # 3. Start a cloud browser session (waits for provisioning)
39
+ thinkrun cloud start
40
+
41
+ # 4. Navigate and interact
42
+ thinkrun navigate "https://example.com"
43
+ thinkrun snapshot # Get accessibility tree
44
+ thinkrun click "button.submit"
45
+ thinkrun screenshot --output page.png
46
+
47
+ # 5. Stop the session
48
+ thinkrun cloud stop
49
+ ```
50
+
51
+ ## Stateless page cache (no session)
52
+
53
+ One-shot HTML, text, or screenshot via `POST /api/cache/*` (uses your configured API URL and key — same as cloud commands):
54
+
55
+ ```bash
56
+ thinkrun cache text https://example.com --json
57
+ thinkrun cache html https://example.com --provider local --sensitive
58
+ thinkrun cache screenshot https://example.com --json
59
+ ```
60
+
61
+ ## Local Endpoint Quick Start (mech-browser-service)
62
+
63
+ ```bash
64
+ # 1. Point CLI at local server
65
+ thinkrun config set apiUrl http://localhost:3009
66
+
67
+ # 2. Use local TEST_API_KEY from mech-browser-service/.env (often ak_...)
68
+ thinkrun config set-key ak_your_local_test_key
69
+
70
+ # 3. Start/select session, then run actions
71
+ thinkrun cloud start
72
+ thinkrun navigate http://localhost:3000
73
+ ```
74
+
75
+ Use `thinkrun doctor` anytime to verify endpoint mode, health, bridge status, and active session.
76
+
77
+ ## AI Agent Workflow
78
+
79
+ The `snapshot` command returns an accessibility tree — ideal for AI agents that need to understand page structure without screenshots:
80
+
81
+ ```bash
82
+ thinkrun cloud start
83
+ thinkrun navigate "https://github.com/trending"
84
+ thinkrun snapshot # Returns accessibility tree
85
+ thinkrun click "a.repo-name" # AI decides what to click
86
+ thinkrun wait-for-text "README" # Wait for content
87
+ thinkrun extract "article" --format json
88
+ thinkrun cloud stop
89
+ ```
90
+
91
+ ## Commands
92
+
93
+ ### Session Management
94
+
95
+ | Command | Description |
96
+ |---------|-------------|
97
+ | `cloud start` | Start a new cloud browser session |
98
+ | `cloud stop` | Stop the active session |
99
+ | `cloud list` | List all active sessions |
100
+ | `cloud status` | Show session details |
101
+ | `cloud artifacts` | List session artifacts (screenshots, logs, actions) |
102
+ | `cloud use <id>` | Switch active session |
103
+ | `doctor` | Diagnose endpoint/auth/session setup |
104
+
105
+ #### Cloud Start Options
106
+
107
+ ```bash
108
+ thinkrun cloud start [options]
109
+
110
+ Options:
111
+ -b, --browser <type> Browser: chromium (default), firefox, webkit
112
+ --proxy Enable proxy rotation
113
+ --stealth Enable anti-detection mode
114
+ --no-wait Return immediately without waiting for ready
115
+ ```
116
+
117
+ ### Navigation
118
+
119
+ | Command | Description |
120
+ |---------|-------------|
121
+ | `navigate <url>` | Navigate to a URL |
122
+ | `back` | Go back in browser history |
123
+ | `forward` | Go forward in browser history |
124
+
125
+ ```bash
126
+ thinkrun navigate "https://example.com" --wait-until networkidle
127
+ thinkrun back
128
+ thinkrun forward
129
+ ```
130
+
131
+ `navigate`, `evaluate`, `screenshot`, `snapshot`, `click`, and related browser actions run against:
132
+ - the attached local tab after `thinkrun attach <tabId>`
133
+ - a cloud session after `thinkrun cloud start` or `thinkrun cloud use <id>`
134
+
135
+ Use `--mode local` or `--mode cloud` to override persisted context for a single command.
136
+
137
+ ### Interaction
138
+
139
+ | Command | Description |
140
+ |---------|-------------|
141
+ | `click <selector>` | Click an element |
142
+ | `type <selector> <text>` | Type text (appends) |
143
+ | `fill <selector> <value>` | Fill form field (clears first) |
144
+ | `press <key>` | Press keyboard key |
145
+ | `scroll` | Scroll the page |
146
+ | `hover <selector>` | Hover over element |
147
+ | `select <selector> <value>` | Select dropdown option |
148
+
149
+ ```bash
150
+ thinkrun fill "#email" "user@example.com"
151
+ thinkrun fill "#password" "secret123"
152
+ thinkrun press Enter
153
+ thinkrun click ".submit-btn" --timeout 5000
154
+ thinkrun hover ".dropdown-trigger"
155
+ thinkrun select "#country" "US"
156
+ thinkrun scroll --down 500
157
+ thinkrun scroll --to "#footer"
158
+ ```
159
+
160
+ ### Waiting
161
+
162
+ | Command | Description |
163
+ |---------|-------------|
164
+ | `wait <condition>` | Wait for element or time (ms) |
165
+ | `wait-for-text <text>` | Wait for text on page |
166
+
167
+ ```bash
168
+ thinkrun wait 2000 # Wait 2 seconds
169
+ thinkrun wait ".loading-complete" # Wait for element
170
+ thinkrun wait ".spinner" --hidden # Wait for element to hide
171
+ thinkrun wait-for-text "Success" --timeout 10000 # Wait for text
172
+ ```
173
+
174
+ ### Observation
175
+
176
+ | Command | Description |
177
+ |---------|-------------|
178
+ | `snapshot` | Get accessibility tree |
179
+ | `screenshot` | Capture screenshot (`--caption` required when syncing a local session to ThinkRun) |
180
+ | `extract <selector>` | Extract content from elements |
181
+ | `evaluate [script]` | Execute JavaScript in page |
182
+ | `url` | Get the current page URL (cloud) |
183
+ | `title` | Get the current page title (cloud) |
184
+ | `html` | Get the full page HTML (cloud) |
185
+
186
+ ```bash
187
+ thinkrun snapshot
188
+ thinkrun screenshot --output page.png --full-page
189
+ thinkrun extract "h1"
190
+ thinkrun extract ".item" --all --format json
191
+ thinkrun extract "a" --attr href --all
192
+ thinkrun evaluate "document.title"
193
+ thinkrun evaluate --file script.js
194
+ thinkrun url
195
+ thinkrun title
196
+ thinkrun html > page.html
197
+ ```
198
+
199
+ If a local tab is already synced into the Activity Feed, screenshots must include an explicit caption so the dashboard reflects the agent's intent:
200
+
201
+ ```bash
202
+ thinkrun screenshot --caption "Checkout confirmation before submit" --output page.png
203
+ ```
204
+
205
+ ### Dialog Handling
206
+
207
+ | Command | Description |
208
+ |---------|-------------|
209
+ | `dialog get` | Check for pending dialog |
210
+ | `dialog accept [text]` | Accept dialog |
211
+ | `dialog dismiss` | Dismiss dialog |
212
+
213
+ ```bash
214
+ thinkrun dialog get # Check for alerts/confirms/prompts
215
+ thinkrun dialog accept # Accept alert/confirm
216
+ thinkrun dialog accept "my answer" # Accept prompt with text
217
+ thinkrun dialog dismiss # Dismiss/cancel dialog
218
+ ```
219
+
220
+ ### Monitoring
221
+
222
+ | Command | Description |
223
+ |---------|-------------|
224
+ | `console` | Get browser console messages |
225
+ | `network` | Get network requests |
226
+ | `clear-logs` | Clear console and network logs (cloud) |
227
+
228
+ ```bash
229
+ thinkrun console # View console.log, warnings, errors
230
+ thinkrun network # View XHR, fetch, and other requests
231
+ thinkrun clear-logs # Reset logs for the active session
232
+ ```
233
+
234
+ ### Local Mode (Native Host)
235
+
236
+ These commands require the native host to be running (`thinkrun doctor` will confirm).
237
+
238
+ | Command | Description |
239
+ |---------|-------------|
240
+ | `tabs` | List open tabs in your Chromium-based browser |
241
+ | `new-tab [url]` | Open a new local browser tab without rebinding the active session |
242
+ | `close-tab [tabId]` | Close a local browser tab (defaults to the attached tab) |
243
+ | `attach <tabId>` | Attach to a tab and set it as the active session |
244
+ | `switch-tab <tabId>` | Switch the active tab in your Chromium-based browser without changing session config |
245
+ | `focus` | Bring the attached tab's browser window to the foreground |
246
+ | `new-window [url]` | Open a new local window and auto-attach to it |
247
+ | `release` | Release the local session lock and close the synced CLI session |
248
+
249
+ ```bash
250
+ # List all open tabs
251
+ thinkrun tabs
252
+
253
+ # Open a new background tab, inspect it, then close it
254
+ thinkrun new-tab https://example.com
255
+ thinkrun tabs
256
+ thinkrun close-tab 12345
257
+
258
+ # Attach to a specific tab by ID, then run actions against it
259
+ thinkrun attach 12345
260
+ thinkrun snapshot
261
+ thinkrun navigate "https://example.com"
262
+
263
+ # Switch which tab is active in your Chromium-based browser without updating the session config
264
+ thinkrun switch-tab 12345
265
+ ```
266
+
267
+ If `attach` succeeds but a later browser action still reports a session error, run `thinkrun session debug --json`. That output distinguishes persisted local tab binding, working-location lock, and cloud session context.
268
+
269
+ ## Configuration
270
+
271
+ ```bash
272
+ thinkrun config set-key <api-key> # Set API key
273
+ thinkrun config show # Show current config
274
+ thinkrun config set apiUrl <url> # Set custom API URL
275
+ thinkrun config set defaultBrowser firefox
276
+ thinkrun config reset # Reset all config
277
+ ```
278
+
279
+ Config file: `~/.config/thinkrun/config.json`
280
+
281
+ ## Global Options
282
+
283
+ - `--json` — Force JSON output (auto-enabled for non-TTY)
284
+ - `--quiet` — Suppress non-error output
285
+ - `--verbose` — Show debugging info
286
+
287
+ ## Examples
288
+
289
+ ### Web Scraping
290
+
291
+ ```bash
292
+ thinkrun cloud start
293
+ thinkrun navigate "https://news.ycombinator.com"
294
+ thinkrun extract ".titleline > a" --all --format json > titles.json
295
+ thinkrun screenshot --output hn.png
296
+ thinkrun cloud stop
297
+ ```
298
+
299
+ ### Form Automation
300
+
301
+ ```bash
302
+ thinkrun cloud start
303
+ thinkrun navigate "https://example.com/login"
304
+ thinkrun fill "#email" "user@example.com"
305
+ thinkrun fill "#password" "secret123"
306
+ thinkrun click "button[type=submit]"
307
+ thinkrun wait-for-text "Dashboard"
308
+ thinkrun screenshot --output logged-in.png
309
+ thinkrun cloud stop
310
+ ```
311
+
312
+ ### Debugging a Page
313
+
314
+ ```bash
315
+ thinkrun cloud start
316
+ thinkrun navigate "https://myapp.com"
317
+ thinkrun console # Check for JS errors
318
+ thinkrun network # Check failed requests
319
+ thinkrun snapshot # See page structure
320
+ thinkrun url # Confirm current URL
321
+ thinkrun title # Confirm page title
322
+ thinkrun cloud stop
323
+ ```
324
+
325
+ ## Error Handling
326
+
327
+ The CLI returns structured errors with suggestions:
328
+
329
+ ```
330
+ Error: API key not configured
331
+ Tip: Run: thinkrun config set-key <your-api-key>
332
+ ```
333
+
334
+ Retryable errors (502, 503) are automatically retried with exponential backoff.
335
+
336
+ ## Troubleshooting
337
+
338
+ | Issue | Solution |
339
+ |-------|----------|
340
+ | `API key not configured` | Run `thinkrun config set-key <key>` |
341
+ | `Invalid API key` (local URL) | Use local `TEST_API_KEY` from `mech-browser-service/.env` |
342
+ | `No active session` | Run `thinkrun cloud start`, or `thinkrun cloud list` then `thinkrun cloud use <id>` |
343
+ | `Session provisioning timed out` | Check `thinkrun cloud status`, try again |
344
+ | `fetch is not defined` | Upgrade to Node.js 18+ |
345
+ | All requests return 404 | Update to latest CLI version |
346
+
347
+ ## License
348
+
349
+ MIT
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ThinkRun CLI Entry Point
4
+ */
5
+ export {};
6
+ //# sourceMappingURL=thinkrun.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"thinkrun.d.ts","sourceRoot":"","sources":["../../bin/thinkrun.ts"],"names":[],"mappings":";AAEA;;GAEG"}
@@ -0,0 +1,124 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ThinkRun CLI Entry Point
4
+ */
5
+ import { Command } from 'commander';
6
+ import { existsSync, readFileSync } from 'fs';
7
+ import { fileURLToPath } from 'url';
8
+ import { dirname, join } from 'path';
9
+ import { handleTermSignal } from '../src/session/signal-handler.js';
10
+ import { setJsonMode } from '../src/output/mode.js';
11
+ import { createConfigCommand } from '../src/commands/config.js';
12
+ import { createCloudCommand } from '../src/commands/cloud.js';
13
+ import { createCacheCommand } from '../src/commands/cache.js';
14
+ import { createDoctorCommand } from '../src/commands/doctor.js';
15
+ import { createResetConnectionCommand } from '../src/commands/reset-connection.js';
16
+ import { createInstallCommand } from '../src/commands/install.js';
17
+ import { createSessionDebugCommand } from '../src/commands/session-debug.js';
18
+ import { createSetupCommand } from '../src/commands/setup.js';
19
+ import { createAnalyzeCommand } from '../src/commands/analyze.js';
20
+ import { createReleaseCommand } from '../src/commands/release.js';
21
+ import { createAgentInitCommand } from '../src/commands/agent-init.js';
22
+ import { createNavigateCommand, createClickCommand, createTypeCommand, createFillCommand, createScrollCommand, createWaitCommand, createWaitForTextCommand, createHoverCommand, createSelectCommand, createPressCommand, createBackCommand, createForwardCommand, createResumeCommand, createSnapshotCommand, createScreenshotCommand, createExtractCommand, createEvaluateCommand, createDialogCommand, createConsoleCommand, createNetworkCommand, createTabsCommand, createNewTabCommand, createCloseTabCommand, createAttachCommand, createUrlCommand, createTitleCommand, createHtmlCommand, createClearLogsCommand, createSwitchTabCommand, createFocusCommand, createNewWindowCommand, createTaskCommand, createTaskStatusCommand, createTaskCancelCommand, } from '../src/commands/actions.js';
23
+ const __filename = fileURLToPath(import.meta.url);
24
+ const __dirname = dirname(__filename);
25
+ function resolvePackageJsonPath() {
26
+ const candidates = [
27
+ join(__dirname, '..', 'package.json'),
28
+ join(__dirname, '..', '..', 'package.json'),
29
+ ];
30
+ for (const candidate of candidates) {
31
+ if (existsSync(candidate))
32
+ return candidate;
33
+ }
34
+ throw new Error(`Unable to locate package.json from ${__dirname}`);
35
+ }
36
+ const packageJson = JSON.parse(readFileSync(resolvePackageJsonPath(), 'utf-8'));
37
+ const program = new Command();
38
+ program
39
+ .name('thinkrun')
40
+ .description('CLI for controlling browsers via ThinkRun')
41
+ .version(packageJson.version)
42
+ .option('--json', 'Output in JSON format (default for non-TTY)')
43
+ .option('--quiet', 'Suppress non-error output')
44
+ .option('--verbose', 'Verbose output with debugging info');
45
+ program.addHelpText('after', '\nDocs:\n' +
46
+ ' https://thinkbrowse.io/docs\n' +
47
+ ' https://thinkbrowse.io/llms.txt\n');
48
+ // Activate JSON mode before any command runs if --json flag is set.
49
+ // isJsonMode() also auto-activates for non-TTY stdout (piped/redirected).
50
+ program.hook('preAction', () => {
51
+ if (program.opts().json) {
52
+ setJsonMode(true);
53
+ }
54
+ });
55
+ // Add commands
56
+ program.addCommand(createSetupCommand());
57
+ program.addCommand(createConfigCommand());
58
+ program.addCommand(createCloudCommand());
59
+ program.addCommand(createCacheCommand());
60
+ program.addCommand(createDoctorCommand());
61
+ program.addCommand(createResetConnectionCommand());
62
+ program.addCommand(createInstallCommand());
63
+ program.addCommand(createSessionDebugCommand());
64
+ // Browser actions
65
+ program.addCommand(createNavigateCommand());
66
+ program.addCommand(createBackCommand());
67
+ program.addCommand(createForwardCommand());
68
+ program.addCommand(createClickCommand());
69
+ program.addCommand(createTypeCommand());
70
+ program.addCommand(createFillCommand());
71
+ program.addCommand(createPressCommand());
72
+ program.addCommand(createScrollCommand());
73
+ program.addCommand(createHoverCommand());
74
+ program.addCommand(createSelectCommand());
75
+ // Waiting
76
+ program.addCommand(createWaitCommand());
77
+ program.addCommand(createWaitForTextCommand());
78
+ // Observation
79
+ program.addCommand(createResumeCommand());
80
+ program.addCommand(createSnapshotCommand());
81
+ program.addCommand(createScreenshotCommand());
82
+ program.addCommand(createExtractCommand());
83
+ program.addCommand(createEvaluateCommand());
84
+ // Dialog, console, network
85
+ program.addCommand(createDialogCommand());
86
+ program.addCommand(createConsoleCommand());
87
+ program.addCommand(createNetworkCommand());
88
+ // Agent identity
89
+ program.addCommand(createAgentInitCommand());
90
+ // Local mode (native host) tab management
91
+ program.addCommand(createTabsCommand());
92
+ program.addCommand(createNewTabCommand());
93
+ program.addCommand(createCloseTabCommand());
94
+ program.addCommand(createAttachCommand());
95
+ program.addCommand(createSwitchTabCommand());
96
+ program.addCommand(createFocusCommand());
97
+ program.addCommand(createNewWindowCommand());
98
+ program.addCommand(createReleaseCommand());
99
+ // Page info
100
+ program.addCommand(createUrlCommand());
101
+ program.addCommand(createTitleCommand());
102
+ program.addCommand(createHtmlCommand());
103
+ // Log management
104
+ program.addCommand(createClearLogsCommand());
105
+ // AI task execution (local mode — native host)
106
+ program.addCommand(createTaskCommand());
107
+ program.addCommand(createTaskStatusCommand());
108
+ program.addCommand(createTaskCancelCommand());
109
+ // Recording analysis
110
+ program.addCommand(createAnalyzeCommand());
111
+ // On SIGINT (Ctrl-C) or SIGTERM (kill/Docker/systemd), send a best-effort
112
+ // local-close to the activity feed so the session is marked failed rather
113
+ // than left in a running/orphaned state. Uses synchronous spawnSync inside
114
+ // closeCliSessionSync so the request completes before the process exits.
115
+ // handleTermSignal is in src/session/signal-handler.ts for testability.
116
+ process.on('SIGINT', handleTermSignal(130, 'failed')); // 128+2: user Ctrl-C = failed
117
+ process.on('SIGTERM', handleTermSignal(143, 'completed')); // 128+15: graceful shutdown = completed
118
+ // Parse arguments
119
+ program.parse(process.argv);
120
+ // Show help if no command provided
121
+ if (!process.argv.slice(2).length) {
122
+ program.outputHelp();
123
+ }
124
+ //# sourceMappingURL=thinkrun.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"thinkrun.js","sourceRoot":"","sources":["../../bin/thinkrun.ts"],"names":[],"mappings":"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"}