@bctrl/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,44 +1,97 @@
 # BCTRL CLI
 
-TypeScript command-line interface for BCTRL.
+CLI for controlling BCTRL runtimes, files, runs, vault secrets, tools, and account resources from scripts or AI agents.
 
-This package is intentionally scaffolded around a GitHub CLI-style command architecture:
+## Install
 
-- tiny bin entrypoint
-- testable runtime `main()`
-- lazy factory dependencies
-- IO streams instead of direct `console.log`
-- one module per leaf command
-- `Options + createCommand + run` per command
+```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
+```
 
-## Development
+## Browser Runtime Flow
 
 ```bash
-pnpm -C cli run dev -- --help
-pnpm -C cli run dev -- version
-pnpm -C cli run dev -- auth status
-pnpm -C cli run dev -- space list
+bctrl space list
+bctrl runtime create --space sp_123 --name checkout-test
+bctrl runtime start rt_123
+bctrl runtime connection create rt_123
+bctrl runtime stop rt_123
 ```
 
-## Command Boundary
+## JSON Input
+
+Use `--input` for full request bodies:
 
-This package is for public BCTRL API usage:
+```bash
+bctrl runtime create --input runtime.json
+```
 
-- auth
-- spaces
-- runtimes
-- runs
-- invocations
-- files
-- subaccounts
-- `bctrl version` for current version and future non-blocking update hints
+Use `-` to read from stdin:
 
-Do not add maintainer-only release commands here. CLI publishing belongs in pnpm scripts and CI/CD. Infrastructure rollout commands belong in `@bctrl/machine-cli`.
+```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}}'
+```
 
-Do not add a public `bctrl update` command initially. The public update surface is `bctrl version`, which can later show a safe upgrade command such as `npm install -g @bctrl/cli@latest`.
+## Help
 
-## Build
+Use command help for exact input and output fields:
 
 ```bash
-pnpm -C cli run build
+bctrl runtime create --help
+bctrl runtime start --help
+bctrl runtime connection create --help
 ```

package/dist/api/auth.d.ts

@@ -1,6 +1,7 @@
 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";
         subaccount: "subaccount";

package/dist/api/auth.js

@@ -4,6 +4,7 @@ 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']),
     organizationId: z.string().min(1),
     subaccountId: z.string().min(1).nullable().optional(),

package/dist/commands/ai/index.js

@@ -38,18 +38,26 @@ function createAiProviderCommand(factory) {
             .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('--subaccount <id>', 'Subaccount scope')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return 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' ? { defaultModel: options.defaultModel } : undefined,
+                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,
             };
         },
     }));
@@ -64,22 +72,25 @@ function createAiProviderCommand(factory) {
             .option('--api-key <key>', 'Provider API key')
             .option('--status <status>', 'Provider status')
             .option('--default-model <model>', 'Default model')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .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.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 name: options.name,
                 apiKey: options.apiKey,
                 status: options.status,
-                config: typeof options.defaultModel === 'string' ? { defaultModel: options.defaultModel } : 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,
             };
         },
     }));
-    command.addCommand(addOutputFlags(new Command('test')
-        .description('Test an AI provider')
-        .argument('<id>'))
-        .action(async (id, options) => {
+    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,
         });
@@ -114,10 +125,7 @@ function createAiProxyCommand(factory) {
         path: '/proxies/{id}',
         argNames: ['id'],
     }));
-    command.addCommand(addOutputFlags(new Command('test')
-        .description('Test a proxy')
-        .argument('<id>'))
-        .action(async (id, options) => {
+    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,
         });

package/dist/commands/auth/login.d.ts

@@ -2,10 +2,13 @@ import { Command } from 'commander';
 import type { BctrlConfig } from '../../config/config.js';
 import type { Factory } from '../../factory.js';
 import type { IOStreams } from '../../io/streams.js';
+import { validateAuthToken } from '../../api/auth.js';
 export type AuthLoginOptions = {
     io: IOStreams;
     config: () => Promise<BctrlConfig>;
     withToken?: boolean;
+    validateToken?: typeof validateAuthToken;
+    env?: NodeJS.ProcessEnv;
 };
 export declare function createAuthLoginCommand(factory: Factory, run?: (options: AuthLoginOptions) => Promise<void>): Command;
 export declare function authLoginRun(options: AuthLoginOptions): Promise<void>;

package/dist/commands/auth/login.js

@@ -17,13 +17,12 @@ export function createAuthLoginCommand(factory, run = authLoginRun) {
 }
 export async function authLoginRun(options) {
     const config = await options.config();
-    const token = options.withToken
-        ? (await readStreamText(options.io.in)).trim()
-        : await readHiddenInput(options.io, 'Paste BCTRL API key: ');
+    const { token, source } = await resolveLoginToken(options, config);
     if (!token) {
         throw new CliError('No API key provided');
     }
-    const whoami = await validateAuthToken(config.apiBaseUrl, token);
+    const validateToken = options.validateToken ?? validateAuthToken;
+    const whoami = await validateToken(config.apiBaseUrl, token);
     const now = new Date().toISOString();
     const path = await writeStoredAuth({
         apiBaseUrl: config.apiBaseUrl,
@@ -31,7 +30,10 @@ export async function authLoginRun(options) {
         whoami,
         createdAt: now,
         validatedAt: now,
-    });
+    }, options.env);
+    if (source === 'env') {
+        options.io.writeErr('Using BCTRL_API_KEY from environment.\n');
+    }
     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`);
@@ -43,6 +45,18 @@ export async function authLoginRun(options) {
         options.io.writeErr('BCTRL_API_KEY is set and will take precedence over stored credentials.\n');
     }
 }
+async function resolveLoginToken(options, config) {
+    if (options.withToken) {
+        return { token: (await readStreamText(options.io.in)).trim(), source: 'stdin' };
+    }
+    if (config.activeToken?.source === 'BCTRL_API_KEY') {
+        return { token: config.activeToken.token, source: 'env' };
+    }
+    return {
+        token: await readHiddenInput(options.io, 'Paste BCTRL API key: '),
+        source: 'prompt',
+    };
+}
 async function readStreamText(stream) {
     const chunks = [];
     for await (const chunk of stream) {

package/dist/commands/auth/logout.d.ts

@@ -5,6 +5,7 @@ import type { IOStreams } from '../../io/streams.js';
 export type AuthLogoutOptions = {
     io: IOStreams;
     config: () => Promise<BctrlConfig>;
+    env?: NodeJS.ProcessEnv;
 };
 export declare function createAuthLogoutCommand(factory: Factory, run?: (options: AuthLogoutOptions) => Promise<void>): Command;
 export declare function authLogoutRun(options: AuthLogoutOptions): Promise<void>;

package/dist/commands/auth/logout.js

@@ -10,7 +10,7 @@ export function createAuthLogoutCommand(factory, run = authLogoutRun) {
 }
 export async function authLogoutRun(options) {
     const config = await options.config();
-    const removed = await deleteStoredAuth();
+    const removed = await deleteStoredAuth(options.env);
     if (removed) {
         options.io.writeErr('Removed stored BCTRL credentials.\n');
     }

package/dist/commands/auth/status.d.ts

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import { validateAuthToken } from '../../api/auth.js';
 import type { BctrlConfig } from '../../config/config.js';
 import type { Factory } from '../../factory.js';
 import type { IOStreams } from '../../io/streams.js';
@@ -7,6 +8,7 @@ export type AuthStatusOptions = {
     io: IOStreams;
     config: () => Promise<BctrlConfig>;
     output?: OutputFlags;
+    validateToken?: typeof validateAuthToken;
 };
 export declare function createAuthStatusCommand(factory: Factory, run?: (options: AuthStatusOptions) => Promise<void>): Command;
 export declare function authStatusRun(options: AuthStatusOptions): Promise<void>;

package/dist/commands/auth/status.js

@@ -15,17 +15,61 @@ export function createAuthStatusCommand(factory, run = authStatusRun) {
 export async function authStatusRun(options) {
     const config = await options.config();
     if (!config.activeToken) {
-        await outputData(options.io, {
+        const status = {
             apiBaseUrl: config.apiBaseUrl,
             authenticated: false,
             tokenSource: null,
-        }, options.output);
+        };
+        if (usesStructuredOutput(options.output)) {
+            await outputData(options.io, status, options.output);
+        }
+        else {
+            writeHumanAuthStatus(options.io, status);
+        }
         return;
     }
-    const whoami = await validateAuthToken(config.apiBaseUrl, config.activeToken.token);
-    await outputData(options.io, {
+    const validateToken = options.validateToken ?? validateAuthToken;
+    const whoami = await validateToken(config.apiBaseUrl, config.activeToken.token);
+    const status = {
         apiBaseUrl: config.apiBaseUrl,
         tokenSource: config.activeToken.source,
         ...whoami,
-    }, options.output);
+    };
+    if (usesStructuredOutput(options.output)) {
+        await outputData(options.io, status, options.output);
+    }
+    else {
+        writeHumanAuthStatus(options.io, status);
+    }
+}
+function usesStructuredOutput(output) {
+    return Boolean(output?.json !== undefined || output?.jq || output?.template);
+}
+function writeHumanAuthStatus(io, status) {
+    if (!status.authenticated) {
+        io.writeOut([
+            'Authenticated: no',
+            `API: ${status.apiBaseUrl}`,
+            '',
+            'Run:',
+            '  bctrl auth login',
+            '',
+        ].join('\n'));
+        return;
+    }
+    io.writeOut([
+        'Authenticated: yes',
+        `Email: ${status.email ?? '-'}`,
+        `Plan: ${status.plan}`,
+        `Auth: ${formatTokenSource(status.tokenSource)}`,
+        `API: ${status.apiBaseUrl}`,
+        '',
+    ].join('\n'));
+}
+function formatTokenSource(source) {
+    if (source === 'BCTRL_API_KEY')
+        return 'environment API key';
+    if (source === 'stored')
+        return 'saved API key';
+    return source;
 }

package/dist/commands/browser/index.js

@@ -37,10 +37,10 @@ function createBrowserExtensionCommand(factory) {
         path: '/browser-extensions/import',
         configure: (cmd) => cmd
             .option('--url <url>', 'Extension URL')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string') {
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string') {
+                return readJsonFile(options.input);
             }
             return { source: { type: 'url', url: options.url } };
         },

package/dist/commands/file/index.js

@@ -67,10 +67,10 @@ export function createFileCommand(factory) {
         configure: (cmd) => cmd
             .option('--name <name>', 'Display name')
             .option('--metadata-file <path>', 'Metadata JSON file')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 name: options.name,
                 metadata: typeof options.metadataFile === 'string'

package/dist/commands/invocation/index.js

@@ -17,10 +17,10 @@ export function createInvocationCommand(factory) {
         argNames: ['id'],
         configure: (cmd) => cmd
             .option('--timeout-ms <ms>', 'Timeout in milliseconds')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return { timeoutMs: options.timeoutMs ? Number(options.timeoutMs) : undefined };
         },
     }));

package/dist/commands/run/index.js

@@ -210,10 +210,10 @@ function createRunWaitCommand(factory) {
             .option('--connection <id>', 'Connection id')
             .option('--cursor <cursor>', 'Cursor')
             .option('--timeout-ms <ms>', 'Timeout in milliseconds')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 type: options.type,
                 category: options.category,
@@ -234,10 +234,10 @@ function createRunViewerCommand(factory, name, description) {
         configure: (cmd) => cmd
             .option('--expires-in-seconds <seconds>', 'Viewer expiration in seconds')
             .option('--control <none|input>', 'Live viewer control mode')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 expiresInSeconds: options.expiresInSeconds ? Number(options.expiresInSeconds) : undefined,
                 control: name === 'live' ? options.control : undefined,

package/dist/commands/runtime/index.js

@@ -1,11 +1,12 @@
 import { Command } from 'commander';
 import { CliError } from '../../runtime/errors.js';
+import { addCliHelp } from '../shared/help.js';
 import { readBlob, readJsonFile, writeBinary } from '../shared/io.js';
 import { parsePositiveInteger } from '../shared/options.js';
 import { addOutputFlags, outputData } from '../shared/output.js';
 import { addPaginationFlags, createJsonBodyCommand, createListCommand, createViewCommand, pathTemplate, requestAndPrint, } from '../shared/rest.js';
 export function createRuntimeCommand(factory) {
-    const command = new Command('runtime').description('Launch and manage BCTRL runtimes');
+    const command = new Command('runtime').description('Create, start, stop, and manage BCTRL runtimes');
     command.addCommand(createListCommand(factory, {
         description: 'List runtimes',
         path: '/runtimes',
@@ -23,21 +24,25 @@ export function createRuntimeCommand(factory) {
         description: 'View a runtime',
         path: '/runtimes/{id}',
     }));
-    command.addCommand(createJsonBodyCommand(factory, {
+    command.addCommand(addCliHelp(createJsonBodyCommand(factory, {
         name: 'create',
         description: 'Create a runtime',
         method: 'post',
         path: '/runtimes',
         configure: (cmd) => cmd
-            .requiredOption('--space <id>', 'Space id')
+            .option('--space <id>', 'Space id')
             .option('--name <name>', 'Runtime name')
             .option('--config-file <path>', 'Runtime config JSON file')
             .option('--metadata-file <path>', 'Runtime metadata JSON file')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
+            if (typeof options.space !== 'string' || options.space.length === 0) {
+                throw new CliError('runtime create requires --space unless --input is used');
+            }
             return {
+                type: 'browser',
                 spaceId: options.space,
                 name: options.name,
                 config: typeof options.configFile === 'string' ? await readJsonFile(options.configFile, '--config-file') : undefined,
@@ -46,7 +51,15 @@ export function createRuntimeCommand(factory) {
                     : undefined,
             };
         },
-    }));
+    }), 'runtime.create'));
+    command.addCommand(addCliHelp(addOutputFlags(new Command('start')
+        .description('Start a runtime')
+        .argument('<id>'))
+        .action(async (id, options) => {
+        await requestAndPrint(factory, 'post', `/runtimes/${encodeURIComponent(id)}/start`, {
+            output: options,
+        });
+    }), 'runtime.start'));
     command.addCommand(addOutputFlags(new Command('stop')
         .description('Stop a runtime')
         .argument('<id>'))
@@ -83,7 +96,7 @@ function createRuntimeConnectionCommand(factory) {
             output: options,
         });
     }));
-    command.addCommand(createJsonBodyCommand(factory, {
+    command.addCommand(addCliHelp(createJsonBodyCommand(factory, {
         name: 'create',
         description: 'Create a runtime connection',
         method: 'post',
@@ -91,17 +104,15 @@ function createRuntimeConnectionCommand(factory) {
         argNames: ['runtime'],
         configure: (cmd) => cmd
             .option('--protocol <protocol>', 'Connection protocol', 'cdp')
-            .option('--ttl-seconds <seconds>', 'Connection TTL in seconds')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 protocol: options.protocol,
-                ttlSeconds: options.ttlSeconds ? Number(options.ttlSeconds) : undefined,
             };
         },
-    }));
+    }), 'runtime.connection.create'));
     command.addCommand(addOutputFlags(new Command('delete')
         .description('Revoke a runtime connection')
         .argument('<runtime>')
@@ -169,10 +180,10 @@ function createRuntimeFileCommand(factory) {
             .option('--file <id>', 'Durable file id')
             .option('--storage-path <path>', 'Advanced: durable BCTRL storage path')
             .option('--name <name>', 'Runtime-local name')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return { fileId: options.file, storagePath: options.storagePath, name: options.name };
         },
     }));
@@ -186,10 +197,10 @@ function createRuntimeFileCommand(factory) {
             .requiredOption('--path <path>', 'Runtime-local path')
             .option('--name <name>', 'Durable file name')
             .option('--storage-path <path>', 'Advanced: durable BCTRL storage path')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return { path: options.path, name: options.name, storagePath: options.storagePath };
         },
     }));

package/dist/commands/shared/help.d.ts

@@ -0,0 +1,24 @@
+import type { Command } from 'commander';
+import { type CliHelpCommandId } from '../../generated/help.js';
+export type CommandHelpField = {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+};
+export type CommandHelpFlag = {
+    name: string;
+    value?: string;
+    description: string;
+    mapsTo?: string;
+};
+export type CommandHelpSpec = {
+    purpose: string;
+    flags?: CommandHelpFlag[];
+    input?: CommandHelpField[];
+    output?: CommandHelpField[];
+    examples?: string[];
+    next?: string[];
+};
+export declare function addStructuredHelp(command: Command, spec: CommandHelpSpec): Command;
+export declare function addCliHelp(command: Command, commandId: CliHelpCommandId): Command;