PrivateactivePrivateactivityPrivateaiPrivatechartPrivatecollectedPrivatecommandPrivatecommandPrivatecommandPrivatecommandsPrivateconfigPrivatecontinuationPrivatecurrentPrivatecustomPrivatedatabasePrivatedebouncedPrivatedestroyPrivatedisposedPrivatedragPrivateeventPrivate ReadonlyexactPrivatehistoryPrivateinputPrivateinputPrivatelastPrivatelinePrivatelinksPrivateloadedPrivate ReadonlymaxPrivateoutputPrivateoutputPrivatepagePrivatepaginationPrivatependingPrivatepromptPrivatequeryPrivatequeryPrivatesharingPrivateshowPrivatestartPrivatestatePrivatesyntaxPrivateterminalPrivatethemePrivateactivatePrivatebuildThe schema DDL sent with a prompt, optionally with sample rows and the values of short text columns, so the model can use exact names and values. Previews read at most 10,000 rows per column and are best effort.
Requests cancellation of the query currently executing in the terminal.
The terminal remains locked until the underlying query promise settles, so callers cannot accidentally start another query on the same connection.
Whether a new cancellation request was accepted
PrivatecmdHandles .ai <prompt>: asks the selected local model, which may run SQL.
PrivatecmdPrivatecmdPrivatecmdHandles .clearmodels: lists the downloaded models and removes them after confirmation.
PrivatecmdDownload last query result as a file in the current output format.
PrivatecmdPrivatecmdPrivatecmdPrivatecmdPrivatecmdPrivatecmdPrivatecmdHandles .model: lists the local models, then selects or installs one.
PrivatecmdPrivatecmdPrivatecmdPrivatecmdPrivatecmdPrivatecmdPrivatecmdPrivatecmdCopy last query result to clipboard
PrivatecreatePrivatedatabaseNames of the attached databases, or null when they cannot be listed.
PrivatedescribeTells the model how to use DuckDB database files, loaded or at URLs: they are attached, not read, so it gets the exact ATTACH statement, or the name a file is already attached under (its tables are then in the DDL above). The terminal never attaches a file by itself.
PrivatedescribeAdds the columns and first rows of a file source, e.g. read_csv('name'), to lines.
PrivatedescribeDescribes loaded files the model can query by name, skipping files already loaded into a table of the same name. Without this the model would not know about files the user dropped into the terminal.
PrivatedescribeThe tables and columns of databases attached since before, as DDL with
the first rows of each table for the model, and as a list for the
assistant's answer. Null when nothing was added.
PrivatedescribeDescribes the files at URLs in the conversation's questions like loaded files, so the model knows their columns before its first query, or knows that a file cannot be read (wrong URL, or a server that does not allow browsers). The URLs come newest first; older ones beyond the limit are left out.
Cleans up resources and event listeners.
Call this method when disposing of the terminal to prevent memory leaks. This removes drag-and-drop handlers and clears internal state.
PrivatedisplayDisplays a query result in the current output mode.
Formats and writes the result as table, CSV, TSV, or JSON based on the current outputMode setting.
The query result to display
The SQL statement that produced the result
PrivateemitInternal
Emits an event to all registered listeners.
The event type key from TerminalEvents
The event name to emit
The event payload to pass to listeners
PrivateenqueuePrivateensurePrivateexecuteExecutes a dot command (e.g., .help, .tables, .schema).
Parses the command and arguments, looks up the handler, and executes it. Emits 'commandExecute' event on execution and 'error' on failure.
The full command string including arguments
Executes a SQL query and displays the results.
This method executes the provided SQL statement against the DuckDB database, displays the results in the configured output format (table, CSV, or JSON), and adds the query to the command history.
Large result sets are automatically bounded and paginated with one-row
lookahead. Exact totals are computed eagerly only when exactRowCount is set.
The SQL statement to execute (should end with a semicolon)
A promise that resolves to the query result, or null if an error occurred
PrivateexecuteInternal
Internal SQL execution logic.
The SQL statement to execute
The query result, or null on error
PrivatefindFinds the longest common prefix among an array of strings.
Used for auto-completion to expand to the longest unambiguous prefix.
Array of strings to find common prefix for
The longest common prefix (case-insensitive comparison)
PrivatefinishFocuses the terminal input, including the native mobile keyboard.
PrivateformatPrivategenerateGenerate a filename for download with timestamp or custom name.
PrivategetReturns the in-browser assistant, creating it on first use.
PrivategetReturns the current theme object for terminal styling.
The custom theme if set, otherwise the built-in theme ('dark' or 'light')
PrivategetAsynchronously highlights SQL using DuckDB's tokenizer.
The SQL string to highlight
The highlighted SQL string with ANSI color codes
Gets the current theme mode.
Returns 'dark' or 'light' based on the current theme. For custom themes, this returns 'light' if the theme name is 'light', otherwise 'dark'.
The current theme mode: 'dark' or 'light'
PrivatehandleNavigates to the next command in history (Arrow Down).
PrivatehandleNavigates to the previous command in history (Arrow Up).
PrivatehandleProcesses a single character of user input.
Handles special characters (Enter, Backspace, Tab, Ctrl sequences) and regular printable characters including Unicode.
The single character to process
PrivatehandleHandles Ctrl+C to cancel current input or multi-line collection.
PrivatehandleProcesses files dropped onto the terminal via drag-and-drop.
Uses Promise.allSettled to ensure all files are attempted even if some fail.
Array of File objects to load into DuckDB
PrivatehandleHandles the Enter key press.
For dot commands, executes immediately. For SQL, collects lines until a semicolon terminates the statement, then executes.
PrivatehandleProcesses VT100 escape sequences for special keys.
Handles arrow keys (up/down for history, left/right for cursor), word navigation, Home, End, and Delete keys.
The escape sequence string (e.g., '\x1b[A' for Arrow Up)
PrivatehandleHandles raw terminal input data.
Routes input to the appropriate handler based on terminal state (executing, paginating, or normal input mode). Processes escape sequences separately from regular character input.
The raw input data from the terminal
PrivatehandlePrivatehandleHandles input during pagination mode.
Supports: [n]ext page, [p]revious page, [q]uit, page number entry, and arrow keys for navigation.
The input character or escape sequence
PrivatehandleHandles Ctrl+V to paste content from clipboard.
Inserts text character-by-character, skipping newlines.
PrivatehandleHandles terminal resize events.
Updates the InputBuffer with the new terminal width and redraws the current input line to ensure proper visual alignment after resize.
The new terminal width in columns
PrivatehandleHandles Tab key for auto-completion.
Provides suggestions for SQL keywords, table names, and functions. Single match is applied directly; multiple matches are displayed.
Highlights SQL using DuckDB's tokenizer for syntax coloring.
This method uses DuckDB's internal parser (via the poached extension) to tokenize the SQL and apply ANSI color codes for keywords, strings, numbers, functions, etc. The result can be written to the terminal for colored output.
The SQL string to highlight
The highlighted SQL string with ANSI color codes, or the original SQL if highlighting is disabled or tokenization fails
PrivateinsertPrivateisChecks if a character should trigger syntax highlighting redraw.
The character to check
True if the character is a highlighting trigger (space, semicolon, parentheses, comma)
PrivateisPrivateloadLoads a file into DuckDB's virtual filesystem.
Registers the file and displays usage hints for supported file types (CSV, Parquet, JSON). Emits a 'fileLoaded' event on success.
The file to load
True if the file was loaded successfully, false otherwise
Unsubscribes a listener from a terminal event.
This is an alternative to using the unsubscribe function returned by on.
The event type key from TerminalEvents
The event name to unsubscribe from
The callback function to remove
Subscribes to a terminal event.
The terminal emits various events during its lifecycle that you can subscribe to for monitoring, logging, or integrating with your application.
The event type key from TerminalEvents
The event name to subscribe to
The callback function to invoke when the event occurs
An unsubscribe function that removes the listener when called
Opens the sharing modal to select queries for sharing.
The modal displays the command history (excluding dot commands) and allows the user to select queries to include in a shareable URL.
PrivatereadReads one line of input while a command runs, such as a menu choice or a yes/no answer. Resolves to the trimmed line, or null on Ctrl+C.
PrivateredrawRedraws the current input line from scratch.
After a terminal resize, Gespenst re-wraps content and the cursor position becomes unpredictable. The safest approach is to:
This may result in the old (garbled) content remaining visible above, but the current input will be correctly displayed and functional.
The cursor position before the change (unused, kept for API stability)
The end position before the change (unused, kept for API stability)
PrivateredrawRedraws the current input line with syntax highlighting applied.
This method clears the current line content and rewrites it with color codes for SQL keywords, strings, numbers, etc. Called on delimiter characters (space, semicolon, parentheses, comma) via debouncing.
Uses DuckDB's internal parser via the poached extension for accurate tokenization.
Displays the command prompt.
Useful after programmatically executing SQL via executeSQL to show the prompt for the next input. This is automatically called when the user enters commands via the terminal, but needs to be called manually when executing queries programmatically.
PrivateregisterRegisters all built-in dot commands (.help, .tables, .schema, etc.).
Called during construction to populate the commands map with handlers for terminal commands.
PrivateresolvePrivaterunRuns a statement the model requested, without asking first, including statements that change data. The user sees it like a typed query.
Runs a dot command through the same path as typed commands, preserving pending input. Rejects while executing, collecting multiline SQL, or paginating. Call directly from a click handler for file commands so the file picker retains browser user activation.
PrivatesetPrivatesetInternal
Sets the terminal state and emits a stateChange event.
The new terminal state
Sets the terminal color theme.
You can set a built-in theme ('dark' or 'light') or provide a custom theme object with your own colors. Built-in theme preferences are persisted to localStorage.
The theme to apply: 'dark', 'light', or a custom Theme object
PrivateshowPrivateshowDisplays the command prompt (primary or continuation based on state).
Sets terminal state to 'idle' if not currently collecting multi-line SQL.
Initializes and starts the terminal.
This method performs the following initialization steps:
A promise that resolves when the terminal is fully initialized
PrivatestartPrivatestopOptionalexecution: QueryExecutionContextPrivatethrowWrites text to the terminal without a trailing newline.
Use this method for inline output where you don't want to start a new line. The text is written directly to the terminal without any processing.
The text to write to the terminal
Writes text to the terminal followed by a newline.
Newlines are normalized to CRLF. Gespenst detects links in the rendered viewport.
The text to write to the terminal
A browser-based SQL terminal for DuckDB, powered by Gespenst.
DuckDBTerminal provides a full-featured SQL REPL (Read-Eval-Print Loop) that runs entirely in the browser using DuckDB WASM. It supports:
.help,.tables,.schema, etc.).promptcommand)Implements
Example: Basic usage
Example: With custom prompts
Example: With event listeners
Example: Programmatic SQL execution