prompteryx 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — prompteryx (CLI)
+
+## 0.2.0 — 2026-10-02
+- Requires `@prompteryx/sdk` ^0.5.0 — publish the SDK first.
+- Fixed: `workflows run --wait` failed with "Execution not found" (the SDK
+  never returned the execution id); `workflows list --search` was ignored;
+  `workflows get` / `runs get` printed the API wrapper instead of the record;
+  `runs logs` printed quoted JSON strings.
+- `whoami` shows remaining AI credits, cloud-browser minutes, Connect Hub calls
+  and workflow runs (it showed only the plan).
+- New flags: `agent --model ID`, `workflows run --webhook-url URL`.
+- 429s say whether it is the key's request limit or a used-up allowance, and
+  when to retry.
+
+## 0.1.0 — 2026-09-20
+- First release: OAuth (PKCE + loopback) or API-key login, agent, workflows,
+  runs, browser, schedules, apps (Connect Hub), mcp.

package/README.md

@@ -1,54 +1,54 @@
-# prompteryx
-
-The [Prompteryx](https://www.prompteryx.ai) command line. Run AI browser agents, cloud browsers, Visual Studio workflows and Connect Hub actions from a terminal or a CI job.
-
-```bash
-npm install -g prompteryx      # or: npx prompteryx <command>
-prompteryx login               # opens the browser; approve once, tokens refresh automatically
-prompteryx agent "Find the cheapest direct flight from London to Lisbon next Tuesday"
-```
-
-## Sign in
-
-| Command | Use when |
-|---|---|
-| `prompteryx login` | You are at a keyboard. Opens `https://www.prompteryx.ai/oauth/authorize`; no key is pasted. |
-| `prompteryx login --key px_live_…` | Servers and CI. Create the key in Settings → API Keys. |
-| `prompteryx login --cloud-browser-key pcb_live_…` | Needed only for `prompteryx browser …`. Create it in Cloud Platform → API Keys. |
-
-`PROMPTERYX_API_KEY` and `PROMPTERYX_API_URL` environment variables override the saved config (`~/.prompteryx/config.json`). Add `--json` to any command for machine-readable output.
-
-## Commands
-
-```text
-agent "goal" [--start-url URL] [--max-steps N] [--max-credits N] [--save-as-workflow] [--local]
-workflows list [--search q] | get <id> | run <id> [--input key=value …] [--wait] [--visible]
-runs get <id> | wait <id> | logs <id>
-browser create [--record] [--local] | list | close <id>
-schedules list [--workflow <id>]
-apps list [--search q] | actions <app> | accounts | run <app> <action> --params '{"to":"…"}' [--account <id>]
-mcp <claude-code|cursor|vscode|claude-desktop|http>
-whoami | logout | help | version
-```
-
-### Examples
-
-```bash
-# Run a workflow with variables and wait for the result
-prompteryx workflows run fHX8NlpAJxoWuAOll7zr --input postcode="SW1A 1AA" --wait
-
-# Start a cloud browser and drive it from Playwright
-prompteryx browser create --record
-#   Connect with Playwright: chromium.connectOverCDP("wss://…")
-
-# Send an email through a connected Gmail account
-prompteryx apps actions gmail
-prompteryx apps run gmail gmail-send-email --params '{"to":"hello@example.com","subject":"Hi","body":"From the CLI"}'
-
-# Print the one-line setup for Claude Code
-prompteryx mcp claude-code
-```
-
-Access follows your account's balance of cloud browser minutes and AI credits, whatever plan you are on. When a limit is hit the command explains what to top up.
-
-Docs: https://www.prompteryx.ai/docs/developers/cli
+# prompteryx
+
+The [Prompteryx](https://www.prompteryx.ai) command line. Run AI browser agents, cloud browsers, Visual Studio workflows and Connect Hub actions from a terminal or a CI job.
+
+```bash
+npm install -g prompteryx      # or: npx prompteryx <command>
+prompteryx login               # opens the browser; approve once, tokens refresh automatically
+prompteryx agent "Find the cheapest direct flight from London to Lisbon next Tuesday"
+```
+
+## Sign in
+
+| Command | Use when |
+|---|---|
+| `prompteryx login` | You are at a keyboard. Opens `https://www.prompteryx.ai/oauth/authorize`; no key is pasted. |
+| `prompteryx login --key px_live_…` | Servers and CI. Create the key in Settings → API Keys. |
+| `prompteryx login --cloud-browser-key pcb_live_…` | Needed only for `prompteryx browser …`. Create it in Cloud Platform → API Keys. |
+
+`PROMPTERYX_API_KEY` and `PROMPTERYX_API_URL` environment variables override the saved config (`~/.prompteryx/config.json`). Add `--json` to any command for machine-readable output.
+
+## Commands
+
+```text
+agent "goal" [--start-url URL] [--model ID] [--max-steps N] [--max-credits N] [--save-as-workflow] [--local]
+workflows list [--search q] | get <id> | run <id> [--input key=value …] [--wait] [--visible] [--webhook-url URL]
+runs get <id> | wait <id> | logs <id>
+browser create [--record] [--local] | list | close <id>
+schedules list [--workflow <id>]
+apps list [--search q] | actions <app> | accounts | run <app> <action> --params '{"to":"…"}' [--account <id>]
+mcp <claude-code|cursor|vscode|claude-desktop|http>
+whoami | logout | help | version
+```
+
+### Examples
+
+```bash
+# Run a workflow with variables and wait for the result
+prompteryx workflows run fHX8NlpAJxoWuAOll7zr --input postcode="SW1A 1AA" --wait
+
+# Start a cloud browser and drive it from Playwright
+prompteryx browser create --record
+#   Connect with Playwright: chromium.connectOverCDP("wss://…")
+
+# Send an email through a connected Gmail account
+prompteryx apps actions gmail
+prompteryx apps run gmail gmail-send-email --params '{"to":"hello@example.com","subject":"Hi","body":"From the CLI"}'
+
+# Print the one-line setup for Claude Code
+prompteryx mcp claude-code
+```
+
+Access follows your account's balance of cloud browser minutes and AI credits, whatever plan you are on. When a limit is hit the command explains what to top up.
+
+Docs: https://www.prompteryx.ai/docs/developers/cli

package/dist/index.js

@@ -4,7 +4,7 @@
  *
  *   prompteryx login [--key px_live_…] [--cloud-browser-key pcb_live_…]
  *   prompteryx whoami | logout
- *   prompteryx agent "goal" [--start-url URL] [--max-steps N] [--save-as-workflow] [--local]
+ *   prompteryx agent "goal" [--start-url URL] [--model ID] [--max-steps N] [--save-as-workflow] [--local]
  *   prompteryx workflows list | get <id> | run <id> [--input k=v …] [--wait] [--visible] [--json]
  *   prompteryx runs get <id> | wait <id> | logs <id>
  *   prompteryx browser create [--record] [--local] | list | close <id>
@@ -17,7 +17,7 @@
 import { Prompteryx } from '@prompteryx/sdk';
 import { baseUrl, configPath, readConfig, updateConfig, writeConfig } from './config.js';
 import { ensureFreshOAuth, oauthLogin, revokeOAuth } from './login.js';
-const VERSION = '0.1.0';
+const VERSION = '0.2.0';
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
@@ -148,24 +148,33 @@ async function cmdWhoami() {
         console.log(`Signed in via ${cfg.oauth ? 'OAuth (browser sign-in)' : 'API key'} to ${baseUrl(cfg)}`);
         if (sub?.tier)
             console.log(`Plan: ${sub.tier}`);
-        const u = sub?.usage ?? sub;
-        if (u?.aiCredits !== undefined || u?.aiCreditsUsed !== undefined) {
-            console.log(`AI credits used: ${u.aiCreditsUsed ?? '?'} / ${u.aiCredits ?? u.aiCreditsIncluded ?? '?'}`);
-        }
-        if (u?.cloudBrowserMinutes !== undefined)
-            console.log(`Cloud browser minutes used: ${u.cloudBrowserMinutes}`);
+        // GET /api/v1/subscription → { tier, balances: { aiCredits: { remaining, included }, … }, topUpBalances }
+        const b = sub?.balances ?? {};
+        const top = sub?.topUpBalances ?? {};
+        const line = (label, k) => {
+            if (!b[k])
+                return;
+            const extra = top[k] ? ` (+${top[k]} top-up)` : '';
+            console.log(`${label}: ${b[k].remaining} of ${b[k].included} left${extra}`);
+        };
+        line('AI credits', 'aiCredits');
+        line('Cloud browser minutes', 'cloudBrowserMinutes');
+        line('Connect Hub calls', 'connectHubCalls');
+        line('Workflow runs this month', 'monthlyExecutions');
         console.log(`Cloud-browser key: ${cfg.cloudBrowserKey ? 'saved' : 'not set (needed for `prompteryx browser`)'}`);
     });
 }
 async function cmdAgent(args) {
     const goal = args.positional.slice(1).join(' ').trim();
     if (!goal)
-        throw new UsageError('Usage: prompteryx agent "what you want done" [--start-url URL] [--max-steps N] [--save-as-workflow] [--local]');
+        throw new UsageError('Usage: prompteryx agent "what you want done" [--start-url URL] [--model ID] [--max-steps N] [--max-credits N] [--save-as-workflow] [--local]');
     const px = await client();
     console.error(`Running the AI browser agent${bool(args.flags.local) ? ' on your local Chrome' : ' in a cloud browser'}…`);
     const result = await px.autopilot.run({
         goal,
         startUrl: str(args.flags['start-url']),
+        // Catalog: AUTOPILOT_MODELS in @prompteryx/sdk (default gemini-3.5-flash).
+        model: str(args.flags.model),
         maxSteps: num(args.flags['max-steps']),
         maxCredits: num(args.flags['max-credits']),
         saveAsWorkflow: bool(args.flags['save-as-workflow']),
@@ -203,7 +212,7 @@ async function cmdWorkflows(args) {
             const execution = bool(args.flags.visible) ? { runMode: 'visible' } : undefined;
             if (bool(args.flags.wait)) {
                 console.error('Running and waiting for the result…');
-                const rec = await px.workflows.runAndWait(id, { input, execution, timeoutMs: (num(args.flags.timeout) ?? 300) * 1000 });
+                const rec = await px.workflows.runAndWait(id, { input, execution, webhookUrl: str(args.flags['webhook-url']), timeoutMs: (num(args.flags.timeout) ?? 300) * 1000 });
                 print(rec, () => {
                     console.log(`${rec.status}  (${rec.durationMs != null ? `${Math.round(rec.durationMs / 1000)}s` : ''}) run ${rec.id}`);
                     if (rec.error)
@@ -213,7 +222,7 @@ async function cmdWorkflows(args) {
                 });
                 return;
             }
-            const started = await px.workflows.run(id, { input, execution });
+            const started = await px.workflows.run(id, { input, execution, webhookUrl: str(args.flags['webhook-url']) });
             print(started, () => console.log(`Started run ${started.executionId} (${started.status}). Follow it with: prompteryx runs wait ${started.executionId}`));
             return;
         }
@@ -368,19 +377,19 @@ function cmdMcp(args) {
     }
 }
 function help() {
-    console.log(`prompteryx ${VERSION} — Prompteryx from your terminal
-
-  login [--key px_live_…] [--cloud-browser-key pcb_live_…]   sign in (browser) or save keys
-  whoami | logout
-  agent "goal" [--start-url URL] [--max-steps N] [--save-as-workflow] [--local]
-  workflows list | get <id> | run <id> [--input k=v …] [--wait] [--visible]
-  runs get <id> | wait <id> | logs <id>
-  browser create [--record] [--local] | list | close <id>
-  schedules list [--workflow <id>]
-  apps list [--search q] | actions <app> | accounts | run <app> <action> --params '{…}'
-  mcp <claude-code|cursor|vscode|claude-desktop|http>        print the config for an AI client
-
-  --json on any command prints raw JSON.  PROMPTERYX_API_KEY / PROMPTERYX_API_URL override the saved config.
+    console.log(`prompteryx ${VERSION} — Prompteryx from your terminal
+
+  login [--key px_live_…] [--cloud-browser-key pcb_live_…]   sign in (browser) or save keys
+  whoami | logout
+  agent "goal" [--start-url URL] [--model ID] [--max-steps N] [--max-credits N] [--save-as-workflow] [--local]
+  workflows list [--search q] | get <id> | run <id> [--input k=v …] [--wait] [--visible] [--webhook-url URL]
+  runs get <id> | wait <id> | logs <id>
+  browser create [--record] [--local] | list | close <id>
+  schedules list [--workflow <id>]
+  apps list [--search q] | actions <app> | accounts | run <app> <action> --params '{…}'
+  mcp <claude-code|cursor|vscode|claude-desktop|http>        print the config for an AI client
+
+  --json on any command prints raw JSON.  PROMPTERYX_API_KEY / PROMPTERYX_API_URL override the saved config.
   Docs: https://www.prompteryx.ai/docs/developers/cli`);
 }
 // ── main ─────────────────────────────────────────────────────────────────────
@@ -420,6 +429,10 @@ main().catch((err) => {
         console.error(`Not authorised: ${err.message}\nRun \`prompteryx login\` again.`);
     else if (name === 'QuotaError')
         console.error(`Plan limit: ${err.message}`);
+    else if (name === 'RateLimitError') {
+        const wait = err.retryAfterSeconds ? ` Try again in ${err.retryAfterSeconds}s.` : '';
+        console.error(err.code === 'RATE_LIMIT_EXCEEDED' ? `Too many requests for this key.${wait}` : `Limit reached: ${err.message}.${wait}`);
+    }
     else
         console.error(err?.message || err);
     process.exit(1);

package/package.json

@@ -1,40 +1,41 @@
-{
-  "name": "prompteryx",
-  "version": "0.1.0",
-  "description": "Prompteryx command line: run AI browser agents, cloud browsers, workflows and Connect Hub actions from your terminal.",
-  "author": "Prompteryx <support@prompteryx.ai>",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "prompteryx": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "prompteryx",
-    "cli",
-    "browser-automation",
-    "ai-agent",
-    "workflow",
-    "mcp"
-  ],
-  "dependencies": {
-    "@prompteryx/sdk": "^0.4.2"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "typescript": "^5.4.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "prompteryx",
+  "version": "0.2.0",
+  "description": "Prompteryx command line: run AI browser agents, cloud browsers, workflows and Connect Hub actions from your terminal.",
+  "author": "Prompteryx <support@prompteryx.ai>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "prompteryx": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "prompteryx",
+    "cli",
+    "browser-automation",
+    "ai-agent",
+    "workflow",
+    "mcp"
+  ],
+  "dependencies": {
+    "@prompteryx/sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}