spindb 0.5.5 → 0.7.0

package/README.md

@@ -18,11 +18,23 @@ Spin up local PostgreSQL and MySQL databases without Docker. A lightweight alter
 ## Installation
 
 ```bash
-# Run directly with pnpx (no install needed)
+# Install globally (recommended)
+npm install -g spindb
+
+# Or run directly with pnpx (no install needed)
 pnpx spindb
+```
+
+### Updating
+
+SpinDB checks for updates automatically and will notify you when a new version is available:
+
+```bash
+# Update to latest version
+spindb self-update
 
-# Or install globally
-pnpm add -g spindb
+# Or check manually
+spindb version --check
 ```
 
 ## Quick Start
@@ -61,6 +73,10 @@ spindb connect mydb
 | `spindb config detect` | Auto-detect database tools |
 | `spindb deps check` | Check status of client tools |
 | `spindb deps install` | Install missing client tools |
+| `spindb version` | Show current version |
+| `spindb version --check` | Check for available updates |
+| `spindb self-update` | Update to latest version |
+| `spindb config update-check [on\|off]` | Enable/disable update notifications |
 
 ## Supported Engines
 

package/cli/commands/backup.ts

@@ -51,7 +51,10 @@ export const backupCommand = new Command('backup')
   .argument('[container]', 'Container name')
   .option('-d, --database <name>', 'Database to backup')
   .option('-n, --name <name>', 'Custom backup filename (without extension)')
-  .option('-o, --output <path>', 'Output directory (defaults to current directory)')
+  .option(
+    '-o, --output <path>',
+    'Output directory (defaults to current directory)',
+  )
   .option('--format <format>', 'Output format: sql or dump')
   .option('--sql', 'Output as plain SQL (shorthand for --format sql)')
   .option('--dump', 'Output as dump format (shorthand for --format dump)')
@@ -198,7 +201,10 @@ export const backupCommand = new Command('backup')
         }
 
         // Determine filename
-        const defaultFilename = generateDefaultFilename(containerName, databaseName)
+        const defaultFilename = generateDefaultFilename(
+          containerName,
+          databaseName,
+        )
         let filename = options.name || defaultFilename
 
         // In interactive mode with no name provided, optionally prompt for custom name
@@ -229,17 +235,17 @@ export const backupCommand = new Command('backup')
         console.log(success('Backup complete'))
         console.log()
         console.log(chalk.gray('  File:'), chalk.cyan(result.path))
-        console.log(chalk.gray('  Size:'), chalk.white(formatBytes(result.size)))
+        console.log(
+          chalk.gray('  Size:'),
+          chalk.white(formatBytes(result.size)),
+        )
         console.log(chalk.gray('  Format:'), chalk.white(result.format))
         console.log()
       } catch (err) {
         const e = err as Error
 
         // Check if this is a missing tool error
-        const missingToolPatterns = [
-          'pg_dump not found',
-          'mysqldump not found',
-        ]
+        const missingToolPatterns = ['pg_dump not found', 'mysqldump not found']
 
         const matchingPattern = missingToolPatterns.find((p) =>
           e.message.includes(p),

package/cli/commands/config.ts

@@ -8,7 +8,8 @@ import {
   ENHANCED_SHELLS,
   ALL_TOOLS,
 } from '../../core/config-manager'
-import { error, success, header } from '../ui/theme'
+import { updateManager } from '../../core/update-manager'
+import { error, success, header, info } from '../ui/theme'
 import { createSpinner } from '../ui/spinner'
 import type { BinaryTool } from '../../types'
 
@@ -78,7 +79,9 @@ export const configCommand = new Command('config')
 
           if (config.updatedAt) {
             const isStale = await configManager.isStale()
-            const staleWarning = isStale ? chalk.yellow(' (stale - run config detect to refresh)') : ''
+            const staleWarning = isStale
+              ? chalk.yellow(' (stale - run config detect to refresh)')
+              : ''
             console.log(
               chalk.gray(
                 `  Last updated: ${new Date(config.updatedAt).toLocaleString()}${staleWarning}`,
@@ -291,3 +294,55 @@ export const configCommand = new Command('config')
         }
       }),
   )
+  .addCommand(
+    new Command('update-check')
+      .description('Enable or disable automatic update checks on startup')
+      .argument('[state]', 'on or off (omit to show current status)')
+      .action(async (state?: string) => {
+        try {
+          const cached = await updateManager.getCachedUpdateInfo()
+
+          if (!state) {
+            // Show current status
+            const status = cached.autoCheckEnabled
+              ? chalk.green('enabled')
+              : chalk.yellow('disabled')
+            console.log()
+            console.log(`  Update checks on startup: ${status}`)
+            console.log()
+            console.log(chalk.gray('  Usage:'))
+            console.log(
+              chalk.gray('    spindb config update-check on   # Enable'),
+            )
+            console.log(
+              chalk.gray('    spindb config update-check off  # Disable'),
+            )
+            console.log()
+            return
+          }
+
+          if (state !== 'on' && state !== 'off') {
+            console.error(error('Invalid state. Use "on" or "off"'))
+            process.exit(1)
+          }
+
+          const enabled = state === 'on'
+          await updateManager.setAutoCheckEnabled(enabled)
+
+          if (enabled) {
+            console.log(success('Update checks enabled on startup'))
+          } else {
+            console.log(info('Update checks disabled on startup'))
+            console.log(
+              chalk.gray(
+                '  You can still manually check with: spindb version --check',
+              ),
+            )
+          }
+        } catch (err) {
+          const e = err as Error
+          console.error(error(e.message))
+          process.exit(1)
+        }
+      }),
+  )

package/cli/commands/connect.ts

@@ -26,9 +26,15 @@ export const connectCommand = new Command('connect')
   .option('-d, --database <name>', 'Database name')
   .option('--tui', 'Use usql for enhanced shell experience')
   .option('--install-tui', 'Install usql if not present, then connect')
-  .option('--pgcli', 'Use pgcli for enhanced PostgreSQL shell (dropdown auto-completion)')
+  .option(
+    '--pgcli',
+    'Use pgcli for enhanced PostgreSQL shell (dropdown auto-completion)',
+  )
   .option('--install-pgcli', 'Install pgcli if not present, then connect')
-  .option('--mycli', 'Use mycli for enhanced MySQL shell (dropdown auto-completion)')
+  .option(
+    '--mycli',
+    'Use mycli for enhanced MySQL shell (dropdown auto-completion)',
+  )
   .option('--install-mycli', 'Install mycli if not present, then connect')
   .action(
     async (
@@ -164,7 +170,9 @@ export const connectCommand = new Command('connect')
         const usePgcli = options.pgcli || options.installPgcli
         if (usePgcli) {
           if (engineName !== 'postgresql') {
-            console.error(error('pgcli is only available for PostgreSQL containers'))
+            console.error(
+              error('pgcli is only available for PostgreSQL containers'),
+            )
             console.log(chalk.gray('For MySQL, use: spindb connect --mycli'))
             process.exit(1)
           }
@@ -173,7 +181,9 @@ export const connectCommand = new Command('connect')
 
           if (!pgcliInstalled) {
             if (options.installPgcli) {
-              console.log(info('Installing pgcli for enhanced PostgreSQL shell...'))
+              console.log(
+                info('Installing pgcli for enhanced PostgreSQL shell...'),
+              )
               const pm = await detectPackageManager()
               if (pm) {
                 const result = await installPgcli(pm)
@@ -181,7 +191,9 @@ export const connectCommand = new Command('connect')
                   console.log(success('pgcli installed successfully!'))
                   console.log()
                 } else {
-                  console.error(error(`Failed to install pgcli: ${result.error}`))
+                  console.error(
+                    error(`Failed to install pgcli: ${result.error}`),
+                  )
                   console.log()
                   console.log(chalk.gray('Manual installation:'))
                   for (const instruction of getPgcliManualInstructions()) {
@@ -201,7 +213,9 @@ export const connectCommand = new Command('connect')
             } else {
               console.error(error('pgcli is not installed'))
               console.log()
-              console.log(chalk.gray('Install pgcli for enhanced PostgreSQL shell:'))
+              console.log(
+                chalk.gray('Install pgcli for enhanced PostgreSQL shell:'),
+              )
               console.log(chalk.cyan('  spindb connect --install-pgcli'))
               console.log()
               console.log(chalk.gray('Or install manually:'))
@@ -218,7 +232,9 @@ export const connectCommand = new Command('connect')
         if (useMycli) {
           if (engineName !== 'mysql') {
             console.error(error('mycli is only available for MySQL containers'))
-            console.log(chalk.gray('For PostgreSQL, use: spindb connect --pgcli'))
+            console.log(
+              chalk.gray('For PostgreSQL, use: spindb connect --pgcli'),
+            )
             process.exit(1)
           }
 
@@ -234,7 +250,9 @@ export const connectCommand = new Command('connect')
                   console.log(success('mycli installed successfully!'))
                   console.log()
                 } else {
-                  console.error(error(`Failed to install mycli: ${result.error}`))
+                  console.error(
+                    error(`Failed to install mycli: ${result.error}`),
+                  )
                   console.log()
                   console.log(chalk.gray('Manual installation:'))
                   for (const instruction of getMycliManualInstructions()) {
@@ -327,7 +345,9 @@ export const connectCommand = new Command('connect')
 
             if (clientCmd === 'usql') {
               console.log(chalk.gray('  Install usql:'))
-              console.log(chalk.cyan('  brew tap xo/xo && brew install xo/xo/usql'))
+              console.log(
+                chalk.cyan('  brew tap xo/xo && brew install xo/xo/usql'),
+              )
             } else if (clientCmd === 'pgcli') {
               console.log(chalk.gray('  Install pgcli:'))
               console.log(chalk.cyan('  brew install pgcli'))

package/cli/commands/create.ts

@@ -20,7 +20,7 @@ import { getMissingDependencies } from '../../core/dependency-manager'
 import { platformService } from '../../core/platform-service'
 import { startWithRetry } from '../../core/start-with-retry'
 import { TransactionManager } from '../../core/transaction-manager'
-import type { EngineName } from '../../types'
+import { Engine } from '../../types'
 
 /**
  * Detect if a location string is a connection string or a file path
@@ -28,19 +28,19 @@ import type { EngineName } from '../../types'
  */
 function detectLocationType(location: string): {
   type: 'connection' | 'file' | 'not_found'
-  inferredEngine?: EngineName
+  inferredEngine?: Engine
 } {
   // Check for PostgreSQL connection string
   if (
     location.startsWith('postgresql://') ||
     location.startsWith('postgres://')
   ) {
-    return { type: 'connection', inferredEngine: 'postgresql' }
+    return { type: 'connection', inferredEngine: Engine.PostgreSQL }
   }
 
   // Check for MySQL connection string
   if (location.startsWith('mysql://')) {
-    return { type: 'connection', inferredEngine: 'mysql' }
+    return { type: 'connection', inferredEngine: Engine.MySQL }
   }
 
   // Check if file exists
@@ -79,7 +79,7 @@ export const createCommand = new Command('create')
 
       try {
         let containerName = name
-        let engine: EngineName = (options.engine as EngineName) || 'postgresql'
+        let engine: Engine = (options.engine as Engine) || Engine.PostgreSQL
         let version = options.version
         let database = options.database
 
@@ -136,7 +136,7 @@ export const createCommand = new Command('create')
         if (!containerName) {
           const answers = await promptCreateOptions()
           containerName = answers.name
-          engine = answers.engine as EngineName
+          engine = answers.engine as Engine
           version = answers.version
           database = answers.database
         }
@@ -254,7 +254,7 @@ export const createCommand = new Command('create')
 
         try {
           await containerManager.create(containerName, {
-            engine: dbEngine.name as EngineName,
+            engine: dbEngine.name as Engine,
             version,
             port,
             database,

package/cli/commands/list.ts

@@ -85,8 +85,7 @@ export const listCommand = new Command('list')
         const engineDisplay = `${engineIcon} ${container.engine}`
 
         // Format size: show value if running, dash if stopped
-        const sizeDisplay =
-          size !== null ? formatBytes(size) : chalk.gray('—')
+        const sizeDisplay = size !== null ? formatBytes(size) : chalk.gray('—')
 
         console.log(
           chalk.gray('  ') +

package/cli/commands/menu.ts

@@ -35,7 +35,7 @@ import { platformService } from '../../core/platform-service'
 import { portManager } from '../../core/port-manager'
 import { defaults } from '../../config/defaults'
 import { getPostgresHomebrewPackage } from '../../config/engine-defaults'
-import type { EngineName } from '../../types'
+import { Engine } from '../../types'
 import inquirer from 'inquirer'
 import {
   getMissingDependencies,
@@ -56,6 +56,7 @@ import {
   isMariaDB,
   getMysqlInstallInfo,
 } from '../../engines/mysql/binary-detection'
+import { updateManager } from '../../core/update-manager'
 
 type MenuChoice =
   | {
@@ -167,6 +168,7 @@ async function showMainMenu(): Promise<void> {
       disabled: hasEngines ? false : 'No engines installed',
     },
     new inquirer.Separator(),
+    { name: `${chalk.cyan('↑')} Check for updates`, value: 'check-update' },
     { name: `${chalk.gray('⏻')} Exit`, value: 'exit' },
   ]
 
@@ -205,6 +207,9 @@ async function showMainMenu(): Promise<void> {
     case 'engines':
       await handleEngines()
       break
+    case 'check-update':
+      await handleCheckUpdate()
+      break
     case 'exit':
       console.log(chalk.gray('\n  Goodbye!\n'))
       process.exit(0)
@@ -214,6 +219,94 @@ async function showMainMenu(): Promise<void> {
   await showMainMenu()
 }
 
+async function handleCheckUpdate(): Promise<void> {
+  console.clear()
+  console.log(header('Check for Updates'))
+  console.log()
+
+  const spinner = createSpinner('Checking for updates...')
+  spinner.start()
+
+  const result = await updateManager.checkForUpdate(true)
+
+  if (!result) {
+    spinner.fail('Could not reach npm registry')
+    console.log()
+    console.log(info('Check your internet connection and try again.'))
+    console.log(chalk.gray('  Manual update: npm install -g spindb@latest'))
+    console.log()
+    await pressEnterToContinue()
+    return
+  }
+
+  if (result.updateAvailable) {
+    spinner.succeed('Update available')
+    console.log()
+    console.log(chalk.gray(`  Current version: ${result.currentVersion}`))
+    console.log(
+      chalk.gray(`  Latest version:  ${chalk.green(result.latestVersion)}`),
+    )
+    console.log()
+
+    const { action } = await inquirer.prompt<{ action: string }>([
+      {
+        type: 'list',
+        name: 'action',
+        message: 'What would you like to do?',
+        choices: [
+          { name: 'Update now', value: 'update' },
+          { name: 'Remind me later', value: 'later' },
+          { name: "Don't check for updates on startup", value: 'disable' },
+        ],
+      },
+    ])
+
+    if (action === 'update') {
+      console.log()
+      const updateSpinner = createSpinner('Updating spindb...')
+      updateSpinner.start()
+
+      const updateResult = await updateManager.performUpdate()
+
+      if (updateResult.success) {
+        updateSpinner.succeed('Update complete')
+        console.log()
+        console.log(
+          success(
+            `Updated from ${updateResult.previousVersion} to ${updateResult.newVersion}`,
+          ),
+        )
+        console.log()
+        if (updateResult.previousVersion !== updateResult.newVersion) {
+          console.log(warning('Please restart spindb to use the new version.'))
+          console.log()
+        }
+      } else {
+        updateSpinner.fail('Update failed')
+        console.log()
+        console.log(error(updateResult.error || 'Unknown error'))
+        console.log()
+        console.log(info('Manual update: npm install -g spindb@latest'))
+      }
+      await pressEnterToContinue()
+    } else if (action === 'disable') {
+      await updateManager.setAutoCheckEnabled(false)
+      console.log()
+      console.log(info('Update checks disabled on startup.'))
+      console.log(chalk.gray('  Re-enable with: spindb config update-check on'))
+      console.log()
+      await pressEnterToContinue()
+    }
+    // 'later' just returns to menu
+  } else {
+    spinner.succeed('You are on the latest version')
+    console.log()
+    console.log(chalk.gray(`  Version: ${result.currentVersion}`))
+    console.log()
+    await pressEnterToContinue()
+  }
+}
+
 async function handleCreate(): Promise<void> {
   console.log()
   const answers = await promptCreateOptions()
@@ -294,7 +387,7 @@ async function handleCreate(): Promise<void> {
   createSpinnerInstance.start()
 
   await containerManager.create(containerName, {
-    engine: dbEngine.name as EngineName,
+    engine: dbEngine.name as Engine,
     version,
     port,
     database,
@@ -1063,7 +1156,7 @@ async function handleCreateForRestore(): Promise<{
   createSpinnerInstance.start()
 
   await containerManager.create(containerName, {
-    engine: dbEngine.name as EngineName,
+    engine: dbEngine.name as Engine,
     version,
     port,
     database,
@@ -1630,7 +1723,9 @@ async function handleBackup(): Promise<void> {
     missingDeps = await getMissingDependencies(config.engine)
     if (missingDeps.length > 0) {
       console.log(
-        error(`Still missing tools: ${missingDeps.map((d) => d.name).join(', ')}`),
+        error(
+          `Still missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
+        ),
       )
       return
     }
@@ -1646,7 +1741,10 @@ async function handleBackup(): Promise<void> {
   let databaseName: string
 
   if (databases.length > 1) {
-    databaseName = await promptDatabaseSelect(databases, 'Select database to backup:')
+    databaseName = await promptDatabaseSelect(
+      databases,
+      'Select database to backup:',
+    )
   } else {
     databaseName = databases[0]
   }

package/cli/commands/self-update.ts

@@ -0,0 +1,109 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import inquirer from 'inquirer'
+import { updateManager } from '../../core/update-manager'
+import { createSpinner } from '../ui/spinner'
+import { success, error, info, header } from '../ui/theme'
+
+export const selfUpdateCommand = new Command('self-update')
+  .alias('update')
+  .description('Update spindb to the latest version')
+  .option('-f, --force', 'Update even if already on latest version')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .action(
+    async (options: { force?: boolean; yes?: boolean }): Promise<void> => {
+      console.log()
+      console.log(header('SpinDB Self-Update'))
+      console.log()
+
+      const checkSpinner = createSpinner('Checking for updates...')
+      checkSpinner.start()
+
+      const result = await updateManager.checkForUpdate(true)
+
+      if (!result) {
+        checkSpinner.fail('Could not reach npm registry')
+        console.log()
+        console.log(info('Check your internet connection and try again.'))
+        console.log(chalk.gray('  Manual update: npm install -g spindb@latest'))
+        process.exit(1)
+      }
+
+      if (!result.updateAvailable && !options.force) {
+        checkSpinner.succeed('Already on latest version')
+        console.log()
+        console.log(chalk.gray(`  Current version: ${result.currentVersion}`))
+        console.log(chalk.gray(`  Latest version:  ${result.latestVersion}`))
+        console.log()
+        return
+      }
+
+      if (result.updateAvailable) {
+        checkSpinner.succeed('Update available')
+      } else {
+        checkSpinner.succeed('Version check complete')
+      }
+
+      console.log()
+      console.log(chalk.gray(`  Current version: ${result.currentVersion}`))
+      console.log(
+        chalk.gray(
+          `  Latest version:  ${result.updateAvailable ? chalk.green(result.latestVersion) : result.latestVersion}`,
+        ),
+      )
+      console.log()
+
+      // Confirm unless --yes
+      if (!options.yes) {
+        const message = result.updateAvailable
+          ? `Update spindb from ${result.currentVersion} to ${result.latestVersion}?`
+          : `Reinstall spindb ${result.currentVersion}?`
+
+        const { confirm } = await inquirer.prompt<{ confirm: boolean }>([
+          {
+            type: 'confirm',
+            name: 'confirm',
+            message,
+            default: true,
+          },
+        ])
+
+        if (!confirm) {
+          console.log(chalk.yellow('Update cancelled'))
+          return
+        }
+      }
+
+      console.log()
+      const updateSpinner = createSpinner('Updating spindb...')
+      updateSpinner.start()
+
+      const updateResult = await updateManager.performUpdate()
+
+      if (updateResult.success) {
+        updateSpinner.succeed('Update complete')
+        console.log()
+        console.log(
+          success(
+            `Updated from ${updateResult.previousVersion} to ${updateResult.newVersion}`,
+          ),
+        )
+        console.log()
+        if (updateResult.previousVersion !== updateResult.newVersion) {
+          console.log(
+            chalk.gray(
+              '  Please restart your terminal to use the new version.',
+            ),
+          )
+          console.log()
+        }
+      } else {
+        updateSpinner.fail('Update failed')
+        console.log()
+        console.log(error(updateResult.error || 'Unknown error'))
+        console.log()
+        console.log(info('Manual update: npm install -g spindb@latest'))
+        process.exit(1)
+      }
+    },
+  )

package/cli/commands/version.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { updateManager } from '../../core/update-manager'
+import { createSpinner } from '../ui/spinner'
+
+export const versionCommand = new Command('version')
+  .description('Show version information and check for updates')
+  .option('-c, --check', 'Check for available updates')
+  .option('-j, --json', 'Output as JSON')
+  .action(
+    async (options: { check?: boolean; json?: boolean }): Promise<void> => {
+      const currentVersion = updateManager.getCurrentVersion()
+
+      if (options.check) {
+        const spinner = createSpinner('Checking for updates...')
+        if (!options.json) spinner.start()
+
+        const result = await updateManager.checkForUpdate(true)
+
+        if (!options.json) spinner.stop()
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              current: currentVersion,
+              latest: result?.latestVersion || null,
+              updateAvailable: result?.updateAvailable || false,
+            }),
+          )
+        } else {
+          console.log()
+          console.log(`SpinDB v${currentVersion}`)
+          if (result) {
+            if (result.updateAvailable) {
+              console.log(
+                chalk.yellow(`Update available: v${result.latestVersion}`),
+              )
+              console.log(chalk.gray("Run 'spindb self-update' to update."))
+            } else {
+              console.log(chalk.green('You are on the latest version.'))
+            }
+          } else {
+            console.log(chalk.gray('Could not check for updates (offline?)'))
+          }
+          console.log()
+        }
+      } else {
+        if (options.json) {
+          console.log(JSON.stringify({ current: currentVersion }))
+        } else {
+          console.log(`SpinDB v${currentVersion}`)
+        }
+      }
+    },
+  )

package/cli/index.ts

@@ -1,5 +1,10 @@
 import { program } from 'commander'
+import { createRequire } from 'module'
+import chalk from 'chalk'
 import { createCommand } from './commands/create'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json') as { version: string }
 import { listCommand } from './commands/list'
 import { startCommand } from './commands/start'
 import { stopCommand } from './commands/stop'
@@ -15,12 +20,86 @@ import { enginesCommand } from './commands/engines'
 import { editCommand } from './commands/edit'
 import { urlCommand } from './commands/url'
 import { infoCommand } from './commands/info'
+import { selfUpdateCommand } from './commands/self-update'
+import { versionCommand } from './commands/version'
+import { updateManager } from '../core/update-manager'
+
+/**
+ * Show update notification banner if an update is available (from cached data)
+ * This shows on every run until the user updates or disables checks
+ */
+async function showUpdateNotificationIfAvailable(): Promise<void> {
+  try {
+    const cached = await updateManager.getCachedUpdateInfo()
+
+    // Skip if auto-check is disabled or no cached version
+    if (!cached.autoCheckEnabled || !cached.latestVersion) return
+
+    const currentVersion = updateManager.getCurrentVersion()
+    const latestVersion = cached.latestVersion
+
+    // Skip if no update available
+    if (updateManager.compareVersions(latestVersion, currentVersion) <= 0)
+      return
+
+    // Show notification banner
+    console.log()
+    console.log(chalk.cyan('┌' + '─'.repeat(52) + '┐'))
+    console.log(
+      chalk.cyan('│') +
+        chalk.yellow(' Update available! ') +
+        chalk.gray(`${currentVersion} -> `) +
+        chalk.green(latestVersion) +
+        ' '.repeat(
+          Math.max(
+            0,
+            52 - 21 - currentVersion.length - 4 - latestVersion.length,
+          ),
+        ) +
+        chalk.cyan('│'),
+    )
+    console.log(
+      chalk.cyan('│') +
+        chalk.gray(' Run: ') +
+        chalk.cyan('spindb self-update') +
+        ' '.repeat(28) +
+        chalk.cyan('│'),
+    )
+    console.log(
+      chalk.cyan('│') +
+        chalk.gray(' To disable: ') +
+        chalk.gray('spindb config update-check off') +
+        ' '.repeat(8) +
+        chalk.cyan('│'),
+    )
+    console.log(chalk.cyan('└' + '─'.repeat(52) + '┘'))
+    console.log()
+  } catch {
+    // Silently ignore errors - update notification is not critical
+  }
+}
+
+/**
+ * Trigger background update check (fire and forget)
+ * This updates the cache for the next run's notification
+ */
+function triggerBackgroundUpdateCheck(): void {
+  updateManager.checkForUpdate(false).catch(() => {
+    // Silently ignore - background check is best-effort
+  })
+}
 
 export async function run(): Promise<void> {
+  // Trigger background update check (non-blocking, updates cache for next run)
+  triggerBackgroundUpdateCheck()
+
+  // Show update notification if an update is available (from cached data)
+  await showUpdateNotificationIfAvailable()
+
   program
     .name('spindb')
     .description('Spin up local database containers without Docker')
-    .version('0.1.0', '-v, --version', 'output the version number')
+    .version(pkg.version, '-v, --version', 'output the version number')
 
   program.addCommand(createCommand)
   program.addCommand(listCommand)
@@ -38,6 +117,8 @@ export async function run(): Promise<void> {
   program.addCommand(editCommand)
   program.addCommand(urlCommand)
   program.addCommand(infoCommand)
+  program.addCommand(selfUpdateCommand)
+  program.addCommand(versionCommand)
 
   // If no arguments provided, show interactive menu
   if (process.argv.length <= 2) {

package/cli/ui/prompts.ts

@@ -251,7 +251,8 @@ export async function promptDatabaseName(
   engine?: string,
 ): Promise<string> {
   // MySQL uses "schema" terminology (database and schema are synonymous)
-  const label = engine === 'mysql' ? 'Database (schema) name:' : 'Database name:'
+  const label =
+    engine === 'mysql' ? 'Database (schema) name:' : 'Database name:'
 
   const { database } = await inquirer.prompt<{ database: string }>([
     {

package/config/defaults.ts

@@ -5,6 +5,7 @@ import {
   getSupportedEngines,
   type EngineDefaults,
 } from './engine-defaults'
+import { Engine } from '../types'
 
 // Re-export engine-related functions and types
 export {
@@ -24,50 +25,25 @@ export type PortRange = {
   end: number
 }
 
-/**
- * Legacy Defaults type - kept for backward compatibility
- * New code should use getEngineDefaults(engine) instead
- */
 export type Defaults = {
-  /** @deprecated Use getEngineDefaults(engine).defaultVersion instead */
-  postgresVersion: string
   port: number
   portRange: PortRange
-  engine: string
-  /** @deprecated Use getEngineDefaults(engine).supportedVersions instead */
-  supportedPostgresVersions: string[]
+  engine: Engine
   superuser: string
   platformMappings: PlatformMappings
 }
 
-// Get PostgreSQL defaults from engine-defaults
 const pgDefaults = engineDefaults.postgresql
 
 /**
- * Default configuration values
- * For backward compatibility, this defaults to PostgreSQL settings.
- * New code should use getEngineDefaults(engine) for engine-specific defaults.
+ * Default configuration values (PostgreSQL-based defaults)
+ * Use getEngineDefaults(engine) for engine-specific defaults.
  */
 export const defaults: Defaults = {
-  // Default PostgreSQL version (from engine defaults)
-  postgresVersion: pgDefaults.defaultVersion,
-
-  // Default port (standard PostgreSQL port)
   port: pgDefaults.defaultPort,
-
-  // Port range to scan if default is busy
   portRange: pgDefaults.portRange,
-
-  // Default engine
-  engine: 'postgresql',
-
-  // Supported PostgreSQL versions (from engine defaults)
-  supportedPostgresVersions: pgDefaults.supportedVersions,
-
-  // Default superuser (from engine defaults)
+  engine: Engine.PostgreSQL,
   superuser: pgDefaults.superuser,
-
-  // Platform mappings for zonky.io binaries (PostgreSQL specific)
   platformMappings: {
     'darwin-arm64': 'darwin-arm64v8',
     'darwin-x64': 'darwin-amd64',

package/core/binary-manager.ts

@@ -6,7 +6,7 @@ import { exec } from 'child_process'
 import { promisify } from 'util'
 import { paths } from '../config/paths'
 import { defaults } from '../config/defaults'
-import type { ProgressCallback, InstalledBinary } from '../types'
+import { Engine, type ProgressCallback, type InstalledBinary } from '../types'
 
 const execAsync = promisify(exec)
 
@@ -91,7 +91,7 @@ export class BinaryManager {
         const parts = entry.name.split('-')
         if (parts.length >= 4) {
           installed.push({
-            engine: parts[0],
+            engine: parts[0] as Engine,
             version: parts[1],
             platform: parts[2],
             arch: parts[3],

package/core/config-manager.ts

@@ -29,12 +29,7 @@ const POSTGRESQL_TOOLS: BinaryTool[] = [
   'pg_basebackup',
 ]
 
-const MYSQL_TOOLS: BinaryTool[] = [
-  'mysql',
-  'mysqldump',
-  'mysqladmin',
-  'mysqld',
-]
+const MYSQL_TOOLS: BinaryTool[] = ['mysql', 'mysqldump', 'mysqladmin', 'mysqld']
 
 const ENHANCED_SHELLS: BinaryTool[] = ['pgcli', 'mycli', 'usql']
 
@@ -359,9 +354,4 @@ export class ConfigManager {
 export const configManager = new ConfigManager()
 
 // Export tool categories for use in commands
-export {
-  POSTGRESQL_TOOLS,
-  MYSQL_TOOLS,
-  ENHANCED_SHELLS,
-  ALL_TOOLS,
-}
+export { POSTGRESQL_TOOLS, MYSQL_TOOLS, ENHANCED_SHELLS, ALL_TOOLS }

package/core/container-manager.ts

@@ -5,10 +5,11 @@ import { processManager } from './process-manager'
 import { portManager } from './port-manager'
 import { getEngineDefaults, getSupportedEngines } from '../config/defaults'
 import { getEngine } from '../engines'
-import type { ContainerConfig, EngineName } from '../types'
+import type { ContainerConfig } from '../types'
+import { Engine } from '../types'
 
 export type CreateOptions = {
-  engine: EngineName
+  engine: Engine
   version: string
   port: number
   database: string
@@ -398,7 +399,9 @@ export class ContainerManager {
 
     // Don't remove the primary database from the array
     if (database === config.database) {
-      throw new Error(`Cannot remove primary database "${database}" from tracking`)
+      throw new Error(
+        `Cannot remove primary database "${database}" from tracking`,
+      )
     }
 
     if (config.databases) {

package/core/update-manager.ts

@@ -0,0 +1,194 @@
+import { exec } from 'child_process'
+import { promisify } from 'util'
+import { createRequire } from 'module'
+import { configManager } from './config-manager'
+
+const execAsync = promisify(exec)
+const require = createRequire(import.meta.url)
+
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/spindb'
+const CHECK_THROTTLE_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+export type UpdateCheckResult = {
+  currentVersion: string
+  latestVersion: string
+  updateAvailable: boolean
+  lastChecked: string
+}
+
+export type UpdateResult = {
+  success: boolean
+  previousVersion: string
+  newVersion: string
+  error?: string
+}
+
+export class UpdateManager {
+  /**
+   * Get currently installed version from package.json
+   */
+  getCurrentVersion(): string {
+    const pkg = require('../package.json') as { version: string }
+    return pkg.version
+  }
+
+  /**
+   * Check npm registry for latest version
+   * Throttled to once per 24 hours unless force=true
+   */
+  async checkForUpdate(force = false): Promise<UpdateCheckResult | null> {
+    const config = await configManager.load()
+    const lastCheck = config.update?.lastCheck
+
+    // Return cached result if within throttle period
+    if (!force && lastCheck) {
+      const elapsed = Date.now() - new Date(lastCheck).getTime()
+      if (elapsed < CHECK_THROTTLE_MS && config.update?.latestVersion) {
+        const currentVersion = this.getCurrentVersion()
+        return {
+          currentVersion,
+          latestVersion: config.update.latestVersion,
+          updateAvailable:
+            this.compareVersions(config.update.latestVersion, currentVersion) >
+            0,
+          lastChecked: lastCheck,
+        }
+      }
+    }
+
+    try {
+      const latestVersion = await this.fetchLatestVersion()
+      const currentVersion = this.getCurrentVersion()
+
+      // Update cache
+      config.update = {
+        ...config.update,
+        lastCheck: new Date().toISOString(),
+        latestVersion,
+      }
+      await configManager.save()
+
+      return {
+        currentVersion,
+        latestVersion,
+        updateAvailable:
+          this.compareVersions(latestVersion, currentVersion) > 0,
+        lastChecked: new Date().toISOString(),
+      }
+    } catch {
+      // Offline or registry error - return null
+      return null
+    }
+  }
+
+  /**
+   * Perform self-update via npm
+   */
+  async performUpdate(): Promise<UpdateResult> {
+    const previousVersion = this.getCurrentVersion()
+
+    try {
+      // Execute npm install globally
+      await execAsync('npm install -g spindb@latest', { timeout: 60000 })
+
+      // Verify new version by checking what npm reports
+      const { stdout } = await execAsync('npm list -g spindb --json')
+      const npmData = JSON.parse(stdout) as {
+        dependencies?: { spindb?: { version?: string } }
+      }
+      const newVersion =
+        npmData.dependencies?.spindb?.version || previousVersion
+
+      return {
+        success: true,
+        previousVersion,
+        newVersion,
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+
+      // Detect permission issues
+      if (message.includes('EACCES') || message.includes('permission')) {
+        return {
+          success: false,
+          previousVersion,
+          newVersion: previousVersion,
+          error: 'Permission denied. Try: sudo npm install -g spindb@latest',
+        }
+      }
+
+      return {
+        success: false,
+        previousVersion,
+        newVersion: previousVersion,
+        error: message,
+      }
+    }
+  }
+
+  /**
+   * Get cached update info (for showing notification without network call)
+   */
+  async getCachedUpdateInfo(): Promise<{
+    latestVersion?: string
+    autoCheckEnabled: boolean
+  }> {
+    const config = await configManager.load()
+    return {
+      latestVersion: config.update?.latestVersion,
+      autoCheckEnabled: config.update?.autoCheckEnabled !== false,
+    }
+  }
+
+  /**
+   * Set whether auto-update checks are enabled
+   */
+  async setAutoCheckEnabled(enabled: boolean): Promise<void> {
+    const config = await configManager.load()
+    config.update = {
+      ...config.update,
+      autoCheckEnabled: enabled,
+    }
+    await configManager.save()
+  }
+
+  /**
+   * Fetch latest version from npm registry
+   */
+  private async fetchLatestVersion(): Promise<string> {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 10000)
+
+    try {
+      const response = await fetch(NPM_REGISTRY_URL, {
+        signal: controller.signal,
+      })
+      if (!response.ok) {
+        throw new Error(`Registry returned ${response.status}`)
+      }
+      const data = (await response.json()) as {
+        'dist-tags': { latest: string }
+      }
+      return data['dist-tags'].latest
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  /**
+   * Compare semver versions
+   * Returns >0 if a > b, <0 if a < b, 0 if equal
+   */
+  compareVersions(a: string, b: string): number {
+    const partsA = a.split('.').map((n) => parseInt(n, 10) || 0)
+    const partsB = b.split('.').map((n) => parseInt(n, 10) || 0)
+
+    for (let i = 0; i < 3; i++) {
+      const diff = (partsA[i] || 0) - (partsB[i] || 0)
+      if (diff !== 0) return diff
+    }
+    return 0
+  }
+}
+
+export const updateManager = new UpdateManager()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.5.5",
+  "version": "0.7.0",
   "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL and MySQL.",
   "type": "module",
   "bin": {

package/types/index.ts

@@ -1,6 +1,6 @@
 export type ContainerConfig = {
   name: string
-  engine: EngineName
+  engine: Engine
   version: string
   port: number
   database: string
@@ -14,7 +14,10 @@ export type ContainerConfig = {
  * Supported database engine names
  * Extendable for future engines (sqlite, etc.)
  */
-export type EngineName = 'postgresql' | 'mysql'
+export enum Engine {
+  PostgreSQL = 'postgresql',
+  MySQL = 'mysql',
+}
 
 export type ProgressCallback = (progress: {
   stage: string
@@ -22,7 +25,7 @@ export type ProgressCallback = (progress: {
 }) => void
 
 export type InstalledBinary = {
-  engine: string
+  engine: Engine
   version: string
   platform: string
   arch: string
@@ -141,10 +144,16 @@ export type SpinDBConfig = {
   }
   // Default settings
   defaults?: {
-    engine?: EngineName
+    engine?: Engine
     version?: string
     port?: number
   }
   // Last updated timestamp
   updatedAt?: string
+  // Self-update tracking
+  update?: {
+    lastCheck?: string // ISO timestamp of last npm registry check
+    latestVersion?: string // Latest version found from registry
+    autoCheckEnabled?: boolean // Default true, user can disable
+  }
 }