@phnx-labs/agents-cli 1.20.51 → 1.20.52

package/dist/commands/logs.js

@@ -1,10 +1,14 @@
 /**
- * `agents logs` — unified, discoverable run-log viewer.
+ * `agents logs` — unified, discoverable run-log viewer + audit trail.
  *
  * Resolves a run across two substrates and shows (or `-f` follows) its log:
  *  - host-dispatch tasks (`agents run --host`) → combined-stdout log, offset-tailed
  *  - sessions (the local index) → transcript, tailed via the sessions tailer
  *
+ * Subcommands:
+ *  - `agents logs audit` — read the structured audit/event log
+ *  - `agents logs stats` — show aggregate audit statistics
+ *
  * Concise by default: a bare `agents logs <id>` prints the same summary digest as
  * `agents sessions <id>` — cheap for an agent to glance at. The token-heavy full
  * transcript / raw stdout is opt-in behind `--full` (alias `-m/--markdown`).
@@ -17,12 +21,14 @@
  * the same underlying helpers (showHostTaskLog / streamSessionTail).
  */
 import chalk from 'chalk';
+import * as fs from 'fs';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
 import { parseAgentFilter, renderSessionLog } from './sessions.js';
 import { streamSessionTail, isTailable } from './sessions-tail.js';
 import { showHostTaskLog } from '../lib/hosts/logs.js';
 import { listTasks } from '../lib/hosts/tasks.js';
 import { itemPicker } from '../lib/picker.js';
+import { query, stats, getLogsPath, rotate, levelFor, } from '../lib/events.js';
 /** Compact one-line label used by both the picker and the non-TTY list. */
 function candidateLabel(c) {
     if (c.kind === 'task') {
@@ -130,11 +136,207 @@ async function runLogs(id, opts) {
         return;
     await showCandidate(picked.item, follow, full);
 }
+function parseSince(s) {
+    const m = s.match(/^(\d+)([smhdw])$/);
+    if (m) {
+        const n = parseInt(m[1], 10);
+        const unitMs = {
+            s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000,
+        };
+        return new Date(Date.now() - n * unitMs[m[2]]);
+    }
+    const ms = Date.parse(s);
+    if (isNaN(ms))
+        throw new Error(`Invalid --since value: ${s} (use e.g. 2h, 7d, or an ISO date)`);
+    return new Date(ms);
+}
+function originLabel(r) {
+    if (r.transport === 'ssh') {
+        return chalk.yellow(`ssh${r.sshClientIp ? ' ' + r.sshClientIp : ''}`);
+    }
+    return chalk.gray('local');
+}
+function auditDetailFor(r) {
+    if (r.command)
+        return r.command;
+    const bits = [];
+    if (typeof r.team === 'string')
+        bits.push(`team=${r.team}`);
+    if (typeof r.bundle === 'string')
+        bits.push(`bundle=${r.bundle}`);
+    if (typeof r.skill === 'string')
+        bits.push(`skill=${r.skill}`);
+    if (typeof r.version === 'string')
+        bits.push(`v=${r.version}`);
+    if (typeof r.profile === 'string')
+        bits.push(`profile=${r.profile}`);
+    if (typeof r.server === 'string')
+        bits.push(`server=${r.server}`);
+    if (typeof r.error === 'string')
+        bits.push(chalk.red(r.error));
+    return bits.join(' ');
+}
+function levelColor(level) {
+    if (level === 'audit')
+        return chalk.magenta(level);
+    if (level === 'warn')
+        return chalk.yellow(level);
+    if (level === 'debug')
+        return chalk.gray(level);
+    return chalk.blue(level);
+}
+function renderAuditRow(r) {
+    const time = chalk.gray(r.ts.slice(0, 19).replace('T', ' '));
+    const user = `${r.osUser ?? '?'}@${r.hostname}`;
+    const ev = r.event.startsWith('error') ? chalk.red(r.event) : chalk.cyan(r.event);
+    const lvl = levelColor(r.level ?? levelFor(r.event));
+    const agent = r.agent ? chalk.gray(` ${r.agent}`) : '';
+    const caller = chalk.gray(`via ${r.caller ?? 'unknown'}${r.session ? ` ${r.session}` : ''}`);
+    return `${time}  ${lvl.padEnd(14)} ${originLabel(r).padEnd(24)} ${user.padEnd(22)} ${caller.padEnd(28)} ${ev.padEnd(26)}${agent}  ${auditDetailFor(r)}`;
+}
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+async function runAudit(opts) {
+    if (opts.follow) {
+        await followAuditLog();
+        return;
+    }
+    const limit = Math.max(1, parseInt(opts.limit ?? '50', 10) || 50);
+    let startDate;
+    try {
+        startDate = opts.since ? parseSince(opts.since) : undefined;
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(2);
+    }
+    const records = query({
+        startDate,
+        eventTypes: opts.event?.length ? opts.event : undefined,
+        level: opts.level,
+        agent: opts.agent,
+        caller: opts.caller,
+        command: opts.command,
+        module: opts.module,
+        limit,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(records, null, 2));
+        return;
+    }
+    if (records.length === 0) {
+        console.log(chalk.gray('No matching events.'));
+        return;
+    }
+    for (const r of records.slice().reverse())
+        console.log(renderAuditRow(r));
+    console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
+}
+async function followAuditLog() {
+    const file = getLogsPath();
+    let offset = 0;
+    try {
+        offset = fs.statSync(file).size;
+    }
+    catch {
+        // File may not exist yet — start at 0.
+    }
+    console.log(chalk.gray(`Tailing ${file} — Ctrl-C to stop`));
+    const drain = () => {
+        let size = 0;
+        try {
+            size = fs.statSync(file).size;
+        }
+        catch {
+            return;
+        }
+        if (size <= offset) {
+            if (size < offset)
+                offset = 0;
+            return;
+        }
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            offset = size;
+            for (const line of buf.toString('utf-8').split('\n').filter(Boolean)) {
+                try {
+                    console.log(renderAuditRow(JSON.parse(line)));
+                }
+                catch {
+                    // Skip malformed lines.
+                }
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    };
+    await new Promise(() => {
+        setInterval(drain, 500);
+    });
+}
+function humanBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function runStats(opts) {
+    let days = 7;
+    if (opts.since) {
+        try {
+            const d = parseSince(opts.since);
+            days = Math.max(1, Math.ceil((Date.now() - d.getTime()) / 86_400_000));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    }
+    const s = stats({ days });
+    if (opts.json) {
+        console.log(JSON.stringify(s, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`Audit statistics (last ${days} day${days === 1 ? '' : 's'})\n`));
+    console.log(`  Total events:  ${s.totalEvents}`);
+    console.log(`  Log files:     ${s.fileCount} (${humanBytes(s.totalBytes)})`);
+    console.log(`  Log path:      ${chalk.gray(getLogsPath())}`);
+    if (Object.keys(s.byLevel).length) {
+        console.log(chalk.bold('\n  By level:'));
+        for (const [k, v] of Object.entries(s.byLevel).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${levelColor(k).padEnd(20)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byEvent).length) {
+        console.log(chalk.bold('\n  By event (top 15):'));
+        for (const [k, v] of Object.entries(s.byEvent).sort((a, b) => b[1] - a[1]).slice(0, 15)) {
+            console.log(`    ${chalk.cyan(k).padEnd(30)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byModule).length) {
+        console.log(chalk.bold('\n  By module:'));
+        for (const [k, v] of Object.entries(s.byModule).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${k.padEnd(20)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byUser).length) {
+        console.log(chalk.bold('\n  By user:'));
+        for (const [k, v] of Object.entries(s.byUser).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${k.padEnd(30)} ${v}`);
+        }
+    }
+    console.log();
+}
 /** Register the top-level `agents logs` command. */
 export function registerLogsCommand(program) {
-    program
+    const logsCmd = program
         .command('logs [id]')
-        .description('Show a run’s concise summary — a host-dispatch task or a session. --full for the raw transcript, -f to follow a live one.')
+        .description('Show a run log, audit trail, or stats. Subcommands: audit, stats, rotate.')
         .option('--host <name>', 'Scope to runs dispatched to a host')
         .option('-a, --agent <agent>', 'Filter by agent (e.g. claude, codex@0.116.0)')
         .option('--version <version>', 'Filter by agent version')
@@ -142,4 +344,47 @@ export function registerLogsCommand(program) {
         .option('-f, --follow', 'Follow live output')
         .option('-m, --full', 'Show the full raw transcript / stdout instead of the concise summary')
         .action((id, opts) => runLogs(id, opts));
+    logsCmd
+        .command('audit')
+        .description('Read the structured audit/event log (who ran what, from where)')
+        .option('--module <name>', 'Only events from this command group (e.g. teams, secrets)')
+        .option('--command <path>', 'Only this command path — prefix match (e.g. "teams create")')
+        .option('--event <type>', 'Only this typed event (repeatable)', collect, [])
+        .option('--agent <name>', 'Only events tagged with this agent')
+        .option('--caller <kind>', 'Only this caller kind (claude-code, codex, gemini, cursor, terminal, script)')
+        .option('--level <level>', 'Only this level: audit, warn, info, debug')
+        .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
+        .option('--limit <n>', 'Max records to show (default 50)', '50')
+        .option('--json', 'Output raw records as JSON')
+        .option('-f, --follow', "Tail today's log live")
+        .addHelpText('after', `
+Examples:
+  agents logs audit                          Recent activity across everything
+  agents logs audit --module teams           Team lifecycle (create / add / disband)
+  agents logs audit --module secrets         Every secret accessed or revealed
+  agents logs audit --level audit            Only audit-level events
+  agents logs audit --command "teams create" Just team creations
+  agents logs audit --event secrets.get --since 7d --json
+  agents logs audit -f                       Live tail`)
+        .action(async (options) => runAudit(options));
+    logsCmd
+        .command('stats')
+        .description('Show aggregate audit statistics')
+        .option('--since <time>', 'Window size (e.g. 7d, 30d; default 7d)')
+        .option('--json', 'Output stats as JSON')
+        .action(async (opts) => runStats(opts));
+    logsCmd
+        .command('rotate')
+        .description('Force log rotation — remove files older than the retention period')
+        .option('--days <n>', 'Retention period in days (default 7)', '7')
+        .action((opts) => {
+        const days = Math.max(1, parseInt(opts.days ?? '7', 10) || 7);
+        const removed = rotate(days);
+        if (removed > 0) {
+            console.log(`Removed ${removed} log file${removed === 1 ? '' : 's'} older than ${days} day${days === 1 ? '' : 's'}.`);
+        }
+        else {
+            console.log(chalk.gray('No log files to remove.'));
+        }
+    });
 }

package/dist/commands/mcp.js

@@ -3,6 +3,7 @@ import { truncate } from '../lib/format.js';
 import ora from 'ora';
 import { checkbox } from '@inquirer/prompts';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
+import { emit } from '../lib/events.js';
 import { AGENTS, getAllCliStates, resolveAgentName, formatAgentError, registerMcpToTargets, unregisterMcpFromTargets, listInstalledMcpsWithScope, parseMcpConfig, getMcpConfigPathForHome, agentLabel, } from '../lib/agents.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
@@ -293,6 +294,7 @@ Examples:
             };
         }
         writeManifest(localPath, manifest);
+        emit('mcp.add', { module: 'mcp', server: name });
         console.log(chalk.green(`Added MCP server '${name}' to manifest`));
         console.log(chalk.gray('Run: agents mcp register to apply'));
     });
@@ -441,6 +443,8 @@ Examples:
             console.log(chalk.yellow('No MCP servers removed.'));
         }
         else {
+            for (const n of mcpsToRemove)
+                emit('mcp.remove', { module: 'mcp', server: n });
             console.log(chalk.green(`\nRemoved ${removed} MCP server(s).`));
         }
     });
@@ -575,6 +579,7 @@ Examples:
                 targets = resolveConfiguredAgentTargets(config.agents, config.agentVersions, capableAgents('mcp'));
             }
             const results = await registerMcpToTargets(targets, mcpName, commandOrUrl, config.scope || 'user', transport, { headers: config.headers });
+            const applied = results.filter(r => r.success).length;
             for (const result of results) {
                 if (result.success) {
                     console.log(`    ${chalk.green('+')} ${formatTargetLabel(result.agentId, result.version)}`);
@@ -586,6 +591,8 @@ Examples:
                     console.log(`    ${chalk.red('x')} ${formatTargetLabel(result.agentId, result.version)}: ${result.error}`);
                 }
             }
+            if (applied > 0)
+                emit('mcp.register', { module: 'mcp', server: mcpName, applied });
         }
     });
 }

package/dist/commands/secrets.d.ts

@@ -17,6 +17,28 @@ import { type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.j
  * a filesystem path.
  */
 export declare function readImportDotenv(from: string): string;
+/** Where `secrets import` pulls keys from, parsed off the unified `--from`. */
+export type ImportSource = {
+    kind: 'dotenv';
+    path: string;
+} | {
+    kind: '1password';
+    vault?: string;
+} | {
+    kind: 'icloud';
+};
+/**
+ * Parse the unified `--from <source>` value: a .env path (`-` reads stdin),
+ * `1password:<vault>` (bare `1password` prompts for the vault), or `icloud`
+ * (legacy iCloud Keychain bundles). The deprecated `--from-1password --vault`
+ * pair maps onto the 1password source. A file literally named `icloud` or
+ * `1password` can still be imported via an explicit path (`./icloud`).
+ */
+export declare function parseImportSource(opts: {
+    from?: string;
+    from1password?: boolean;
+    vault?: string;
+}): ImportSource;
 /**
  * Build the remote `agents secrets unlock` argv for `unlock --host`. `--all`
  * forwards verbatim; otherwise the explicit bundle names. A `--ttl` is passed

package/dist/commands/secrets.js

@@ -24,6 +24,7 @@ import { parseDuration } from '../lib/hooks/cache.js';
 import { emit } from '../lib/events.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { discoverSyncedBundles, importSyncedBundle, } from '../lib/secrets/icloud-import.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
 import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 import { registerSecretsImportKeyringCommand } from './secrets-import.js';
@@ -135,6 +136,101 @@ async function resolveVault(vaultOpt) {
 export function readImportDotenv(from) {
     return from === '-' ? readStdinSync() : fs.readFileSync(from, 'utf-8');
 }
+/**
+ * Parse the unified `--from <source>` value: a .env path (`-` reads stdin),
+ * `1password:<vault>` (bare `1password` prompts for the vault), or `icloud`
+ * (legacy iCloud Keychain bundles). The deprecated `--from-1password --vault`
+ * pair maps onto the 1password source. A file literally named `icloud` or
+ * `1password` can still be imported via an explicit path (`./icloud`).
+ */
+export function parseImportSource(opts) {
+    if (opts.from && opts.from1password) {
+        throw new Error('--from and --from-1password are mutually exclusive.');
+    }
+    if (opts.from1password)
+        return { kind: '1password', vault: opts.vault };
+    if (!opts.from) {
+        throw new Error("Pass --from <source>: a .env path (- reads stdin), '1password:<vault>', or 'icloud'.");
+    }
+    if (opts.from === 'icloud')
+        return { kind: 'icloud' };
+    if (opts.from === '1password')
+        return { kind: '1password', vault: opts.vault };
+    if (opts.from.startsWith('1password:')) {
+        const vault = opts.from.slice('1password:'.length);
+        return { kind: '1password', vault: vault || opts.vault };
+    }
+    return { kind: 'dotenv', path: opts.from };
+}
+/**
+ * `secrets import --from icloud` — recover bundles stranded in the iCloud
+ * Keychain by the device-local cutover. With a bundle name, imports exactly
+ * that bundle; without one, interactively multi-selects from everything
+ * discovered (all pre-checked — the common case is "bring them all back").
+ */
+async function importFromICloud(bundleName, opts) {
+    if (process.platform !== 'darwin') {
+        throw new Error('--from icloud reads the macOS iCloud Keychain and is only available on macOS.');
+    }
+    const candidates = discoverSyncedBundles();
+    if (candidates.length === 0) {
+        console.log('No legacy iCloud Keychain bundles found.');
+        return;
+    }
+    const describe = (c) => `${c.name} (${c.keys.length} key${c.keys.length === 1 ? '' : 's'}${c.hasMeta ? '' : ', no metadata'})`;
+    let chosen;
+    if (bundleName) {
+        const hit = candidates.find((c) => c.name === bundleName);
+        if (!hit) {
+            throw new Error(`No iCloud Keychain bundle named '${bundleName}'. Found: ${candidates.map((c) => c.name).join(', ')}`);
+        }
+        chosen = [hit];
+    }
+    else if (!isInteractiveTerminal()) {
+        throw new Error(`Found ${candidates.length} iCloud Keychain bundle(s): ${candidates.map((c) => c.name).join(', ')}. ` +
+            'Pass a bundle name to import non-interactively.');
+    }
+    else {
+        const { checkbox } = await import('@inquirer/prompts');
+        chosen = await checkbox({
+            message: 'Which iCloud Keychain bundles to import?',
+            choices: candidates.map((c) => ({ name: describe(c), value: c, checked: true })),
+        });
+        if (chosen.length === 0) {
+            console.log('Nothing selected.');
+            return;
+        }
+    }
+    for (const candidate of chosen) {
+        const result = importSyncedBundle(candidate, opts);
+        const parts = [`imported ${result.added} key(s)`];
+        if (result.skipped)
+            parts.push(`skipped ${result.skipped} (already set, pass --force)`);
+        if (result.missing.length)
+            parts.push(`unreadable (left in iCloud): ${result.missing.join(', ')}`);
+        if (opts.purge)
+            parts.push(`purged ${result.purged} iCloud item(s)`);
+        const line = `${candidate.name}: ${parts.join(', ')}`;
+        console.log(result.missing.length ? chalk.yellow(line) : chalk.green(line));
+    }
+}
+/**
+ * Printed under a "bundle not found" failure: if the name matches a bundle
+ * stranded in the iCloud Keychain (pre-device-local-cutover era), point at the
+ * recovery command instead of leaving a dead end.
+ */
+function maybePrintSyncedHint(name) {
+    if (process.platform !== 'darwin')
+        return;
+    try {
+        if (discoverSyncedBundles().some((c) => c.name === name)) {
+            console.error(chalk.yellow(`A legacy iCloud Keychain copy of '${name}' exists. Recover it with: agents secrets import ${name} --from icloud`));
+        }
+    }
+    catch {
+        // Hint only — never mask the original error.
+    }
+}
 /**
  * Build the remote `agents secrets unlock` argv for `unlock --host`. `--all`
  * forwards verbatim; otherwise the explicit bundle names. A `--ttl` is passed
@@ -525,7 +621,8 @@ export function registerSecretsCommands(program) {
         agents secrets status                          show held bundles + when they lock
         agents secrets rotate <bundle> <key>           rotate value, preserve metadata
         agents secrets import <bundle> --from .env     bulk import from .env
-        agents secrets import <bundle> --from-1password --vault <name>
+        agents secrets import <bundle> --from 1password:<vault>
+        agents secrets import --from icloud            recover legacy iCloud Keychain bundles
         agents secrets generate [length]               generate a random password / PIN / hex
         agents secrets migrate-acl                     upgrade legacy items to the biometry ACL
     `,
@@ -610,7 +707,15 @@ export function registerSecretsCommands(program) {
                 return;
             }
             const resolvedName = name ?? (await pickBundleName('view'));
-            const bundle = readBundle(resolvedName);
+            let bundle;
+            try {
+                bundle = readBundle(resolvedName);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                maybePrintSyncedHint(resolvedName);
+                process.exit(1);
+            }
             const entries = describeBundle(bundle);
             console.log(chalk.bold(bundle.name));
             if (bundle.description)
@@ -672,7 +777,7 @@ export function registerSecretsCommands(program) {
                     emit('secrets.get', {
                         module: 'secrets',
                         bundle: bundle.name,
-                        caller: 'view --reveal',
+                        operation: 'view --reveal',
                         source: 'reveal',
                         status: 'success',
                         keyCount: exposedCount,
@@ -713,24 +818,48 @@ export function registerSecretsCommands(program) {
         }
     });
     cmd
-        .command('get <item>')
-        .description('Print a raw keychain item by name (for shell hooks/automation). Cross-platform; no bundle required.')
-        .action((item) => {
+        .command('get <item> [key]')
+        .description('Print one secret value for shell hooks/automation. One arg = a raw keychain item by name; two args = one KEY out of a bundle (`get <bundle> <KEY>`). Cross-platform.')
+        .action((item, key) => {
+        if (key === undefined) {
+            // Raw keychain item path — unchanged.
+            try {
+                // Routes through the platform keychain layer: macOS reads bare items
+                // via /usr/bin/security (no Touch ID), Linux via secret-tool with the
+                // encrypted-file fallback. The value goes to stdout (newline-terminated
+                // so `$(agents secrets get NAME)` captures it cleanly); diagnostics go
+                // to stderr so they never pollute the captured value.
+                const value = getKeychainToken(item);
+                // Raw item reads bypass readAndResolveBundleEnv, so audit here too.
+                // `item` is the keychain service name, never the value.
+                emit('secrets.get', { module: 'secrets', item, source: 'raw-item', status: 'success' });
+                process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
+            }
+            catch {
+                // Missing item is a normal, quiet outcome for a hook probe: exit 1,
+                // print nothing to stdout. Callers test the exit code / empty capture.
+                process.exit(1);
+            }
+            return;
+        }
+        // Bundle-key path: `get <bundle> <KEY>` prints exactly one resolved value.
+        // Ungated like the raw path (it IS the automation primitive); the
+        // `secrets.get` audit event is emitted inside readAndResolveBundleEnv.
         try {
-            // Routes through the platform keychain layer: macOS reads bare items
-            // via /usr/bin/security (no Touch ID), Linux via secret-tool with the
-            // encrypted-file fallback. The value goes to stdout (newline-terminated
-            // so `$(agents secrets get NAME)` captures it cleanly); diagnostics go
-            // to stderr so they never pollute the captured value.
-            const value = getKeychainToken(item);
-            // Raw item reads bypass readAndResolveBundleEnv, so audit here too.
-            // `item` is the keychain service name, never the value.
-            emit('secrets.get', { module: 'secrets', item, source: 'raw-item', status: 'success' });
+            if (!bundleExists(item)) {
+                console.error(chalk.red(`Secrets bundle '${item}' not found.`));
+                process.exit(1);
+            }
+            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key] });
+            if (!(key in env)) {
+                console.error(chalk.red(`Key '${key}' not in bundle '${item}'.`));
+                process.exit(1);
+            }
+            const value = env[key];
             process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
         }
-        catch {
-            // Missing item is a normal, quiet outcome for a hook probe: exit 1,
-            // print nothing to stdout. Callers test the exit code / empty capture.
+        catch (err) {
+            console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
@@ -1160,23 +1289,34 @@ Examples:
     });
     cmd
         .command('import [bundle]')
-        .description('Import keys from a .env file or a 1Password vault into a bundle. The bundle is created if it does not exist. Values are stored in the bundle\'s backend (keychain by default).')
-        .option('--from <path>', 'Path to a .env file (use - to read the .env from stdin)')
-        .option('--from-1password', 'Import secrets from a 1Password vault (requires the op CLI)')
-        .option('--vault <name>', '1Password vault name (used with --from-1password)')
+        .description('Import keys into a bundle from a .env file, a 1Password vault, or legacy iCloud Keychain bundles. The bundle is created if it does not exist. Values are stored in the bundle\'s backend (keychain by default).')
+        .option('--from <source>', "Source: a .env path (- reads stdin), '1password:<vault>', or 'icloud' (legacy iCloud Keychain bundles)")
+        .addOption(new Option('--from-1password', 'deprecated alias for --from 1password:<vault>').hideHelp())
+        .addOption(new Option('--vault <name>', 'deprecated: name the vault in --from 1password:<vault>').hideHelp())
         .option('--all-plaintext', 'Store every imported value as a literal in the bundle metadata (skip keychain item creation)')
         .option('--backend <backend>', 'When creating the bundle: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .option('--force', 'Overwrite an existing key in the bundle')
+        .option('--purge', 'With --from icloud: delete the iCloud copies after a successful import (iCloud propagates the deletion to your other devices)')
         .action(async (bundleName, opts) => {
         try {
-            if (!opts.from && !opts.from1password) {
-                throw new Error('Pass --from <path> to import a .env file, or --from-1password to import from a 1Password vault.');
+            const source = parseImportSource(opts);
+            if (opts.purge && source.kind !== 'icloud') {
+                throw new Error('--purge only applies to --from icloud.');
             }
-            if (opts.from && opts.from1password) {
-                throw new Error('--from and --from-1password are mutually exclusive.');
+            if (opts.from1password) {
+                console.log(chalk.yellow('--from-1password is deprecated; use --from 1password:<vault>.'));
             }
-            const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
             const requestedBackend = parseBackendOpt(opts.backend);
+            if (source.kind === 'icloud') {
+                await importFromICloud(bundleName, {
+                    force: opts.force,
+                    allPlaintext: opts.allPlaintext,
+                    backend: requestedBackend === 'file' ? 'file' : undefined,
+                    purge: opts.purge,
+                });
+                return;
+            }
+            const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
             // Read the bundle if it exists (inheriting its backend); otherwise
             // create it with the requested backend so a single `import --backend
             // file` works (this is what `export --host ... --remote-backend file`
@@ -1199,9 +1339,9 @@ Examples:
             const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
             let added = 0;
             let skipped = 0;
-            if (opts.from1password) {
+            if (source.kind === '1password') {
                 assertOpAvailable();
-                const vault = await resolveVault(opts.vault);
+                const vault = await resolveVault(source.vault);
                 const items = listItems(vault);
                 const { secrets, skipped: opSkipped } = extractSecrets(items, vault);
                 for (const { envKey, value } of secrets) {
@@ -1226,7 +1366,7 @@ Examples:
                 console.log(chalk.green(`Imported ${added} key(s) from 1Password vault '${vault}'${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
             }
             else {
-                const raw = readImportDotenv(opts.from);
+                const raw = readImportDotenv(source.path);
                 const pairs = parseDotenv(raw);
                 for (const [key, value] of Object.entries(pairs)) {
                     if (!opts.force && key in bundle.vars) {
@@ -1720,20 +1860,11 @@ Examples:
                 console.error(chalk.yellow('Aborted.'));
                 return;
             }
-            const wasDaily = bundlePolicy(bundle) === 'daily';
             bundle.policy = next;
+            // writeBundle evicts any broker-held copy, so tightening daily ->
+            // always/never takes effect NOW: the next read re-prompts (`always`)
+            // or reads its no-ACL item directly (`never`).
             writeBundle(bundle);
-            // Tightening daily -> always/never must take effect NOW, not up to the
-            // ~7d hold later. If the broker is already serving this bundle silently
-            // (auto-cached under the old `daily` policy), evict it so the next read
-            // re-prompts (`always`) or reads its no-ACL item directly (`never`).
-            // macOS-only + best-effort; agentLock no-ops off darwin / with no broker.
-            if (wasDaily && next !== 'daily') {
-                try {
-                    await agentLock(bundle.name);
-                }
-                catch { /* broker down — nothing held */ }
-            }
             console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
             if (next === 'daily') {
                 console.log(chalk.gray('Held by the secrets-agent for ~7 days after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));