@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/commands/secrets.js

@@ -1,8 +1,17 @@
+/**
+ * Secrets bundle management commands.
+ *
+ * Registers the `agents secrets` command tree for creating, viewing,
+ * and managing named bundles of environment variables backed by macOS
+ * Keychain. Bundles are injected at run time via `agents run --secrets`.
+ */
 import chalk from 'chalk';
 import * as fs from 'fs';
-import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, parseDotenv, readBundle, validateBundleName, validateEnvKey, writeBundle, } from '../lib/secrets-bundles.js';
-import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets.js';
+import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, parseDotenv, readBundle, validateBundleName, validateEnvKey, writeBundle, } from '../lib/secrets/bundles.js';
+import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { registerCommandGroups } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
         throw new Error('A secret is required but the shell is not interactive. Pass --value, --value-stdin, or run from a TTY.');
@@ -10,6 +19,79 @@ async function promptForSecret(message) {
     const { password } = await import('@inquirer/prompts');
     return await password({ message, mask: true });
 }
+/** Prompt the user to pick an existing bundle by name. Requires an interactive TTY. */
+async function pickBundleName(action) {
+    const bundles = listBundles();
+    if (bundles.length === 0) {
+        throw new Error('No secrets bundles configured. Try: agents secrets create <name>');
+    }
+    if (!isInteractiveTerminal()) {
+        throw new Error('A bundle name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { select } = await import('@inquirer/prompts');
+    return await select({
+        message: `Which bundle to ${action}?`,
+        choices: bundles.map((b) => ({
+            name: b.name,
+            value: b.name,
+            description: b.description || undefined,
+        })),
+    });
+}
+/** Prompt the user to type a new bundle name. Requires an interactive TTY. */
+async function promptBundleName() {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A bundle name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { input } = await import('@inquirer/prompts');
+    return await input({
+        message: 'Bundle name',
+        validate: (value) => {
+            try {
+                validateBundleName(value);
+                return true;
+            }
+            catch (err) {
+                return err.message;
+            }
+        },
+    });
+}
+/** Prompt the user to pick an existing key from a bundle. Requires an interactive TTY. */
+async function pickKey(bundle, action) {
+    const keys = Object.keys(bundle.vars);
+    if (keys.length === 0) {
+        throw new Error(`Bundle '${bundle.name}' has no keys.`);
+    }
+    if (!isInteractiveTerminal()) {
+        throw new Error('A key name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { select } = await import('@inquirer/prompts');
+    return await select({
+        message: `Which key to ${action}?`,
+        choices: keys.map((k) => ({ name: k, value: k })),
+    });
+}
+/** Prompt the user to type a new key name for a bundle. Requires an interactive TTY. */
+async function promptKeyName(bundleName) {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A key name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { input } = await import('@inquirer/prompts');
+    return await input({
+        message: `Key name to add to '${bundleName}'`,
+        validate: (value) => {
+            try {
+                validateEnvKey(value);
+                return true;
+            }
+            catch (err) {
+                return err.message;
+            }
+        },
+    });
+}
+/** Read all available data from stdin synchronously, trimmed. */
 function readStdinSync() {
     const chunks = [];
     const buf = Buffer.alloc(65536);
@@ -27,12 +109,14 @@ function readStdinSync() {
     }
     return Buffer.concat(chunks).toString('utf-8').trim();
 }
+/** Format a single bundle as a table row for the `secrets list` output. */
 function renderBundleRow(b) {
     const entries = describeBundle(b);
     const keys = entries.length;
     const sensitive = entries.filter((e) => e.kind === 'keychain').length;
     return `${chalk.cyan(b.name.padEnd(20))} ${String(keys).padEnd(6)} ${chalk.yellow(String(sensitive).padEnd(10))} ${chalk.gray(b.description || '')}`;
 }
+/** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
     switch (kind) {
         case 'literal': return chalk.gray('literal');
@@ -43,6 +127,7 @@ function kindLabel(kind) {
         default: return kind;
     }
 }
+/** Mask a value with asterisks unless reveal is true. */
 function redact(value, reveal) {
     if (reveal)
         return value;
@@ -50,10 +135,53 @@ function redact(value, reveal) {
         return '';
     return '*'.repeat(Math.min(value.length, 8));
 }
+/** Register the `agents secrets` command tree. */
 export function registerSecretsCommands(program) {
     const cmd = program
         .command('secrets')
-        .description('Named bundles of env variables backed by macOS Keychain. Inject into agents via `agents run --secrets <name>`.');
+        .description('Named bundles of env variables backed by macOS Keychain. Inject into agents via `agents run --secrets <name>`.')
+        .addHelpText('after', `
+Workflow:
+  Bundles are containers; secrets are the variables inside them. Create a
+  bundle once, add secrets to it, then inject the whole bundle into any agent
+  run with --secrets <name>. Keychain-backed values never touch disk in
+  plaintext.
+
+Examples:
+  # Create a bundle for production credentials
+  agents secrets create prod --description "Production keys for the api stack"
+
+  # Add a keychain-backed secret (prompts for the value)
+  agents secrets add prod STRIPE_API_KEY
+
+  # Add a literal (non-sensitive) value
+  agents secrets add prod LOG_LEVEL --value info
+
+  # Import an entire .env file straight into keychain
+  agents secrets import prod --from .env.prod
+
+  # See what's in a bundle (values masked)
+  agents secrets view prod
+
+  # Reveal the real values in an interactive shell
+  agents secrets view prod --reveal
+
+  # Inject the bundle into an agent run
+  agents run claude "deploy the worker" --secrets prod
+
+  # Eval the bundle into your current shell
+  eval "$(agents secrets export prod --plaintext)"
+
+  # Remove one key (purges the keychain item by default)
+  agents secrets remove prod STRIPE_API_KEY
+
+  # Delete the whole bundle and purge every keychain item it owned
+  agents secrets delete prod
+`);
+    registerCommandGroups(cmd, [
+        { title: 'Bundle commands', names: ['list', 'view', 'create', 'delete'] },
+        { title: 'Secret commands', names: ['add', 'remove', 'import', 'export'] },
+    ]);
     cmd
         .command('list')
         .alias('ls')
@@ -62,7 +190,7 @@ export function registerSecretsCommands(program) {
         const bundles = listBundles();
         if (bundles.length === 0) {
             console.log(chalk.gray('No secrets bundles configured.'));
-            console.log(chalk.gray('Try: agents secrets add <name>'));
+            console.log(chalk.gray('Try: agents secrets create <name>'));
             return;
         }
         console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(6)} ${'SENSITIVE'.padEnd(10)} DESCRIPTION`));
@@ -71,20 +199,23 @@ export function registerSecretsCommands(program) {
         }
     });
     cmd
-        .command('view <name>')
+        .command('view [name]')
         .alias('show')
         .description('Show a bundle. Keychain values are masked by default — pass --reveal to see them.')
         .option('--reveal', 'Print keychain-backed values in the clear (TTY only unless --plaintext)')
         .option('--plaintext', 'Allow --reveal in non-interactive shells (use with care)')
-        .action((name, opts) => {
+        .action(async (name, opts) => {
         try {
-            const bundle = readBundle(name);
+            const resolvedName = name ?? (await pickBundleName('view'));
+            const bundle = readBundle(resolvedName);
             const entries = describeBundle(bundle);
             console.log(chalk.bold(bundle.name));
             if (bundle.description)
                 console.log(chalk.gray(bundle.description));
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
+            if (bundle.icloud_sync)
+                console.log(chalk.cyan('icloud_sync: true'));
             console.log();
             if (entries.length === 0) {
                 console.log(chalk.gray('(no keys)'));
@@ -98,12 +229,12 @@ export function registerSecretsCommands(program) {
             for (const e of entries) {
                 if (e.kind === 'keychain') {
                     const item = secretsKeychainItem(bundle.name, e.detail);
-                    const stored = hasKeychainToken(item);
+                    const stored = hasKeychainToken(item, bundle.icloud_sync);
                     const marker = stored ? chalk.green('stored') : chalk.red('missing');
                     let valueCol = `[keychain:${e.detail}] ${marker}`;
                     if (reveal && stored) {
                         try {
-                            valueCol = redact(getKeychainToken(item), true);
+                            valueCol = redact(getKeychainToken(item, bundle.icloud_sync), true);
                         }
                         catch {
                             // fall through to masked
@@ -124,41 +255,48 @@ export function registerSecretsCommands(program) {
             }
         }
         catch (err) {
+            if (isPromptCancelled(err))
+                return;
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
     cmd
-        .command('add <name>')
+        .command('create [name]')
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
+        .option('--icloud-sync', 'Store keychain values in iCloud Keychain so they sync across your Macs (requires Xcode CLT)')
         .option('--force', 'Overwrite an existing bundle')
-        .action((name, opts) => {
+        .action(async (name, opts) => {
         try {
-            validateBundleName(name);
-            if (bundleExists(name) && !opts.force) {
-                console.error(chalk.red(`Bundle '${name}' already exists. Use --force to overwrite.`));
+            const resolvedName = name ?? (await promptBundleName());
+            validateBundleName(resolvedName);
+            if (bundleExists(resolvedName) && !opts.force) {
+                console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
                 process.exit(1);
             }
             const bundle = {
-                name,
+                name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
+                icloud_sync: opts.icloudSync,
                 vars: {},
             };
             writeBundle(bundle);
-            console.log(chalk.green(`Bundle '${name}' created.`));
-            console.log(chalk.gray(`Try: agents secrets set ${name} MY_KEY`));
+            console.log(chalk.green(`Bundle '${resolvedName}' created.`));
+            console.log(chalk.gray(`Try: agents secrets add ${resolvedName} MY_KEY`));
         }
         catch (err) {
+            if (isPromptCancelled(err))
+                return;
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
     cmd
-        .command('set <bundle> <key>')
-        .description('Set a variable. Defaults to keychain-backed; pass --value for literal, --env/--file/--exec for refs.')
+        .command('add [bundle] [key]')
+        .description('Add a variable to a bundle. Defaults to keychain-backed; pass --value for literal, --env/--file/--exec for refs.')
         .option('--value <v>', 'Store as a plaintext literal in the YAML (non-sensitive values only)')
         .option('--value-stdin', 'Read the value from stdin (stored in keychain unless combined with --value)')
         .option('--env <VAR>', 'Store as an env: ref that reads from the parent process.env at run time')
@@ -166,37 +304,39 @@ export function registerSecretsCommands(program) {
         .option('--exec <cmd>', 'Store as an exec: ref that runs a command at run time (requires allow_exec)')
         .action(async (bundleName, key, opts) => {
         try {
-            validateEnvKey(key);
-            const bundle = readBundle(bundleName);
+            const resolvedBundleName = bundleName ?? (await pickBundleName('add to'));
+            const bundle = readBundle(resolvedBundleName);
+            const resolvedKey = key ?? (await promptKeyName(resolvedBundleName));
+            validateEnvKey(resolvedKey);
             const sources = [opts.value !== undefined, Boolean(opts.env), Boolean(opts.file), Boolean(opts.exec)].filter(Boolean).length;
             if (sources > 1) {
                 throw new Error('Pick one of: --value, --env, --file, --exec.');
             }
             if (opts.env) {
-                bundle.vars[key] = `env:${opts.env}`;
+                bundle.vars[resolvedKey] = `env:${opts.env}`;
                 writeBundle(bundle);
-                console.log(chalk.green(`${bundleName}.${key} -> env:${opts.env}`));
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> env:${opts.env}`));
                 return;
             }
             if (opts.file) {
-                bundle.vars[key] = `file:${opts.file}`;
+                bundle.vars[resolvedKey] = `file:${opts.file}`;
                 writeBundle(bundle);
-                console.log(chalk.green(`${bundleName}.${key} -> file:${opts.file}`));
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> file:${opts.file}`));
                 return;
             }
             if (opts.exec) {
                 if (!bundle.allow_exec) {
-                    throw new Error(`Bundle '${bundleName}' does not allow exec refs. Re-create with --allow-exec.`);
+                    throw new Error(`Bundle '${resolvedBundleName}' does not allow exec refs. Re-create with --allow-exec.`);
                 }
-                bundle.vars[key] = `exec:${opts.exec}`;
+                bundle.vars[resolvedKey] = `exec:${opts.exec}`;
                 writeBundle(bundle);
-                console.log(chalk.green(`${bundleName}.${key} -> exec:${opts.exec}`));
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> exec:${opts.exec}`));
                 return;
             }
             if (opts.value !== undefined) {
-                bundle.vars[key] = { value: opts.value };
+                bundle.vars[resolvedKey] = { value: opts.value };
                 writeBundle(bundle);
-                console.log(chalk.green(`${bundleName}.${key} = <literal>`));
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} = <literal>`));
                 return;
             }
             // Default path: keychain-backed.
@@ -207,13 +347,14 @@ export function registerSecretsCommands(program) {
                     throw new Error('No value received on stdin.');
             }
             else {
-                secretValue = await promptForSecret(`Enter value for ${bundleName}.${key}`);
+                secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
             }
-            const item = secretsKeychainItem(bundleName, key);
-            setKeychainToken(item, secretValue);
-            bundle.vars[key] = keychainRef(key);
+            const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
+            setKeychainToken(item, secretValue, bundle.icloud_sync);
+            bundle.vars[resolvedKey] = keychainRef(resolvedKey);
             writeBundle(bundle);
-            console.log(chalk.green(`${bundleName}.${key} stored in keychain (${item}).`));
+            const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -223,68 +364,95 @@ export function registerSecretsCommands(program) {
         }
     });
     cmd
-        .command('unset <bundle> <key>')
+        .command('remove [bundle] [key]')
         .description('Remove a key from the bundle. Purges the keychain item if the ref was keychain:. Use --keep-secret to retain it.')
         .option('--keep-secret', 'Leave the keychain item in place after removing the YAML ref')
-        .action((bundleName, key, opts) => {
+        .action(async (bundleName, key, opts) => {
         try {
-            const bundle = readBundle(bundleName);
-            if (!(key in bundle.vars)) {
-                console.error(chalk.red(`Key '${key}' not found in bundle '${bundleName}'.`));
+            const resolvedBundleName = bundleName ?? (await pickBundleName('remove from'));
+            const bundle = readBundle(resolvedBundleName);
+            const resolvedKey = key ?? (await pickKey(bundle, 'remove'));
+            if (!(resolvedKey in bundle.vars)) {
+                console.error(chalk.red(`Key '${resolvedKey}' not found in bundle '${resolvedBundleName}'.`));
                 process.exit(1);
             }
-            const raw = bundle.vars[key];
-            delete bundle.vars[key];
+            const raw = bundle.vars[resolvedKey];
+            delete bundle.vars[resolvedKey];
             writeBundle(bundle);
             if (!opts.keepSecret && typeof raw === 'string' && raw.startsWith('keychain:')) {
-                const item = secretsKeychainItem(bundleName, raw.slice('keychain:'.length));
-                const removed = deleteKeychainToken(item);
+                const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
+                const removed = deleteKeychainToken(item, bundle.icloud_sync);
                 if (removed) {
-                    console.log(chalk.green(`Removed ${bundleName}.${key} and purged keychain item.`));
+                    console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged keychain item.`));
                     return;
                 }
             }
-            console.log(chalk.green(`Removed ${bundleName}.${key}.`));
+            console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey}.`));
         }
         catch (err) {
+            if (isPromptCancelled(err))
+                return;
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
     cmd
-        .command('rm <name>')
-        .alias('remove')
+        .command('delete [name]')
         .description('Delete a bundle and purge all its keychain items (use --keep-secrets to retain them).')
         .option('--keep-secrets', 'Leave keychain items in place after deleting the bundle file')
-        .action((name, opts) => {
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .action(async (name, opts) => {
         try {
-            const bundle = readBundle(name);
+            const resolvedName = name ?? (await pickBundleName('delete'));
+            const bundle = readBundle(resolvedName);
+            if (!opts.yes) {
+                if (!isInteractiveTerminal()) {
+                    console.error(chalk.red(`Refusing to delete '${resolvedName}' without --yes in a non-interactive shell.`));
+                    process.exit(1);
+                }
+                const keychainCount = describeBundle(bundle).filter((e) => e.kind === 'keychain').length;
+                const suffix = keychainCount && !opts.keepSecrets
+                    ? ` and purge ${keychainCount} keychain item${keychainCount === 1 ? '' : 's'}`
+                    : '';
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: `Delete bundle '${resolvedName}'${suffix}?`,
+                    default: false,
+                });
+                if (!proceed) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+            }
             if (!opts.keepSecrets) {
                 for (const { item } of keychainItemsForBundle(bundle)) {
-                    deleteKeychainToken(item);
+                    deleteKeychainToken(item, bundle.icloud_sync);
                 }
             }
-            const existed = deleteBundle(name);
+            const existed = deleteBundle(resolvedName);
             if (!existed) {
-                console.error(chalk.red(`Bundle '${name}' not found.`));
+                console.error(chalk.red(`Bundle '${resolvedName}' not found.`));
                 process.exit(1);
             }
-            console.log(chalk.green(`Bundle '${name}' removed.`));
+            console.log(chalk.green(`Bundle '${resolvedName}' deleted.`));
         }
         catch (err) {
+            if (isPromptCancelled(err))
+                return;
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
     cmd
-        .command('import <bundle>')
+        .command('import [bundle]')
         .description('Import keys from a .env file into a bundle. By default every key is stored in keychain.')
         .requiredOption('--from <path>', 'Path to a .env file')
         .option('--all-plaintext', 'Store every imported value as a YAML literal (skip keychain prompts)')
         .option('--force', 'Overwrite an existing key in the bundle')
-        .action((bundleName, opts) => {
+        .action(async (bundleName, opts) => {
         try {
-            const bundle = readBundle(bundleName);
+            const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
+            const bundle = readBundle(resolvedBundleName);
             const raw = fs.readFileSync(opts.from, 'utf-8');
             const pairs = parseDotenv(raw);
             let added = 0;
@@ -298,8 +466,8 @@ export function registerSecretsCommands(program) {
                     bundle.vars[key] = { value };
                 }
                 else {
-                    const item = secretsKeychainItem(bundleName, key);
-                    setKeychainToken(item, value);
+                    const item = secretsKeychainItem(resolvedBundleName, key);
+                    setKeychainToken(item, value, bundle.icloud_sync);
                     bundle.vars[key] = keychainRef(key);
                 }
                 added++;
@@ -308,18 +476,21 @@ export function registerSecretsCommands(program) {
             console.log(chalk.green(`Imported ${added} key(s)${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
         }
         catch (err) {
+            if (isPromptCancelled(err))
+                return;
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
     cmd
-        .command('export <bundle>')
+        .command('export [bundle]')
         .description('Resolve a bundle and print KEY=VALUE lines (for `eval "$(agents secrets export prod)"`). Refuses on a TTY unless --plaintext.')
         .option('--plaintext', 'Acknowledge that the resolved values will be printed in the clear')
         .action(async (bundleName, opts) => {
         try {
-            const { resolveBundleEnv } = await import('../lib/secrets-bundles.js');
-            const bundle = readBundle(bundleName);
+            const { resolveBundleEnv } = await import('../lib/secrets/bundles.js');
+            const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
+            const bundle = readBundle(resolvedBundleName);
             if (isInteractiveTerminal() && !opts.plaintext) {
                 console.error(chalk.red('export to a TTY requires --plaintext (prevents shoulder-surfing).'));
                 process.exit(1);
@@ -331,9 +502,10 @@ export function registerSecretsCommands(program) {
             }
         }
         catch (err) {
+            if (isPromptCancelled(err))
+                return;
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
 }
-//# sourceMappingURL=secrets.js.map

package/dist/commands/sessions-picker.d.ts

@@ -11,6 +11,7 @@ export interface SessionPickerConfig {
     pageSize?: number;
     initialSearch?: string;
 }
+/** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;
+/** Show an interactive session picker and return the selected session with its action (resume or view). */
 export declare function sessionPicker(config: SessionPickerConfig): Promise<PickedSession | null>;
-//# sourceMappingURL=sessions-picker.d.ts.map