@bctrl/cli 0.1.2 → 0.1.4

package/dist/generated/help.js

@@ -1,47 +1,20 @@
 // Generated by scripts/generate/cli-help.mjs. Do not edit by hand.
 export const CLI_HELP_COMMANDS = {
-    "runtime.create": {
-        "kind": "command",
-        "command": "runtime.create",
-        "summary": "Create a browser runtime definition. This does not start the browser.",
-        "usage": "bctrl runtime create [flags]",
-        "flags": [
-            {
-                "name": "--space",
-                "value": "<id>",
-                "description": "Owning space id.",
-                "mapsTo": "input.spaceId"
-            },
-            {
-                "name": "--name",
-                "value": "<name>",
-                "description": "Runtime name.",
-                "mapsTo": "input.name"
-            },
-            {
-                "name": "--config-file",
-                "value": "<path>",
-                "description": "Read runtime config JSON from a file.",
-                "mapsTo": "input.config"
-            },
-            {
-                "name": "--metadata-file",
-                "value": "<path>",
-                "description": "Read runtime metadata JSON from a file.",
-                "mapsTo": "input.metadata"
-            },
-            {
-                "name": "--input",
-                "value": "<path>",
-                "description": "Read the full JSON request body from a file, or - for stdin."
-            }
+    "runtimes.create": {
+        "kind": "topic",
+        "topic": "runtimes.create",
+        "aliases": [
+            "runtime.create",
+            "bctrl runtime create"
         ],
+        "title": "Create a runtime",
+        "summary": "Create a browser runtime definition. This does not start the browser.",
         "input": {
             "fields": [
                 {
                     "name": "spaceId",
-                    "type": "uuid",
-                    "required": true
+                    "type": "uuid | \"default\"",
+                    "required": false
                 },
                 {
                     "name": "type",
@@ -49,7 +22,7 @@ export const CLI_HELP_COMMANDS = {
                     "values": [
                         "\"browser\""
                     ],
-                    "required": true
+                    "required": false
                 },
                 {
                     "name": "name",
@@ -75,6 +48,11 @@ export const CLI_HELP_COMMANDS = {
                     "type": "uuid",
                     "required": true
                 },
+                {
+                    "name": "spaceId",
+                    "type": "uuid",
+                    "required": true
+                },
                 {
                     "name": "name",
                     "type": "string",
@@ -82,11 +60,9 @@ export const CLI_HELP_COMMANDS = {
                 },
                 {
                     "name": "type",
-                    "type": "\"browser\" | \"desktop\" | \"spreadsheet\"",
+                    "type": "\"browser\"",
                     "values": [
-                        "\"browser\"",
-                        "\"desktop\"",
-                        "\"spreadsheet\""
+                        "\"browser\""
                     ],
                     "required": true
                 },
@@ -105,14 +81,19 @@ export const CLI_HELP_COMMANDS = {
                     "type": "uuid | null",
                     "required": true
                 },
+                {
+                    "name": "lastActivityAt",
+                    "type": "datetime",
+                    "required": false
+                },
                 {
                     "name": "createdAt",
-                    "type": "string",
+                    "type": "datetime",
                     "required": true
                 },
                 {
                     "name": "updatedAt",
-                    "type": "string",
+                    "type": "datetime",
                     "required": true
                 },
                 {
@@ -127,155 +108,208 @@ export const CLI_HELP_COMMANDS = {
                 }
             ]
         },
-        "examples": [
-            {
-                "command": "bctrl runtime create --space sp_123 --name checkout-test"
-            },
+        "api": {
+            "method": "POST",
+            "path": "/v1/runtimes",
+            "operationId": "runtimes.create",
+            "requestFields": [
+                "spaceId",
+                "type",
+                "name",
+                "config",
+                "metadata"
+            ],
+            "responseFields": [
+                "id",
+                "spaceId",
+                "name",
+                "type",
+                "status",
+                "activeRunId",
+                "lastActivityAt",
+                "createdAt",
+                "updatedAt",
+                "config",
+                "metadata"
+            ]
+        },
+        "sdk": [
             {
-                "command": "bctrl runtime create --input runtime.json"
+                "language": "typescript",
+                "package": "@bctrl/sdk",
+                "method": "client.runtimes.create"
             }
         ],
-        "next": [
-            {
-                "command": "bctrl runtime start <runtimeId>"
-            }
-        ]
-    },
-    "runtime.start": {
-        "kind": "command",
-        "command": "runtime.start",
-        "summary": "Start a runtime and open its active run.",
-        "usage": "bctrl runtime start <runtimeId>",
-        "output": {
-            "fields": [
+        "cli": {
+            "command": "bctrl runtime create",
+            "usage": "bctrl runtime create [flags]",
+            "flags": [
                 {
-                    "name": "runtime",
-                    "type": "object",
-                    "required": true
+                    "name": "--space",
+                    "value": "<id>",
+                    "description": "Owning space id."
                 },
                 {
-                    "name": "run",
-                    "type": "object",
-                    "required": true
+                    "name": "--name",
+                    "value": "<name>",
+                    "description": "Runtime name."
+                },
+                {
+                    "name": "--profile",
+                    "description": "Persist browser state across runtime starts."
+                },
+                {
+                    "name": "--proxy",
+                    "value": "<id-or-url>",
+                    "description": "Saved proxy id or inline custom proxy URL."
+                },
+                {
+                    "name": "--device",
+                    "value": "<desktop|mobile>",
+                    "description": "Fingerprint device filter."
+                },
+                {
+                    "name": "--os",
+                    "value": "<windows|macos|android|ios>",
+                    "description": "Fingerprint OS filter."
+                },
+                {
+                    "name": "--browser",
+                    "value": "<chrome|edge|safari>",
+                    "description": "Fingerprint browser filter."
+                },
+                {
+                    "name": "--browser-version",
+                    "value": "<version>",
+                    "description": "Fingerprint browser version filter."
+                },
+                {
+                    "name": "--locale",
+                    "value": "<locale>",
+                    "description": "Fingerprint locale/language filter; repeat to set an ordered language stack."
+                },
+                {
+                    "name": "--config-file",
+                    "value": "<path>",
+                    "description": "Read runtime config JSON from a file."
+                },
+                {
+                    "name": "--metadata-file",
+                    "value": "<path>",
+                    "description": "Read runtime metadata JSON from a file."
+                },
+                {
+                    "name": "--input",
+                    "value": "<path>",
+                    "description": "Read the full JSON request body from a file, or - for stdin."
                 }
             ]
         },
         "examples": [
             {
-                "command": "bctrl runtime start rt_123"
+                "audience": "cli",
+                "command": "bctrl runtime create --space sp_123 --name checkout-test"
+            },
+            {
+                "audience": "cli",
+                "command": "bctrl runtime create --name mobile-de --proxy pxy_123 --device mobile --os ios --browser safari --locale de-DE --locale de"
+            },
+            {
+                "audience": "cli",
+                "command": "bctrl runtime create --input runtime.json"
             }
         ],
         "next": [
             {
-                "command": "bctrl runtime connection create <runtimeId>"
+                "topic": "runtimes.start",
+                "command": "bctrl runtime start <runtimeId>"
             }
         ]
     },
-    "runtime.connection.create": {
-        "kind": "command",
-        "command": "runtime.connection.create",
-        "summary": "Create a short-lived CDP connection lease for a started runtime.",
-        "usage": "bctrl runtime connection create <runtimeId> [flags]",
-        "flags": [
-            {
-                "name": "--protocol",
-                "value": "<protocol>",
-                "description": "Connection protocol. Defaults to cdp.",
-                "mapsTo": "input.protocol"
-            },
-            {
-                "name": "--input",
-                "value": "<path>",
-                "description": "Read the full JSON request body from a file, or - for stdin."
-            }
+    "runtimes.start": {
+        "kind": "topic",
+        "topic": "runtimes.start",
+        "aliases": [
+            "runtime.start",
+            "bctrl runtime start"
         ],
-        "input": {
-            "fields": [
-                {
-                    "name": "protocol",
-                    "type": "\"cdp\"",
-                    "values": [
-                        "\"cdp\""
-                    ],
-                    "required": true
-                },
-                {
-                    "name": "options",
-                    "type": "object",
-                    "required": false
-                }
-            ]
-        },
+        "title": "Start a runtime",
+        "summary": "Start a runtime and open its active run.",
         "output": {
             "fields": [
                 {
-                    "name": "id",
+                    "name": "runtimeId",
                     "type": "uuid",
                     "required": true
                 },
                 {
-                    "name": "protocol",
-                    "type": "\"cdp\" | \"cua\" | \"rdp\" | \"vnc\" | \"mcp\" | \"http\"",
-                    "values": [
-                        "\"cdp\"",
-                        "\"cua\"",
-                        "\"rdp\"",
-                        "\"vnc\"",
-                        "\"mcp\"",
-                        "\"http\""
-                    ],
+                    "name": "runId",
+                    "type": "uuid",
                     "required": true
                 },
                 {
                     "name": "status",
-                    "type": "\"active\" | \"expired\" | \"revoked\" | \"closed\"",
+                    "type": "\"active\" | \"stopped\" | \"failed\"",
                     "values": [
                         "\"active\"",
-                        "\"expired\"",
-                        "\"revoked\"",
-                        "\"closed\""
+                        "\"stopped\"",
+                        "\"failed\""
                     ],
                     "required": true
                 },
                 {
-                    "name": "runId",
-                    "type": "uuid",
-                    "required": true
-                },
-                {
-                    "name": "createdAt",
-                    "type": "datetime",
+                    "name": "connectUrl",
+                    "type": "string",
                     "required": true
                 },
                 {
-                    "name": "expiresAt",
-                    "type": "datetime | null",
+                    "name": "protocol",
+                    "type": "\"cdp\"",
+                    "values": [
+                        "\"cdp\""
+                    ],
                     "required": true
                 },
                 {
-                    "name": "closedAt",
-                    "type": "datetime | null",
-                    "required": false
-                },
-                {
-                    "name": "revokedAt",
-                    "type": "datetime | null",
-                    "required": false
-                },
-                {
-                    "name": "endpoint",
-                    "type": "object",
+                    "name": "started",
+                    "type": "boolean",
                     "required": true
                 }
             ]
         },
+        "api": {
+            "method": "POST",
+            "path": "/v1/runtimes/{runtimeId}/start",
+            "operationId": "runtimes.start",
+            "responseFields": [
+                "runtimeId",
+                "runId",
+                "status",
+                "connectUrl",
+                "protocol",
+                "started"
+            ]
+        },
+        "sdk": [
+            {
+                "language": "typescript",
+                "package": "@bctrl/sdk",
+                "method": "client.runtimes.start"
+            }
+        ],
+        "cli": {
+            "command": "bctrl runtime start",
+            "usage": "bctrl runtime start <runtimeId>"
+        },
         "examples": [
             {
-                "command": "bctrl runtime connection create rt_123"
+                "audience": "cli",
+                "command": "bctrl runtime start rt_123"
             }
         ],
         "next": [
             {
+                "topic": "runs.activity.list",
                 "command": "bctrl run events <runId>"
             }
         ]

package/dist/root.js

@@ -1,9 +1,11 @@
 import { Command } from 'commander';
 import { createAiCommand } from './commands/ai/index.js';
+import { createApiKeyCommand } from './commands/api-key/index.js';
 import { createAuthCommand } from './commands/auth/index.js';
-import { createBrowserCommand } from './commands/browser/index.js';
+import { createBrowserExtensionCommand } from './commands/browser-extension/index.js';
 import { createFileCommand } from './commands/file/index.js';
-import { createInvocationCommand } from './commands/invocation/index.js';
+import { createHelpCommand } from './commands/help/index.js';
+import { createProxyCommand } from './commands/proxy/index.js';
 import { createRunCommand } from './commands/run/index.js';
 import { createRuntimeCommand } from './commands/runtime/index.js';
 import { createSpaceCommand } from './commands/space/index.js';
@@ -11,6 +13,7 @@ import { createSubaccountCommand } from './commands/subaccount/index.js';
 import { createToolCommand } from './commands/tool/index.js';
 import { createToolCallCommand } from './commands/tool-call/index.js';
 import { createToolsetCommand } from './commands/toolset/index.js';
+import { createUsageCommand } from './commands/usage/index.js';
 import { createVaultCommand } from './commands/vault/index.js';
 import { createVersionCommand } from './commands/version/version.js';
 export function createRootCommand(factory) {
@@ -25,16 +28,19 @@ export function createRootCommand(factory) {
     command.addCommand(createVersionCommand(factory));
     command.addCommand(createAuthCommand(factory));
     command.addCommand(createAiCommand(factory));
-    command.addCommand(createBrowserCommand(factory));
+    command.addCommand(createApiKeyCommand(factory));
+    command.addCommand(createBrowserExtensionCommand(factory));
     command.addCommand(createFileCommand(factory));
-    command.addCommand(createInvocationCommand(factory));
+    command.addCommand(createHelpCommand(factory));
     command.addCommand(createRunCommand(factory));
     command.addCommand(createRuntimeCommand(factory));
+    command.addCommand(createProxyCommand(factory));
     command.addCommand(createSpaceCommand(factory));
     command.addCommand(createSubaccountCommand(factory));
     command.addCommand(createToolCommand(factory));
     command.addCommand(createToolsetCommand(factory));
     command.addCommand(createToolCallCommand(factory));
+    command.addCommand(createUsageCommand(factory));
     command.addCommand(createVaultCommand(factory));
     return command;
 }

package/package.json

@@ -1,47 +1,47 @@
-{
-  "name": "@bctrl/cli",
-  "version": "0.1.2",
-  "description": "BCTRL command-line interface",
-  "type": "module",
-  "bin": {
-    "bctrl": "./dist/bin/bctrl.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "pnpm run clean && tsc -p tsconfig.json",
-    "dev": "tsx src/bin/bctrl.ts",
-    "prepack": "pnpm run build",
-    "test": "tsx --test \"tests/**/*.test.ts\"",
-    "typecheck": "tsc --noEmit",
-    "typecheck:tests": "tsc --noEmit -p tests/tsconfig.json"
-  },
-  "keywords": [
-    "bctrl",
-    "cli",
-    "browser-automation",
-    "agents"
-  ],
-  "author": "",
-  "license": "ISC",
-  "packageManager": "pnpm@10.12.4",
-  "dependencies": {
-    "commander": "^14.0.3",
-    "handlebars": "^4.7.9",
-    "jq-web": "^0.6.2",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^25.7.0",
-    "tsx": "^4.21.0",
-    "typescript": "^6.0.3"
-  }
-}
+{
+  "name": "@bctrl/cli",
+  "version": "0.1.4",
+  "description": "BCTRL command-line interface",
+  "type": "module",
+  "bin": {
+    "bctrl": "./dist/bin/bctrl.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "dev": "tsx src/bin/bctrl.ts",
+    "prepack": "pnpm run build",
+    "test": "tsx --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc --noEmit -p tests/tsconfig.json"
+  },
+  "keywords": [
+    "bctrl",
+    "cli",
+    "browser-automation",
+    "agents"
+  ],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.12.4",
+  "dependencies": {
+    "commander": "^14.0.3",
+    "handlebars": "^4.7.9",
+    "jq-web": "^0.6.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  }
+}

package/dist/commands/browser/index.js

@@ -1,53 +0,0 @@
-import { Command } from 'commander';
-import { readBlob, readJsonFile } from '../shared/io.js';
-import { addOutputFlags, outputData } from '../shared/output.js';
-import { createDeleteCommand, createJsonBodyCommand, createListCommand, createViewCommand, } from '../shared/rest.js';
-export function createBrowserCommand(factory) {
-    const command = new Command('browser').description('Manage browser resources');
-    command.addCommand(createBrowserExtensionCommand(factory));
-    return command;
-}
-function createBrowserExtensionCommand(factory) {
-    const command = new Command('extension').description('Manage browser extensions');
-    command.addCommand(createListCommand(factory, {
-        description: 'List browser extensions',
-        path: '/browser-extensions',
-        configure: (cmd) => cmd,
-    }));
-    command.addCommand(createViewCommand(factory, {
-        description: 'View a browser extension',
-        path: '/browser-extensions/{id}',
-    }));
-    command.addCommand(addOutputFlags(new Command('upload')
-        .description('Upload a browser extension package')
-        .argument('<path>'))
-        .action(async (path, options) => {
-        const client = await factory.apiClient();
-        const file = await readBlob(path);
-        const result = await client.uploadFile('/browser-extensions/upload', {
-            file: file.blob,
-            fileName: file.fileName,
-        });
-        await outputData(factory.io, result, options);
-    }));
-    command.addCommand(createJsonBodyCommand(factory, {
-        name: 'import',
-        description: 'Import a browser extension from a URL',
-        method: 'post',
-        path: '/browser-extensions/import',
-        configure: (cmd) => cmd
-            .option('--url <url>', 'Extension URL')
-            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
-        body: async (_args, options) => {
-            if (typeof options.input === 'string') {
-                return readJsonFile(options.input);
-            }
-            return { source: { type: 'url', url: options.url } };
-        },
-    }));
-    command.addCommand(createDeleteCommand(factory, {
-        description: 'Delete a browser extension',
-        path: '/browser-extensions/{id}',
-    }));
-    return command;
-}

package/dist/commands/invocation/index.js

@@ -1,36 +0,0 @@
-import { Command } from 'commander';
-import { readJsonFile } from '../shared/io.js';
-import { addOutputFlags } from '../shared/output.js';
-import { createJsonBodyCommand, createViewCommand, requestAndPrint } from '../shared/rest.js';
-export function createInvocationCommand(factory) {
-    const command = new Command('invocation')
-        .description('Inspect and control BCTRL invocations');
-    command.addCommand(createViewCommand(factory, {
-        description: 'View an invocation',
-        path: '/invocations/{id}',
-    }));
-    command.addCommand(createJsonBodyCommand(factory, {
-        name: 'wait',
-        description: 'Wait for an invocation',
-        method: 'post',
-        path: '/invocations/{id}/wait',
-        argNames: ['id'],
-        configure: (cmd) => cmd
-            .option('--timeout-ms <ms>', 'Timeout in milliseconds')
-            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
-        body: async (_args, options) => {
-            if (typeof options.input === 'string')
-                return readJsonFile(options.input);
-            return { timeoutMs: options.timeoutMs ? Number(options.timeoutMs) : undefined };
-        },
-    }));
-    command.addCommand(addOutputFlags(new Command('cancel')
-        .description('Cancel an invocation')
-        .argument('<id>'))
-        .action(async (id, options) => {
-        await requestAndPrint(factory, 'post', `/invocations/${encodeURIComponent(id)}/cancel`, {
-            output: options,
-        });
-    }));
-    return command;
-}