@lifestreamdynamics/vault-cli 1.3.6 → 1.3.8

package/dist/commands/admin.js

@@ -4,7 +4,9 @@ import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 import { formatBytes, formatUptime } from '../utils/format.js';
 export function registerAdminCommands(program) {
-    const admin = program.command('admin').description('System administration (requires admin role)');
+    const admin = program.command('admin')
+        .description('System administration (requires admin role)')
+        .addHelpText('after', '\nNOTE: Admin commands require JWT authentication with admin role.\nRun "lsvault auth login" to authenticate first.');
     // ── System Stats ────────────────────────────────────────────────────
     const stats = admin.command('stats').description('View system-wide statistics and metrics');
     const statsAction = async (_opts) => {

package/dist/commands/analytics.js

@@ -67,7 +67,7 @@ export function registerAnalyticsCommands(program) {
         .addHelpText('after', `
 NOTE
   The publishedDocId is a UUID, NOT a document path. Get it from:
-    lsvault publish list <vaultId>`))
+    lsvault analytics published`))
         .action(async (vaultId, publishedDocId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/booking.js

@@ -405,7 +405,8 @@ export function registerBookingCommands(program) {
     addGlobalFlags(booking.command('reschedule')
         .description('Reschedule a booking by guest reschedule token')
         .argument('<token>', 'Reschedule token (from guest email link)')
-        .argument('<newStartAt>', 'New start time in ISO 8601 format (e.g. 2026-03-15T10:00:00Z)'))
+        .argument('<newStartAt>', 'New start time in ISO 8601 format (e.g. 2026-03-15T10:00:00Z)')
+        .addHelpText('after', '\n  The <token> is the guest reschedule token from the booking confirmation email,\n  not the booking ID.'))
         .action(async (token, newStartAt, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/completion.js

@@ -1,45 +1,217 @@
 const SAFE_COMMAND_NAME = /^[a-z][a-z0-9-]*$/;
-function collectCommandNames(cmd, prefix = '') {
-    const names = [];
+/**
+ * Recursively walk the Commander tree and produce a structured CommandNode tree.
+ * Only names matching SAFE_COMMAND_NAME are included (shell injection guard).
+ */
+function collectCommandTree(cmd) {
+    const nodes = [];
     for (const sub of cmd.commands) {
         const name = sub.name();
-        // Skip any name that doesn't match the safe pattern to prevent shell injection
         if (!SAFE_COMMAND_NAME.test(name))
             continue;
-        const full = prefix ? `${prefix} ${name}` : name;
-        names.push(name);
-        names.push(...collectCommandNames(sub, full));
+        // Collect long-form option flags from this command's declared options.
+        const options = sub.options
+            .map((o) => o.long)
+            .filter((flag) => typeof flag === 'string');
+        nodes.push({
+            name,
+            description: sub.description() ?? '',
+            subcommands: collectCommandTree(sub),
+            options,
+        });
     }
-    return names;
+    return nodes;
+}
+// ---------------------------------------------------------------------------
+// Bash
+// ---------------------------------------------------------------------------
+/**
+ * Emit the bash case arm for a top-level command.
+ * Handles COMP_CWORD == 2 (show subcommand names) and COMP_CWORD >= 3 (show
+ * a flat list of options for the matched sub/sub-subcommand).
+ */
+function bashCaseArm(node, indent) {
+    const lines = [];
+    lines.push(`${indent}${node.name})`);
+    if (node.subcommands.length > 0) {
+        const subNames = node.subcommands.map(s => s.name).join(' ');
+        lines.push(`${indent}  if [[ $COMP_CWORD -eq 2 ]]; then`);
+        lines.push(`${indent}    COMPREPLY=($(compgen -W "${subNames}" -- "$cur"))`);
+        lines.push(`${indent}  else`);
+        // Third-level: match sub-subcommand name in COMP_WORDS[2] and show its options
+        lines.push(`${indent}    case "$cmd2" in`);
+        for (const sub of node.subcommands) {
+            const allOpts = sub.options.join(' ');
+            // Also include sub-subcommand names if this node has nested commands
+            const deepNames = sub.subcommands.map(s => s.name).join(' ');
+            const completions = [deepNames, allOpts].filter(Boolean).join(' ');
+            lines.push(`${indent}      ${sub.name})`);
+            if (completions) {
+                lines.push(`${indent}        COMPREPLY=($(compgen -W "${completions}" -- "$cur"))`);
+            }
+            lines.push(`${indent}        ;;`);
+        }
+        lines.push(`${indent}    esac`);
+        lines.push(`${indent}  fi`);
+    }
+    else if (node.options.length > 0) {
+        // Leaf command with flags only
+        const opts = node.options.join(' ');
+        lines.push(`${indent}  COMPREPLY=($(compgen -W "${opts}" -- "$cur"))`);
+    }
+    lines.push(`${indent}  ;;`);
+    return lines.join('\n');
 }
 export function generateBashCompletion(program) {
-    const commands = collectCommandNames(program);
+    const tree = collectCommandTree(program);
+    const topLevelNames = tree.map(n => n.name).join(' ');
+    const caseArms = tree.map(node => bashCaseArm(node, '    ')).join('\n');
     return `# Bash completion for lsvault
 # Add to ~/.bashrc: eval "$(lsvault completion bash)"
 _lsvault_completions() {
   local cur="\${COMP_WORDS[COMP_CWORD]}"
-  local commands="${commands.join(' ')}"
-  COMPREPLY=($(compgen -W "\${commands}" -- "\${cur}"))
+  local cmd1="\${COMP_WORDS[1]:-}"
+  local cmd2="\${COMP_WORDS[2]:-}"
+
+  # Top-level completions
+  if [[ $COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "${topLevelNames}" -- "$cur"))
+    return
+  fi
+
+  # Second-level and deeper
+  case "$cmd1" in
+${caseArms}
+  esac
 }
 complete -F _lsvault_completions lsvault
 `;
 }
+// ---------------------------------------------------------------------------
+// Zsh
+// ---------------------------------------------------------------------------
+function zshDescribeArray(nodes, varName, indent) {
+    const lines = [];
+    lines.push(`${indent}local -a ${varName}`);
+    lines.push(`${indent}${varName}=(`);
+    for (const n of nodes) {
+        // Escape single quotes in description
+        const desc = n.description.replace(/'/g, "'\\''");
+        lines.push(`${indent}  '${n.name}:${desc}'`);
+    }
+    lines.push(`${indent})`);
+    return lines.join('\n');
+}
+function zshCaseArm(node, indent) {
+    const lines = [];
+    lines.push(`${indent}${node.name})`);
+    if (node.subcommands.length > 0) {
+        lines.push(zshDescribeArray(node.subcommands, 'subcmds', indent + '  '));
+        lines.push(`${indent}  if (( CURRENT == 3 )); then`);
+        lines.push(`${indent}    _describe 'subcommand' subcmds`);
+        lines.push(`${indent}  else`);
+        // Third-level: show options for matched subcommand
+        lines.push(`${indent}    case "$words[3]" in`);
+        for (const sub of node.subcommands) {
+            if (sub.options.length > 0 || sub.subcommands.length > 0) {
+                lines.push(`${indent}      ${sub.name})`);
+                if (sub.subcommands.length > 0) {
+                    lines.push(zshDescribeArray(sub.subcommands, 'deepcmds', indent + '        '));
+                    lines.push(`${indent}        if (( CURRENT == 4 )); then`);
+                    lines.push(`${indent}          _describe 'subcommand' deepcmds`);
+                    if (sub.options.length > 0) {
+                        const optSpecs = sub.options.map(o => `'${o}'`).join(' ');
+                        lines.push(`${indent}        else`);
+                        lines.push(`${indent}          _arguments ${optSpecs}`);
+                    }
+                    lines.push(`${indent}        fi`);
+                }
+                else if (sub.options.length > 0) {
+                    const optSpecs = sub.options.map(o => `'${o}'`).join(' ');
+                    lines.push(`${indent}        _arguments ${optSpecs}`);
+                }
+                lines.push(`${indent}        ;;`);
+            }
+        }
+        lines.push(`${indent}    esac`);
+        lines.push(`${indent}  fi`);
+    }
+    else if (node.options.length > 0) {
+        const optSpecs = node.options.map(o => `'${o}'`).join(' ');
+        lines.push(`${indent}  _arguments ${optSpecs}`);
+    }
+    lines.push(`${indent}  ;;`);
+    return lines.join('\n');
+}
 export function generateZshCompletion(program) {
-    const commands = collectCommandNames(program);
+    const tree = collectCommandTree(program);
+    const topLevelArray = zshDescribeArray(tree, 'toplevel', '  ');
+    const caseArms = tree.map(node => zshCaseArm(node, '    ')).join('\n');
     return `# Zsh completion for lsvault
 # Add to ~/.zshrc: eval "$(lsvault completion zsh)"
 _lsvault() {
-  local -a commands
-  commands=(${commands.map(c => `'${c}'`).join(' ')})
-  _describe 'lsvault commands' commands
+${topLevelArray}
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' toplevel
+    return
+  fi
+
+  case "$words[2]" in
+${caseArms}
+  esac
 }
 compdef _lsvault lsvault
 `;
 }
+// ---------------------------------------------------------------------------
+// Fish
+// ---------------------------------------------------------------------------
+/**
+ * Escape a string for use inside a fish completion -d '...' description.
+ * Fish uses single quotes and doesn't support backslash escapes within them,
+ * so we just strip single quotes entirely.
+ */
+function fishDesc(s) {
+    return s.replace(/'/g, '');
+}
 export function generateFishCompletion(program) {
-    const commands = collectCommandNames(program);
-    return commands.map(c => `complete -c lsvault -n '__fish_use_subcommand' -a '${c}' -d '${c} command'`).join('\n') + '\n';
+    const tree = collectCommandTree(program);
+    const lines = [];
+    // Helper: the names of all top-level commands (used in __fish_seen_subcommand_from guards)
+    const topLevelNames = tree.map(n => n.name).join(' ');
+    for (const node of tree) {
+        // Top-level command — only show when no subcommand has been entered yet
+        lines.push(`complete -c lsvault -n '__fish_use_subcommand' -a '${node.name}' -d '${fishDesc(node.description)}'`);
+        if (node.subcommands.length > 0) {
+            // Subcommand names — show when this top-level command is active and no sub-subcommand yet
+            for (const sub of node.subcommands) {
+                lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and not __fish_seen_subcommand_from ${sub.subcommands.map(s => s.name).concat(node.subcommands.map(s => s.name)).join(' ')}' -a '${sub.name}' -d '${fishDesc(sub.description)}'`);
+                // Options for this subcommand — show when top-level AND subcommand are both seen
+                for (const opt of sub.options) {
+                    lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and __fish_seen_subcommand_from ${sub.name}' -a '${opt}'`);
+                }
+                // Third-level sub-subcommands
+                for (const deep of sub.subcommands) {
+                    lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and __fish_seen_subcommand_from ${sub.name}' -a '${deep.name}' -d '${fishDesc(deep.description)}'`);
+                    for (const opt of deep.options) {
+                        lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and __fish_seen_subcommand_from ${deep.name}' -a '${opt}'`);
+                    }
+                }
+            }
+        }
+        else {
+            // Leaf top-level command — offer its own options when active
+            for (const opt of node.options) {
+                lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${topLevelNames}' -f -a '${opt}'`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
 }
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
 export function registerCompletionCommands(program) {
     const completion = program.command('completion').description('Generate shell completion scripts');
     completion.command('bash')

package/dist/commands/config.js

@@ -46,6 +46,7 @@ EXAMPLES
         }
         else {
             process.stdout.write(chalk.yellow(`Key "${key}" not set in profile "${profile}"`) + '\n');
+            process.exitCode = 1;
         }
     });
     config

package/dist/commands/custom-domains.js

@@ -106,8 +106,9 @@ export function registerCustomDomainCommands(program) {
         }
     });
     addGlobalFlags(domains.command('verify')
-        .description('Verify a custom domain via DNS')
-        .argument('<domainId>', 'Domain ID'))
+        .description('Trigger DNS verification check for a custom domain')
+        .argument('<domainId>', 'Domain ID')
+        .addHelpText('after', '\n  Submits a verification request to the server, which checks your DNS TXT record.\n  Use "check" to read the current verification status without triggering a new check.'))
         .action(async (domainId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
@@ -122,8 +123,9 @@ export function registerCustomDomainCommands(program) {
         }
     });
     addGlobalFlags(domains.command('check')
-        .description('Check DNS configuration for a custom domain')
-        .argument('<domainId>', 'Domain ID'))
+        .description('Show current DNS verification status for a custom domain')
+        .argument('<domainId>', 'Domain ID')
+        .addHelpText('after', '\n  Returns the current verification status without triggering a new check.\n  Use "verify" to submit a fresh DNS verification request to the server.'))
         .action(async (domainId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/docs.js

@@ -165,9 +165,11 @@ EXAMPLES
             else {
                 doc = await client.documents.put(vaultId, docPath, content);
             }
-            out.success(`Document saved: ${chalk.cyan(doc.path)} (${doc.sizeBytes ?? 0} bytes)`, {
-                path: doc.path,
-                sizeBytes: doc.sizeBytes ?? 0,
+            const docPath2 = doc.path ?? docPath;
+            const size = doc.sizeBytes ?? Buffer.byteLength(content, 'utf8');
+            out.success(`Document saved: ${chalk.cyan(docPath2)} (${size} bytes)`, {
+                path: docPath2,
+                sizeBytes: size,
                 encrypted: doc.encrypted ?? false,
             });
         }

package/dist/commands/links.js

@@ -22,16 +22,16 @@ export function registerLinkCommands(program) {
             out.list(linkList.map(link => ({
                 targetPath: link.targetPath,
                 linkText: link.linkText,
-                resolved: link.isResolved ? 'Yes' : 'No',
+                isResolved: link.isResolved,
             })), {
                 emptyMessage: 'No forward links found.',
                 columns: [
                     { key: 'targetPath', header: 'Target' },
                     { key: 'linkText', header: 'Link Text' },
-                    { key: 'resolved', header: 'Resolved' },
+                    { key: 'isResolved', header: 'Resolved' },
                 ],
                 textFn: (link) => {
-                    const resolved = link.resolved === 'Yes' ? chalk.green('✓') : chalk.red('✗');
+                    const resolved = link.isResolved ? chalk.green('✓') : chalk.red('✗');
                     return `  ${resolved} [[${String(link.linkText)}]] → ${String(link.targetPath)}`;
                 },
             });
@@ -55,18 +55,23 @@ export function registerLinkCommands(program) {
             const backlinks = await client.documents.getBacklinks(vaultId, docPath);
             out.stopSpinner();
             out.list(backlinks.map(bl => ({
-                source: bl.sourceDocument.title || bl.sourceDocument.path,
+                sourcePath: bl.sourceDocument.path,
+                sourceTitle: bl.sourceDocument.title || null,
                 linkText: bl.linkText,
                 context: bl.contextSnippet || '',
             })), {
                 emptyMessage: 'No backlinks found.',
                 columns: [
-                    { key: 'source', header: 'Source' },
+                    { key: 'sourcePath', header: 'Source Path' },
+                    { key: 'sourceTitle', header: 'Source Title' },
                     { key: 'linkText', header: 'Link Text' },
                     { key: 'context', header: 'Context' },
                 ],
                 textFn: (bl) => {
-                    const lines = [chalk.cyan(`  ${String(bl.source)}`)];
+                    const displayName = bl.sourceTitle ? String(bl.sourceTitle) : String(bl.sourcePath);
+                    const lines = [chalk.cyan(`  ${displayName}`)];
+                    if (bl.sourceTitle)
+                        lines.push(`  Path: ${String(bl.sourcePath)}`);
                     lines.push(`  Link: [[${String(bl.linkText)}]]`);
                     if (bl.context)
                         lines.push(`  Context: ...${String(bl.context)}...`);

package/dist/commands/mfa.js

@@ -1,158 +1,208 @@
 import chalk from 'chalk';
-import ora from 'ora';
 import { getClientAsync } from '../client.js';
+import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
+import { createOutput, handleError } from '../utils/output.js';
 import { promptPassword, promptMfaCode } from '../utils/prompt.js';
 export function registerMfaCommands(program) {
     const mfa = program.command('mfa')
         .description('Multi-factor authentication management (requires JWT auth — use "lsvault auth login" first)')
         .addHelpText('after', '\nNOTE: MFA management requires JWT authentication. API key auth is not sufficient.\nRun "lsvault auth login" to authenticate with email/password first.');
-    mfa.command('status')
-        .description('Show MFA status and configured methods')
-        .action(async () => {
-        const spinner = ora('Fetching MFA status...').start();
+    addGlobalFlags(mfa.command('status')
+        .description('Show MFA status and configured methods'))
+        .action(async (_opts) => {
+        const flags = resolveFlags(_opts);
+        const out = createOutput(flags);
+        out.startSpinner('Fetching MFA status...');
         try {
             const client = await getClientAsync();
             const status = await client.mfa.getStatus();
-            spinner.stop();
-            console.log(chalk.bold('MFA Status'));
-            console.log(`  Enabled:              ${status.mfaEnabled ? chalk.green('Yes') : chalk.dim('No')}`);
-            console.log(`  TOTP Configured:      ${status.totpConfigured ? chalk.green('Yes') : chalk.dim('No')}`);
-            console.log(`  Passkeys Registered:  ${status.passkeyCount > 0 ? chalk.cyan(status.passkeyCount) : chalk.dim('0')}`);
-            console.log(`  Backup Codes Left:    ${status.backupCodesRemaining > 0 ? chalk.cyan(status.backupCodesRemaining) : chalk.yellow('0')}`);
-            if (status.passkeys.length > 0) {
-                console.log('');
-                console.log(chalk.bold('Registered Passkeys:'));
-                for (const passkey of status.passkeys) {
-                    const lastUsed = passkey.lastUsedAt
-                        ? new Date(passkey.lastUsedAt).toLocaleDateString()
-                        : chalk.dim('never');
-                    console.log(`  - ${chalk.cyan(passkey.name)} (last used: ${lastUsed})`);
+            out.stopSpinner();
+            if (flags.output === 'json') {
+                out.record({
+                    mfaEnabled: status.mfaEnabled,
+                    totpConfigured: status.totpConfigured,
+                    passkeyCount: status.passkeyCount,
+                    backupCodesRemaining: status.backupCodesRemaining,
+                    passkeys: status.passkeys,
+                });
+            }
+            else {
+                out.raw(chalk.bold('MFA Status') + '\n');
+                out.raw(`  Enabled:              ${status.mfaEnabled ? chalk.green('Yes') : chalk.dim('No')}\n`);
+                out.raw(`  TOTP Configured:      ${status.totpConfigured ? chalk.green('Yes') : chalk.dim('No')}\n`);
+                out.raw(`  Passkeys Registered:  ${status.passkeyCount > 0 ? chalk.cyan(status.passkeyCount) : chalk.dim('0')}\n`);
+                out.raw(`  Backup Codes Left:    ${status.backupCodesRemaining > 0 ? chalk.cyan(status.backupCodesRemaining) : chalk.yellow('0')}\n`);
+                if (status.passkeys.length > 0) {
+                    out.raw('\n');
+                    out.raw(chalk.bold('Registered Passkeys:') + '\n');
+                    for (const passkey of status.passkeys) {
+                        const lastUsed = passkey.lastUsedAt
+                            ? new Date(passkey.lastUsedAt).toLocaleDateString()
+                            : chalk.dim('never');
+                        out.raw(`  - ${chalk.cyan(passkey.name)} (last used: ${lastUsed})\n`);
+                    }
                 }
             }
         }
         catch (err) {
-            spinner.fail('Failed to fetch MFA status');
-            console.error(err instanceof Error ? err.message : String(err));
+            out.failSpinner('Failed to fetch MFA status');
+            handleError(out, err, 'MFA management requires JWT authentication');
         }
     });
-    mfa.command('setup-totp')
-        .description('Set up TOTP authenticator app (Google Authenticator, Authy, etc.)')
-        .action(async () => {
-        const spinner = ora('Generating TOTP secret...').start();
+    addGlobalFlags(mfa.command('setup-totp')
+        .description('Set up TOTP authenticator app (Google Authenticator, Authy, etc.)'))
+        .action(async (_opts) => {
+        const flags = resolveFlags(_opts);
+        const out = createOutput(flags);
+        out.startSpinner('Generating TOTP secret...');
         try {
             const client = await getClientAsync();
             const setup = await client.mfa.setupTotp();
-            spinner.stop();
-            console.log(chalk.bold('TOTP Setup'));
-            console.log('');
-            console.log(`Secret:  ${chalk.cyan(setup.secret)}`);
-            console.log('');
-            console.log('Add this URI to your authenticator app:');
-            console.log(chalk.dim(setup.otpauthUri));
-            console.log('');
-            console.log(chalk.yellow('Note: QR codes cannot be displayed in the terminal.'));
-            console.log(chalk.yellow('      Copy the URI above to any authenticator app that supports otpauth:// URIs.'));
-            console.log('');
-            // Prompt for verification code
+            out.stopSpinner();
+            if (flags.output === 'json') {
+                out.record({ secret: setup.secret, otpauthUri: setup.otpauthUri });
+            }
+            else {
+                out.raw(chalk.bold('TOTP Setup') + '\n');
+                out.raw('\n');
+                out.raw(`Secret:  ${chalk.cyan(setup.secret)}\n`);
+                out.raw('\n');
+                out.raw('Add this URI to your authenticator app:\n');
+                out.raw(chalk.dim(setup.otpauthUri) + '\n');
+                out.raw('\n');
+                out.raw(chalk.yellow('Note: QR codes cannot be displayed in the terminal.') + '\n');
+                out.raw(chalk.yellow('      Copy the URI above to any authenticator app that supports otpauth:// URIs.') + '\n');
+                out.raw('\n');
+            }
+            // Prompt for verification code — skip in quiet mode
+            if (flags.quiet)
+                return;
             const code = await promptMfaCode();
             if (!code) {
-                console.log(chalk.yellow('Setup cancelled.'));
+                out.status(chalk.yellow('Setup cancelled.'));
                 return;
             }
-            const verifySpinner = ora('Verifying code and enabling TOTP...').start();
+            out.startSpinner('Verifying code and enabling TOTP...');
             const result = await client.mfa.verifyTotp(code);
-            verifySpinner.succeed('TOTP enabled successfully!');
-            console.log('');
-            console.log(chalk.bold.yellow('IMPORTANT: Save these backup codes securely!'));
-            console.log(chalk.dim('You can use them to access your account if you lose your authenticator device.'));
-            console.log('');
-            // Display backup codes in a grid (2 columns)
-            const codes = result.backupCodes;
-            for (let i = 0; i < codes.length; i += 2) {
-                const left = codes[i] || '';
-                const right = codes[i + 1] || '';
-                console.log(`  ${chalk.cyan(left.padEnd(20))}  ${chalk.cyan(right)}`);
+            out.stopSpinner();
+            out.success('TOTP enabled successfully!');
+            if (flags.output === 'json') {
+                out.list(result.backupCodes.map((code) => ({ code })), { emptyMessage: 'No backup codes returned.' });
+            }
+            else {
+                out.raw('\n');
+                out.raw(chalk.bold.yellow('IMPORTANT: Save these backup codes securely!') + '\n');
+                out.raw(chalk.dim('You can use them to access your account if you lose your authenticator device.') + '\n');
+                out.raw('\n');
+                // Display backup codes in a grid (2 columns)
+                const codes = result.backupCodes;
+                for (let i = 0; i < codes.length; i += 2) {
+                    const left = codes[i] || '';
+                    const right = codes[i + 1] || '';
+                    out.raw(`  ${chalk.cyan(left.padEnd(20))}  ${chalk.cyan(right)}\n`);
+                }
+                out.raw('\n');
             }
-            console.log('');
         }
         catch (err) {
-            spinner.fail('TOTP setup failed');
-            console.error(err instanceof Error ? err.message : String(err));
+            handleError(out, err, 'TOTP setup failed');
         }
     });
-    mfa.command('disable-totp')
-        .description('Disable TOTP authentication (requires password)')
-        .action(async () => {
+    addGlobalFlags(mfa.command('disable-totp')
+        .description('Disable TOTP authentication (requires password)'))
+        .action(async (_opts) => {
+        const flags = resolveFlags(_opts);
+        const out = createOutput(flags);
+        // Skip interactive prompt in quiet mode
+        if (flags.quiet) {
+            out.error('Password prompt required — cannot run in quiet mode without --password-stdin.');
+            process.exitCode = 1;
+            return;
+        }
         const password = await promptPassword();
         if (!password) {
-            console.log(chalk.yellow('Operation cancelled.'));
+            out.status(chalk.yellow('Operation cancelled.'));
             return;
         }
-        const spinner = ora('Disabling TOTP...').start();
+        out.startSpinner('Disabling TOTP...');
         try {
             const client = await getClientAsync();
             const result = await client.mfa.disableTotp(password);
-            spinner.succeed(result.message);
+            out.stopSpinner();
+            out.success(result.message, { message: result.message });
         }
         catch (err) {
-            spinner.fail('Failed to disable TOTP');
-            console.error(err instanceof Error ? err.message : String(err));
+            handleError(out, err, 'Failed to disable TOTP');
         }
     });
-    mfa.command('backup-codes')
+    addGlobalFlags(mfa.command('backup-codes')
         .description('Show remaining backup code count or regenerate codes')
-        .option('--regenerate', 'Generate new backup codes (requires password, invalidates old codes)')
-        .action(async (opts) => {
-        if (opts.regenerate) {
+        .option('--regenerate', 'Generate new backup codes (requires password, invalidates old codes)'))
+        .action(async (_opts) => {
+        const flags = resolveFlags(_opts);
+        const out = createOutput(flags);
+        if (_opts.regenerate) {
             // Regenerate backup codes
+            if (flags.quiet) {
+                out.error('Password prompt required — cannot run in quiet mode without --password-stdin.');
+                process.exitCode = 1;
+                return;
+            }
             const password = await promptPassword();
             if (!password) {
-                console.log(chalk.yellow('Operation cancelled.'));
+                out.status(chalk.yellow('Operation cancelled.'));
                 return;
             }
-            const spinner = ora('Regenerating backup codes...').start();
+            out.startSpinner('Regenerating backup codes...');
             try {
                 const client = await getClientAsync();
                 const result = await client.mfa.regenerateBackupCodes(password);
-                spinner.succeed('Backup codes regenerated!');
-                console.log('');
-                console.log(chalk.bold.yellow('IMPORTANT: Save these new backup codes securely!'));
-                console.log(chalk.dim('All previous backup codes have been invalidated.'));
-                console.log('');
-                // Display backup codes in a grid (2 columns)
-                const codes = result.backupCodes;
-                for (let i = 0; i < codes.length; i += 2) {
-                    const left = codes[i] || '';
-                    const right = codes[i + 1] || '';
-                    console.log(`  ${chalk.cyan(left.padEnd(20))}  ${chalk.cyan(right)}`);
+                out.stopSpinner();
+                out.success('Backup codes regenerated!');
+                if (flags.output === 'json') {
+                    out.list(result.backupCodes.map((code) => ({ code })), { emptyMessage: 'No backup codes returned.' });
+                }
+                else {
+                    out.raw('\n');
+                    out.raw(chalk.bold.yellow('IMPORTANT: Save these new backup codes securely!') + '\n');
+                    out.raw(chalk.dim('All previous backup codes have been invalidated.') + '\n');
+                    out.raw('\n');
+                    // Display backup codes in a grid (2 columns)
+                    const codes = result.backupCodes;
+                    for (let i = 0; i < codes.length; i += 2) {
+                        const left = codes[i] || '';
+                        const right = codes[i + 1] || '';
+                        out.raw(`  ${chalk.cyan(left.padEnd(20))}  ${chalk.cyan(right)}\n`);
+                    }
+                    out.raw('\n');
                 }
-                console.log('');
             }
             catch (err) {
-                spinner.fail('Failed to regenerate backup codes');
-                console.error(err instanceof Error ? err.message : String(err));
-                process.exitCode = 1;
+                handleError(out, err, 'Failed to regenerate backup codes');
             }
         }
         else {
             // Show backup code count
-            const spinner = ora('Fetching backup code count...').start();
+            out.startSpinner('Fetching backup code count...');
             try {
                 const client = await getClientAsync();
                 const status = await client.mfa.getStatus();
-                spinner.stop();
-                console.log(chalk.bold('Backup Codes'));
-                console.log(`  Remaining: ${status.backupCodesRemaining > 0 ? chalk.cyan(status.backupCodesRemaining) : chalk.yellow('0')}`);
-                if (status.backupCodesRemaining === 0) {
-                    console.log('');
-                    console.log(chalk.yellow('You have no backup codes remaining.'));
-                    console.log(chalk.yellow('Run `lsvault mfa backup-codes --regenerate` to generate new codes.'));
+                out.stopSpinner();
+                if (flags.output === 'json') {
+                    out.record({ backupCodesRemaining: status.backupCodesRemaining });
+                }
+                else {
+                    out.raw(chalk.bold('Backup Codes') + '\n');
+                    out.raw(`  Remaining: ${status.backupCodesRemaining > 0 ? chalk.cyan(status.backupCodesRemaining) : chalk.yellow('0')}\n`);
+                    if (status.backupCodesRemaining === 0) {
+                        out.raw('\n');
+                        out.raw(chalk.yellow('You have no backup codes remaining.') + '\n');
+                        out.raw(chalk.yellow('Run `lsvault mfa backup-codes --regenerate` to generate new codes.') + '\n');
+                    }
                 }
             }
             catch (err) {
-                spinner.fail('Failed to fetch backup code count');
-                console.error(err instanceof Error ? err.message : String(err));
-                process.exitCode = 1;
+                handleError(out, err, 'Failed to fetch backup code count');
             }
         }
     });

package/dist/commands/plugins.js

@@ -44,7 +44,7 @@ export function registerPluginCommands(program) {
     addGlobalFlags(plugins.command('install')
         .description('Install a plugin from the marketplace')
         .requiredOption('--plugin-id <pluginId>', 'Plugin marketplace identifier (e.g. org/plugin-name)')
-        .requiredOption('--version <version>', 'Version to install'))
+        .requiredOption('--plugin-version <version>', 'Version to install'))
         .action(async (_opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
@@ -53,7 +53,7 @@ export function registerPluginCommands(program) {
             const client = await getClientAsync();
             const installed = await client.plugins.install({
                 pluginId: _opts.pluginId,
-                version: _opts.version,
+                version: _opts.pluginVersion,
             });
             out.stopSpinner();
             if (flags.output === 'json') {

package/dist/commands/publish-vault.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
+import { confirmAction } from '../utils/confirm.js';
 export function registerPublishVaultCommands(program) {
     const pv = program.command('publish-vault').description('Manage whole-vault publishing (public sites)');
     addGlobalFlags(pv.command('list')
@@ -37,7 +38,7 @@ export function registerPublishVaultCommands(program) {
         .option('--description <desc>', 'Site description')
         .option('--show-sidebar', 'Show sidebar navigation')
         .option('--enable-search', 'Enable search on the site')
-        .option('--theme <theme>', 'Site theme')
+        .option('--theme <theme>', 'Site theme (e.g. default, minimal, blog, docs)')
         .option('--domain <domainId>', 'Custom domain ID'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
@@ -68,7 +69,7 @@ export function registerPublishVaultCommands(program) {
         .option('--description <desc>', 'Site description')
         .option('--show-sidebar', 'Show sidebar')
         .option('--enable-search', 'Enable search')
-        .option('--theme <theme>', 'Site theme')
+        .option('--theme <theme>', 'Site theme (e.g. default, minimal, blog, docs)')
         .option('--domain <domainId>', 'Custom domain ID'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
@@ -100,12 +101,18 @@ export function registerPublishVaultCommands(program) {
     });
     addGlobalFlags(pv.command('unpublish')
         .description('Unpublish a vault site')
-        .argument('<vaultId>', 'Vault ID'))
+        .argument('<vaultId>', 'Vault ID')
+        .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
-        out.startSpinner('Unpublishing vault...');
         try {
+            const confirmed = await confirmAction(`Unpublish vault site for vault ${vaultId}?`, { yes: _opts.yes });
+            if (!confirmed) {
+                out.status('Unpublish cancelled.');
+                return;
+            }
+            out.startSpinner('Unpublishing vault...');
             const client = await getClientAsync();
             await client.publishVault.unpublish(vaultId);
             out.success('Vault unpublished', { vaultId });

package/dist/commands/saml.js

@@ -3,7 +3,9 @@ import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 export function registerSamlCommands(program) {
-    const saml = program.command('saml').description('SAML SSO configuration management (requires admin role)');
+    const saml = program.command('saml')
+        .description('SAML SSO configuration management (requires admin role)')
+        .addHelpText('after', '\nNOTE: SAML commands require JWT authentication with admin role.\nRun "lsvault auth login" to authenticate first.');
     // ── list-configs ─────────────────────────────────────────────────────────
     addGlobalFlags(saml.command('list-configs')
         .description('List all SSO configurations'))

package/dist/commands/search.js

@@ -16,7 +16,11 @@ EXAMPLES
   lsvault search "meeting notes"
   lsvault search "project plan" --vault abc123
   lsvault search "typescript" --tags dev,code --limit 5
-  lsvault search "machine learning" --mode semantic`))
+  lsvault search "machine learning" --mode semantic
+
+NOTE
+  Semantic search (--mode semantic) requires the embedding worker to have
+  processed documents. If results are empty, ensure the worker is running.`))
         .action(async (query, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/shares.js

@@ -5,6 +5,7 @@ import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 import { promptPassword, readPasswordFromStdin } from '../utils/prompt.js';
 import { resolveVaultId } from '../utils/resolve-vault.js';
+import { confirmAction } from '../utils/confirm.js';
 export function registerShareCommands(program) {
     const shares = program.command('shares').description('Create, list, and revoke document share links');
     addGlobalFlags(shares.command('list')
@@ -134,12 +135,18 @@ export function registerShareCommands(program) {
     addGlobalFlags(shares.command('revoke')
         .description('Revoke a share link')
         .argument('<vaultId>', 'Vault ID or slug')
-        .argument('<shareId>', 'Share link ID'))
+        .argument('<shareId>', 'Share link ID')
+        .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (vaultId, shareId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
-        out.startSpinner('Revoking share link...');
         try {
+            const confirmed = await confirmAction(`Revoke share link ${shareId}?`, { yes: _opts.yes });
+            if (!confirmed) {
+                out.status('Revoke cancelled.');
+                return;
+            }
+            out.startSpinner('Revoking share link...');
             vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             await client.shares.revoke(vaultId, shareId);

package/dist/commands/sync.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
+import { confirmAction } from '../utils/confirm.js';
 import { formatUptime } from '../utils/format.js';
 import { loadSyncConfigs, createSyncConfig, deleteSyncConfig, getSyncConfig, } from '../sync/config.js';
 import { deleteSyncState, loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } from '../sync/state.js';
@@ -124,12 +125,18 @@ Sync modes:
     // sync delete <syncId>
     addGlobalFlags(sync.command('delete')
         .description('Delete a sync configuration')
-        .argument('<syncId>', 'Sync configuration ID'))
+        .argument('<syncId>', 'Sync configuration ID')
+        .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (syncId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
-        out.startSpinner('Deleting sync configuration...');
         try {
+            const confirmed = await confirmAction(`Delete sync configuration ${syncId}?`, { yes: _opts.yes });
+            if (!confirmed) {
+                out.status('Delete cancelled.');
+                return;
+            }
+            out.startSpinner('Deleting sync configuration...');
             const deleted = deleteSyncConfig(syncId);
             if (!deleted) {
                 out.failSpinner('Sync configuration not found');
@@ -274,8 +281,6 @@ Sync modes:
             }
             out.stopSpinner();
             if (flags.dryRun) {
-                out.status(chalk.yellow('Dry run — no changes will be made:'));
-                out.status(formatDiff(diff));
                 if (flags.output === 'json') {
                     out.record({
                         dryRun: true,
@@ -285,6 +290,10 @@ Sync modes:
                         totalBytes: diff.totalBytes,
                     });
                 }
+                else {
+                    out.status(chalk.yellow('Dry run — no changes will be made:'));
+                    out.status(formatDiff(diff));
+                }
                 return;
             }
             if (flags.verbose) {

package/dist/commands/user.js

@@ -5,6 +5,7 @@ import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 import { formatBytes } from '../utils/format.js';
 import { promptPassword, readPasswordFromStdin } from '../utils/prompt.js';
+import { confirmAction } from '../utils/confirm.js';
 export function registerUserCommands(program) {
     const user = program.command('user').description('View account details and storage usage');
     addGlobalFlags(user.command('storage')
@@ -176,10 +177,16 @@ export function registerUserCommands(program) {
         .description('Request account deletion')
         .option('--password-stdin', 'Read password from stdin for CI usage')
         .option('--reason <reason>', 'Reason for deletion')
-        .option('--export-data', 'Request data export before deletion'))
+        .option('--export-data', 'Request data export before deletion')
+        .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (_opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
+        const confirmed = await confirmAction('Are you sure you want to delete your account? This cannot be undone.', { yes: _opts.yes });
+        if (!confirmed) {
+            out.status('Account deletion cancelled.');
+            return;
+        }
         let password;
         if (_opts.passwordStdin) {
             password = await readPasswordFromStdin();

package/dist/commands/vaults.js

@@ -5,17 +5,21 @@ import { createOutput, handleError } from '../utils/output.js';
 import { generateVaultKey } from '@lifestreamdynamics/vault-sdk';
 import { getCredentialManager } from '../config.js';
 import { resolveVaultId } from '../utils/resolve-vault.js';
+import { confirmAction } from '../utils/confirm.js';
 export function registerVaultCommands(program) {
     const vaults = program.command('vaults').description('Create, list, and inspect document vaults');
     addGlobalFlags(vaults.command('list')
-        .description('List all vaults accessible to the current user'))
+        .description('List all vaults accessible to the current user')
+        .option('--include-archived', 'Include archived vaults in the list'))
         .action(async (_opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Fetching vaults...');
         try {
             const client = await getClientAsync();
-            const vaultList = await client.vaults.list();
+            const vaultList = await client.vaults.list({
+                includeArchived: _opts.includeArchived === true,
+            });
             out.stopSpinner();
             out.list(vaultList.map(v => ({ name: v.name, slug: v.slug, encrypted: v.encryptionEnabled ? 'yes' : 'no', description: v.description ?? null, id: v.id })), {
                 emptyMessage: 'No vaults found.',
@@ -45,6 +49,7 @@ export function registerVaultCommands(program) {
         const out = createOutput(flags);
         out.startSpinner('Fetching vault...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const vault = await client.vaults.get(vaultId);
             out.stopSpinner();
@@ -196,12 +201,18 @@ EXAMPLES
     // vault archive
     addGlobalFlags(vaults.command('archive')
         .description('Archive a vault')
-        .argument('<vaultId>', 'Vault ID'))
+        .argument('<vaultId>', 'Vault ID')
+        .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
-        out.startSpinner('Archiving vault...');
         try {
+            const confirmed = await confirmAction(`Archive vault ${vaultId}?`, { yes: _opts.yes });
+            if (!confirmed) {
+                out.status('Archive cancelled.');
+                return;
+            }
+            out.startSpinner('Archiving vault...');
             const client = await getClientAsync();
             const vault = await client.vaults.archive(vaultId);
             out.success(`Vault archived: ${vault.name}`, { id: vault.id, name: vault.name, isArchived: vault.isArchived });

package/dist/utils/output.js

@@ -96,6 +96,8 @@ export class Output {
      * - table: prints a single-row table
      */
     record(data, columns) {
+        if (this.flags.quiet)
+            return;
         switch (this.flags.output) {
             case 'json':
                 process.stdout.write(JSON.stringify(data) + '\n');
@@ -131,11 +133,11 @@ export class Output {
             }
             return;
         }
+        if (this.flags.quiet)
+            return;
         switch (this.flags.output) {
             case 'json':
-                for (const item of data) {
-                    process.stdout.write(JSON.stringify(item) + '\n');
-                }
+                process.stdout.write(JSON.stringify(data) + '\n');
                 break;
             case 'table':
                 this.table(data, options?.columns);
@@ -166,8 +168,8 @@ export class Output {
      * Print a success result (used for create/update/delete confirmations).
      */
     success(message, data) {
-        if (this.flags.output === 'json' && data) {
-            process.stdout.write(JSON.stringify(data) + '\n');
+        if (this.flags.output === 'json') {
+            process.stdout.write(JSON.stringify(data ?? { success: true, message }) + '\n');
         }
         else if (!this.flags.quiet) {
             this.succeedSpinner(message);

package/dist/utils/resolve-vault.js

@@ -11,7 +11,7 @@ export async function resolveVaultId(idOrSlug) {
     if (UUID_RE.test(idOrSlug))
         return idOrSlug;
     const client = await getClientAsync();
-    const vaults = await client.vaults.list();
+    const vaults = await client.vaults.list({ includeArchived: true });
     const match = vaults.find(v => v.slug === idOrSlug);
     if (!match)
         throw new Error(`Vault not found: "${idOrSlug}"`);

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@lifestreamdynamics/vault-cli",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Command-line interface for Lifestream Vault",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "type": "module",
   "bin": {