@tuskydp/cli 0.2.1 → 0.4.0

package/src/commands/download.ts

@@ -1,22 +1,23 @@
 import type { Command } from 'commander';
 import { writeFileSync } from 'fs';
 import { join } from 'path';
+import ora from 'ora';
 import chalk from 'chalk';
 import { getApiUrl, getApiKey } from '../config.js';
 import { createSDKClient } from '../sdk.js';
 import { formatBytes } from '../lib/output.js';
-import { createSpinner } from '../lib/progress.js';
-import { decryptBuffer } from '../crypto.js';
-import { loadMasterKey } from '../lib/keyring.js';
-import { sealDecrypt, getSuiKeypair } from '../seal.js';
+import { sealDecrypt, sealDecryptMetadata, getSuiKeypair } from '../seal.js';
 
 export async function downloadCommand(fileId: string, options: {
   output?: string;
+  stdout?: boolean;
 }, program: Command) {
   const apiUrl = getApiUrl(program.opts().apiUrl);
   const apiKey = getApiKey(program.opts().apiKey);
   const sdk = createSDKClient(apiUrl, apiKey);
-  const spinner = createSpinner('Fetching file info...');
+  // When piping to stdout, send spinner to stderr to avoid polluting the binary stream
+  const spinnerStream = options.stdout ? process.stderr : process.stdout;
+  const spinner = ora({ text: 'Fetching file info...', stream: spinnerStream as NodeJS.WritableStream });
   spinner.start();
 
   try {
@@ -54,10 +55,9 @@ export async function downloadCommand(fileId: string, options: {
     const arrayBuf = await response.arrayBuffer();
     let fileBuffer: Buffer = Buffer.from(new Uint8Array(arrayBuf));
 
-    // Decrypt if needed — dispatch on encryption type
+    // Decrypt if needed — SEAL-encrypted (shared vault)
     if (encryption?.encrypted) {
       if ('type' in encryption && encryption.type === 'seal') {
-        // SEAL-encrypted (shared vault)
         spinner.text = 'SEAL decrypting...';
         const keypair = getSuiKeypair();
         if (!keypair) {
@@ -71,32 +71,42 @@ export async function downloadCommand(fileId: string, options: {
         const vault = await sdk.vaults.get(fileInfo.vaultId);
         const decrypted = await sealDecrypt(new Uint8Array(fileBuffer), vault, keypair);
         fileBuffer = Buffer.from(decrypted);
-      } else {
-        // Passphrase-encrypted (private vault)
-        spinner.text = 'Decrypting...';
-        const masterKey = loadMasterKey();
-        if (!masterKey) {
-          spinner.fail('Encryption session not unlocked. Run: tusky encryption unlock');
-          return;
-        }
-        // Narrow to passphrase type
-        const enc = encryption as { type: 'passphrase'; encrypted: true; wrappedKey: string; iv: string; plaintextChecksumSha256: string | null };
-        fileBuffer = decryptBuffer(
-          fileBuffer,
-          enc.wrappedKey,
-          enc.iv,
-          masterKey,
-          enc.plaintextChecksumSha256 ?? undefined,
-        );
       }
     }
 
-    // Write to disk — use getStatus to get filename
+
+    // Output: stdout or disk
     const fileInfo = await sdk.files.getStatus(fileId);
-    const outputPath = options.output || join(process.cwd(), fileInfo.name);
-    writeFileSync(outputPath, fileBuffer);
 
-    spinner.succeed(`Downloaded -> ${outputPath} (${formatBytes(fileBuffer.length)})`);
+    // Resolve the real filename — decrypt if nameEncrypted
+    let displayName = fileInfo.name;
+    if (fileInfo.nameEncrypted) {
+      try {
+        if (fileInfo.encryptedMetadata) {
+          // Shared vault — decrypt with SEAL keypair
+          const keypair = getSuiKeypair();
+          if (keypair) {
+            const fileObj = await sdk.files.get(fileId);
+            const vault = await sdk.vaults.get(fileObj.vaultId);
+            const meta = await sealDecryptMetadata(fileInfo.encryptedMetadata, vault, keypair);
+            displayName = meta.n;
+          }
+        }
+      } catch {
+        // Fall back to placeholder if decryption fails
+      }
+    }
+
+
+    if (options.stdout) {
+      // Pipe raw bytes to stdout — stop spinner first so it doesn't interleave
+      spinner.stop();
+      process.stdout.write(fileBuffer);
+    } else {
+      const outputPath = options.output || join(process.cwd(), displayName);
+      writeFileSync(outputPath, fileBuffer);
+      spinner.succeed(`Downloaded -> ${outputPath} (${formatBytes(fileBuffer.length)})`);
+    }
   } catch (err: any) {
     spinner.fail(`Download failed: ${err.message}`);
   }

package/src/commands/export.ts

@@ -1,14 +1,13 @@
 /**
  * `tusky export` — Export file metadata for disaster recovery.
  *
- * Dumps all file records (including Walrus blob IDs, encryption keys,
- * and epoch info) to a JSON file. This allows users to recover their
- * data directly from Walrus if the Tusky service is unavailable.
+ * Dumps all file records (including Walrus blob IDs and epoch info)
+ * to a JSON file. This allows users to recover their data directly
+ * from Walrus if the Tusky service is unavailable.
  *
  * The export contains everything needed to:
  *   1. Fetch files from Walrus aggregators using blobId
- *   2. Decrypt private vault files using wrappedKey + iv + master key
- *   3. Renew Walrus epochs using blobObjectId + a Sui wallet
+ *   2. Renew Walrus epochs using blobObjectId + a Sui wallet
  */
 
 import type { Command } from 'commander';
@@ -35,16 +34,12 @@ export interface ExportedFile {
   walrusBlobObjectId: string | null;
   /** Epoch when Walrus storage expires (renew before this) */
   walrusEpochEnd: string | null;
-  /** Whether the file is client-side encrypted */
+  /** Whether the file is client-side encrypted (SEAL for shared vaults) */
   encrypted: boolean;
-  /** AES-256-GCM file key, wrapped with the master key (base64) */
-  wrappedKey: string | null;
-  /** AES-256-GCM initialization vector (base64) */
-  encryptionIv: string | null;
-  /** SHA-256 of the plaintext — for integrity verification after decryption */
-  plaintextChecksumSha256: string | null;
-  /** Original plaintext size in bytes (before encryption) */
-  plaintextSizeBytes: number | null;
+  /** Whether the filename is encrypted */
+  nameEncrypted: boolean;
+  /** SEAL-encrypted filename+mimeType blob (shared vaults) */
+  encryptedMetadata: string | null;
   createdAt: string;
 }
 
@@ -56,16 +51,6 @@ export interface ExportManifest {
     email: string;
     plan: string;
   };
-  /** Account encryption params — needed to derive master key from passphrase */
-  encryption: {
-    setupComplete: boolean;
-    /** PBKDF2 salt (base64) */
-    salt: string | null;
-    /** HMAC verifier for passphrase validation (base64) */
-    verifier: string | null;
-    /** Master key wrapped with passphrase-derived key (base64) */
-    encryptedMasterKey: string | null;
-  };
   walrusNetwork: string;
   walrusAggregatorUrl: string;
   totalFiles: number;
@@ -79,10 +64,11 @@ export interface ExportManifest {
 export function registerExportCommand(program: Command) {
   program
     .command('export')
-    .description('Export file metadata for disaster recovery (Walrus blob IDs, encryption keys)')
+    .description('Export file metadata for disaster recovery (Walrus blob IDs, epoch info)')
     .option('-o, --output <path>', 'Output file path', 'tusky-export.json')
+    .option('--stdout', 'Write JSON manifest to stdout instead of a file')
     .option('--vault <vaultId>', 'Export only files from a specific vault')
-    .action(async (options: { output: string; vault?: string }) => {
+    .action(async (options: { output: string; stdout?: boolean; vault?: string }) => {
       const apiUrl = getApiUrl(program.opts().apiUrl);
       const apiKey = getApiKey(program.opts().apiKey);
       const sdk = createSDKClient(apiUrl, apiKey);
@@ -91,9 +77,8 @@ export function registerExportCommand(program: Command) {
       spinner.start();
 
       try {
-        // Fetch account + encryption params
+        // Fetch account
         const account = await sdk.account.get();
-        const encryptionParams = await sdk.account.getEncryptionParams();
 
         // Fetch all vaults
         spinner.text = 'Fetching vaults...';
@@ -139,10 +124,8 @@ export function registerExportCommand(program: Command) {
                 walrusBlobObjectId: file.walrusBlobObjectId,
                 walrusEpochEnd: file.walrusEpochEnd,
                 encrypted: file.encrypted,
-                wrappedKey: file.wrappedKey,
-                encryptionIv: file.encryptionIv,
-                plaintextChecksumSha256: file.plaintextChecksumSha256,
-                plaintextSizeBytes: file.plaintextSizeBytes,
+                nameEncrypted: file.nameEncrypted ?? false,
+                encryptedMetadata: file.encryptedMetadata ?? null,
                 createdAt: file.createdAt,
               });
             }
@@ -168,12 +151,6 @@ export function registerExportCommand(program: Command) {
             email: account.email,
             plan: account.planName,
           },
-          encryption: {
-            setupComplete: encryptionParams.setupComplete,
-            salt: encryptionParams.salt ?? null,
-            verifier: encryptionParams.verifier ?? null,
-            encryptedMasterKey: encryptionParams.encryptedMasterKey ?? null,
-          },
           walrusNetwork: isMainnet ? 'mainnet' : 'testnet',
           walrusAggregatorUrl,
           totalFiles: exportedFiles.length,
@@ -191,30 +168,6 @@ export function registerExportCommand(program: Command) {
               '  OR: walrus read <walrusBlobId> -o <filename>',
               '  OR: tusky rehydrate <walrusBlobId> -o <filename>',
               '',
-              '--- DECRYPT PRIVATE VAULT FILES ---',
-              'Files with encrypted=true are AES-256-GCM encrypted.',
-              '',
-              'Option A — Using the Tusky CLI decrypt command (easiest):',
-              '  tusky decrypt <encrypted-file> --export <this-file.json> -o <output>',
-              '  This reads the wrappedKey/iv from this manifest and prompts for your passphrase.',
-              '  You can also pass --passphrase <passphrase> or set TUSKYDP_PASSWORD env var.',
-              '  If the Tusky API is still reachable, you can skip the export and use:',
-              '  tusky decrypt <encrypted-file> --file-id <fileId> -o <output>',
-              '',
-              'Option B — Using the standalone script (zero dependencies, fully offline):',
-              '  node tusky-decrypt.mjs <encrypted-file> <output> <passphrase> <salt> <wrappedKey> <iv> [encryptedMasterKey]',
-              '  The salt and encryptedMasterKey come from your account encryption params.',
-              '',
-              'Option C — Manual decryption (any language with AES-256-GCM + PBKDF2):',
-              '  1. Derive wrapping key: PBKDF2(passphrase, salt, 600000 iterations, SHA-256, 32 bytes)',
-              '  2. If your account has an encryptedMasterKey, unwrap it: AES-256-GCM-decrypt(encryptedMasterKey, wrappingKey)',
-              '     Otherwise the wrapping key IS the master key (legacy accounts)',
-              '  3. Unwrap the file key: AES-256-GCM-decrypt(wrappedKey, masterKey)',
-              '     wrappedKey format: [12-byte IV | ciphertext | 16-byte auth tag]',
-              '  4. Decrypt the file: AES-256-GCM-decrypt(fileData, fileKey, encryptionIv)',
-              '     File data format: [ciphertext | 16-byte auth tag]',
-              '  5. Verify integrity: SHA-256(plaintext) should match plaintextChecksumSha256',
-              '',
               '--- RENEW WALRUS EPOCHS ---',
               'Files with a walrusBlobObjectId can have their storage extended:',
               '  walrus extend <walrusBlobObjectId> --epochs 5',
@@ -223,27 +176,30 @@ export function registerExportCommand(program: Command) {
           },
         };
 
-        // Write to disk
-        const outputPath = resolve(options.output);
-        writeFileSync(outputPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
-
-        spinner.succeed(`Exported ${exportedFiles.length} files from ${vaults.length} vault(s)`);
-        console.log(chalk.dim(`  Output: ${outputPath}`));
-        console.log('');
-
-        // Summary stats
-        const withBlob = exportedFiles.filter((f) => f.walrusBlobId).length;
-        const encrypted = exportedFiles.filter((f) => f.encrypted).length;
-        const hotOnly = exportedFiles.filter((f) => !f.walrusBlobId && f.status === 'hot').length;
+        if (options.stdout) {
+          spinner.stop();
+          process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
+        } else {
+          // Write to disk
+          const outputPath = resolve(options.output);
+          writeFileSync(outputPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+          spinner.succeed(`Exported ${exportedFiles.length} files from ${vaults.length} vault(s)`);
+          console.log(chalk.dim(`  Output: ${outputPath}`));
+          console.log('');
+        }
 
-        console.log(`  On Walrus:     ${withBlob} files (recoverable from Walrus network)`);
-        console.log(`  Encrypted:     ${encrypted} files (require passphrase to decrypt)`);
-        if (hotOnly > 0) {
-          console.log(chalk.yellow(`  Hot only:      ${hotOnly} files (NOT yet on Walrus — only in Tusky hot cache)`));
+        if (!options.stdout) {
+          // Summary stats (only for disk output — stdout is clean JSON)
+          const withBlob = exportedFiles.filter((f) => f.walrusBlobId).length;
+          const hotOnly = exportedFiles.filter((f) => !f.walrusBlobId && f.status === 'hot').length;
+
+          console.log(`  On Walrus:     ${withBlob} files (recoverable from Walrus network)`);
+          if (hotOnly > 0) {
+            console.log(chalk.yellow(`  Hot only:      ${hotOnly} files (NOT yet on Walrus — only in Tusky hot cache)`));
+          }
+          console.log('');
+          console.log(chalk.dim('  See the "recovery.instructions" field inside for full recovery steps.'));
         }
-        console.log('');
-        console.log(chalk.yellow('  Store this file securely — it contains encryption keys.'));
-        console.log(chalk.dim('  See the "recovery.instructions" field inside for full recovery steps.'));
       } catch (err: any) {
         spinner.fail(`Export failed: ${err.message}`);
       }

package/src/commands/files.ts

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { cliConfig } from '../config.js';
 import { getSDKClient } from '../sdk.js';
-import { createTable, formatBytes, formatDate } from '../lib/output.js';
+import { createTable, formatBytes, formatDate, shortId } from '../lib/output.js';
 import { resolveVault } from '../lib/resolve.js';
 
 export function registerFileCommands(program: Command) {
@@ -12,6 +12,7 @@ export function registerFileCommands(program: Command) {
     .description('List files')
     .option('--sort <field>', 'Sort by: name, size, date', 'date')
     .option('--limit <n>', 'Max results', '50')
+    .option('--folder <folder-id>', 'Filter by folder ID')
     .option('-f, --follow', 'Watch mode: refresh every 3 seconds')
     .action(async (vaultRef: string | undefined, options) => {
       const sdk = getSDKClient(program);
@@ -27,6 +28,7 @@ export function registerFileCommands(program: Command) {
       const fetchAndRender = async (): Promise<void> => {
         const { files } = await sdk.files.list({
           vaultId,
+          folderId: options.folder,
           limit: parseInt(options.limit),
           sortBy: sortMap[options.sort] as 'createdAt' | 'name' | 'sizeBytes',
           order: 'desc',
@@ -42,7 +44,12 @@ export function registerFileCommands(program: Command) {
           return;
         }
 
-        const table = createTable(['Name', 'Size', 'Status', 'Uploaded', 'ID']);
+        const showFolder = !options.folder && files.some(f => f.folderId);
+        const headers = showFolder
+          ? ['Name', 'Size', 'Status', 'Folder', 'Uploaded', 'ID']
+          : ['Name', 'Size', 'Status', 'Uploaded', 'ID'];
+
+        const table = createTable(headers);
         for (const f of files) {
           const statusColors: Record<string, typeof chalk.green> = {
             hot: chalk.green,
@@ -53,13 +60,17 @@ export function registerFileCommands(program: Command) {
           };
           const statusColor = statusColors[f.status] || chalk.white;
 
-          table.push([
+          const row = [
             f.name,
-            formatBytes(f.plaintextSizeBytes || f.sizeBytes),
+            formatBytes(f.sizeBytes),
             statusColor(f.status),
-            formatDate(f.createdAt),
-            chalk.dim(f.id),
-          ]);
+          ];
+          if (showFolder) {
+            row.push(f.folderId ? chalk.dim(shortId(f.folderId)) : chalk.dim('-'));
+          }
+          row.push(formatDate(f.createdAt));
+          row.push(chalk.dim(f.id));
+          table.push(row);
         }
         console.log(table.toString());
       };
@@ -102,14 +113,26 @@ export function registerFileCommands(program: Command) {
       }
 
       console.log(`Name:        ${file.name}`);
-      console.log(`Size:        ${formatBytes(file.plaintextSizeBytes || file.sizeBytes)}`);
+      console.log(`Size:        ${formatBytes(file.sizeBytes)}`);
       console.log(`MIME:        ${file.mimeType}`);
       console.log(`Status:      ${file.status}`);
       console.log(`Encrypted:   ${file.encrypted ? 'Yes' : 'No'}`);
       console.log(`Vault:       ${file.vaultId}`);
-      if (file.folderId) console.log(`Folder:      ${file.folderId}`);
+      if (file.folderId) {
+        // Try to resolve folder name
+        try {
+          const folder = await sdk.folders.get(file.folderId);
+          console.log(`Folder:      ${folder.name} (${file.folderId})`);
+        } catch {
+          console.log(`Folder:      ${file.folderId}`);
+        }
+      }
       if (file.walrusBlobId) console.log(`Walrus Blob: ${file.walrusBlobId}`);
+      if (file.walrusBlobObjectId) console.log(`Blob Object: ${file.walrusBlobObjectId}`);
       if (file.lastSyncError) console.log(`Sync Error:  ${chalk.red(file.lastSyncError)}`);
+      if (file.autoRenew) console.log(`Auto-Renew:  ${chalk.green('On')}`);
+      if (file.ppuEpochEnd) console.log(`PPU Epoch:   ${new Date(file.ppuEpochEnd).toLocaleString()}`);
+      if (file.hotUntil) console.log(`Hot Until:   ${new Date(file.hotUntil).toLocaleString()}`);
       console.log(`Uploaded:    ${new Date(file.createdAt).toISOString()}`);
       console.log(`ID:          ${file.id}`);
     });
@@ -165,7 +188,7 @@ export function registerFileCommands(program: Command) {
 
   // rm command
   program.command('rm <file-ids...>')
-    .description('Delete one or more files')
+    .description('Delete one or more files (moves to trash)')
     .option('--force', 'Skip confirmation prompt')
     .action(async (fileIds: string[], options) => {
       const sdk = getSDKClient(program);
@@ -174,7 +197,7 @@ export function registerFileCommands(program: Command) {
         const answers = await inquirer.prompt([{
           type: 'confirm',
           name: 'confirm',
-          message: `Delete ${fileIds.length} file(s)? This cannot be undone.`,
+          message: `Delete ${fileIds.length} file(s)? Files will be moved to trash.`,
           default: false,
         }]);
         if (!answers.confirm) return;
@@ -189,4 +212,65 @@ export function registerFileCommands(program: Command) {
         }
       }
     });
+
+  // mv command — move file to a folder
+  program.command('mv <file-id>')
+    .description('Move a file to a different folder (or vault root)')
+    .option('--folder <folder-id>', 'Target folder ID')
+    .option('--root', 'Move to vault root (no folder)')
+    .action(async (fileId: string, options) => {
+      const sdk = getSDKClient(program);
+
+      if (!options.folder && !options.root) {
+        console.error(chalk.red('Specify --folder <id> or --root'));
+        return;
+      }
+
+      const folderId = options.root ? null : options.folder;
+      await sdk.files.move(fileId, { folderId });
+      console.log(chalk.green(folderId ? `File moved to folder ${folderId}` : 'File moved to vault root'));
+    });
+
+  // extend command — extend PPU storage epochs
+  program.command('extend <file-id>')
+    .description('Extend PPU storage by purchasing additional epochs')
+    .requiredOption('--epochs <n>', 'Number of additional epochs to purchase')
+    .action(async (fileId: string, options) => {
+      const sdk = getSDKClient(program);
+      const epochs = parseInt(options.epochs);
+      if (isNaN(epochs) || epochs <= 0) {
+        console.error(chalk.red('Epochs must be a positive integer.'));
+        return;
+      }
+
+      const result = await sdk.files.extend(fileId, { epochs });
+      console.log(chalk.green(`Extended ${fileId} by ${epochs} epoch(s).`));
+      if (result.payment) {
+        console.log(`  WAL cost: ${result.payment.walMist} MIST`);
+      }
+      if (result.file.ppuEpochEnd) {
+        console.log(`  New epoch end: ${new Date(result.file.ppuEpochEnd).toLocaleString()}`);
+      }
+    });
+
+  // auto-renew command
+  program.command('auto-renew <file-id>')
+    .description('Toggle auto-renewal for a file\'s Walrus storage')
+    .option('--on', 'Enable auto-renew')
+    .option('--off', 'Disable auto-renew')
+    .action(async (fileId: string, options) => {
+      const sdk = getSDKClient(program);
+
+      if (!options.on && !options.off) {
+        // Show current status
+        const file = await sdk.files.get(fileId);
+        console.log(`Auto-Renew: ${file.autoRenew ? chalk.green('On') : chalk.dim('Off')}`);
+        console.log(chalk.dim('Use --on or --off to change.'));
+        return;
+      }
+
+      const autoRenew = !!options.on;
+      await sdk.files.setAutoRenew(fileId, { autoRenew });
+      console.log(chalk.green(`Auto-renew ${autoRenew ? 'enabled' : 'disabled'} for ${fileId}`));
+    });
 }

package/src/commands/folder.ts

@@ -0,0 +1,169 @@
+import type { Command } from 'commander';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { cliConfig } from '../config.js';
+import { getSDKClientFromParent } from '../sdk.js';
+import { createTable, formatDate, shortId } from '../lib/output.js';
+import { resolveVault } from '../lib/resolve.js';
+
+export function registerFolderCommands(program: Command) {
+  const folder = program.command('folder').description('Manage folders within vaults');
+
+  // ── create ──────────────────────────────────────────────────────────
+  folder.command('create <name>')
+    .description('Create a folder in a vault')
+    .requiredOption('--vault <vault>', 'Target vault (ID, slug, or name)')
+    .option('--parent <parent-id>', 'Parent folder ID (for nested folders)')
+    .action(async (name: string, options) => {
+      const sdk = getSDKClientFromParent(folder);
+      const vaultId = await resolveVault(sdk, options.vault);
+
+      const created = await sdk.folders.create({
+        vaultId,
+        parentId: options.parent,
+        name,
+      });
+      console.log(chalk.green(`Folder "${created.name}" created (${created.id})`));
+    });
+
+  // ── list ────────────────────────────────────────────────────────────
+  folder.command('list')
+    .description('List folders in a vault')
+    .requiredOption('--vault <vault>', 'Target vault (ID, slug, or name)')
+    .option('--parent <parent-id>', 'Parent folder ID (list children of this folder)')
+    .action(async (options) => {
+      const sdk = getSDKClientFromParent(folder);
+      const root = folder.parent || folder;
+      const format = root.opts().format || cliConfig.get('outputFormat');
+      const vaultId = await resolveVault(sdk, options.vault);
+
+      const folders = await sdk.folders.list({ vaultId, parentId: options.parent });
+
+      if (format === 'json') {
+        console.log(JSON.stringify(folders, null, 2));
+        return;
+      }
+
+      if (folders.length === 0) {
+        console.log(chalk.dim('No folders found.'));
+        return;
+      }
+
+      const table = createTable(['Name', 'Parent', 'Created', 'ID']);
+      for (const f of folders) {
+        table.push([
+          f.name,
+          f.parentId ? chalk.dim(shortId(f.parentId)) : chalk.dim('(root)'),
+          formatDate(f.createdAt),
+          chalk.dim(shortId(f.id)),
+        ]);
+      }
+      console.log(table.toString());
+    });
+
+  // ── info ────────────────────────────────────────────────────────────
+  folder.command('info <folder-id>')
+    .description('Show folder details')
+    .action(async (folderId: string) => {
+      const sdk = getSDKClientFromParent(folder);
+      const root = folder.parent || folder;
+      const format = root.opts().format || cliConfig.get('outputFormat');
+      const f = await sdk.folders.get(folderId);
+
+      if (format === 'json') {
+        console.log(JSON.stringify(f, null, 2));
+        return;
+      }
+
+      console.log(`Name:        ${f.name}`);
+      console.log(`ID:          ${f.id}`);
+      console.log(`Vault:       ${f.vaultId}`);
+      console.log(`Parent:      ${f.parentId || chalk.dim('(root)')}`);
+      console.log(`Created:     ${new Date(f.createdAt).toLocaleString()}`);
+    });
+
+  // ── contents ────────────────────────────────────────────────────────
+  folder.command('contents <folder-id>')
+    .description('List folder contents (files and subfolders)')
+    .action(async (folderId: string) => {
+      const sdk = getSDKClientFromParent(folder);
+      const root = folder.parent || folder;
+      const format = root.opts().format || cliConfig.get('outputFormat');
+      const contents = await sdk.folders.getContents(folderId);
+
+      if (format === 'json') {
+        console.log(JSON.stringify(contents, null, 2));
+        return;
+      }
+
+      if (contents.folders.length === 0 && contents.files.length === 0) {
+        console.log(chalk.dim('Folder is empty.'));
+        return;
+      }
+
+      if (contents.folders.length > 0) {
+        console.log(chalk.bold('Subfolders:'));
+        const folderTable = createTable(['Name', 'Created', 'ID']);
+        for (const f of contents.folders) {
+          folderTable.push([
+            f.name,
+            formatDate(f.createdAt),
+            chalk.dim(shortId(f.id)),
+          ]);
+        }
+        console.log(folderTable.toString());
+      }
+
+      if (contents.files.length > 0) {
+        if (contents.folders.length > 0) console.log('');
+        console.log(chalk.bold('Files:'));
+        const { formatBytes } = await import('../lib/output.js');
+        const fileTable = createTable(['Name', 'Size', 'Status', 'Created', 'ID']);
+        const statusColors: Record<string, typeof chalk.green> = {
+          hot: chalk.green, synced: chalk.blue, cold: chalk.yellow,
+          error: chalk.red, uploading: chalk.dim,
+        };
+        for (const f of contents.files) {
+          const sc = statusColors[f.status] || chalk.white;
+          fileTable.push([
+            f.name,
+            formatBytes(f.sizeBytes),
+            sc(f.status),
+            formatDate(f.createdAt),
+            chalk.dim(shortId(f.id)),
+          ]);
+        }
+        console.log(fileTable.toString());
+      }
+    });
+
+  // ── rename ──────────────────────────────────────────────────────────
+  folder.command('rename <folder-id> <new-name>')
+    .description('Rename a folder')
+    .action(async (folderId: string, newName: string) => {
+      const sdk = getSDKClientFromParent(folder);
+      await sdk.folders.update(folderId, { name: newName });
+      console.log(chalk.green(`Folder renamed to "${newName}"`));
+    });
+
+  // ── delete ──────────────────────────────────────────────────────────
+  folder.command('delete <folder-id>')
+    .description('Delete a folder (must be empty)')
+    .option('--force', 'Skip confirmation prompt')
+    .action(async (folderId: string, options) => {
+      const sdk = getSDKClientFromParent(folder);
+
+      if (!options.force) {
+        const answers = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirm',
+          message: 'Delete folder? It must be empty.',
+          default: false,
+        }]);
+        if (!answers.confirm) return;
+      }
+
+      await sdk.folders.delete(folderId);
+      console.log(chalk.green('Folder deleted.'));
+    });
+}