@bctrl/cli 0.1.8 → 0.1.9

package/README.md

@@ -1,113 +1,37 @@
 # BCTRL CLI
 
-Command-line tools for BCTRL cloud browser automation. Use it to create browser runtimes, start live sessions, submit hosted invocations, inspect runs and files, and manage account resources from a terminal or script.
-
-## Install
-
 ```bash
 npm install -g @bctrl/cli
+bctrl auth login
 ```
 
-Requires Node.js 22.14 or newer.
-
-## Authenticate
-
-For an interactive terminal, start the browser approval flow and wait for completion:
-
-```bash
-bctrl auth login --url --wait
-```
-
-For CI, agents, or one-off shells, use an API key:
-
-```bash
-export BCTRL_API_KEY="bctrl_..."
-bctrl auth status
-```
-
-`BCTRL_API_KEY` takes precedence over credentials stored by `bctrl auth login`.
-
-## Quick Start
-
-Create a browser runtime, start it, run an extraction task, then stop it:
-
-```bash
-bctrl runtime create --name research-browser --json
-bctrl runtime start <runtime-id> --json
-
-bctrl runtime invocation create <runtime-id> \
-  --action extract \
-  --instruction "Extract the page title." \
-  --json
-
-bctrl runtime invocation wait <runtime-id> <invocation-id> --json
-bctrl runtime stop <runtime-id>
-```
-
-For full request bodies, pass JSON with `--body`. Inline JSON, `@file`, and `-` for stdin are supported:
-
-```bash
-bctrl runtime invocation create <runtime-id> \
-  --body '{"action":"observe","instruction":"Summarize the current page."}' \
-  --json
-
-cat invocation.json | bctrl runtime invocation create <runtime-id> --body - --json
-```
-
-Use `--params` for path and query overrides when you need the exact API surface:
+Create and start runtimes with `bctrl runtime`. Automation is exposed through a
+small generic Tool interface:
 
 ```bash
-bctrl run list --params '{"limit":25}' --json
-```
-
-## Output
+bctrl tools call stagehand.act \
+  --body '{"runtimeId":"rt_...","instruction":"Click Continue"}'
 
-Print full JSON:
-
-```bash
-bctrl runtime list --json
+bctrl tools start captcha.solve --body '{"runtimeId":"rt_..."}'
+bctrl tool-calls result call_... --params '{"waitSeconds":60}'
 ```
 
-Print selected fields:
+Use persistent conversations for long-running agents:
 
 ```bash
-bctrl runtime list --json id,status,name
+bctrl conversations create \
+  --body '{"agent":"browser-use","runtimeId":"rt_..."}'
+bctrl conversations message conv_... --body '{"text":"Complete checkout"}'
+bctrl conversations stream conv_...
 ```
 
-Filter with jq syntax:
+Every automation path contributes to one Run:
 
 ```bash
-bctrl runtime list --json --jq '.data[] | select(.status == "active")'
+bctrl runs trace run_...
+bctrl runs events run_...
+bctrl runs stream run_...
 ```
 
-Render with a template:
-
-```bash
-bctrl runtime list \
-  --json \
-  --template '{{#each data}}{{id}} {{status}}{{newline}}{{/each}}'
-```
-
-## Common Commands
-
-```bash
-bctrl space list
-bctrl runtime create --name browser-task
-bctrl runtime start <runtime-id>
-bctrl runtime target create <runtime-id> --uri https://example.com --activate
-bctrl runtime invocation create <runtime-id> --action act --instruction "Click the sign in button"
-bctrl run list --json
-bctrl runtime stop <runtime-id>
-```
-
-Run any command with `--help` for the exact arguments and flags:
-
-```bash
-bctrl runtime invocation create --help
-```
-
-## Documentation
-
-- CLI guide: https://platform.bctrl.ai/cli
-- Command reference: https://platform.bctrl.ai/cli/reference
-- API reference: https://platform.bctrl.ai/api-reference
+All JSON-body commands accept inline JSON, `@file.json`, or `-` for stdin through
+`--body`. Use `--json`, `--jq`, or `--template` to control output.

package/dist/api/client.d.ts

@@ -17,6 +17,7 @@ export type RequestOptions = {
     query?: Record<string, string | number | boolean | undefined>;
     idempotencyKey?: string;
     actingSubaccountId?: string;
+    runtimeId?: string;
 };
 export type JsonRequestOptions = RequestOptions & {
     body?: unknown;

package/dist/api/client.js

@@ -120,6 +120,7 @@ function requestHeaders(token, options, accept) {
         authorization: `Bearer ${token}`,
         'user-agent': 'BCTRL CLI',
         ...(options?.actingSubaccountId ? { 'BCTRL-Subaccount-Id': options.actingSubaccountId } : {}),
+        ...(options?.runtimeId ? { 'BCTRL-Runtime-Id': options.runtimeId } : {}),
     };
 }
 function buildUrl(baseUrl, path, query) {

package/dist/api/errors.js

@@ -77,8 +77,8 @@ function suggestionForApiError(error) {
             return commandWithOptionalSpace('bctrl toolset list', error.details);
         case 'tool_call.not_found':
             return 'bctrl tool-call list';
-        case 'vault_secret.not_found':
-            return 'bctrl vault list';
+        case 'tool.not_found':
+            return 'bctrl tools list';
         case 'browser_extension.not_found':
             return 'bctrl browser extension list';
         case 'ai_credential.not_found':

package/dist/commands/{vault → account}/index.d.ts

@@ -1,3 +1,3 @@
 import { Command } from 'commander';
 import type { Factory } from '../../factory.js';
-export declare function createVaultCommand(factory: Factory): Command;
+export declare function createAccountCommand(factory: Factory): Command;

package/dist/commands/account/index.js

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+import { addOutputFlags } from '../shared/output.js';
+import { createOperationJsonBodyCommand, outputFlags, requestOperationAndPrint, } from '../shared/operation.js';
+export function createAccountCommand(factory) {
+    const command = new Command('account').description('Manage organization settings');
+    command.addCommand(addOutputFlags(new Command('get').description('Get organization settings')).action(async (options) => {
+        await requestOperationAndPrint(factory, 'account.get', {
+            output: outputFlags(options),
+        });
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'account.update',
+        name: 'patch',
+        description: 'Update organization settings (use --body for branding merge-patch JSON)',
+        configure: (cmd) => cmd.option('--dry-run', 'Validate and resolve without persisting'),
+        query: (_args, options) => ({
+            dryRun: options.dryRun === true,
+        }),
+    }));
+    return command;
+}

package/dist/commands/ai/index.js

@@ -70,14 +70,19 @@ function createAiCredentialWriteCommand(factory, name, operationId, argNames = [
         name,
         description: name === 'create' ? 'Create an AI credential' : 'Update an AI credential',
         argNames,
-        configure: (cmd) => cmd
-            .option('--name <name>', 'Credential name')
-            .option('--provider <provider>', 'Provider key')
-            .option('--api-key <key>', 'Provider API key')
-            .option('--status <status>', 'Credential status')
-            .option('--default-model <model>', 'Default model')
-            .option('--base-url <url>', 'Custom provider base URL')
-            .option('--subaccount-id <id>', 'Subaccount scope when using a parent/org key'),
+        configure: (cmd) => {
+            const configured = cmd
+                .option('--name <name>', 'Credential name')
+                .option('--provider <provider>', 'Provider key')
+                .option('--api-key <key>', 'Provider API key')
+                .option('--status <status>', 'Credential status')
+                .option('--default-model <model>', 'Default model')
+                .option('--base-url <url>', 'Custom provider base URL');
+            if (name === 'create') {
+                configured.option('--subaccount-id <id>', 'Use this Subaccount account context with an Organization key');
+            }
+            return configured;
+        },
         body: async (_args, options) => {
             return {
                 name: options.name,

package/dist/commands/api-key/index.js

@@ -23,7 +23,7 @@ export function createApiKeyCommand(factory) {
         description: 'Create an API key',
         configure: (cmd) => cmd
             .option('--name <name>', 'API key name')
-            .option('--subaccount-id <id>', 'Create a subaccount-scoped key')
+            .option('--subaccount-id <id>', 'Create a key confined to this Subaccount')
             .option('--expires-at <iso>', 'Expiration timestamp'),
         body: async (_args, options) => {
             return {

package/dist/commands/browser-extension/index.js

@@ -5,7 +5,7 @@ import { actingSubaccountOption, createOperationDeleteCommand, createOperationJs
 export function createBrowserExtensionCommand(factory) {
     const command = new Command('browser-extension').description('Manage browser extensions');
     command.addCommand(createOperationListCommand(factory, {
-        operationId: 'browser-extensions.list',
+        operationId: 'browser.extensions.list',
         description: 'List browser extensions',
         configure: (cmd) => cmd
             .option('--subaccount-id <id>', 'Filter by subaccount id')
@@ -20,7 +20,7 @@ export function createBrowserExtensionCommand(factory) {
         actingSubaccountId: actingSubaccountOption(),
     }));
     command.addCommand(createOperationViewCommand(factory, {
-        operationId: 'browser-extensions.get',
+        operationId: 'browser.extensions.get',
         name: 'get',
         description: 'Get a browser extension',
         argName: 'extensionId',
@@ -29,9 +29,9 @@ export function createBrowserExtensionCommand(factory) {
         .description('Upload a browser extension package')
         .argument('<path>')
         .option('--name <name>', 'Display name')
-        .option('--subaccount-id <id>', 'Create under a subaccount when using a parent/org key')).action(async (path, options) => {
+        .option('--subaccount-id <id>', 'Create in this Subaccount account context with an Organization key')).action(async (path, options) => {
         const file = await readBlob(path);
-        const result = await uploadOperationFile(factory, 'browser-extensions.upload', {
+        const result = await uploadOperationFile(factory, 'browser.extensions.create', {
             file: file.blob,
             fileName: file.fileName,
             fields: {
@@ -42,13 +42,13 @@ export function createBrowserExtensionCommand(factory) {
         await outputData(factory.io, result, options);
     }));
     command.addCommand(createOperationJsonBodyCommand(factory, {
-        operationId: 'browser-extensions.import',
+        operationId: 'browser.extensions.create',
         name: 'import',
         description: 'Import a browser extension from a URL',
         configure: (cmd) => cmd
             .option('--url <url>', 'Extension URL')
             .option('--name <name>', 'Display name')
-            .option('--subaccount-id <id>', 'Create under a subaccount when using a parent/org key'),
+            .option('--subaccount-id <id>', 'Create in this Subaccount account context with an Organization key'),
         body: async (_args, options) => {
             return {
                 url: options.url,
@@ -58,7 +58,7 @@ export function createBrowserExtensionCommand(factory) {
         actingSubaccountId: (_args, options) => actingSubaccountOption()(options),
     }));
     command.addCommand(createOperationJsonBodyCommand(factory, {
-        operationId: 'browser-extensions.update',
+        operationId: 'browser.extensions.update',
         name: 'patch',
         description: 'Update a browser extension',
         argNames: ['extensionId'],
@@ -69,7 +69,7 @@ export function createBrowserExtensionCommand(factory) {
         },
     }));
     command.addCommand(createOperationDeleteCommand(factory, {
-        operationId: 'browser-extensions.delete',
+        operationId: 'browser.extensions.delete',
         description: 'Delete a browser extension',
         argNames: ['extensionId'],
     }));

package/dist/commands/conversation/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import type { Factory } from '../../factory.js';
+export declare function createConversationCommand(factory: Factory): Command;

package/dist/commands/conversation/index.js

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import { createOperationJsonBodyCommand, createOperationListCommand, createOperationViewCommand, streamOperationText, } from '../shared/operation.js';
+export function createConversationCommand(factory) {
+    const command = new Command('conversations').description('Converse with runtime agents');
+    command.addCommand(createOperationListCommand(factory, {
+        operationId: 'conversations.list',
+        description: 'List conversations',
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'conversations.create',
+        name: 'create',
+        description: 'Create a conversation',
+    }));
+    command.addCommand(createOperationViewCommand(factory, {
+        operationId: 'conversations.get',
+        name: 'get',
+        description: 'Get a conversation and its messages',
+        argName: 'conversationId',
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'conversations.update',
+        name: 'patch',
+        description: 'Update the default agent, model, toolset, or title',
+        argNames: ['conversationId'],
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'conversations.messages.create',
+        name: 'message',
+        description: 'Send a message and start an agent turn',
+        argNames: ['conversationId'],
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'conversations.cancel',
+        name: 'cancel',
+        description: 'Cancel the active agent turn',
+        argNames: ['conversationId'],
+    }));
+    command.addCommand(new Command('stream')
+        .description('Stream normalized conversation events')
+        .argument('<conversationId>')
+        .option('--after <cursor>', 'Resume after a stream cursor')
+        .action(async (conversationId, options) => {
+        const stream = await streamOperationText(factory, 'conversations.stream', {
+            pathParams: { conversationId },
+            query: { after: options.after },
+        });
+        for await (const chunk of stream)
+            factory.io.writeOut(chunk);
+    }));
+    return command;
+}

package/dist/commands/file/index.js

@@ -10,21 +10,26 @@ export function createFileCommand(factory) {
         description: 'List files',
         configure: (cmd) => cmd
             .option('--space <id>', 'Filter by space id')
+            .option('--run <id>', 'Filter by run id')
+            .option('--runtime <id>', 'Filter by runtime id')
+            .option('--type <type...>', 'Filter by file artifact type')
             .option('--source <source>', 'Filter by file source')
             .option('--prefix <path>', 'Filter by path prefix')
             .option('--folders', 'Directory view: direct files plus subfolder rollups')
             .option('--created-after <iso>', 'Only files created after this timestamp')
-            .option('--query <text>', 'Search query')
+            .option('--q <text>', 'Search query')
             .option('-L, --limit <number>', 'Maximum number of results to return', parsePositiveInteger)
             .option('--cursor <cursor>', 'Pagination cursor'),
         query: (options) => ({
             spaceId: typeof options.space === 'string' ? options.space : undefined,
+            runId: typeof options.run === 'string' ? options.run : undefined,
+            runtimeId: typeof options.runtime === 'string' ? options.runtime : undefined,
+            type: Array.isArray(options.type) ? options.type : undefined,
             source: typeof options.source === 'string' ? options.source : undefined,
             prefix: typeof options.prefix === 'string' ? options.prefix : undefined,
             include: options.folders === true ? 'folders' : undefined,
             createdAfter: typeof options.createdAfter === 'string' ? options.createdAfter : undefined,
-            // The public query param is `q` (was sent as `query`, which the API ignores).
-            q: typeof options.query === 'string' ? options.query : undefined,
+            q: typeof options.q === 'string' ? options.q : undefined,
             limit: typeof options.limit === 'number' ? options.limit : undefined,
             cursor: typeof options.cursor === 'string' ? options.cursor : undefined,
         }),