# How to Use DBX CLI for Schema Inspection and Query Execution: A Complete Guide > Master DBX CLI for schema inspection and query execution. Explore database schemas and run SQL queries with terminal commands from the t8y2/dbx repository. Get results in Markdown JSON or CSV. - Repository: [skyler/dbx](https://github.com/t8y2/dbx) - Tags: how-to-guide - Published: 2026-07-10 --- **The DBX CLI provides terminal-based commands for exploring database schemas and executing read-only SQL queries, offering output in Markdown tables, JSON, or CSV formats through a Node.js wrapper architecture.** The **DBX CLI** (available in the `t8y2/dbx` repository) is a thin Node.js wrapper around the `@dbx-app/node-core` backend that enables developers to inspect database structures and run queries directly from the command line. Whether you need to quickly list tables in a connection, examine column metadata, or validate SQL scripts, the CLI provides a streamlined interface that automatically handles driver detection, safety validation, and formatted output rendering. ## Understanding the DBX CLI Architecture The CLI implementation in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts) follows a three-stage pipeline that transforms raw command-line arguments into executed database operations: - **Argument parsing** – The `parseFlags` function (lines 37-74) processes `process.argv` into a structured `ParsedFlags` object, extracting connection names, SQL statements, and formatting options. - **Backend initialization** – The `createBackend` function imported from `@dbx-app/node-core` (lines 61-63) instantiates a driver-aware backend capable of direct database communication or proxying through the DBX Desktop bridge. - **Command dispatch** – Lines 64-126 route parsed commands to specific handlers for `schema`, `query`, `context`, and other sub-commands, each resolving connections via `backend.findConnection` before invoking database methods. ## Schema Inspection Commands Schema exploration relies on two primary commands that interface directly with the backend's metadata methods. ### Listing Tables and Views The `dbx schema list ` command retrieves all tables and views available in the specified connection: ```bash dbx schema list production --json ``` Internally, this resolves the connection configuration through `backend.findConnection` (lines 39-43 in [`cli.ts`](https://github.com/t8y2/dbx/blob/main/cli.ts)), then invokes `backend.listTables` (lines 27-33). Results render as a Markdown table by default, or as JSON or CSV when using the `--json` or `--format csv` flags. ### Describing Table Structure To inspect column-level metadata—including data types, nullability constraints, defaults, and comments—use the describe command: ```bash dbx schema describe production users --format csv ``` This executes `backend.describeTable` and formats output through the `mdTable` helper in [`packages/cli/src/cli-format.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli-format.ts), with the same format overrides available as the list command. ## Query Execution Workflow The `dbx query` command enables read-only SQL execution with built-in safety mechanisms and flexible input methods. ### SQL Safety Evaluation Before executing any statement, the CLI invokes `evaluateSqlSafety` (lines 68-76 in [`cli.ts`](https://github.com/t8y2/dbx/blob/main/cli.ts)) to validate the query against configured safety flags: - **`allowWrites`** – Blocks or permits data modification statements - **`allowDangerous`** – Controls execution of potentially destructive operations These checks respect environment defaults or explicit runtime flags. ### Running Queries from Files For complex multi-line statements, the `--file` parameter reads SQL from disk rather than inline strings: ```bash dbx query analytics --file ./scripts/monthly_report.sql --limit 1000 --timeout 30s ``` The `backend.executeQuery` method (lines 78-84) processes the statement with optional `--limit` (row restriction) and `--timeout` (duration limits) controls. Results output as formatted tables, CSV, or raw JSON depending on the `--format` specification. ## Output Formatting Options Both schema and query commands support three output modes controlled via flags: - **Markdown tables** – Default human-readable format using the `mdTable` utility in [`packages/cli/src/cli-format.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli-format.ts) - **JSON** – Machine-parseable structures via `--json` - **CSV** – Spreadsheet-compatible text via `--format csv` This flexibility allows the CLI to serve both interactive exploration and automated data pipeline integration. ## Integration with DBX Desktop For database drivers requiring the DBX Desktop bridge (such as JDBC connections), the CLI automatically forwards requests via HTTP using `postBridge` (lines 212-218 in [`cli.ts`](https://github.com/t8y2/dbx/blob/main/cli.ts)). The `doctor` command verifies bridge availability and connection health: ```bash dbx doctor ``` To open a specific table directly in the DBX Desktop UI: ```bash dbx open local users ``` This requires an active bridge connection and launches the graphical interface pre-filtered to the specified table. ## Practical Examples List all tables in a local connection with JSON output: ```bash dbx schema list local --json ``` Describe table structure in CSV format for documentation: ```bash dbx schema describe local users --format csv ``` Execute a parameterized query with safety limits: ```bash dbx query local "SELECT id, name FROM users WHERE active = true" --limit 100 --timeout 5s --json ``` Generate schema context for AI prompting: ```bash dbx context local --tables users,orders --json ``` ## Summary - The DBX CLI in `t8y2/dbx` provides **schema inspection** via `schema list` and `schema describe` commands, utilizing `backend.listTables` and `backend.describeTable` from the core Node.js backend. - **Query execution** requires `dbx query` and enforces safety through `evaluateSqlSafety` checks against `allowWrites` and `allowDangerous` flags. - **Output formatting** supports Markdown tables (default), JSON (`--json`), and CSV (`--format csv`) through helpers in [`packages/cli/src/cli-format.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli-format.ts). - **File-based execution** uses `--file ` for complex SQL scripts, while connection resolution occurs through `backend.findConnection`. - **DBX Desktop integration** handles non-direct drivers via `postBridge`, with the `doctor` command verifying bridge status. ## Frequently Asked Questions ### How does the DBX CLI resolve database connections? The CLI resolves connections through `backend.findConnection` (lines 39-43 in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts)), which matches the provided connection name against configured profiles in the DBX backend. This method supports both direct database drivers and connections requiring the DBX Desktop bridge. ### Can I execute INSERT or UPDATE statements with the DBX CLI? No, the DBX CLI is designed for read-only operations. The `evaluateSqlSafety` function (lines 68-76) explicitly checks statements against `allowWrites` flags, blocking data modification commands unless explicitly overridden by environment configurations—providing a safeguard against accidental data changes. ### What file formats does the DBX CLI support for SQL input? The CLI accepts SQL via inline strings or external files using the `--file ` flag (lines 66-68). It reads standard `.sql` text files and passes their contents to `backend.executeQuery`, making it compatible with any UTF-8 encoded SQL script regardless of complexity or line length. ### How do I troubleshoot connection issues with the DBX CLI? Use the `dbx doctor` command to verify backend initialization and bridge availability. For drivers requiring the DBX Desktop application, ensure the HTTP bridge is accessible—the CLI uses `postBridge` (lines 212-218) to forward requests when direct driver connections are unavailable, and the doctor command reports specific connectivity failures.