@bctrl/cli 0.1.7 → 0.1.9

package/README.md

@@ -1,109 +1,37 @@
 # BCTRL CLI
 
-CLI for controlling BCTRL runtimes, files, runs, vault secrets, tools, and account resources from scripts or AI agents.
-
-## Install
-
 ```bash
 npm install -g @bctrl/cli
-```
-
-## Auth
-
-The CLI authenticates with either a browser-approved CLI session or a BCTRL API key.
-
-For a local terminal, start a browser approval and let the CLI poll until you approve it:
-
-```bash
-bctrl auth login --url --wait
-```
-
-For agents that need to hand the URL to a human, split the flow into two commands:
-
-```bash
-bctrl auth login --url
-# approve the printed URL
 bctrl auth login
 ```
 
-Use an API key for CI or a single shell:
-
-```bash
-export BCTRL_API_KEY="bctrl_..."
-```
-
-`BCTRL_API_KEY` takes precedence over stored credentials.
-
-Check the active auth:
-
-```bash
-bctrl auth status
-```
-
-Point contributors at a local or staging stack with `BCTRL_API_URL`:
-
-```bash
-BCTRL_API_URL=http://127.0.0.1:8787/v1 bctrl auth login --url --wait
-```
-
-## Browser Runtime Flow
-
-```bash
-bctrl space list
-bctrl runtime create --space sp_123 --name checkout-test
-bctrl runtime start rt_123
-bctrl runtime stop rt_123
-```
-
-## JSON Input
-
-Use `--input` for full request bodies:
+Create and start runtimes with `bctrl runtime`. Automation is exposed through a
+small generic Tool interface:
 
 ```bash
-bctrl runtime create --input runtime.json
-```
-
-Use `-` to read from stdin:
+bctrl tools call stagehand.act \
+  --body '{"runtimeId":"rt_...","instruction":"Click Continue"}'
 
-```bash
-echo '{"type":"browser","spaceId":"sp_123","name":"agent-runtime"}' \
-  | bctrl runtime create --input -
+bctrl tools start captcha.solve --body '{"runtimeId":"rt_..."}'
+bctrl tool-calls result call_... --params '{"waitSeconds":60}'
 ```
 
-## Output
-
-Print full JSON:
+Use persistent conversations for long-running agents:
 
 ```bash
-bctrl runtime list --space sp_123 --json
+bctrl conversations create \
+  --body '{"agent":"browser-use","runtimeId":"rt_..."}'
+bctrl conversations message conv_... --body '{"text":"Complete checkout"}'
+bctrl conversations stream conv_...
 ```
 
-Print selected JSON fields:
+Every automation path contributes to one Run:
 
 ```bash
-bctrl runtime list --space sp_123 --json id,status,name
+bctrl runs trace run_...
+bctrl runs events run_...
+bctrl runs stream run_...
 ```
 
-Filter with `jq`:
-
-```bash
-bctrl runtime list --space sp_123 --json --jq '.data[] | select(.status == "active")'
-```
-
-Render with a template:
-
-```bash
-bctrl runtime list \
-  --space sp_123 \
-  --json \
-  --template '{{#each data}}{{id}} {{status}}{{newline}}{{/each}}'
-```
-
-## Help
-
-Use command help for exact input and output fields:
-
-```bash
-bctrl runtime create --help
-bctrl runtime start --help
-```
+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,
         }),