@phnx-labs/agents-cli 1.20.50 → 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

@@ -1,7 +1,9 @@
 import chalk from 'chalk';
+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';
@@ -292,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'));
     });
@@ -440,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).`));
         }
     });
@@ -574,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)}`);
@@ -585,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 });
         }
     });
 }
@@ -764,7 +772,7 @@ function buildMcpRows(opts) {
         const displayCommand = declaredCommand || firstCommand;
         rows.push({
             name,
-            description: displayCommand ? truncateString(displayCommand, 60) : '',
+            description: displayCommand ? truncate(displayCommand, 60) : '',
             extra: source,
             targets,
             buildDetail: () => formatMcpDetail(name, source, centralConfig, manifestConfig, displayCommand, targets),
@@ -811,8 +819,3 @@ function formatMcpDetail(name, source, centralConfig, manifestConfig, command, t
     lines.push(buildTargetsSection(targets));
     return lines.join('\n');
 }
-function truncateString(s, max) {
-    if (s.length <= max)
-        return s;
-    return s.slice(0, max - 1) + '…';
-}

package/dist/commands/message.js

@@ -1,13 +1,10 @@
 import chalk from 'chalk';
+import { die } from '../lib/format.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { resolveMessageTarget } from '../lib/mailbox-target.js';
-function die(msg, code = 1) {
-    console.error(chalk.red(msg));
-    process.exit(code);
-}
 export function registerMessageCommand(program) {
     program
         .command('message <target> <text>')

package/dist/commands/profiles.js

@@ -7,7 +7,7 @@
  * through a standard agent CLI with no local proxy.
  */
 import chalk from 'chalk';
-import * as fs from 'fs';
+import { readStdinSync } from '../lib/format.js';
 import { spawn } from 'child_process';
 import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, validateProfileName, getPresetForProfile, } from '../lib/profiles.js';
 import { getPreset, listPresets, expandPreset } from '../lib/profiles-presets.js';
@@ -41,23 +41,6 @@ async function promptForSecret(message) {
     return await password({ message, mask: true });
 }
 /** Read all available data from stdin synchronously, trimmed. */
-function readStdinSync() {
-    const chunks = [];
-    const buf = Buffer.alloc(65536);
-    while (true) {
-        let bytesRead;
-        try {
-            bytesRead = fs.readSync(0, buf, 0, buf.length, null);
-        }
-        catch {
-            break;
-        }
-        if (bytesRead === 0)
-            break;
-        chunks.push(Buffer.from(buf.subarray(0, bytesRead)));
-    }
-    return Buffer.concat(chunks).toString('utf-8').trim();
-}
 /** Ensure a provider API key exists in keychain, prompting or reading stdin if missing. */
 async function ensureProviderToken(provider, signupUrl, fromStdin) {
     const item = keychainItemName(provider);

package/dist/commands/repo.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { visibleWidth, padVisible } from '../lib/format.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -26,7 +27,7 @@ function resolveRepoPath(target) {
     return path.join(HOME, `.agents-${trimmed}`);
 }
 import { applyExtraAliasToVersions, ensureAgentsDir, getExtraRepoDir, getSystemAgentsDir, getUserAgentsDir, readMeta, resolveExtraRepoDir, updateMeta, } from '../lib/state.js';
-import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin } from '../lib/git.js';
+import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin, adoptRepo } from '../lib/git.js';
 import { DEFAULT_SYSTEM_REPO } from '../lib/types.js';
 import { ALL_AGENT_IDS, isAgentName, resolveAgentName } from '../lib/agents.js';
 import { refresh } from '../lib/refresh.js';
@@ -218,14 +219,6 @@ async function diffResourceEntries(git, range) {
     }
     return out;
 }
-/** Visible character width of a string with embedded ANSI color codes. */
-function visibleWidth(s) {
-    return s.replace(/\[[0-9;]*m/g, '').length;
-}
-/** Pad string with trailing spaces to a target visible column width. */
-function padVisible(s, width) {
-    return s + ' '.repeat(Math.max(0, width - visibleWidth(s)));
-}
 /**
  * Read one repo's status into structured data: branch, resource-level sync (what
  * a pull/push would move), resource-level local edits, and remote URL + commit.
@@ -752,9 +745,9 @@ export function registerRepoCommands(program) {
         await toggle(alias, false);
     });
     repoCmd
-        .command('pull [alias]')
-        .description('Pull updates. Aliases: "system" (~/.agents/.system/), "user" (~/.agents/), or any registered extra. No arg pulls all.')
-        .action(async (alias) => {
+        .command('pull [alias] [url]')
+        .description('Pull updates. Aliases: "system" (~/.agents/.system/), "user" (~/.agents/), or any registered extra. No arg pulls all. Pass a git URL to git-back a not-yet-cloned user repo: "agents repo pull user <url>".')
+        .action(async (alias, url) => {
         const targets = collectRepoTargets(alias);
         if (!targets) {
             process.exitCode = 1;
@@ -766,8 +759,34 @@ export function registerRepoCommands(program) {
         }
         for (const t of targets) {
             if (!fs.existsSync(t.dir) || !isGitRepo(t.dir)) {
-                console.log(chalk.yellow(`  ${t.alias}: not a git repo, skipping`));
-                continue;
+                // A plain (never-cloned) user repo — setup makes ~/.agents a bare dir and
+                // never git-clones it (state.ts ensureAgentsDir), so a fresh/Windows box
+                // silently falls out of config sync. If a URL was passed, git-back it in
+                // place (keeping local files, backing up any that differ); else guide the
+                // user. Only the USER repo gets this — system is cloned by setup, extras
+                // by `repo add`.
+                if (t.alias === 'user' && url) {
+                    const spinner = ora(`Git-backing ${t.dir} from ${url}...`).start();
+                    const res = await adoptRepo(url, t.dir);
+                    if (!res.success) {
+                        spinner.fail(`user: could not git-back — ${res.error}`);
+                        process.exitCode = 1;
+                        continue;
+                    }
+                    spinner.succeed(`user: git-backed -> ${res.commit}`);
+                    if (res.backedUp.length > 0) {
+                        console.log(chalk.yellow(`  backed up ${res.backedUp.length} locally-modified file(s) to ${res.backupDir}`));
+                        console.log(chalk.gray(`  (${res.backedUp.slice(0, 5).join(', ')}${res.backedUp.length > 5 ? ', …' : ''})`));
+                    }
+                    // Now a git repo — fall through to the normal pull below.
+                }
+                else {
+                    console.log(chalk.yellow(`  ${t.alias}: not a git repo, skipping`));
+                    if (t.alias === 'user') {
+                        console.log(chalk.gray('  git-back it from your config remote: agents repo pull user <git-url>'));
+                    }
+                    continue;
+                }
             }
             if (t.alias === 'system') {
                 // Skip system repo unless explicitly requested

package/dist/commands/resource-view.d.ts

@@ -58,3 +58,4 @@ export declare function resourceLayout(cols: number, o: {
 }): ResourceLayout;
 /** Build the sync targets section showing version pills grouped by agent. */
 export declare function buildTargetsSection(targets: SyncTarget[]): string;
+/** Pad a string to a fixed width, accounting for ANSI escape codes in length calculation. */

package/dist/commands/resource-view.js

@@ -7,6 +7,7 @@
  * filtering, and paging.
  */
 import chalk from 'chalk';
+import { truncate, padVisible } from '../lib/format.js';
 import { agentLabel } from '../lib/agents.js';
 import { itemPicker } from '../lib/picker.js';
 import { isInteractiveTerminal, isPromptCancelled, printWithPager } from './utils.js';
@@ -65,15 +66,15 @@ function filterRows(rows, query) {
 }
 /** Row label rendered inside the picker list. */
 function formatPickerRow(row, opts) {
-    const name = chalk.cyan(padRight(row.name, 22));
+    const name = chalk.cyan(padVisible(row.name, 22));
     const extra = opts.extraLabel
-        ? chalk.gray(padRight(row.extra ?? '-', 10))
+        ? chalk.gray(padVisible(row.extra ?? '-', 10))
         : '';
     const extra2 = opts.extra2Label
-        ? chalk.gray(padRight(row.extra2 ?? '-', 16))
+        ? chalk.gray(padVisible(row.extra2 ?? '-', 16))
         : '';
     const descRaw = row.description ? truncate(row.description, 40) : '';
-    const desc = padRight(chalk.gray(descRaw), 42);
+    const desc = padVisible(chalk.gray(descRaw), 42);
     const sync = formatSyncSummary(row.targets, opts);
     return `${name} ${extra}${extra2}${desc} ${sync}`;
 }
@@ -252,16 +253,3 @@ function formatVersionPill(t) {
     }
 }
 /** Pad a string to a fixed width, accounting for ANSI escape codes in length calculation. */
-function padRight(s, width) {
-    // Strip ANSI for length calc
-    const raw = s.replace(/\x1b\[[0-9;]*m/g, '');
-    if (raw.length >= width)
-        return s;
-    return s + ' '.repeat(width - raw.length);
-}
-/** Truncate a string to a maximum length, appending an ellipsis if needed. */
-function truncate(s, max) {
-    if (s.length <= max)
-        return s;
-    return s.slice(0, max - 1) + '…';
-}

package/dist/commands/secrets.d.ts

@@ -9,6 +9,7 @@ import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
 import { type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
+/** Read all available data from stdin synchronously, trimmed. */
 /**
  * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
  * from stdin (the SSH push path: `export --host` pipes the resolved dotenv over
@@ -16,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