@thinkbrowse/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,10 +1,20 @@
 # @thinkbrowse/cli
 
-CLI for controlling browsers via ThinkBrowse cloud infrastructure. 21 commands covering the full browser automation API.
+CLI for ThinkBrowse browser automation.
+
+This package now exposes two global commands:
+- `browse`: portable dual-mode CLI (local native-host + cloud) compatible with existing `scripts/browse.sh` usage.
+- `thinkbrowse`: cloud-focused typed CLI commands.
 
 ## Requirements
 
 - Node.js 18+ (uses native `fetch`)
+- For `browse` command: `bash`, `curl`, `jq`
+
+## OS Support
+
+- `thinkbrowse` command: macOS, Linux, Windows
+- `browse` command: macOS, Linux, and Windows via WSL/Git Bash
 
 ## Installation
 
@@ -12,11 +22,36 @@ CLI for controlling browsers via ThinkBrowse cloud infrastructure. 21 commands c
 npm install -g @thinkbrowse/cli
 ```
 
+Install directly from this repository on your machine:
+
+```bash
+npm install -g /Users/kefentse/dev_env/mech/mech-browse/packages/cli
+```
+
+After install, use from any project:
+
+```bash
+browse session-create
+browse goto <sid> https://example.com
+browse --mode cloud session-artifacts <sid>
+```
+
+### Cloud Session Reuse (via `browse`)
+
+Use `browse --mode cloud` when you want cloud-session parity (persisted session metadata, actions, and artifacts):
+
+```bash
+browse --mode cloud session-details <sid>
+browse --mode cloud session-actions <sid> 100 0
+browse --mode cloud session-artifacts <sid>
+browse --mode cloud artifact-download <artifactId> ./artifact.bin
+```
+
 ## Quick Start
 
 ```bash
 # 1. Configure API key
-thinkbrowse config set-key mech_browse_your_api_key_here
+thinkbrowse config set-key tb_your_api_key_here
 
 # 2. Start a cloud browser session (waits for provisioning)
 thinkbrowse cloud start
@@ -31,6 +66,22 @@ thinkbrowse screenshot --output page.png
 thinkbrowse cloud stop
 ```
 
+## Local Endpoint Quick Start (mech-browser-service)
+
+```bash
+# 1. Point CLI at local server
+thinkbrowse config set apiUrl http://localhost:3009
+
+# 2. Use local TEST_API_KEY from mech-browser-service/.env (often ak_...)
+thinkbrowse config set-key ak_your_local_test_key
+
+# 3. Start/select session, then run actions
+thinkbrowse cloud start
+thinkbrowse navigate http://localhost:3000
+```
+
+Use `thinkbrowse doctor` anytime to verify endpoint mode, health, bridge status, and active session.
+
 ## AI Agent Workflow
 
 The `snapshot` command returns an accessibility tree — ideal for AI agents that need to understand page structure without screenshots:
@@ -56,6 +107,7 @@ thinkbrowse cloud stop
 | `cloud list` | List all active sessions |
 | `cloud status` | Show session details |
 | `cloud use <id>` | Switch active session |
+| `doctor` | Diagnose endpoint/auth/session setup |
 
 #### Cloud Start Options
 
@@ -236,7 +288,8 @@ Retryable errors (502, 503) are automatically retried with exponential backoff.
 | Issue | Solution |
 |-------|----------|
 | `API key not configured` | Run `thinkbrowse config set-key <key>` |
-| `No active session` | Run `thinkbrowse cloud start` first |
+| `Invalid API key` (local URL) | Use local `TEST_API_KEY` from `mech-browser-service/.env` |
+| `No active session` | Run `thinkbrowse cloud start`, or `thinkbrowse cloud list` then `thinkbrowse cloud use <id>` |
 | `Session provisioning timed out` | Check `thinkbrowse cloud status`, try again |
 | `fetch is not defined` | Upgrade to Node.js 18+ |
 | All requests return 404 | Update to latest CLI version |

package/dist/bin/browse.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=browse.d.ts.map

package/dist/bin/browse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../bin/browse.ts"],"names":[],"mappings":""}

package/dist/bin/browse.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packagedScript = join(__dirname, '..', 'scripts', 'browse.sh');
+const devScript = join(__dirname, '..', '..', 'scripts', 'browse.sh');
+const scriptPath = existsSync(packagedScript) ? packagedScript : devScript;
+if (!existsSync(scriptPath)) {
+    console.error('ERROR: browse.sh not found in CLI package.');
+    process.exit(1);
+}
+const result = spawnSync('bash', [scriptPath, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: process.env,
+});
+if (typeof result.status === 'number') {
+    process.exit(result.status);
+}
+process.exit(1);
+//# sourceMappingURL=browse.js.map

package/dist/bin/browse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse.js","sourceRoot":"","sources":["../../bin/browse.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AACrE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AACtE,MAAM,UAAU,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC;AAE3E,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;IAC5B,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;IACvE,KAAK,EAAE,SAAS;IAChB,GAAG,EAAE,OAAO,CAAC,GAAG;CACjB,CAAC,CAAC;AAEH,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}

package/dist/bin/thinkbrowse.js

@@ -19,13 +19,18 @@ program
     .option('--json', 'Output in JSON format (default for non-TTY)')
     .option('--quiet', 'Suppress non-error output')
     .option('--verbose', 'Verbose output with debugging info');
+program.addHelpText('after', '\nDocs:\n' +
+    '  https://thinkbrowse.io/docs\n' +
+    '  https://thinkbrowse.io/llms.txt\n');
 // Import commands
 import { createConfigCommand } from '../src/commands/config.js';
 import { createCloudCommand } from '../src/commands/cloud.js';
+import { createDoctorCommand } from '../src/commands/doctor.js';
 import { createNavigateCommand, createClickCommand, createTypeCommand, createFillCommand, createScrollCommand, createWaitCommand, createWaitForTextCommand, createHoverCommand, createSelectCommand, createPressCommand, createBackCommand, createForwardCommand, createSnapshotCommand, createScreenshotCommand, createExtractCommand, createEvaluateCommand, createDialogCommand, createConsoleCommand, createNetworkCommand, } from '../src/commands/actions.js';
 // Add commands
 program.addCommand(createConfigCommand());
 program.addCommand(createCloudCommand());
+program.addCommand(createDoctorCommand());
 // Browser actions
 program.addCommand(createNavigateCommand());
 program.addCommand(createBackCommand());

package/dist/bin/thinkbrowse.js.map

@@ -1 +1 @@
-{"version":3,"file":"thinkbrowse.js","sourceRoot":"","sources":["../../bin/thinkbrowse.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"thinkbrowse.js","sourceRoot":"","sources":["../../bin/thinkbrowse.ts"],"names":[],"mappings":"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"}