Documentation / Commands

Command reference

Officially documented BroadSQL commands: keyword, description, and its aliases, grouped by category. Generated from the source code at release time: click through for arguments, examples, and full notes.

Overview

84 commands across 14 categories.

Category	Description	Commands
Connections	Connect to databases and manage saved connections.	12
Database Groups	Group related database connections.	5
Environments	Define DEV, QA, PROD and other environments.	4
Login Scripts	Configure SQL automatically executed when a connection opens.	5
Running Queries	Execute SQL and work with query results.	6
Database Exploration	Explore schemas, tables, columns and database metadata.	11
Export & Local Data	Export and preserve data using Excel, ODS, CSV, H2 and more.	4
Data Import	Import data into existing database tables.	1
Scripts Library	Run and manage reusable Scripts: text files of SQL and BroadSQL commands.	10
Light Scripting (JS)	Run and manage JavaScript against query results.	4
Session & Settings	Control the BroadSQL session and display behavior.	7
API Client	Configure, import, browse and execute HTTP API endpoints (SPRINT XT02, Universal API Client).	10
General	Basic session tools: HELP, VERSION, CONFIG, CLS, PRINT.	5
Extension Commands	BroadSQL does not currently ship with any extension commands. This category is reserved for commands provided through BroadSQL's extension mechanism and may include optional commands in future releases.	0

Connections

Connect to databases and manage saved connections.

Command	Description	Aliases
`ADD CONNECTION`	Creates a new database connection	ADD CO, ADDCO, AD CO, ADCO
`CONNECT`	CONNECT <id> opens a connection to a database defined in the Connections Definition File. CONNECT API <api>:<environment> establishes an active API session context instead - the API and environment RUN and SHOW ENDPOINTS use when none is repeated on the command line. The two contexts are entirely independent: connecting to an API never closes or replaces the current database connection, and connecting to a database never clears an active API context. The prompt shows both when both are active, for example $CDF [API DESK:PROD]>. Use DISCONNECT API to clear only the API context.	OPEN, CONN, CON
`DEL CONNECTION`	Deletes an existing database connection	DEL CO, DELCO, DE CO, DECO
`DISCONNECT`	DISCONNECT (or BYE, or CLOSE) reconnects to the Connections Definition File, closing whatever database connection was open. DISCONNECT API clears only the active API session context established by CONNECT API, without affecting the database connection at all. If there is no active API context, DISCONNECT API is a no-op.	BYE, CLOSE
`DUPLICATE CONNECTION`	Duplicates an existing database connection under a new ID	DUP CO, DUPCO
`EDIT CONNECTION`	Edits an existing database connection	ED CO, EDCO
`LOGOUT`	Prompts user for authentication
`PING`	Tests a database connection	CHECK
`REACTIVATE CONNECTION`	Reactivates an inactive database connection	REACT CO, REACO
`SHOW ALL CONNECTIONS`	Displays list of all database connections in the CDF file	SH ALL CO, SH AL CO, SHALLCO, SHALCO
`SHOW CONNECTION`	Shows details about a specified connection	SH CO, SHCO
`SHOW INACTIVE CONNECTIONS`	Displays list of all inactive database connections in the CDF file	SH INACT CO, SHINACO

Database Groups

Group related database connections.

Command	Description	Aliases
`ADD GROUP`	Creates a new Database Group	ADD GR, ADDGR
`DEL GROUP`	Deletes an existing Database Group	DEL GR, DELGR
`EDIT GROUP`	Edits an existing Database Group	EDIT GR, EDGR
`SHOW ALL GROUPS`	Shows all configured Database Groups	SHALGR
`SHOW GROUP`	Shows all environments for a given Database Group	SHOW ENVIRONMENTS, SH ENV, SHENV, SHOW ENVTS

Environments

Define DEV, QA, PROD and other environments.

Command	Description	Aliases
`ADD ENVIRONMENT`	Creates a new Environment	ADD ENV, ADDENV
`DEL ENVIRONMENT`	Deletes an existing Environment	DEL ENV, DELENV
`EDIT ENVIRONMENT`	Edits an existing Environment	EDIT ENV, EDENV
`SHOW ALL ENVIRONMENTS`	Shows the globally configured Environments	SHALENV, SHOW ALL ENVTS

Configure SQL automatically executed when a connection opens.

Command	Description	Aliases
`ADD LOGIN SCRIPT LINE`	Appends a new line to an existing connection's login script	ADD LOG SC LI, ADDLOGSCLI
`DEL LOGIN SCRIPT LINE`	Deletes a line from a connection's login script	DEL LOG SC LI, DELLOGSCLI
`EDIT LOGIN SCRIPT LINE`	Edits an existing line of a connection's login script	EDIT LOG SC LI, EDLOGSCLI
`MOVE LOGIN SCRIPT LINE`	Moves a line of a connection's login script up or down by one position	MOVE LOG SC LI, MOVLOGSCLI
`SHOW LOGIN SCRIPT`	Displays the login script of an existing database connection	SH LOG SC, SHLOGSC

Running Queries

Execute SQL and work with query results.

Command	Description	Aliases
`ALL`	Displays all rows from a table
`CNT`	Displays result of a SELECT COUNT(*) for a table
`EDIT`	Opens the BroadSQL Editor, the native workspace for browsing, editing, formatting, validating, running and versioning the Scripts Library; with a name, opens/focuses that Script	ED
`EXPAND`	Replaces the current SQL's SELECT * / alias.* projection with real column names from database metadata
`FORMAT`	Reformats the current SQL for readability without changing its meaning
`SHOW QUERY`	Displays the current SQL query stored in memory	SH QU, SHQU

Database Exploration

Explore schemas, tables, columns and database metadata.

Command	Description	Aliases
`COMPARE TABLE STRUCTURE`	Compares the column structure of a table between the current connection and another connection	CM TA ST, CMTAST
`DESCR`	Describes the structure of the table	DESC, DESCRIBE
`FIND COLUMN`	Shows tables having a column name that contains the input text	FI COL, FICOL, SHOW COLUMN, SH COL, SHCOL
`LINK TABLE`	Creates a link to a table from a remote database (not available for all databases)	LINKT
`SHOW CATALOGS`	Displays a list of catalogs in the current database	SH CA, SHCA
`SHOW DBINFOS`	Displays current database properties	SH DBIN, SHDBIN
`SHOW DRIVERS`	Lists available JDBC drivers	SH DR, SHDR
`SHOW PK`	Shows the primary keys for a given table name	SHOW PRIMARY KEYS, SH PK, SHPK
`SHOW SCHEMAS`	Displays a list of schemas in the current database	SH SC, SHSC
`SHOW TABLES`	Displays all tables whose schema and name match the entered pattern	SH TA, SHTA
`SHOW VIEWS`	Displays all views whose schema and name match the entered pattern	SH VI, SHVI

Export & Local Data

Export and preserve data using Excel, ODS, CSV, H2 and more.

Command	Description	Aliases
`COPY RESULT`	Copies the most recently produced result, SQL query or RUN, whichever ran last, to the system clipboard as tab-separated text, ready to paste into Excel/Calc
`DUMP`	Extracts the full content of a table in a local file
`EXPORT`	Turns export mode ON or OFF and, if ON, specifies the target file name. Supported formats: text files, CSV, MS Excel (XLSX), OpenDocument Spreadsheet (ODS), MS Access(MDB)	EXP, EXTRACT, EXT
`PULL`	Copies a query's current results into a table of an H2 database (AS H2), a tab of an Excel/ODS file (AS XLSX/AS ODS), or a whole flat file (AS CSV/AS TXT/AS JSON/AS MD/AS HTML). AS H2 reuses an existing connection by name, or creates and registers one automatically; MODE OVERWRITE (the default) drops and recreates the table each run, MODE APPEND KEY(<column>) only inserts rows newer than the target's current maximum key value - the source query may use JOIN, but BroadSQL cannot always verify an outer join's key is never NULL, so add FORCE to proceed past that check when needed (MODE MERGE not implemented yet). Every successful AS H2 run also appends one row to BROADSQL_PULL_AUDIT inside the target database (destination table, source query, completion time, source connection, row count, mode) - a reserved table name that cannot itself be used as a PULL destination. AS XLSX/AS ODS always erase and replace the named tab, leaving every other tab in the file untouched, and keep a 'QUERIES' info tab listing each tab's query, date, source connection, and row count. Every flat-file format (CSV/TXT/JSON/MD/HTML) always fully overwrites the whole file - no MODE clause, no per-file metadata, since a flat file has no second tab to hold it; AS CSV uses CsvSeparator from the INI file (semicolon if absent), AS TXT always uses a tab (neither honors SET SEP); AS JSON writes a single array of objects (numbers written exactly, ISO-8601 dates); AS MD writes a GitHub-Flavored-Markdown table; AS HTML writes a standalone <table> fragment meant to be pasted into an email/wiki page. This whole command is the recommended, unified replacement for EXPORT/DUMP's file output for a one-shot query/table extraction (EXPORT/DUMP remain fully supported, unchanged). AS XLSX/AS ODS accept an optional trailing OPEN: after a successful export, BroadSQL asks the operating system to open the resulting file with its registered/default application (Excel/LibreOffice/whatever is configured - not a hardcoded Excel launch). If OPEN itself fails, the export is still reported as successful and the file is kept; only a secondary warning is printed. PULL API RESULT TO ... uses the last RUN result held in memory as its source instead of a SQL query - every destination kind above works the same way, except MODE APPEND is rejected (there is no source-side SQL shape to validate a delta filter against); AS JSON for this source exports the flattened tabular shape (its columns), not the original raw API response body.

Data Import

Import data into existing database tables.

Command	Description	Aliases
`LOAD`	Loads records from a source file into a table using safe, parameter-bound INSERT statements. Every value is bound through a JDBC PreparedStatement parameter, never concatenated into SQL text, and the target table/columns are resolved against real database metadata before any SQL is built. PREVIEW validates without writing; a plain LOAD asks for confirmation before writing (default No) unless running inside a script, where it requires EXECUTE instead. Any unrecognized source column, or any row that fails to convert, refuses the whole load; there is no partial load of only the valid rows.	LO

Scripts Library

Run and manage reusable Scripts: text files of SQL and BroadSQL commands.

Command	Description	Aliases
`@`	The preferred, concise way to run a Script, a text file of SQL statements and BroadSQL commands. `@foo.bsql` runs a Script from the Scripts Library, `@./foo.bsql` runs a file relative to the working directory (or to the running Script's own directory when written inside a Script), and `@C:\temp\foo.bsql` runs a file anywhere. No extension is ever added.
`LIB DEL`	Archives (soft-deletes) a Script in the Scripts Library, after confirmation; see LIB UNDO / LIB RESTORE	LI DE, LIDE
`LIB EDIT`	Opens a Scripts Library script in the BroadSQL Editor (nothing is saved by opening it)	LI ED, LIED
`LIB FIND`	Full-text, case-insensitive search across the whole Scripts Library (content, not just paths), regardless of Database Group or environment	LI FI, LIFI
`LIB LINT`	Checks the Scripts Library for consistency issues: non-contiguous %N parameters, unknown @instance/@environment ids	LI LN, LILN
`LIB LIST`	Lists the Scripts in the Scripts Library (subfolders included), scoped to the current connection's Database Group and environment by default	LI LI, LILI
`LIB RESTORE`	Restores a specific archived (LIB DEL) Script	LI RS, LIRS
`LIB RUN`	Runs a Script stored in the Scripts Library, the same way `@` does. The name is a path relative to the library root, exactly as written: `LIB RUN maintenance/foo.bsql` runs `maintenance/foo.bsql`. No extension is added and the path cannot leave the library.	LI RU, LIRU
`LIB SHOW`	Displays a Script from the Scripts Library	LI SH, LISH
`LIB UNDO`	Restores the most recently archived (LIB DEL) Script	LI UN, LIUN

Light Scripting (JS)

Run and manage JavaScript against query results.

Command	Description	Aliases
`JS EVAL`	Runs a short piece of JavaScript typed directly on the command line	JS EV, JSEV
`JS FIND`	Full-text, case-insensitive search across the whole JS scripts catalog (content, not just file names), regardless of Database Group or environment	JS FI, JSFI
`JS LIST`	Displays the list of files in the JS scripts catalog, scoped to the current connection's Database Group and environment by default	JS LI, JSLI
`JS RUN`	Runs a saved .js script from the JS scripts catalog, optionally passing positional arguments	JS RU, JSRU

Session & Settings

Control the BroadSQL session and display behavior.

Command	Description	Aliases
`AUTOCOMMIT`	Displays autocommit setting for the current connection	SHOW AUTOCOMMIT, SH AU, SHAU
`SET AUTOCOMMIT`	Turns autocommit ON or OFF	SE AU
`SET LIST`	Sets the display mode of query resuls: OFF=tab view (default), ON=form view	SELI
`SET MASTER PASSWORD`	Changes the master password for the Connections Definition File	SET MAPA
`SET PASSWORD`	Changes the password of the current connection	SE PA
`SET SCHEMA`	Selects a different schema	SE SC, SESC
`SET SEPARATOR`	Specifies a columns separator for export to text files (default is pipe)	SEPARATOR, SEP, SET SEP

API Client

Configure, import, browse and execute HTTP API endpoints (SPRINT XT02, Universal API Client).

Command	Description	Aliases
`CONFIG API`	Opens the API Configuration window: manage APIs, environments (base URL, variables), authentication (Inherit/None/Basic/Bearer/API Key/OAuth2 Client Credentials), variables and headers, folders and endpoints (every HTTP method, plus an optional BroadSQL alias reserved for future script usage), and Bruno YAML import/export, all without hand-editing SQL or the underlying metadata tables. This GUI only configures APIs; it never executes a request (see RUN for that). Same Windows-only, $CDF-only gate as CONFIG.
`IMPORT API BRUNO`	Imports a bundled OpenCollection YAML (Bruno) API collection into BroadSQL's API catalog: creates the API (with environments, folders, and endpoints of every HTTP method) if it does not exist yet, or safely re-imports into an existing one: an object present in the source is created or updated, an object from a previous import no longer present in the source is left untouched, never deleted. Every HTTP verb is imported and listed by SHOW ENDPOINTS; GET, HEAD, POST, PUT, PATCH, and DELETE can be executed (RUN refuses OPTIONS and any other verb). Scripts, assertions and request/response automation are never imported. Only the bundled (single-file) OpenCollection YAML format is supported.
`RUN`	URL-native execution: the relative URL is resolved against the currently connected API (CONNECT API <api>:<environment>; first); RUN never takes an explicit API/environment clause of its own. HTTP_METHOD is optional and defaults to GET; DELETE/POST/PUT/PATCH/HEAD/OPTIONS and other configured methods can be given explicitly, e.g. RUN DELETE /api/customer/123;. A :name segment/query value is resolved, in order: a matching session VAR, the current API environment's own variable, this endpoint's persisted CONFIG API value, its configured default, or a clear missing-parameter error; a literal value (e.g. 123) is used directly. ${name}/{{name}} (API/environment variable templating, the same syntax already used inside a stored endpoint's own definition) also resolves directly in the typed URL now, against the connected API's active environment, before endpoint matching happens (so it can affect which endpoint a URL matches). ${ENV:NAME} reads an operating-system environment variable at invocation time instead (undefined fails explicitly, never silently substitutes an empty string); this is a different, unrelated namespace from ${name}. An endpoint's id, alias (CONFIG API), or name is a completion/discovery shortcut only: RUN <reference>; with no query/tab-expansion is rejected with a hint toward SYNTAX <reference>; or RUN <reference><TAB>, never executed directly. Most imported endpoints never have an alias set at all, only a name and a numeric id, and completion works from any of the three. Query parameters are URL-native: only what is written in the URL is sent (plus any required parameter with no value in the URL that can still be resolved via VAR/persisted/default), never a configured-but-unmentioned optional query parameter. The optional trailing TABLE/RAW clause selects the response rendering exactly as before; the default remains a complete LIST view.
`SHOW ALL APIS`	Lists every API as a bordered table: ID, NAME, TYPE (Manual, or Bruno YAML for an imported API), and DESCRIPTION. Long values may be ellipsized for display; the persisted value itself is never truncated. See SHOW ENDPOINTS to list one API's endpoints, and SHOW API ENVIRONMENTS to list its environments.	SHALAP, ALL APIS
`SHOW API ENVIRONMENTS`	Lists every environment defined for one API as a bordered table: ID, NAME, BASE URL. Never shows a secret environment variable, only these non-secret fields. Use CONNECT API <apiId>:<environment> then RUN <url> to execute against one of these. See SHOW API ENVIRONMENT for the detail of one environment (including its variables) instead of this list.	SHAPENV, ALL ENVT, ALL ENV
`SHOW API ENVIRONMENT`	Always scoped to the active CONNECT API session's API. With no argument, shows the session's own connected environment; with an environment name, shows that named environment of the same API instead. This is a runtime/session-scoped read only: it does not depend on, and this sprint does not introduce, any persisted 'current environment' concept; CONNECT API remains the sole source of which environment is active. Shows enough information to diagnose ${name}/{{name}}/:name variable substitution: id, name, base URL, and every variable (name, value, enabled/disabled) with a secret value masked, never shown in full.	SHAPIENV
`SHOW ENDPOINTS`	Lists endpoints as a table (ID, VERB, FOLDER, NAME, ALIAS). With API <apiId>, targets that API directly: no active session required. Without it, lists the active CONNECT API session's API, revalidating its status on every call (a session can outlive the API it points at being deactivated via CONFIG API in the meantime). A bare HTTP method (e.g. GET) filters on that exact, case-insensitive verb, the canonical form; the legacy VERB <verb> form is still accepted for backward compatibility. MATCH <keyword> filters on a case-insensitive substring over folder, name, and alias combined; both filters may be combined, in either order, after API <apiId> (or first, when API is omitted). The numeric ID or an assigned alias is what SHOW ENDPOINT/SYNTAX/HELP take to select an endpoint unambiguously, since duplicate endpoint names across different folders are normal. See also SHOW ENDPOINT <id> for a single endpoint's full detail (URL, headers, parameters, body).	ENDPOINTS, ALL ENDPOINTS, SHENDS
`SHOW ENDPOINT`	Shows one endpoint's full detail as a vertical view (the same collection => table, single object => detail-view convention as SHOW CONNECTION): ID, owning API, folder, name, alias, method, and the composed effective URL (base path plus enabled query parameters plus fragment, the same composition the CONFIG API endpoint editor and RUN's request builder use). Then, where present: query parameters and path parameters (name, value, enabled/disabled; a value flagged secret is masked), headers (same masking rule), the request body (mode and full content), and an authentication summary (type only, or 'Inherited', never a resolved credential value). The argument accepts a numeric id (global, unique across every API, no active session needed), an alias, or a name (both scoped to the active CONNECT API session's API). A name matching more than one endpoint is reported as an ambiguous-candidates table instead of being guessed at; use the id or alias in that case.	ENDPOINT, SHEND
`SYNTAX`	Generated entirely from the endpoint's own stored parameter metadata (CONFIG API), never a separately maintained syntax string, so it can never drift from what RUN actually accepts. Requires an active CONNECT API session (unlike SHOW ENDPOINT, even a numeric id is scoped to that session's API here). Shows the canonical colon-style URL, every required path/query parameter, optional query parameters with their allowed values, and both a literal and a parameterized (VAR-based) RUN example. The argument accepts a numeric id, an alias, or a name; a name matching more than one endpoint is reported as an ambiguous-candidates table instead of being guessed at, same as SHOW ENDPOINT.
`VAR`	Creates or replaces a temporary, session-only variable, looked up case-insensitively by RUN for a matching :name path or query placeholder; this is step 1 of the resolution precedence, ahead of the current API environment variable, this endpoint's persisted CONFIG API value, and its default (section 7.3, extended by SPRINT XT02B section 4.3). A value may reference ${ENV:NAME} (an operating-system environment variable), resolved once at assignment time; an undefined environment variable fails explicitly. A value containing spaces must be double-quoted. With the trailing PERSIST keyword (requires an active CONNECT API session): instead of a session variable, upserts the value into the current environment's variable set (the same store CONFIG API's Environment tab edits) by case-insensitive name, preserving every other field of an existing row, then clears any session VAR of the same name so the newly persisted environment value is what every subsequent command sees, immediately, through the normal resolution chain.

General

Basic session tools: HELP, VERSION, CONFIG, CLS, PRINT.

Command	Description	Aliases
`CLS`	Clears the screen	CLEAR
`CONFIG`	Displays the GUI for maintaining connections (Windows only)
`HELP`	Displays a list of supported command categories, or help for a specified command/category
`PRINT`	Prints text	PRNT
`VERSION`	Displays the current version of BroadSQL	VERS

Extension Commands

BroadSQL does not currently ship with any extension commands. This category is reserved for commands provided through BroadSQL's extension mechanism and may include optional commands in future releases.