sqlite-hub 0.12.0 → 0.17.0

package/bin/sqlite-hub.js

@@ -1,26 +1,56 @@
 #!/usr/bin/env node
 
+const fs = require('node:fs');
+const path = require('node:path');
 const { spawn } = require('node:child_process');
 
 const DEFAULT_PORT = 4173;
+const EXPORT_FORMATS = new Set(['csv', 'tsv', 'md']);
 
 function printHelp() {
     console.log(`SQLite Hub CLI
 
 Usage:
   sqlite-hub [--port:4173]
+  sqlite-hub --database
+  sqlite-hub --database:"name" --tables
+  sqlite-hub --database:"name" --execute:"Saved Query"
+  sqlite-hub --database:"name" --query:"Saved Query"
+  sqlite-hub --database:"name" --notes:"Saved Query"
+  sqlite-hub --database:"name" --export:"Saved Query" --format:csv
+  sqlite-hub --database:"name" --documents
+  sqlite-hub --database:"name" --documents:"Document Name"
+  sqlite-hub --database:"name" --documents:"Document Name" --export
+  sqlite-hub --database:"name" --table:"table_name"
+  sqlite-hub --database:"name" --table:"table_name" --export:"primary-key"
 
 Options:
-  --help                      Show this help text.
-  --port:PORT                 Start the server on a custom port.
-  --version                   Show the version number.
-  --database                  List all imported databases.
-  --database-path:name        Get the file path of a database by name.
-  --database-size:name        Get the size of a database by name.
-  --database-lastopened:name  Get the last opened timestamp of a database by name.
-  --database-tables:name      Get all table names from a database.
-  --database:name --sqleditor List all saved queries for a database.
-  --database:name --sqleditor:"query"  Execute a saved query by name.
+  --help, -h                         Show this help text.
+  --version, -v                      Show the version number.
+  --config                           Show CLI port, URL, app version, and SQLite version.
+  --open                             Start/open SQLite Hub in the browser.
+  --port:PORT                        Start the server on a custom port.
+  --database, -d                     List all imported databases.
+  --database:"name"                  Select an imported database by name or id.
+  --path                             Print the selected database file path.
+  --size                             Print the selected database file size.
+  --lastopened                       Print the selected database last-opened timestamp.
+  --tables                           List tables in the selected database.
+  --queries                          List saved SQL Editor queries for the selected database.
+  --execute:"query"                  Execute a saved SQL Editor query by name.
+  --query:"query"                    Print a saved SQL Editor query by name.
+  --notes:"query"                    Print notes for a saved SQL Editor query by name.
+  --export:"query"                   Export a saved query when --table is not set.
+  --format:csv|tsv|md                Export format for query exports. Defaults to csv.
+  --documents                        List Markdown documents for the selected database.
+  --documents:"name"                 Print a document's Markdown content.
+  --documents:"name" --export        Export a document as a Markdown file.
+  --table:"table"                    Print table metadata.
+  --table:"table" --export:"pk"      Export one row as JSON by primary key or rowid.
+
+Legacy aliases still work:
+  --database-path:name, --database-size:name, --database-lastopened:name
+  --database-tables:name, --database:name --sqleditor, --database:name --sqleditor:"query"
 `);
 }
 
@@ -34,76 +64,330 @@ function parsePort(rawValue) {
     return port;
 }
 
+function splitArgument(argument) {
+    const colonIndex = argument.indexOf(':');
+    const equalsIndex = argument.indexOf('=');
+    const separators = [colonIndex, equalsIndex].filter(index => index > -1);
+
+    if (separators.length === 0) {
+        return {
+            flag: normalizeFlagName(argument),
+            value: undefined,
+        };
+    }
+
+    const separatorIndex = Math.min(...separators);
+
+    return {
+        flag: normalizeFlagName(argument.slice(0, separatorIndex)),
+        value: argument.slice(separatorIndex + 1),
+    };
+}
+
+function normalizeFlagName(flag) {
+    if (flag === '---path') {
+        return '--path';
+    }
+
+    return flag;
+}
+
+function takeFlagValue(flag, inlineValue, argv, index) {
+    if (inlineValue !== undefined) {
+        return {
+            value: inlineValue,
+            nextIndex: index,
+        };
+    }
+
+    const nextValue = argv[index + 1];
+
+    if (nextValue === undefined || nextValue.startsWith('--')) {
+        throw new Error(`${flag} requires a value.`);
+    }
+
+    return {
+        value: nextValue,
+        nextIndex: index + 1,
+    };
+}
+
+function takeOptionalFlagValue(inlineValue, argv, index) {
+    if (inlineValue !== undefined) {
+        return {
+            hasValue: true,
+            value: inlineValue,
+            nextIndex: index,
+        };
+    }
+
+    const nextValue = argv[index + 1];
+
+    if (nextValue === undefined || nextValue.startsWith('--')) {
+        return {
+            hasValue: false,
+            value: null,
+            nextIndex: index,
+        };
+    }
+
+    return {
+        hasValue: true,
+        value: nextValue,
+        nextIndex: index + 1,
+    };
+}
+
+function normalizeExportFormat(format) {
+    const normalized = String(format ?? 'csv').toLowerCase();
+
+    if (!EXPORT_FORMATS.has(normalized)) {
+        throw new Error(`Unsupported export format: ${format}. Use csv, tsv, or md.`);
+    }
+
+    return normalized;
+}
+
 function parseCliArguments(argv) {
-    let port;
-    let databaseName = null;
+    const options = {
+        help: false,
+        version: false,
+        config: false,
+        open: false,
+        port: undefined,
+        databaseList: false,
+        databaseName: null,
+        pathInfo: false,
+        sizeInfo: false,
+        lastOpenedInfo: false,
+        tables: false,
+        queries: false,
+        executeQuery: null,
+        showQuery: null,
+        showNotes: null,
+        exportTarget: null,
+        exportFormat: 'csv',
+        documents: false,
+        documentName: null,
+        documentExport: false,
+        tableName: null,
+    };
 
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
+        const { flag, value } = splitArgument(argument);
 
-        if (argument === '--help' || argument === '-h') {
-            return { help: true };
+        if (flag === '--help' || flag === '-h') {
+            options.help = true;
+            continue;
         }
 
-        if (argument === '--database' || argument === '-d') {
-            return { database: true };
+        if (flag === '--version' || flag === '-v') {
+            options.version = true;
+            continue;
         }
 
-        if (argument.startsWith('--database:')) {
-            databaseName = argument.slice('--database:'.length);
+        if (flag === '--config') {
+            options.config = true;
             continue;
         }
 
-        if (argument.startsWith('--database-path:')) {
-            return { databasePath: argument.slice('--database-path:'.length) };
+        if (flag === '--open') {
+            options.open = true;
+            continue;
         }
 
-        if (argument.startsWith('--database-size:')) {
-            return { databaseSize: argument.slice('--database-size:'.length) };
+        if (flag === '--port') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.port = parsePort(parsed.value);
+            index = parsed.nextIndex;
+            continue;
         }
 
-        if (argument.startsWith('--database-lastopened:')) {
-            return { databaseLastOpened: argument.slice('--database-lastopened:'.length) };
+        if (flag === '--database' || flag === '-d') {
+            const parsed = takeOptionalFlagValue(value, argv, index);
+
+            if (parsed.hasValue) {
+                options.databaseName = parsed.value;
+            } else {
+                options.databaseList = true;
+            }
+
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--database-path') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.databaseName = parsed.value;
+            options.pathInfo = true;
+            index = parsed.nextIndex;
+            continue;
         }
 
-        if (argument.startsWith('--database-tables:')) {
-            return { databaseTables: argument.slice('--database-tables:'.length) };
+        if (flag === '--database-size') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.databaseName = parsed.value;
+            options.sizeInfo = true;
+            index = parsed.nextIndex;
+            continue;
         }
 
-        if (argument === '--sqleditor') {
-            return { sqlEditor: true, databaseName };
+        if (flag === '--database-lastopened') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.databaseName = parsed.value;
+            options.lastOpenedInfo = true;
+            index = parsed.nextIndex;
+            continue;
         }
 
-        if (argument.startsWith('--sqleditor:')) {
-            return { sqlEditorQuery: argument.slice('--sqleditor:'.length), databaseName };
+        if (flag === '--database-tables') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.databaseName = parsed.value;
+            options.tables = true;
+            index = parsed.nextIndex;
+            continue;
         }
 
-        if (argument.startsWith('--port:')) {
-            port = parsePort(argument.slice('--port:'.length));
+        if (flag === '--path') {
+            options.pathInfo = true;
             continue;
         }
 
-        if (argument.startsWith('--port=')) {
-            port = parsePort(argument.slice('--port='.length));
+        if (flag === '--size') {
+            options.sizeInfo = true;
             continue;
         }
 
-        if (argument === '--port') {
-            port = parsePort(argv[index + 1]);
-            index += 1;
+        if (flag === '--lastopened') {
+            options.lastOpenedInfo = true;
             continue;
         }
 
-        if (argument === '--version' || argument === '-v') {
-            const { version } = require('../package.json');
-            console.log(`SQLite Hub CLI version ${version}`);
-            process.exit(0);
+        if (flag === '--tables') {
+            options.tables = true;
+            continue;
+        }
+
+        if (flag === '--queries') {
+            options.queries = true;
+            continue;
+        }
+
+        if (flag === '--sqleditor') {
+            const parsed = takeOptionalFlagValue(value, argv, index);
+
+            if (parsed.hasValue) {
+                options.executeQuery = parsed.value;
+            } else {
+                options.queries = true;
+            }
+
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--execute') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.executeQuery = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--query') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.showQuery = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--notes') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.showNotes = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--documents') {
+            const parsed = takeOptionalFlagValue(value, argv, index);
+
+            options.documents = true;
+            if (parsed.hasValue) {
+                const rawDocumentName = String(parsed.value ?? '');
+
+                if (rawDocumentName.endsWith('--export')) {
+                    options.documentName = rawDocumentName.slice(0, -'--export'.length);
+                    options.documentExport = true;
+                } else {
+                    options.documentName = rawDocumentName;
+                }
+            }
+
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--documents-export') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.documents = true;
+            options.documentName = parsed.value;
+            options.documentExport = true;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--export') {
+            if (options.documents && options.documentName && value === undefined) {
+                const nextValue = argv[index + 1];
+
+                if (nextValue === undefined || nextValue.startsWith('--')) {
+                    options.documentExport = true;
+                    continue;
+                }
+            }
+
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.exportTarget = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--format') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.exportFormat = normalizeExportFormat(parsed.value);
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--table') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.tableName = parsed.value;
+            index = parsed.nextIndex;
+            continue;
         }
 
         throw new Error(`Unknown argument: ${argument}`);
     }
 
-    return { help: false, port };
+    return options;
+}
+
+function hasDatabaseOperation(options) {
+    return Boolean(
+        options.pathInfo ||
+            options.sizeInfo ||
+            options.lastOpenedInfo ||
+            options.tables ||
+            options.queries ||
+            options.executeQuery ||
+            options.showQuery ||
+            options.showNotes ||
+            options.documents ||
+            options.documentName ||
+            options.documentExport ||
+            options.exportTarget ||
+            options.tableName,
+    );
 }
 
 function openInDefaultBrowser(url) {
@@ -138,7 +422,8 @@ function openInDefaultBrowser(url) {
 }
 
 function findDatabaseByName(connections, name) {
-    const normalizedName = name.toLowerCase();
+    const normalizedName = String(name ?? '').toLowerCase();
+
     return connections.find(
         conn => conn.label.toLowerCase() === normalizedName || conn.id.toLowerCase() === normalizedName,
     );
@@ -151,243 +436,774 @@ function formatSize(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
-async function main() {
-    const {
-        help,
-        database,
-        databasePath,
-        databaseSize,
-        databaseLastOpened,
-        databaseTables,
-        sqlEditor,
-        sqlEditorQuery,
-        databaseName,
-        port = DEFAULT_PORT,
-    } = parseCliArguments(process.argv.slice(2));
-
-    if (help) {
-        printHelp();
-        return;
+function sanitizeFilenameBase(value, fallback = 'export') {
+    const sanitized = String(value ?? '')
+        .replace(/[<>:"/\\|?*\u0000-\u001f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/[. ]+$/g, '');
+
+    if (!sanitized) {
+        return fallback;
     }
 
+    return sanitized.slice(0, 120);
+}
+
+function createAppStateStore() {
     const { resolveAppStatePaths } = require('../server/utils/appPaths');
     const { AppStateStore } = require('../server/services/storage/appStateStore');
-    const path = require('path');
+    const packageRoot = path.resolve(__dirname, '..');
+    const { appStateDbPath } = resolveAppStatePaths(packageRoot);
 
-    const PACKAGE_ROOT = path.resolve(__dirname, '..');
-    const { appStateDbPath: APP_STATE_DB_PATH } = resolveAppStatePaths(PACKAGE_ROOT);
+    return new AppStateStore(appStateDbPath);
+}
 
-    const appStateStore = new AppStateStore(APP_STATE_DB_PATH);
-    const connections = appStateStore.getRecentConnections();
+function createReadOnlyRuntime(conn, appStateStore) {
+    const { ConnectionManager } = require('../server/services/sqlite/connectionManager');
+    const { DataBrowserService } = require('../server/services/sqlite/dataBrowserService');
+    const { ExportService } = require('../server/services/sqlite/exportService');
+    const { SqlExecutor } = require('../server/services/sqlite/sqlExecutor');
 
-    if (databasePath) {
-        const conn = findDatabaseByName(connections, databasePath);
-        if (!conn) {
-            console.error(`Database not found: ${databasePath}`);
-            process.exit(1);
-        }
-        console.log(conn.path);
+    const connectionManager = new ConnectionManager({ appStateStore });
+
+    connectionManager.openConnection({
+        filePath: conn.path,
+        label: conn.label,
+        id: conn.id,
+        logoPath: conn.logoPath ?? null,
+        makeActive: false,
+        readOnly: true,
+    });
+
+    const sqlExecutor = new SqlExecutor({ connectionManager, appStateStore });
+    const exportService = new ExportService({ appStateStore, connectionManager, sqlExecutor });
+    const dataBrowserService = new DataBrowserService({ connectionManager });
+
+    return {
+        connectionManager,
+        db: connectionManager.getActiveDatabase(),
+        dataBrowserService,
+        exportService,
+        sqlExecutor,
+        close() {
+            connectionManager.closeCurrent();
+        },
+    };
+}
+
+function printDatabaseList(connections) {
+    if (connections.length === 0) {
+        console.log('No databases imported yet.');
         return;
     }
 
-    if (databaseSize) {
-        const conn = findDatabaseByName(connections, databaseSize);
-        if (!conn) {
-            console.error(`Database not found: ${databaseSize}`);
-            process.exit(1);
-        }
-        console.log(formatSize(conn.sizeBytes));
+    console.log(`\nImported databases (${connections.length}):`);
+    console.log('─'.repeat(60));
+
+    connections.forEach((conn, index) => {
+        const size = formatSize(conn.sizeBytes);
+        const readOnly = conn.readOnly ? ' (read-only)' : '';
+        console.log(`${index + 1}. ${conn.label}${readOnly}`);
+        console.log(`   Path: ${conn.path}`);
+        console.log(`   Size: ${size}`);
+        console.log(`   Last opened: ${conn.lastOpenedAt}`);
+        console.log('');
+    });
+}
+
+function printSingleDatabaseInfo(conn) {
+    const readOnly = conn.readOnly ? 'yes' : 'no';
+
+    console.log(`Database: ${conn.label}`);
+    console.log(`Path: ${conn.path}`);
+    console.log(`Size: ${formatSize(conn.sizeBytes)}`);
+    console.log(`Last opened: ${conn.lastOpenedAt}`);
+    console.log(`Read-only: ${readOnly}`);
+}
+
+function printTables(conn, tables) {
+    if (tables.length === 0) {
+        console.log('No tables found in this database.');
         return;
     }
 
-    if (databaseLastOpened) {
-        const conn = findDatabaseByName(connections, databaseLastOpened);
-        if (!conn) {
-            console.error(`Database not found: ${databaseLastOpened}`);
-            process.exit(1);
-        }
-        console.log(conn.lastOpenedAt);
+    console.log(`\nTables in ${conn.label} (${tables.length}):`);
+    console.log('─'.repeat(60));
+
+    tables.forEach((table, index) => {
+        console.log(`${index + 1}. ${table.name ?? table}`);
+    });
+
+    console.log('');
+}
+
+function getQueryTitle(item) {
+    return item?.title || item?.displayTitle || item?.previewSql || item?.rawSql || '(untitled query)';
+}
+
+function findQueryByName(appStateStore, conn, queryName) {
+    const normalizedQueryName = String(queryName ?? '').trim().toLowerCase();
+
+    if (!normalizedQueryName) {
+        throw new Error('Query name is required.');
+    }
+
+    const collection = appStateStore.buildQueryHistoryCollection({
+        databaseKey: conn.id,
+        search: queryName,
+        onlySaved: false,
+        limit: 100,
+    });
+
+    return (
+        collection.items.find(item => {
+            const candidates = [item.id, item.title, item.displayTitle].filter(Boolean);
+
+            return candidates.some(candidate => String(candidate).toLowerCase() === normalizedQueryName);
+        }) ||
+        collection.items.find(item => String(item.rawSql ?? '').toLowerCase().includes(normalizedQueryName)) ||
+        null
+    );
+}
+
+function getSavedQueries(appStateStore, conn, limit = 100) {
+    return appStateStore.buildQueryHistoryCollection({
+        databaseKey: conn.id,
+        onlySaved: true,
+        limit,
+    });
+}
+
+function printAvailableQueries(appStateStore, conn) {
+    const allQueries = getSavedQueries(appStateStore, conn);
+
+    console.error('\nAvailable saved queries:');
+
+    if (allQueries.items.length > 0) {
+        allQueries.items.forEach(query => {
+            console.error(`  - ${getQueryTitle(query)}`);
+        });
         return;
     }
 
-    if (databaseTables) {
-        const conn = findDatabaseByName(connections, databaseTables);
-        if (!conn) {
-            console.error(`Database not found: ${databaseTables}`);
-            process.exit(1);
-        }
+    console.error('  (none)');
+}
 
-        const Database = require('better-sqlite3');
-        const db = new Database(conn.path, { readonly: true });
+function requireMatchingQuery(appStateStore, conn, queryName) {
+    const matchingQuery = findQueryByName(appStateStore, conn, queryName);
 
-        try {
-            const tables = db
-                .prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")
-                .all()
-                .map(row => row.name);
+    if (!matchingQuery) {
+        console.error(`Saved query not found: ${queryName}`);
+        printAvailableQueries(appStateStore, conn);
+        process.exit(1);
+    }
 
-            if (tables.length === 0) {
-                console.log('No tables found in this database.');
-            } else {
-                console.log(`\nTables in ${conn.label} (${tables.length}):`);
-                console.log('─'.repeat(60));
-                tables.forEach((table, index) => {
-                    console.log(`${index + 1}. ${table}`);
+    return matchingQuery;
+}
+
+function listSavedQueries(appStateStore, conn) {
+    const savedQueries = getSavedQueries(appStateStore, conn);
+
+    if (savedQueries.items.length === 0) {
+        console.log(`No saved queries found for ${conn.label}.`);
+        return;
+    }
+
+    console.log(`\nSaved queries for ${conn.label} (${savedQueries.total}):`);
+    console.log('─'.repeat(60));
+
+    savedQueries.items.forEach((query, index) => {
+        console.log(`${index + 1}. ${getQueryTitle(query)}`);
+    });
+
+    console.log('');
+}
+
+function formatCellValue(value) {
+    if (value === null) {
+        return 'NULL';
+    }
+
+    if (value && typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+
+    return String(value);
+}
+
+function printExecutionResult(result) {
+    console.log(`\nStatement count: ${result.statementCount}`);
+    console.log(`Timing: ${result.timingMs}ms`);
+
+    result.statements.forEach((statement, index) => {
+        console.log(`\nStatement ${index + 1} (${statement.kind}):`);
+
+        if (statement.kind === 'resultSet') {
+            console.log(`Rows: ${statement.rowCount}`);
+            console.log(`Columns: ${statement.columns.join(', ')}`);
+
+            if (statement.rows.length > 0) {
+                console.log('\nResults:');
+                statement.rows.forEach((row, rowIndex) => {
+                    const values = statement.columns.map(column => formatCellValue(row[column]));
+                    console.log(`  [${rowIndex}] ${values.join(' | ')}`);
                 });
-                console.log('');
             }
-        } finally {
-            db.close();
+
+            return;
+        }
+
+        if (statement.kind === 'mutation') {
+            console.log(`Changes: ${statement.changes}`);
+
+            if (statement.lastInsertRowid) {
+                console.log('Last insert rowid:', statement.lastInsertRowid);
+            }
         }
+    });
+}
+
+function executeSavedQuery({ appStateStore, conn, sqlExecutor, queryName }) {
+    const matchingQuery = requireMatchingQuery(appStateStore, conn, queryName);
+
+    console.log(`\nExecuting: ${getQueryTitle(matchingQuery)}`);
+    console.log(`SQL: ${matchingQuery.previewSql || matchingQuery.rawSql}`);
+    console.log('─'.repeat(60));
+
+    const result = sqlExecutor.execute(matchingQuery.rawSql, {
+        persistHistory: false,
+    });
+
+    printExecutionResult(result);
+}
+
+function showSavedQuery({ appStateStore, conn, queryName }) {
+    const matchingQuery = requireMatchingQuery(appStateStore, conn, queryName);
+
+    console.log(matchingQuery.rawSql);
+}
+
+function showSavedQueryNotes({ appStateStore, conn, queryName }) {
+    const matchingQuery = requireMatchingQuery(appStateStore, conn, queryName);
+    const notes = String(matchingQuery.notes ?? '').trim();
+
+    if (notes) {
+        console.log(notes);
         return;
     }
 
-    if (sqlEditor || sqlEditorQuery) {
-        const dbName = databaseName || databasePath || databaseSize || databaseLastOpened || databaseTables;
-        if (!dbName) {
-            console.error('Error: --sqleditor requires a database name.');
-            console.error('Usage: sqlite-hub --database:name --sqleditor');
-            console.error('       sqlite-hub --database:name --sqleditor:"query name"');
-            process.exit(1);
+    console.log(`No notes saved for: ${getQueryTitle(matchingQuery)}`);
+}
+
+function exportSavedQuery({ appStateStore, conn, exportService, queryName, format }) {
+    const matchingQuery = requireMatchingQuery(appStateStore, conn, queryName);
+    const result = exportService.exportQuery(matchingQuery.rawSql, { format });
+    const outputPath = path.resolve(process.cwd(), result.filename);
+
+    fs.writeFileSync(outputPath, result.content, 'utf8');
+
+    console.log(`Exported query: ${getQueryTitle(matchingQuery)}`);
+    console.log(`Format: ${result.format}`);
+    console.log(`Rows: ${result.rowCount}`);
+    console.log(`File: ${outputPath}`);
+}
+
+function getDocumentTitle(document) {
+    return document?.filename || document?.title || document?.id || '(untitled document)';
+}
+
+function printAvailableDocuments(appStateStore, conn) {
+    const documents = appStateStore.listDatabaseDocuments(conn.id);
+
+    console.error('\nAvailable documents:');
+
+    if (documents.length > 0) {
+        documents.forEach(document => {
+            console.error(`  - ${getDocumentTitle(document)}`);
+        });
+        return;
+    }
+
+    console.error('  (none)');
+}
+
+function findDocumentByName(appStateStore, conn, documentName) {
+    const normalizedDocumentName = String(documentName ?? '').trim().toLowerCase();
+
+    if (!normalizedDocumentName) {
+        throw new Error('Document name is required.');
+    }
+
+    const documents = appStateStore.listDatabaseDocuments(conn.id);
+    const exactMatch = documents.find(document => {
+        const candidates = [document.id, document.filename, document.title].filter(Boolean);
+
+        return candidates.some(candidate => String(candidate).toLowerCase() === normalizedDocumentName);
+    });
+
+    if (exactMatch) {
+        return appStateStore.getDatabaseDocument(conn.id, exactMatch.id);
+    }
+
+    const partialMatch = documents.find(document => {
+        const candidates = [document.filename, document.title].filter(Boolean);
+
+        return candidates.some(candidate => String(candidate).toLowerCase().includes(normalizedDocumentName));
+    });
+
+    return partialMatch ? appStateStore.getDatabaseDocument(conn.id, partialMatch.id) : null;
+}
+
+function requireMatchingDocument(appStateStore, conn, documentName) {
+    const matchingDocument = findDocumentByName(appStateStore, conn, documentName);
+
+    if (!matchingDocument) {
+        console.error(`Document not found: ${documentName}`);
+        printAvailableDocuments(appStateStore, conn);
+        process.exit(1);
+    }
+
+    return matchingDocument;
+}
+
+function listDocuments(appStateStore, conn) {
+    const documents = appStateStore.listDatabaseDocuments(conn.id);
+
+    if (documents.length === 0) {
+        console.log(`No documents found for ${conn.label}.`);
+        return;
+    }
+
+    console.log(`\nDocuments for ${conn.label} (${documents.length}):`);
+    console.log('─'.repeat(60));
+
+    documents.forEach((document, index) => {
+        console.log(`${index + 1}. ${document.filename}`);
+        console.log(`   Updated: ${document.updatedAt}`);
+        console.log(`   Characters: ${document.contentLength}`);
+    });
+
+    console.log('');
+}
+
+function showDocumentMarkdown({ appStateStore, conn, documentName }) {
+    const matchingDocument = requireMatchingDocument(appStateStore, conn, documentName);
+
+    console.log(matchingDocument.content ?? '');
+}
+
+function normalizeMarkdownExportFilename(filename, fallback = 'document.md') {
+    let normalizedFilename = String(filename ?? '')
+        .replace(/[\u0000-\u001f\u007f]/g, ' ')
+        .replace(/[<>:"/\\|?*]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^\.+/, '')
+        .replace(/[. ]+$/g, '');
+
+    if (!normalizedFilename) {
+        normalizedFilename = fallback;
+    }
+
+    if (!/\.md$/i.test(normalizedFilename)) {
+        normalizedFilename = `${normalizedFilename}.md`;
+    }
+
+    if (normalizedFilename.length > 160) {
+        normalizedFilename = `${normalizedFilename.slice(0, 157)}.md`;
+    }
+
+    return normalizedFilename;
+}
+
+function exportDocumentMarkdown({ appStateStore, conn, documentName }) {
+    const matchingDocument = requireMatchingDocument(appStateStore, conn, documentName);
+    const filename = normalizeMarkdownExportFilename(matchingDocument.filename, `${matchingDocument.title || 'document'}.md`);
+    const outputPath = path.resolve(process.cwd(), filename);
+
+    fs.writeFileSync(outputPath, matchingDocument.content ?? '', 'utf8');
+
+    console.log(`Exported document: ${matchingDocument.filename}`);
+    console.log(`Characters: ${matchingDocument.contentLength}`);
+    console.log(`File: ${outputPath}`);
+}
+
+function coerceIdentityValue(column, value) {
+    const text = String(value ?? '');
+    const affinity = String(column?.affinity ?? '').toUpperCase();
+
+    if ((affinity === 'INTEGER' || affinity === 'REAL' || affinity === 'NUMERIC') && text.trim() !== '') {
+        const numberValue = Number(text);
+
+        if (Number.isFinite(numberValue)) {
+            return numberValue;
         }
+    }
+
+    return value;
+}
+
+function parseCompositePrimaryKeyValue(rawValue) {
+    try {
+        const parsed = JSON.parse(rawValue);
+
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    } catch (error) {
+        // Fall through to the clearer error below.
+    }
+
+    throw new Error('Composite primary key export requires a JSON object, for example --export:\'{"id":1,"locale":"en"}\'.');
+}
+
+function buildIdentityFromExportTarget(tableDetail, exportTarget) {
+    if (tableDetail.identityStrategy?.type === 'rowid') {
+        const numberValue = Number(exportTarget);
+        const rowid = Number.isInteger(numberValue) ? numberValue : exportTarget;
+
+        return {
+            kind: 'rowid',
+            values: {
+                rowid,
+            },
+        };
+    }
+
+    if (tableDetail.identityStrategy?.type === 'primaryKey') {
+        const columns = tableDetail.identityStrategy.columns ?? [];
+
+        if (columns.length === 1) {
+            const columnName = columns[0];
+            const column = tableDetail.columns.find(candidate => candidate.name === columnName);
+
+            return {
+                kind: 'primaryKey',
+                columns,
+                values: {
+                    [columnName]: coerceIdentityValue(column, exportTarget),
+                },
+            };
+        }
+
+        const parsed = parseCompositePrimaryKeyValue(exportTarget);
+
+        return {
+            kind: 'primaryKey',
+            columns,
+            values: Object.fromEntries(
+                columns.map(columnName => {
+                    if (!Object.prototype.hasOwnProperty.call(parsed, columnName)) {
+                        throw new Error(`Missing primary key value for ${columnName}.`);
+                    }
+
+                    const column = tableDetail.columns.find(candidate => candidate.name === columnName);
+
+                    return [columnName, coerceIdentityValue(column, parsed[columnName])];
+                }),
+            ),
+        };
+    }
+
+    throw new Error(`Table ${tableDetail.name} has no stable row identity.`);
+}
+
+function buildDataRowEditorJsonObject({ row, columns = [] } = {}) {
+    const names = columns
+        .map(column => String(typeof column === 'object' ? column?.name : column ?? '').trim())
+        .filter(name => name && name !== '__identity');
+    const sourceNames = names.length
+        ? names
+        : Object.keys(row ?? {}).filter(name => name !== '__identity');
+
+    return Object.fromEntries(
+        sourceNames
+            .map(name => [name, Object.prototype.hasOwnProperty.call(row ?? {}, name) ? row[name] : undefined])
+            .filter(([, value]) => value !== undefined),
+    );
+}
+
+function exportTableRowAsJson({ dataBrowserService, db, tableName, exportTarget }) {
+    const { getTableDetail } = require('../server/services/sqlite/introspection');
+    const tableDetail = getTableDetail(db, tableName, { includeRowCount: false });
+    const identity = buildIdentityFromExportTarget(tableDetail, exportTarget);
+    const { row } = dataBrowserService.getTableRow(tableName, { identity });
+    const rowObject = buildDataRowEditorJsonObject({
+        row,
+        columns: tableDetail.columns.filter(column => column.visible),
+    });
+    const filenameBase = sanitizeFilenameBase(`${tableName}-${exportTarget}`, `${tableName}-row`);
+    const outputPath = path.resolve(process.cwd(), `${filenameBase}.json`);
+
+    fs.writeFileSync(outputPath, `${JSON.stringify(rowObject, null, 2)}\n`, 'utf8');
+
+    console.log(`Exported row: ${tableName}`);
+    console.log(`Key: ${exportTarget}`);
+    console.log(`File: ${outputPath}`);
+}
+
+function formatColumnFlags(column, foreignKeyColumns) {
+    const flags = [];
+
+    if (column.primaryKeyPosition > 0) {
+        flags.push(`PK${column.primaryKeyPosition > 1 ? `:${column.primaryKeyPosition}` : ''}`);
+    }
+
+    if (foreignKeyColumns.has(column.name)) {
+        flags.push('FK');
+    }
+
+    if (column.notNull) {
+        flags.push('NOT NULL');
+    }
+
+    if (column.generated) {
+        flags.push('GENERATED');
+    }
+
+    return flags.length ? ` [${flags.join(', ')}]` : '';
+}
+
+function printTableInfo(tableDetail) {
+    const foreignKeyColumns = new Set(
+        tableDetail.foreignKeys.flatMap(foreignKey => foreignKey.mappings.map(mapping => mapping.from)),
+    );
+
+    console.log(`Table: ${tableDetail.name}`);
+    console.log(`Rows: ${tableDetail.rowCount ?? 'N/A'}`);
+    console.log(`Identity: ${tableDetail.identityStrategy.type}`);
+    console.log(`Columns: ${tableDetail.columns.filter(column => column.visible).length}`);
+    console.log('');
+
+    tableDetail.columns
+        .filter(column => column.visible)
+        .forEach(column => {
+            const type = column.declaredType || column.affinity || 'ANY';
+            console.log(`  - ${column.name} ${type}${formatColumnFlags(column, foreignKeyColumns)}`);
+        });
+
+    if (tableDetail.foreignKeys.length > 0) {
+        console.log('');
+        console.log(`Foreign keys: ${tableDetail.foreignKeys.length}`);
+        tableDetail.foreignKeys.forEach(foreignKey => {
+            const mapping = foreignKey.mappings.map(item => `${item.from} -> ${item.to}`).join(', ');
+            console.log(`  - ${mapping} (${foreignKey.referencedTable})`);
+        });
+    }
+
+    if (tableDetail.indexes.length > 0) {
+        console.log('');
+        console.log(`Indexes: ${tableDetail.indexes.length}`);
+        tableDetail.indexes.forEach(index => {
+            const unique = index.unique ? ' UNIQUE' : '';
+            const columns = index.columns.map(column => column.name).filter(Boolean).join(', ') || 'expression';
+            console.log(`  - ${index.name}${unique}: ${columns}`);
+        });
+    }
+}
+
+function printConfig(port) {
+    const Database = require('better-sqlite3');
+    const { version } = require('../package.json');
+    const db = new Database(':memory:');
+
+    try {
+        const sqliteVersion = db.prepare('SELECT sqlite_version() AS version').get().version;
+        const url = `http://127.0.0.1:${port}`;
+
+        console.log('SQLite Hub config');
+        console.log(`Port: ${port}`);
+        console.log(`URL: ${url}`);
+        console.log(`App version: ${version}`);
+        console.log(`SQLite version: ${sqliteVersion}`);
+    } finally {
+        db.close();
+    }
+}
+
+async function startAndOpen(port) {
+    const { startServer } = require('../server/server');
+    const fallbackUrl = `http://127.0.0.1:${port}`;
+
+    try {
+        const { url } = await startServer({ port });
+        openInDefaultBrowser(url);
+    } catch (error) {
+        if (error.code === 'EADDRINUSE') {
+            console.warn(`Server already appears to be running on ${fallbackUrl}`);
+            openInDefaultBrowser(fallbackUrl);
+            return;
+        }
+
+        throw error;
+    }
+}
+
+function requireDatabaseName(options) {
+    if (!options.databaseName) {
+        console.error('Error: this command requires --database:"name".');
+        process.exit(1);
+    }
+
+    return options.databaseName;
+}
+
+async function main() {
+    const options = parseCliArguments(process.argv.slice(2));
+    const port = options.port ?? DEFAULT_PORT;
+
+    if (options.help) {
+        printHelp();
+        return;
+    }
+
+    if (options.version) {
+        const { version } = require('../package.json');
+        console.log(`SQLite Hub CLI version ${version}`);
+        return;
+    }
+
+    if (options.config) {
+        printConfig(port);
+        return;
+    }
+
+    if (options.open) {
+        await startAndOpen(port);
+        return;
+    }
+
+    const appStateStore = createAppStateStore();
+    const connections = appStateStore.getRecentConnections();
+
+    if (options.databaseList && !options.databaseName && !hasDatabaseOperation(options)) {
+        printDatabaseList(connections);
+        return;
+    }
+
+    if (options.databaseName || hasDatabaseOperation(options)) {
+        const dbName = requireDatabaseName(options);
         const conn = findDatabaseByName(connections, dbName);
+
         if (!conn) {
             console.error(`Database not found: ${dbName}`);
             process.exit(1);
         }
 
-        const Database = require('better-sqlite3');
-        const { SqlExecutor } = require('../server/services/sqlite/sqlExecutor');
-        const { ConnectionManager } = require('../server/services/sqlite/connectionManager');
-
-        const db = new Database(conn.path, { readonly: true });
+        if (options.documents) {
+            if (options.documentName) {
+                if (options.documentExport) {
+                    exportDocumentMarkdown({
+                        appStateStore,
+                        conn,
+                        documentName: options.documentName,
+                    });
+                } else {
+                    showDocumentMarkdown({
+                        appStateStore,
+                        conn,
+                        documentName: options.documentName,
+                    });
+                }
+                return;
+            }
 
-        try {
-            const connectionManager = new ConnectionManager({ appStateStore });
-            connectionManager.openConnection({
-                filePath: conn.path,
-                label: conn.label,
-                makeActive: true,
-                readOnly: true,
-            });
+            listDocuments(appStateStore, conn);
+            return;
+        }
 
-            const sqlExecutor = new SqlExecutor({ connectionManager, appStateStore });
+        if (options.tableName || options.tables || options.queries || options.executeQuery || options.showQuery || options.showNotes || options.exportTarget) {
+            const runtime = createReadOnlyRuntime(conn, appStateStore);
 
-            if (sqlEditorQuery) {
-                const queryHistory = appStateStore.buildQueryHistoryCollection({
-                    databaseKey: conn.id,
-                    search: sqlEditorQuery,
-                    onlySaved: false,
-                    limit: 100,
-                });
+            try {
+                if (options.tableName) {
+                    const { getTableDetail } = require('../server/services/sqlite/introspection');
 
-                const matchingQuery = queryHistory.items.find(
-                    item =>
-                        item.title?.toLowerCase() === sqlEditorQuery.toLowerCase() ||
-                        item.rawSql.toLowerCase().includes(sqlEditorQuery.toLowerCase()),
-                );
-
-                if (!matchingQuery) {
-                    console.error(`Saved query not found: ${sqlEditorQuery}`);
-                    console.error('\nAvailable saved queries:');
-                    const allQueries = appStateStore.buildQueryHistoryCollection({
-                        databaseKey: conn.id,
-                        onlySaved: true,
-                        limit: 100,
-                    });
-                    if (allQueries.items.length > 0) {
-                        allQueries.items.forEach(q => {
-                            console.log(`  - ${q.title || q.displayTitle}`);
+                    if (options.exportTarget) {
+                        exportTableRowAsJson({
+                            dataBrowserService: runtime.dataBrowserService,
+                            db: runtime.db,
+                            tableName: options.tableName,
+                            exportTarget: options.exportTarget,
                         });
                     } else {
-                        console.log('  (none)');
+                        printTableInfo(getTableDetail(runtime.db, options.tableName));
                     }
-                    process.exit(1);
+
+                    return;
                 }
 
-                console.log(`\nExecuting: ${matchingQuery.title || matchingQuery.displayTitle}`);
-                console.log(`SQL: ${matchingQuery.previewSql}`);
-                console.log('─'.repeat(60));
+                if (options.exportTarget) {
+                    exportSavedQuery({
+                        appStateStore,
+                        conn,
+                        exportService: runtime.exportService,
+                        queryName: options.exportTarget,
+                        format: options.exportFormat,
+                    });
+                    return;
+                }
 
-                const result = sqlExecutor.execute(matchingQuery.rawSql, {
-                    persistHistory: false,
-                });
+                if (options.executeQuery) {
+                    executeSavedQuery({
+                        appStateStore,
+                        conn,
+                        sqlExecutor: runtime.sqlExecutor,
+                        queryName: options.executeQuery,
+                    });
+                    return;
+                }
 
-                console.log(`\nStatement count: ${result.statementCount}`);
-                console.log(`Timing: ${result.timingMs}ms`);
-
-                result.statements.forEach((stmt, index) => {
-                    console.log(`\nStatement ${index + 1} (${stmt.kind}):`);
-                    if (stmt.kind === 'resultSet') {
-                        console.log(`Rows: ${stmt.rowCount}`);
-                        console.log(`Columns: ${stmt.columns.join(', ')}`);
-                        if (stmt.rows.length > 0) {
-                            console.log('\nResults:');
-                            stmt.rows.forEach((row, rowIndex) => {
-                                const values = stmt.columns.map(col => {
-                                    const val = row[col];
-                                    return val === null ? 'NULL' : String(val);
-                                });
-                                console.log(`  [${rowIndex}] ${values.join(' | ')}`);
-                            });
-                        }
-                    } else if (stmt.kind === 'mutation') {
-                        console.log(`Changes: ${stmt.changes}`);
-                        if (stmt.lastInsertRowid) {
-                            console.log('Last insert rowid:', stmt.lastInsertRowid);
-                        }
-                    }
-                });
-            } else {
-                const savedQueries = appStateStore.buildQueryHistoryCollection({
-                    databaseKey: conn.id,
-                    onlySaved: true,
-                    limit: 100,
-                });
+                if (options.showQuery) {
+                    showSavedQuery({ appStateStore, conn, queryName: options.showQuery });
+                    return;
+                }
 
-                if (savedQueries.items.length === 0) {
-                    console.log(`No saved queries found for ${conn.label}.`);
-                } else {
-                    console.log(`\nSaved queries for ${conn.label} (${savedQueries.total}):`);
-                    console.log('─'.repeat(60));
-                    savedQueries.items.forEach((q, index) => {
-                        const title = q.title || q.displayTitle;
-                        console.log(`${index + 1}. ${title}`);
-                    });
-                    console.log('');
+                if (options.showNotes) {
+                    showSavedQueryNotes({ appStateStore, conn, queryName: options.showNotes });
+                    return;
+                }
+
+                if (options.queries) {
+                    listSavedQueries(appStateStore, conn);
+                    return;
+                }
+
+                if (options.tables) {
+                    printTables(conn, runtime.dataBrowserService.listTables());
+                    return;
                 }
+            } finally {
+                runtime.close();
             }
-        } finally {
-            db.close();
         }
-        return;
-    }
 
-    if (database) {
-        if (connections.length === 0) {
-            console.log('No databases imported yet.');
+        if (options.pathInfo) {
+            console.log(conn.path);
             return;
         }
 
-        console.log(`\nImported databases (${connections.length}):`);
-        console.log('─'.repeat(60));
+        if (options.sizeInfo) {
+            console.log(formatSize(conn.sizeBytes));
+            return;
+        }
 
-        connections.forEach((conn, index) => {
-            const size = formatSize(conn.sizeBytes);
-            const readOnly = conn.readOnly ? ' (read-only)' : '';
-            console.log(`${index + 1}. ${conn.label}${readOnly}`);
-            console.log(`   Path: ${conn.path}`);
-            console.log(`   Size: ${size}`);
-            console.log(`   Last opened: ${conn.lastOpenedAt}`);
-            console.log('');
-        });
+        if (options.lastOpenedInfo) {
+            console.log(conn.lastOpenedAt);
+            return;
+        }
 
+        printSingleDatabaseInfo(conn);
         return;
     }
 
-    const { startServer } = require('../server/server');
-    const { url } = await startServer({ port });
-    openInDefaultBrowser(url);
+    if (options.databaseList) {
+        printDatabaseList(connections);
+        return;
+    }
+
+    await startAndOpen(port);
 }
 
 if (require.main === module) {
@@ -399,6 +1215,7 @@ if (require.main === module) {
 
 module.exports = {
     main,
+    normalizeExportFormat,
     openInDefaultBrowser,
     parseCliArguments,
 };