@lifestreamdynamics/vault-cli 1.3.5 → 1.3.7

package/dist/commands/publish.js

@@ -2,16 +2,18 @@ import chalk from 'chalk';
 import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
+import { resolveVaultId } from '../utils/resolve-vault.js';
 export function registerPublishCommands(program) {
     const publish = program.command('publish').description('Publish documents to public profile pages');
     addGlobalFlags(publish.command('list')
         .description('List your published documents')
-        .argument('<vaultId>', 'Vault ID (required by route)'))
+        .argument('<vaultId>', 'Vault ID or slug (required by route)'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Fetching published documents...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const docs = await client.publish.listMine(vaultId);
             out.stopSpinner();
@@ -49,7 +51,7 @@ export function registerPublishCommands(program) {
     });
     addGlobalFlags(publish.command('create')
         .description('Publish a document')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<docPath>', 'Document path (e.g., blog/post.md)')
         .requiredOption('--slug <slug>', 'URL-friendly slug for the published page')
         .option('--title <title>', 'SEO title')
@@ -60,6 +62,7 @@ export function registerPublishCommands(program) {
         const out = createOutput(flags);
         out.startSpinner('Publishing document...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const params = {
                 slug: String(_opts.slug),
@@ -73,6 +76,7 @@ export function registerPublishCommands(program) {
             const pub = await client.publish.create(vaultId, docPath, params);
             out.success('Document published successfully!', {
                 slug: pub.slug,
+                url: `/${pub.publishedBy}/${pub.slug}`,
                 isPublished: pub.isPublished,
                 seoTitle: pub.seoTitle || null,
                 seoDescription: pub.seoDescription || null,
@@ -85,7 +89,7 @@ export function registerPublishCommands(program) {
     });
     addGlobalFlags(publish.command('update')
         .description('Update a published document')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<docPath>', 'Document path (e.g., blog/post.md)')
         .requiredOption('--slug <slug>', 'URL-friendly slug (required for updates)')
         .option('--title <title>', 'SEO title')
@@ -96,6 +100,7 @@ export function registerPublishCommands(program) {
         const out = createOutput(flags);
         out.startSpinner('Updating published document...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const params = {
                 slug: String(_opts.slug),
@@ -120,7 +125,7 @@ export function registerPublishCommands(program) {
     });
     addGlobalFlags(publish.command('delete')
         .description('Unpublish a document')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<docPath>', 'Document path (e.g., blog/post.md)')
         .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (vaultId, docPath, _opts) => {
@@ -132,6 +137,7 @@ export function registerPublishCommands(program) {
         }
         out.startSpinner('Unpublishing document...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             await client.publish.delete(vaultId, docPath);
             out.success('Document unpublished successfully', { path: docPath, unpublished: true });
@@ -143,16 +149,25 @@ export function registerPublishCommands(program) {
     const subdomain = publish.command('subdomain').description('Subdomain management for published vaults');
     addGlobalFlags(subdomain.command('get')
         .description('Get the subdomain for a published vault')
-        .argument('<vaultId>', 'Vault ID'))
+        .argument('<vaultId>', 'Vault ID or slug'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Fetching subdomain...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const result = await client.publish.getSubdomain(vaultId);
             out.stopSpinner();
-            out.record({ subdomain: result.subdomain });
+            if (flags.output === 'json') {
+                out.record({ subdomain: result.subdomain });
+            }
+            else if (result.subdomain == null) {
+                out.status('No subdomain configured.');
+            }
+            else {
+                out.record({ subdomain: result.subdomain });
+            }
         }
         catch (err) {
             handleError(out, err, 'Failed to fetch subdomain');
@@ -160,13 +175,14 @@ export function registerPublishCommands(program) {
     });
     addGlobalFlags(subdomain.command('set')
         .description('Set a subdomain for a published vault')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<subdomain>', 'Subdomain to assign'))
         .action(async (vaultId, subdomainArg, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Setting subdomain...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const result = await client.publish.setSubdomain(vaultId, subdomainArg);
             out.success(`Subdomain set: ${result.subdomain}`, { subdomain: result.subdomain });
@@ -177,7 +193,7 @@ export function registerPublishCommands(program) {
     });
     addGlobalFlags(subdomain.command('delete')
         .description('Remove the subdomain for a published vault')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
@@ -188,6 +204,7 @@ export function registerPublishCommands(program) {
         }
         out.startSpinner('Removing subdomain...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const result = await client.publish.deleteSubdomain(vaultId);
             out.success(result.message, { message: result.message });

package/dist/commands/search.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 { resolveVaultId } from '../utils/resolve-vault.js';
 export function registerSearchCommands(program) {
     addGlobalFlags(program.command('search')
         .description('Full-text search across all documents')
@@ -21,6 +22,8 @@ EXAMPLES
         const out = createOutput(flags);
         out.startSpinner('Searching...');
         try {
+            if (_opts.vault)
+                _opts.vault = await resolveVaultId(String(_opts.vault));
             const client = await getClientAsync();
             const mode = _opts.mode;
             const response = await client.search.search({
@@ -31,6 +34,9 @@ EXAMPLES
                 mode: mode,
             });
             out.stopSpinner();
+            if (response.results.length === 0 && mode === 'semantic') {
+                out.warn('Semantic search returned no results. Ensure document embeddings have been generated (the embedding worker must be running).');
+            }
             if (flags.output === 'text') {
                 const modeInfo = mode && mode !== 'text' ? `[${mode}] ` : '';
                 out.status(chalk.dim(`${modeInfo}${response.total} result(s) for "${response.query}":\n`));
@@ -39,6 +45,7 @@ EXAMPLES
                 title: r.title || r.path,
                 path: r.path,
                 vaultName: r.vaultName,
+                rank: r.rank,
                 tags: r.tags.join(', '),
                 snippet: r.snippet ? r.snippet.replace(/<[^>]+>/g, '') : '',
             })), {

package/dist/commands/shares.js

@@ -1,19 +1,22 @@
 import chalk from 'chalk';
 import { getClientAsync } from '../client.js';
+import { loadConfigAsync } from '../config.js';
 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';
 export function registerShareCommands(program) {
     const shares = program.command('shares').description('Create, list, and revoke document share links');
     addGlobalFlags(shares.command('list')
         .description('List share links for a document')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<docPath>', 'Document path (e.g., notes/meeting.md)'))
         .action(async (vaultId, docPath, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Fetching share links...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const links = await client.shares.list(vaultId, docPath);
             out.stopSpinner();
@@ -53,7 +56,7 @@ export function registerShareCommands(program) {
     });
     addGlobalFlags(shares.command('create')
         .description('Create a share link for a document')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<docPath>', 'Document path (e.g., notes/meeting.md)')
         .option('--permission <perm>', 'Permission level: view or edit', 'view')
         .option('--protect-with-password', 'Prompt for a password to protect the link (interactive TTY only)')
@@ -85,6 +88,7 @@ export function registerShareCommands(program) {
         }
         out.startSpinner('Creating share link...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const params = {};
             if (_opts.permission)
@@ -97,9 +101,12 @@ export function registerShareCommands(program) {
                 params.maxViews = parseInt(String(_opts.maxViews), 10);
             const result = await client.shares.create(vaultId, docPath, params);
             out.stopSpinner();
+            const config = await loadConfigAsync();
+            const shareUrl = `${config.apiUrl}/share/${result.fullToken}`;
             if (flags.output === 'json') {
                 out.record({
                     token: result.fullToken,
+                    url: shareUrl,
                     id: result.shareLink.id,
                     permission: result.shareLink.permission,
                     expiresAt: result.shareLink.expiresAt || null,
@@ -109,6 +116,7 @@ export function registerShareCommands(program) {
             else {
                 out.warn('\nIMPORTANT: Save this token. It cannot be retrieved later.\n');
                 process.stdout.write(chalk.green.bold(`Token: ${result.fullToken}\n`));
+                process.stdout.write(chalk.green(`URL:   ${shareUrl}\n`));
                 process.stdout.write(`\nID:         ${result.shareLink.id}\n`);
                 process.stdout.write(`Permission: ${result.shareLink.permission}\n`);
                 if (result.shareLink.expiresAt) {
@@ -125,13 +133,14 @@ export function registerShareCommands(program) {
     });
     addGlobalFlags(shares.command('revoke')
         .description('Revoke a share link')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<shareId>', 'Share link ID'))
         .action(async (vaultId, shareId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Revoking share link...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             await client.shares.revoke(vaultId, shareId);
             out.success('Share link revoked successfully', { id: shareId, revoked: true });

package/dist/commands/sync.js

@@ -186,8 +186,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,
@@ -197,6 +195,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

@@ -409,9 +409,19 @@ export function registerUserCommands(program) {
     addGlobalFlags(consents.command('set')
         .description('Record a consent decision')
         .requiredOption('--type <t>', 'Consent type')
-        .requiredOption('--version <v>', 'Policy version')
+        .requiredOption('--policy-version <v>', 'Policy version')
         .option('--granted', 'Grant consent')
-        .option('--no-granted', 'Deny consent'))
+        .option('--no-granted', 'Deny consent')
+        .addHelpText('after', `
+CONSENT TYPES
+  terms_of_service    Terms of Service acceptance
+  privacy_policy      Privacy Policy acceptance
+  ai_processing       AI feature data processing consent
+  marketing           Marketing communications consent
+
+EXAMPLES
+  lsvault user consents set --type terms_of_service --policy-version 1.0 --granted
+  lsvault user consents set --type ai_processing --policy-version 1.0 --no-granted`))
         .action(async (_opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
@@ -420,7 +430,7 @@ export function registerUserCommands(program) {
             const client = await getClientAsync();
             const result = await client.user.recordConsent({
                 consentType: _opts.type,
-                version: _opts.version,
+                version: _opts.policyVersion,
                 granted: _opts.granted !== false,
             });
             out.success(result.message, { message: result.message });

package/dist/commands/vaults.js

@@ -4,6 +4,7 @@ import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 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';
 export function registerVaultCommands(program) {
     const vaults = program.command('vaults').description('Create, list, and inspect document vaults');
     addGlobalFlags(vaults.command('list')
@@ -16,7 +17,7 @@ export function registerVaultCommands(program) {
             const client = await getClientAsync();
             const vaultList = await client.vaults.list();
             out.stopSpinner();
-            out.list(vaultList.map(v => ({ name: v.name, slug: v.slug, encrypted: v.encryptionEnabled ? 'yes' : 'no', description: v.description || 'No description', id: v.id })), {
+            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.',
                 columns: [
                     { key: 'name', header: 'Name' },
@@ -27,7 +28,8 @@ export function registerVaultCommands(program) {
                 ],
                 textFn: (v) => {
                     const encIcon = v.encrypted === 'yes' ? chalk.green(' [encrypted]') : '';
-                    return `${chalk.cyan(String(v.name))} ${chalk.dim(`(${String(v.slug)})`)}${encIcon} -- ${String(v.description)}`;
+                    const desc = v.description != null ? ` -- ${String(v.description)}` : '';
+                    return `${chalk.cyan(String(v.name))} ${chalk.dim(`(${String(v.slug)})`)}${encIcon}${desc}`;
                 },
             });
         }
@@ -160,12 +162,13 @@ EXAMPLES
     // vault tree
     addGlobalFlags(vaults.command('tree')
         .description('Show vault file tree')
-        .argument('<vaultId>', 'Vault ID'))
+        .argument('<vaultId>', 'Vault ID or slug'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Fetching vault tree...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const tree = await client.vaults.getTree(vaultId);
             out.stopSpinner();

package/dist/commands/versions.js

@@ -2,11 +2,12 @@ import chalk from 'chalk';
 import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
+import { resolveVaultId } from '../utils/resolve-vault.js';
 export function registerVersionCommands(program) {
     const versions = program.command('versions').description('View and manage document version history');
     addGlobalFlags(versions.command('list')
         .description('List version history for a document')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<path>', 'Document path (e.g., notes/todo.md)')
         .addHelpText('after', `
 EXAMPLES
@@ -16,6 +17,7 @@ EXAMPLES
         const out = createOutput(flags);
         out.startSpinner('Fetching versions...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const versionList = await client.documents.listVersions(vaultId, docPath);
             out.stopSpinner();
@@ -23,7 +25,7 @@ EXAMPLES
                 version: v.versionNum,
                 source: v.changeSource,
                 sizeBytes: v.sizeBytes,
-                pinned: v.isPinned ? 'yes' : 'no',
+                pinned: flags.output === 'json' ? v.isPinned : (v.isPinned ? 'yes' : 'no'),
                 createdAt: v.createdAt,
             })), {
                 emptyMessage: 'No versions found.',
@@ -49,7 +51,7 @@ EXAMPLES
     });
     addGlobalFlags(versions.command('view')
         .description('View content of a specific version')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<path>', 'Document path')
         .argument('<version>', 'Version number')
         .addHelpText('after', `
@@ -65,6 +67,7 @@ EXAMPLES
             return;
         }
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const version = await client.documents.getVersion(vaultId, docPath, versionNum);
             if (version.content === null) {
@@ -72,7 +75,12 @@ EXAMPLES
                 process.exitCode = 1;
                 return;
             }
-            out.raw(version.content);
+            if (flags.output === 'json') {
+                out.raw(JSON.stringify({ version: version.versionNum, createdAt: version.createdAt, content: version.content }) + '\n');
+            }
+            else {
+                out.raw(version.content);
+            }
         }
         catch (err) {
             handleError(out, err, 'Failed to get version');
@@ -80,7 +88,7 @@ EXAMPLES
     });
     addGlobalFlags(versions.command('diff')
         .description('Show diff between two versions')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<path>', 'Document path')
         .argument('<from>', 'Source version number')
         .argument('<to>', 'Target version number')
@@ -99,6 +107,7 @@ EXAMPLES
         }
         out.startSpinner('Computing diff...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const diff = await client.documents.diffVersions(vaultId, docPath, from, to);
             out.stopSpinner();
@@ -121,12 +130,18 @@ EXAMPLES
             }
         }
         catch (err) {
-            handleError(out, err, 'Failed to compute diff');
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('not found') || message.includes('Not found')) {
+                handleError(out, new Error(`Version ${from} or ${to} not found for document "${docPath}". Use 'versions list' to see available versions.`), 'Failed to compute diff');
+            }
+            else {
+                handleError(out, err, 'Failed to compute diff');
+            }
         }
     });
     addGlobalFlags(versions.command('restore')
         .description('Restore a document to a previous version')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<path>', 'Document path')
         .argument('<version>', 'Version number to restore')
         .addHelpText('after', `
@@ -143,6 +158,7 @@ EXAMPLES
         }
         out.startSpinner(`Restoring to version ${versionNum}...`);
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const doc = await client.documents.restoreVersion(vaultId, docPath, versionNum);
             out.success(`Restored ${chalk.cyan(docPath)} to version ${versionNum}`, {
@@ -156,7 +172,7 @@ EXAMPLES
     });
     addGlobalFlags(versions.command('pin')
         .description('Pin a version to prevent pruning')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<path>', 'Document path')
         .argument('<version>', 'Version number to pin')
         .addHelpText('after', `
@@ -173,6 +189,7 @@ EXAMPLES
         }
         out.startSpinner(`Pinning version ${versionNum}...`);
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             await client.documents.pinVersion(vaultId, docPath, versionNum);
             out.success(`Pinned version ${versionNum} of ${chalk.cyan(docPath)}`, {
@@ -187,7 +204,7 @@ EXAMPLES
     });
     addGlobalFlags(versions.command('unpin')
         .description('Unpin a version, allowing it to be pruned')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<path>', 'Document path')
         .argument('<version>', 'Version number to unpin')
         .addHelpText('after', `
@@ -204,6 +221,7 @@ EXAMPLES
         }
         out.startSpinner(`Unpinning version ${versionNum}...`);
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             await client.documents.unpinVersion(vaultId, docPath, versionNum);
             out.success(`Unpinned version ${versionNum} of ${chalk.cyan(docPath)}`, {

package/dist/commands/webhooks.js

@@ -2,16 +2,18 @@ import chalk from 'chalk';
 import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
+import { resolveVaultId } from '../utils/resolve-vault.js';
 export function registerWebhookCommands(program) {
     const webhooks = program.command('webhooks').description('Manage vault webhooks');
     addGlobalFlags(webhooks.command('list')
         .description('List all webhooks for a vault')
-        .argument('<vaultId>', 'Vault ID'))
+        .argument('<vaultId>', 'Vault ID or slug'))
         .action(async (vaultId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Fetching webhooks...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const webhookList = await client.webhooks.list(vaultId);
             out.stopSpinner();
@@ -42,18 +44,45 @@ export function registerWebhookCommands(program) {
     });
     addGlobalFlags(webhooks.command('create')
         .description('Create a new webhook')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<url>', 'Webhook endpoint URL')
-        .option('--events <events>', 'Comma-separated events (e.g., create,update,delete)', 'create,update,delete'))
+        .option('--events <events>', 'Comma-separated events (document.created, document.updated, document.deleted, document.moved, document.copied, or * for all)', 'document.created,document.updated,document.deleted')
+        .addHelpText('after', `
+VALID EVENT NAMES
+  document.created   Document was created
+  document.updated   Document content was updated
+  document.deleted   Document was deleted
+  document.moved     Document was moved or renamed
+  document.copied    Document was copied
+  *                  All events
+
+EXAMPLES
+  lsvault webhooks create <vaultId> https://example.com/hook
+  lsvault webhooks create <vaultId> https://example.com/hook --events "document.created,document.deleted"
+  lsvault webhooks create <vaultId> https://example.com/hook --events "*"`))
         .action(async (vaultId, url, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
+        if (!/^https?:\/\//i.test(url)) {
+            out.error(`Invalid webhook URL "${url}". URL must start with http:// or https://`);
+            process.exitCode = 1;
+            return;
+        }
+        const VALID_EVENTS = ['document.created', 'document.updated', 'document.deleted', 'document.moved', 'document.copied', '*'];
+        const events = String(_opts.events || 'document.created,document.updated,document.deleted').split(',').map((e) => e.trim());
+        const invalid = events.filter(e => !VALID_EVENTS.includes(e));
+        if (invalid.length > 0) {
+            out.error(`Invalid event name(s): ${invalid.join(', ')}. Valid values: ${VALID_EVENTS.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
         out.startSpinner('Creating webhook...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const params = {
                 url,
-                events: String(_opts.events || 'create,update,delete').split(',').map((e) => e.trim()),
+                events,
             };
             const webhook = await client.webhooks.create(vaultId, params);
             out.stopSpinner();
@@ -79,7 +108,7 @@ export function registerWebhookCommands(program) {
     });
     addGlobalFlags(webhooks.command('update')
         .description('Update a webhook')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<webhookId>', 'Webhook ID')
         .option('--url <url>', 'New webhook URL')
         .option('--events <events>', 'Comma-separated events')
@@ -95,6 +124,7 @@ export function registerWebhookCommands(program) {
         }
         out.startSpinner('Updating webhook...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const params = {};
             if (_opts.url)
@@ -118,7 +148,7 @@ export function registerWebhookCommands(program) {
     });
     addGlobalFlags(webhooks.command('delete')
         .description('Delete a webhook')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<webhookId>', 'Webhook ID')
         .option('-y, --yes', 'Skip confirmation prompt'))
         .action(async (vaultId, webhookId, _opts) => {
@@ -130,6 +160,7 @@ export function registerWebhookCommands(program) {
         }
         out.startSpinner('Deleting webhook...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             await client.webhooks.delete(vaultId, webhookId);
             out.success('Webhook deleted successfully', { id: webhookId, deleted: true });
@@ -140,13 +171,14 @@ export function registerWebhookCommands(program) {
     });
     addGlobalFlags(webhooks.command('deliveries')
         .description('List recent deliveries for a webhook')
-        .argument('<vaultId>', 'Vault ID')
+        .argument('<vaultId>', 'Vault ID or slug')
         .argument('<webhookId>', 'Webhook ID'))
         .action(async (vaultId, webhookId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
         out.startSpinner('Fetching deliveries...');
         try {
+            vaultId = await resolveVaultId(vaultId);
             const client = await getClientAsync();
             const deliveries = await client.webhooks.listDeliveries(vaultId, webhookId);
             out.stopSpinner();

package/dist/utils/flags.js

@@ -5,7 +5,7 @@ import chalk from 'chalk';
  */
 export function addGlobalFlags(cmd) {
     return cmd
-        .option('-o, --output <format>', 'Output format: text, json, table (default: auto)')
+        .option('-o, --output <format>', 'Output format: text, json, table (default: auto — text for TTY, json for pipes)')
         .option('-v, --verbose', 'Verbose output (debug info)')
         .option('-q, --quiet', 'Minimal output (errors only)')
         .option('--no-color', 'Disable colored output')

package/dist/utils/output.d.ts

@@ -1,4 +1,4 @@
-import type { GlobalFlags } from './flags.js';
+import type { GlobalFlags, OutputFormat } from './flags.js';
 /**
  * Column definition for table output.
  */
@@ -41,8 +41,11 @@ export declare class Output {
     debug(message: string): void;
     /**
      * Print an error message to stderr.
+     * When output format is json, writes a JSON error envelope instead of colored text.
      */
     error(message: string): void;
+    /** Expose the current output format (for error handlers that need it). */
+    get format(): OutputFormat;
     /**
      * Print a warning message to stderr.
      */