@bctrl/cli 0.1.3 → 0.1.5

package/README.md

@@ -1,95 +1,95 @@
-# 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 a BCTRL API key.
-
-Use an API key for the current shell:
-
-```bash
-export BCTRL_API_KEY="bctrl_..."
-```
-
-Or save it locally:
-
-```bash
-bctrl auth login
-```
-
-If `BCTRL_API_KEY` is already set, `auth login` saves that key. Otherwise, it prompts you to paste an API key.
-
-Check the active auth:
-
-```bash
-bctrl auth status
-```
-
-## 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:
-
-```bash
-bctrl runtime create --input runtime.json
-```
-
-Use `-` to read from stdin:
-
-```bash
-echo '{"type":"browser","spaceId":"sp_123","name":"agent-runtime"}' \
-  | bctrl runtime create --input -
-```
-
-## Output
-
-Print full JSON:
-
-```bash
-bctrl runtime list --space sp_123 --json
-```
-
-Print selected JSON fields:
-
-```bash
-bctrl runtime list --space sp_123 --json id,status,name
-```
-
-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
-```
+# 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 a BCTRL API key.
+
+Use an API key for the current shell:
+
+```bash
+export BCTRL_API_KEY="bctrl_..."
+```
+
+Or save it locally:
+
+```bash
+bctrl auth login
+```
+
+If `BCTRL_API_KEY` is already set, `auth login` saves that key. Otherwise, it prompts you to paste an API key.
+
+Check the active auth:
+
+```bash
+bctrl auth status
+```
+
+## 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:
+
+```bash
+bctrl runtime create --input runtime.json
+```
+
+Use `-` to read from stdin:
+
+```bash
+echo '{"type":"browser","spaceId":"sp_123","name":"agent-runtime"}' \
+  | bctrl runtime create --input -
+```
+
+## Output
+
+Print full JSON:
+
+```bash
+bctrl runtime list --space sp_123 --json
+```
+
+Print selected JSON fields:
+
+```bash
+bctrl runtime list --space sp_123 --json id,status,name
+```
+
+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
+```

package/dist/api/auth.d.ts

@@ -1,15 +1,14 @@
 import { z } from 'zod';
 export declare const AuthWhoamiSchema: z.ZodObject<{
-    authenticated: z.ZodLiteral<true>;
     email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    keyKind: z.ZodEnum<{
-        user: "user";
+    scope: z.ZodEnum<{
+        organization: "organization";
         subaccount: "subaccount";
     }>;
     organizationId: z.ZodString;
-    subaccountId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    userId: z.ZodString;
-    apiKeyId: z.ZodString;
+    subaccountId: z.ZodNullable<z.ZodString>;
+    defaultSpaceId: z.ZodString;
+    keyId: z.ZodString;
     plan: z.ZodString;
 }, z.core.$strict>;
 export type AuthWhoami = z.infer<typeof AuthWhoamiSchema>;

package/dist/api/auth.js

@@ -3,13 +3,12 @@ import { CliError } from '../runtime/errors.js';
 import { apiErrorFromResponse } from './errors.js';
 export const AuthWhoamiSchema = z
     .object({
-    authenticated: z.literal(true),
     email: z.string().email().nullable().optional(),
-    keyKind: z.enum(['user', 'subaccount']),
+    scope: z.enum(['organization', 'subaccount']),
     organizationId: z.string().min(1),
-    subaccountId: z.string().min(1).nullable().optional(),
-    userId: z.string().min(1),
-    apiKeyId: z.string().min(1),
+    subaccountId: z.string().min(1).nullable(),
+    defaultSpaceId: z.string().min(1),
+    keyId: z.string().min(1),
     plan: z.string().min(1),
 })
     .strict();

package/dist/api/client.d.ts

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

package/dist/api/client.js

@@ -21,6 +21,9 @@ async function requestJson(config, method, path, options) {
         authorization: `Bearer ${config.activeToken.token}`,
         'user-agent': 'BCTRL CLI',
     };
+    if (options?.idempotencyKey) {
+        headers['idempotency-key'] = options.idempotencyKey;
+    }
     let body;
     if (options && 'body' in options && options.body !== undefined) {
         headers['content-type'] = 'application/json';

package/dist/api/errors.js

@@ -73,8 +73,8 @@ function suggestionForApiError(error) {
             return 'bctrl vault list';
         case 'browser_extension.not_found':
             return 'bctrl browser extension list';
-        case 'ai_provider.not_found':
-            return 'bctrl ai provider list';
+        case 'ai_credential.not_found':
+            return 'bctrl ai credentials list';
         case 'proxy.not_found':
             return 'bctrl ai proxy list';
         case 'subaccount.not_found':

package/dist/commands/ai/index.js

@@ -1,18 +1,37 @@
 import { Command } from 'commander';
 import { readJsonFile } from '../shared/io.js';
 import { addOutputFlags } from '../shared/output.js';
-import { createDeleteCommand, createJsonBodyCommand, createListCommand, createViewCommand, requestAndPrint, } from '../shared/rest.js';
+import { createOperationDeleteCommand, createOperationJsonBodyCommand, createOperationListCommand, createOperationViewCommand, outputFlags, requestOperationAndPrint, } from '../shared/operation.js';
 export function createAiCommand(factory) {
-    const command = new Command('ai').description('Manage AI providers and proxies');
-    command.addCommand(createAiProviderCommand(factory));
-    command.addCommand(createAiProxyCommand(factory));
+    const command = new Command('ai').description('Manage AI models and credentials');
+    command.addCommand(createAiModelsCommand(factory));
+    command.addCommand(createAiCredentialsCommand(factory));
     return command;
 }
-function createAiProviderCommand(factory) {
-    const command = new Command('provider').description('Manage AI providers');
-    command.addCommand(createListCommand(factory, {
-        description: 'List AI providers',
-        path: '/ai-providers',
+function createAiModelsCommand(factory) {
+    const command = new Command('models').description('Discover AI models');
+    command.addCommand(createOperationListCommand(factory, {
+        operationId: 'ai.models.list',
+        description: 'List AI models',
+        configure: (cmd) => cmd
+            .option('--provider <provider>', 'Filter by provider')
+            .option('--status <status>', 'Filter by support status')
+            .option('--managed <value>', 'Filter by managed availability')
+            .option('--engine <engine>', 'Filter by engine: stagehand or browserUse'),
+        query: (options) => ({
+            provider: typeof options.provider === 'string' ? options.provider : undefined,
+            status: typeof options.status === 'string' ? options.status : undefined,
+            managed: typeof options.managed === 'string' ? parseBooleanFlag(options.managed) : undefined,
+            engine: typeof options.engine === 'string' ? options.engine : undefined,
+        }),
+    }));
+    return command;
+}
+function createAiCredentialsCommand(factory) {
+    const command = new Command('credentials').description('Manage BYOK AI credentials');
+    command.addCommand(createOperationListCommand(factory, {
+        operationId: 'ai.credentials.list',
+        description: 'List AI credentials',
         configure: (cmd) => cmd
             .option('--provider <provider>', 'Filter by provider')
             .option('--name <name>', 'Filter by name')
@@ -23,116 +42,62 @@ function createAiProviderCommand(factory) {
             status: typeof options.status === 'string' ? options.status : undefined,
         }),
     }));
-    command.addCommand(createViewCommand(factory, {
-        description: 'View an AI provider',
-        path: '/ai-providers/{id}',
+    command.addCommand(createOperationViewCommand(factory, {
+        operationId: 'ai.credentials.get',
+        name: 'get',
+        description: 'Get an AI credential',
+        argName: 'credentialId',
+    }));
+    command.addCommand(createAiCredentialWriteCommand(factory, 'create', 'ai.credentials.create'));
+    command.addCommand(createAiCredentialWriteCommand(factory, 'patch', 'ai.credentials.update', ['credentialId']));
+    command.addCommand(addOutputFlags(new Command('test').description('Test an AI credential').argument('<credentialId>')).action(async (credentialId, options) => {
+        await requestOperationAndPrint(factory, 'ai.credentials.test', {
+            pathParams: { credentialId },
+            output: outputFlags(options),
+        });
+    }));
+    command.addCommand(createOperationDeleteCommand(factory, {
+        operationId: 'ai.credentials.delete',
+        description: 'Delete an AI credential',
+        argNames: ['credentialId'],
     }));
-    command.addCommand(createJsonBodyCommand(factory, {
-        name: 'create',
-        description: 'Create an AI provider',
-        method: 'post',
-        path: '/ai-providers',
+    return command;
+}
+function createAiCredentialWriteCommand(factory, name, operationId, argNames = []) {
+    return createOperationJsonBodyCommand(factory, {
+        operationId,
+        name,
+        description: name === 'create' ? 'Create an AI credential' : 'Update an AI credential',
+        argNames,
         configure: (cmd) => cmd
-            .option('--name <name>', 'Provider name')
+            .option('--name <name>', 'Credential name')
             .option('--provider <provider>', 'Provider key')
             .option('--api-key <key>', 'Provider API key')
-            .option('--status <status>', 'Provider status')
+            .option('--status <status>', 'Credential status')
             .option('--default-model <model>', 'Default model')
-            .option('--base-url <url>', 'OpenAI-compatible provider base URL')
-            .option('--subaccount <id>', 'Subaccount scope')
+            .option('--base-url <url>', 'Custom provider base URL')
+            .option('--subaccount-id <id>', 'Subaccount scope when using a parent/org key')
             .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);
+            if (typeof options.input === 'string') {
+                return (await readJsonFile(options.input));
+            }
             return {
                 name: options.name,
                 provider: options.provider,
                 apiKey: options.apiKey,
                 status: options.status,
-                scope: typeof options.subaccount === 'string'
-                    ? { subaccountId: options.subaccount }
-                    : undefined,
-                config: typeof options.defaultModel === 'string' || typeof options.baseUrl === 'string'
-                    ? {
-                        defaultModel: typeof options.defaultModel === 'string' ? options.defaultModel : undefined,
-                        baseUrl: typeof options.baseUrl === 'string' ? options.baseUrl : undefined,
-                    }
-                    : undefined,
+                subaccountId: options.subaccountId,
+                defaultModel: options.defaultModel,
+                baseUrl: options.baseUrl,
             };
         },
-    }));
-    command.addCommand(createJsonBodyCommand(factory, {
-        name: 'edit',
-        description: 'Edit an AI provider',
-        method: 'patch',
-        path: '/ai-providers/{id}',
-        argNames: ['id'],
-        configure: (cmd) => cmd
-            .option('--name <name>', 'Provider name')
-            .option('--api-key <key>', 'Provider API key')
-            .option('--status <status>', 'Provider status')
-            .option('--default-model <model>', 'Default model')
-            .option('--base-url <url>', 'OpenAI-compatible provider base 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 {
-                name: options.name,
-                apiKey: options.apiKey,
-                status: options.status,
-                config: typeof options.defaultModel === 'string' || typeof options.baseUrl === 'string'
-                    ? {
-                        defaultModel: typeof options.defaultModel === 'string' ? options.defaultModel : undefined,
-                        baseUrl: typeof options.baseUrl === 'string' ? options.baseUrl : undefined,
-                    }
-                    : undefined,
-            };
-        },
-    }));
-    command.addCommand(addOutputFlags(new Command('test').description('Test an AI provider').argument('<id>')).action(async (id, options) => {
-        await requestAndPrint(factory, 'post', `/ai-providers/${encodeURIComponent(id)}/test`, {
-            output: options,
-        });
-    }));
-    command.addCommand(createDeleteCommand(factory, {
-        description: 'Delete an AI provider',
-        path: '/ai-providers/{id}',
-    }));
-    return command;
+    });
 }
-function createAiProxyCommand(factory) {
-    const command = new Command('proxy').description('Manage AI/browser proxies');
-    command.addCommand(createListCommand(factory, {
-        description: 'List proxies',
-        path: '/proxies',
-        configure: (cmd) => cmd,
-    }));
-    command.addCommand(createViewCommand(factory, {
-        description: 'View a proxy',
-        path: '/proxies/{id}',
-    }));
-    command.addCommand(createJsonBodyCommand(factory, {
-        name: 'create',
-        description: 'Create a proxy',
-        method: 'post',
-        path: '/proxies',
-    }));
-    command.addCommand(createJsonBodyCommand(factory, {
-        name: 'edit',
-        description: 'Edit a proxy',
-        method: 'patch',
-        path: '/proxies/{id}',
-        argNames: ['id'],
-    }));
-    command.addCommand(addOutputFlags(new Command('test').description('Test a proxy').argument('<id>')).action(async (id, options) => {
-        await requestAndPrint(factory, 'post', `/proxies/${encodeURIComponent(id)}/test`, {
-            output: options,
-        });
-    }));
-    command.addCommand(createDeleteCommand(factory, {
-        description: 'Delete a proxy',
-        path: '/proxies/{id}',
-    }));
-    return command;
+function parseBooleanFlag(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return undefined;
 }

package/dist/commands/{browser → api-key}/index.d.ts

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

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

@@ -0,0 +1,47 @@
+import { Command } from 'commander';
+import { readJsonFile } from '../shared/io.js';
+import { createOperationDeleteCommand, createOperationJsonBodyCommand, createOperationListCommand, } from '../shared/operation.js';
+export function createApiKeyCommand(factory) {
+    const command = new Command('api-key').description('Manage API keys');
+    command.addCommand(createOperationListCommand(factory, {
+        operationId: 'api-keys.list',
+        description: 'List API keys',
+        configure: (cmd) => cmd
+            .option('--subaccount-id <id>', 'Filter by subaccount id')
+            .option('--kind <kind>', 'Filter by key kind: organization or subaccount')
+            .option('-L, --limit <number>', 'Maximum number of results to return')
+            .option('--cursor <cursor>', 'Pagination cursor'),
+        query: (options) => ({
+            subaccountId: typeof options.subaccountId === 'string' ? options.subaccountId : undefined,
+            keyKind: typeof options.kind === 'string' ? options.kind : undefined,
+            limit: typeof options.limit === 'string' ? Number(options.limit) : undefined,
+            cursor: typeof options.cursor === 'string' ? options.cursor : undefined,
+        }),
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'api-keys.create',
+        name: 'create',
+        description: 'Create an API key',
+        configure: (cmd) => cmd
+            .option('--name <name>', 'API key name')
+            .option('--subaccount-id <id>', 'Create a subaccount-scoped key')
+            .option('--expires-at <iso>', 'Expiration timestamp')
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.input === 'string') {
+                return (await readJsonFile(options.input));
+            }
+            return {
+                name: options.name,
+                subaccountId: options.subaccountId,
+                expiresAt: options.expiresAt,
+            };
+        },
+    }));
+    command.addCommand(createOperationDeleteCommand(factory, {
+        operationId: 'api-keys.delete',
+        description: 'Delete an API key',
+        argNames: ['keyId'],
+    }));
+    return command;
+}

package/dist/commands/auth/login.js

@@ -36,11 +36,12 @@ export async function authLoginRun(options) {
     }
     options.io.writeErr(`Logged in to ${config.apiBaseUrl}\n`);
     options.io.writeErr(`Credentials saved to ${path}\n`);
-    options.io.writeErr(`Key kind: ${whoami.keyKind}\n`);
+    options.io.writeErr(`Scope: ${whoami.scope}\n`);
     options.io.writeErr(`Organization: ${whoami.organizationId}\n`);
     if (whoami.subaccountId) {
         options.io.writeErr(`Subaccount: ${whoami.subaccountId}\n`);
     }
+    options.io.writeErr(`Default space: ${whoami.defaultSpaceId}\n`);
     if (config.activeToken?.source === 'BCTRL_API_KEY') {
         options.io.writeErr('BCTRL_API_KEY is set and will take precedence over stored credentials.\n');
     }

package/dist/commands/auth/status.js

@@ -31,6 +31,7 @@ export async function authStatusRun(options) {
     const validateToken = options.validateToken ?? validateAuthToken;
     const whoami = await validateToken(config.apiBaseUrl, config.activeToken.token);
     const status = {
+        authenticated: true,
         apiBaseUrl: config.apiBaseUrl,
         tokenSource: config.activeToken.source,
         ...whoami,
@@ -60,6 +61,10 @@ function writeHumanAuthStatus(io, status) {
     io.writeOut([
         'Authenticated: yes',
         `Email: ${status.email ?? '-'}`,
+        `Scope: ${status.scope}`,
+        `Organization: ${status.organizationId}`,
+        ...(status.subaccountId ? [`Subaccount: ${status.subaccountId}`] : []),
+        `Default space: ${status.defaultSpaceId}`,
         `Plan: ${status.plan}`,
         `Auth: ${formatTokenSource(status.tokenSource)}`,
         `API: ${status.apiBaseUrl}`,

package/dist/commands/browser-extension/index.d.ts

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

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

@@ -0,0 +1,85 @@
+import { Command } from 'commander';
+import { readBlob, readJsonFile } from '../shared/io.js';
+import { addOutputFlags, outputData } from '../shared/output.js';
+import { createOperationDeleteCommand, createOperationJsonBodyCommand, createOperationListCommand, createOperationViewCommand, uploadOperationFile, } from '../shared/operation.js';
+export function createBrowserExtensionCommand(factory) {
+    const command = new Command('browser-extension').description('Manage browser extensions');
+    command.addCommand(createOperationListCommand(factory, {
+        operationId: 'browser-extensions.list',
+        description: 'List browser extensions',
+        configure: (cmd) => cmd
+            .option('--subaccount-id <id>', 'Filter by subaccount id')
+            .option('--q <text>', 'Search query')
+            .option('--format <format>', 'Filter by format')
+            .option('--source <source>', 'Filter by source'),
+        query: (options) => ({
+            subaccountId: typeof options.subaccountId === 'string' ? options.subaccountId : undefined,
+            q: typeof options.q === 'string' ? options.q : undefined,
+            format: typeof options.format === 'string' ? options.format : undefined,
+            source: typeof options.source === 'string' ? options.source : undefined,
+        }),
+    }));
+    command.addCommand(createOperationViewCommand(factory, {
+        operationId: 'browser-extensions.get',
+        name: 'get',
+        description: 'Get a browser extension',
+        argName: 'extensionId',
+    }));
+    command.addCommand(addOutputFlags(new Command('upload')
+        .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) => {
+        const file = await readBlob(path);
+        const result = await uploadOperationFile(factory, 'browser-extensions.upload', {
+            file: file.blob,
+            fileName: file.fileName,
+            fields: {
+                ...(options.name ? { name: options.name } : {}),
+                ...(options.subaccountId ? { subaccountId: options.subaccountId } : {}),
+            },
+        });
+        await outputData(factory.io, result, options);
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'browser-extensions.import',
+        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('--input <path>', 'Read full JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.input === 'string') {
+                return (await readJsonFile(options.input));
+            }
+            return {
+                url: options.url,
+                name: options.name,
+                subaccountId: options.subaccountId,
+            };
+        },
+    }));
+    command.addCommand(createOperationJsonBodyCommand(factory, {
+        operationId: 'browser-extensions.update',
+        name: 'patch',
+        description: 'Update a browser extension',
+        argNames: ['extensionId'],
+        configure: (cmd) => cmd
+            .option('--name <name>', 'Display name')
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.input === 'string') {
+                return (await readJsonFile(options.input));
+            }
+            return { name: options.name };
+        },
+    }));
+    command.addCommand(createOperationDeleteCommand(factory, {
+        operationId: 'browser-extensions.delete',
+        description: 'Delete a browser extension',
+        argNames: ['extensionId'],
+    }));
+    return command;
+}