execsql2 2.16.15__tar.gz → 2.16.16__tar.gz

{execsql2-2.16.15 → execsql2-2.16.16}/.github/workflows/ci-cd.yml

@@ -14,6 +14,20 @@ concurrency:
     cancel-in-progress: true
 
 jobs:
+    lint:
+        name: lint
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@v6
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: "3.13"
+            - run: python -m pip install ruff
+            - run: ruff check src/ tests/
+            - run: ruff format --check src/ tests/
+
     tests:
         strategy:
             fail-fast: false
@@ -43,7 +57,8 @@ jobs:
               uses: actions/cache@v5
               with:
                   path: ~/.cache/pip
-                  key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml') }}
+                  key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{
+                      hashFiles('**/pyproject.toml') }}
                   restore-keys: |
                       ${{ runner.os }}-pip-${{ matrix.python-version }}-
             - name: Install dependencies
@@ -86,10 +101,8 @@ jobs:
                 ports:
                     - 5432:5432
                 options: >-
-                    --health-cmd pg_isready
-                    --health-interval 10s
-                    --health-timeout 5s
-                    --health-retries 5
+                    --health-cmd pg_isready --health-interval 10s
+                    --health-timeout 5s --health-retries 5
             mysql:
                 image: mysql:8
                 env:
@@ -100,10 +113,8 @@ jobs:
                 ports:
                     - 3306:3306
                 options: >-
-                    --health-cmd "mysqladmin ping"
-                    --health-interval 10s
-                    --health-timeout 5s
-                    --health-retries 5
+                    --health-cmd "mysqladmin ping" --health-interval 10s
+                    --health-timeout 5s --health-retries 5
         steps:
             - name: Check out repository code
               uses: actions/checkout@v6
@@ -122,7 +133,7 @@ jobs:
     build:
         name: Build distribution 📦
         runs-on: ubuntu-latest
-        needs: [tests, integration-tests]
+        needs: [ lint, tests, integration-tests ]
         if: startsWith(github.ref, 'refs/tags/v')
         permissions:
             contents: read
@@ -147,7 +158,7 @@ jobs:
 
     publish:
         name: PyPI Publish 🚀
-        needs: [build]
+        needs: [ build ]
         if: startsWith(github.ref, 'refs/tags/v')
         runs-on: ubuntu-latest
         environment:
@@ -170,7 +181,7 @@ jobs:
 
     generate-release:
         name: Generate GitHub Release
-        needs: [build]
+        needs: [ build ]
         if: startsWith(github.ref, 'refs/tags/v')
         runs-on: ubuntu-latest
         permissions:

{execsql2-2.16.15 → execsql2-2.16.16}/.pre-commit-config.yaml

@@ -48,6 +48,7 @@ repos:
         exclude: |
           (?x)^(
             \.claude/.*|
+            AUDIT\.md|
             docs/api/.*|
             docs/reference/metacommands\.md|
             docs/guides/documentation\.md|

{execsql2-2.16.15 → execsql2-2.16.16}/CHANGELOG.md

@@ -13,6 +13,25 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.16.16] - 2026-05-02
+
+### Added
+
+- `--init-config` CLI flag to print a default `execsql.conf` template (with all options commented out and documented) to stdout. Use `execsql --init-config > execsql.conf` to bootstrap a configuration file.
+- `--no-system-cmd` CLI flag to disable SYSTEM_CMD/SHELL metacommand execution. Scripts that use SHELL will fail with a clear error when this flag is active. Also configurable via `allow_system_cmd = No` in `execsql.conf` `[config]` section. The library API exposes the same control via `allow_system_cmd=False`.
+
+### Changed
+
+- CLI `--help` output now logically groups related options: connection, encoding, import/export, execution, GUI, configuration, and information.
+- SYSTEM_CMD now uses `subprocess.run()` instead of the deprecated `subprocess.call()`.
+- `execsql.conf` template updated: added missing options (`use_keyring`, `gui_framework`, `allow_system_cmd`, `log_sql`, `max_log_size_mb`, `show_progress`, `import_progress_interval`, `macos_config_file`), fixed incorrect defaults (`password_prompt`, `new_db`, `scan_lines`), added DuckDB (`k`) to database types, modernized all comments.
+
+### Fixed
+
+- SYSTEM_CMD no longer wraps arguments containing `&` in spurious double quotes. The previous behavior (a Windows `cmd.exe` workaround inherited from the upstream monolith) injected literal `"` characters into subprocess arguments, which could cause commands to fail or behave unexpectedly on non-`cmd.exe` targets.
+
+______________________________________________________________________
+
 ## [2.16.15] - 2026-05-02
 
 ### Changed

{execsql2-2.16.15 → execsql2-2.16.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.16.15
+Version: 2.16.16
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql

{execsql2-2.16.15 → execsql2-2.16.16}/docs/about/divergence.md

@@ -31,6 +31,8 @@ ______________________________________________________________________
 | `--lint`                        | Parse the script and perform static analysis without connecting to a database. Reports unmatched IF/ENDIF, LOOP/END LOOP, and BEGIN BATCH/END BATCH blocks (errors); potentially undefined `!!$VAR!!` references (warnings); missing INCLUDE file targets (warnings); and unknown `EXECUTE SCRIPT` targets (warnings). Variable analysis uses two passes so definition order does not matter. The linter descends into named script blocks reached via `EXECUTE SCRIPT` / `EXEC SCRIPT` / `RUN SCRIPT`, reads `SUB_INI` INI files at lint time, recognizes `SUB_EMPTY` / `SUB_ADD` / `SUB_APPEND` / `SUBDATA` as definitions, suppresses false warnings for `$COUNTER_N`, and auto-discovers built-in system variables from the installed source. Exits 0 if no errors, 1 if errors found. |
 | `--parse-tree`                  | Parse the script into an Abstract Syntax Tree and print a visual tree showing block nesting (IF/LOOP/BATCH/SCRIPT), source line ranges, compound conditions (ANDIF/ORIF), and all metacommands. Does not connect to a database or execute anything. Useful for understanding script structure and verifying the parser handles a script correctly.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `--list-plugins`                | List all discovered plugins (metacommands, exporters, importers) from Python entry points and exit. Plugins extend execsql via `execsql.metacommands`, `execsql.exporters`, and `execsql.importers` entry point groups.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--no-system-cmd`               | Disable the `SYSTEM_CMD` (SHELL) metacommand. Scripts that use SHELL will fail with a clear error. Also configurable via `allow_system_cmd = No` in `execsql.conf` `[config]` section, or `allow_system_cmd=False` in the library API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--init-config`                 | Print a default `execsql.conf` template to stdout with all options commented out and documented. Redirect to a file to bootstrap a configuration: `execsql --init-config > execsql.conf`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 ### Export Formats
 

{execsql2-2.16.15 → execsql2-2.16.16}/docs/reference/configuration.md

@@ -15,6 +15,12 @@ Configuration data is read from these files in the order listed above. Informati
 
 An explicit configuration file can also be specified with the `--config FILE` command-line option. This file is loaded **after** all four implicit search paths, so its values take precedence over system, user, script-directory, and working-directory config files. CLI arguments still override everything. The `--config` file may chain additional configs via its `[config]` section, just like any other config file.
 
+To generate a starter configuration file with all options commented out and documented, use:
+
+```bash
+execsql --init-config > execsql.conf
+```
+
 In addition, *execsql* will read additional configuration files if they are specified in any of the standard configuration files ([see below](#config_config)).
 
 Configuration files use the [INI](https://en.wikipedia.org/wiki/INI_file) file format. Section names are case sensitive and must be all in lowercase. Property names are not case sensitive. Property values are read as-is and may or may not be case sensitive, depending on their use. Comments can be included in configuration files; each comment line must start with the "#" character.
@@ -329,6 +335,9 @@ The section and property names that may be used in a configuration file are list
 `max_log_size_mb` { #max_log_size_mb }
 :   Maximum size of the log file in megabytes before it is rotated. When set to a positive integer, the log file is rotated to `.1` before a new run appends to it if the file size exceeds the configured threshold. The default is `0` (disabled — no rotation).
 
+`allow_system_cmd` { #allow_system_cmd }
+:   When set to "No", the `SYSTEM_CMD` (SHELL) metacommand is disabled. Any script that attempts to execute an OS command will fail with an error. The default is "Yes". This can also be set via the `--no-system-cmd` CLI flag or `allow_system_cmd=False` in the library API. See [Security — Disabling SYSTEM_CMD](security.md#disable_system_cmd) for details.
+
 `log_datavars` { #conf_log_datavars }
 :   A value of 'Yes' or 'No' to control whether data variables that are created by the [SELECT_SUB](metacommands.md#select_sub), [PROMPT SELECT_SUB](metacommands.md#prompt_selsub) and [PROMPT ACTION](metacommands.md#prompt_action) metacommands are written to *execsql*'s [log file](../guides/logging.md#logging). By default, this is set to 'Yes', so that all data variable assignments are logged. The performance of scripts that make extensive use of these metacommands (e.g., [Example 27](../guides/examples.md#example27)) can be improved by setting this to 'No'.
 

{execsql2-2.16.15 → execsql2-2.16.16}/docs/reference/security.md

@@ -21,6 +21,36 @@ Variable substitution is applied to the command string before execution, so any
 
 If `outdir` is derived from user input, validate or sanitize it before use in a `SYSTEM_CMD` command.
 
+!!! note "Windows `.bat`/`.cmd` files"
+
+    On Windows, when the target of a `SYSTEM_CMD` is a `.bat` or `.cmd` file, Windows may invoke `cmd.exe` to interpret it. In this case, the `&` character in arguments can be interpreted as a command separator by `cmd.exe`, even though the subprocess is not launched with `shell=True`. Avoid passing untrusted data containing `&` to batch files on Windows.
+
+### Disabling SYSTEM_CMD { #disable_system_cmd }
+
+To prevent scripts from executing OS commands entirely, use the `--no-system-cmd` CLI flag:
+
+```bash
+execsql --no-system-cmd script.sql mydb
+```
+
+Any script that uses `SYSTEM_CMD` or `SHELL` will fail with an error. This is useful for CI pipelines, shared execution environments, or running semi-trusted scripts where shell access is not appropriate.
+
+The same restriction can be set permanently in `execsql.conf`:
+
+```ini
+[config]
+allow_system_cmd = No
+```
+
+The library API provides the same control:
+
+```python
+import execsql
+result = execsql.run("script.sql", dsn="sqlite:///my.db", allow_system_cmd=False)
+```
+
+The `--no-system-cmd` CLI flag always takes precedence — if the flag is passed, `SYSTEM_CMD` is disabled regardless of the config file setting.
+
 ## Credential Handling { #credentials }
 
 ### Interactive password prompts

{execsql2-2.16.15 → execsql2-2.16.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.16.15"
+version = "2.16.16"
 description = "Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -165,7 +165,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.16.15"
+current_version = "2.16.16"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{execsql2-2.16.15 → execsql2-2.16.16}/src/execsql/api.py

@@ -316,6 +316,7 @@ def run(
     encoding: str = "utf-8",
     halt_on_error: bool = True,
     new_db: bool = False,
+    allow_system_cmd: bool = True,
 ) -> ScriptResult:
     """Execute a SQL script and return the result.
 
@@ -337,6 +338,8 @@ def run(
             error.  If ``False``, capture errors and continue.
         new_db: If ``True``, create the database if it does not exist
             (SQLite, PostgreSQL, DuckDB).
+        allow_system_cmd: If ``False``, the SYSTEM_CMD (SHELL) metacommand
+            is disabled and will raise an error if encountered.
 
     Returns:
         A :class:`ScriptResult` with execution outcome, timing, errors,
@@ -434,6 +437,7 @@ def run(
     ctx.subvars = subvars
     ctx.status = StatObj()
     ctx.status.halt_on_err = halt_on_error
+    conf.allow_system_cmd = allow_system_cmd
     ctx.conf = conf
 
     # Capture output to a buffer (suppress stdout/stderr)

{execsql2-2.16.15 → execsql2-2.16.16}/src/execsql/cli/__init__.py

@@ -20,7 +20,7 @@ import typer
 
 from execsql import __version__
 from execsql.cli.dsn import _parse_connection_string, _SCHEME_TO_DBTYPE  # noqa: F401 — re-export
-from execsql.cli.help import _console, _err_console, _print_encodings, _print_metacommands  # noqa: F401 — re-export
+from execsql.cli.help import _console, _err_console, _init_config, _print_encodings, _print_metacommands  # noqa: F401 — re-export
 from execsql.cli.run import _connect_initial_db, _run  # noqa: F401 — re-export
 from execsql.exceptions import ConfigError, ErrInfo
 
@@ -29,6 +29,7 @@ __all__ = [
     "_connect_initial_db",
     "_console",
     "_err_console",
+    "_init_config",
     "_legacy_main",
     "_parse_connection_string",
     "_print_encodings",
@@ -72,28 +73,55 @@ def main(
             "name (client-server DBs) or a database file path (file-based DBs)."
         ),
     ),
-    # Named options — grouped to mirror the original argparse interface
-    sub_vars: list[str] | None = typer.Option(
+    # -- Connection --------------------------------------------------------
+    db_type: str | None = typer.Option(
         None,
-        "-a",
-        "--assign-arg",
-        metavar="VALUE",
-        help="Define the replacement string for a substitution variable [cyan]\\$ARG_x[/cyan].",
+        "-t",
+        "--type",
+        metavar="{a,d,p,s,l,m,k,o,f}",
+        help=(
+            "Database type: [bold]a[/bold]=MS-Access, [bold]p[/bold]=PostgreSQL, "
+            "[bold]s[/bold]=SQL Server, [bold]l[/bold]=SQLite, [bold]m[/bold]=MySQL/MariaDB, "
+            "[bold]k[/bold]=DuckDB, [bold]o[/bold]=Oracle, [bold]f[/bold]=Firebird, "
+            "[bold]d[/bold]=DSN."
+        ),
     ),
-    boolean_int: str | None = typer.Option(
+    dsn: str | None = typer.Option(
         None,
-        "-b",
-        "--boolean-int",
-        metavar="{0,1,t,f,y,n}",
-        help="Treat integers 0 and 1 as boolean values.",
+        "--dsn",
+        "--connection-string",
+        metavar="URL",
+        help=(
+            "Database connection URL, e.g. [cyan]postgresql://user:pass@host:5432/db[/cyan]. "
+            "Supported schemes: postgresql, mysql, mssql, oracle, firebird, sqlite, duckdb. "
+            "Overrides [cyan]-t[/cyan]/[cyan]-u[/cyan]/[cyan]-p[/cyan] and positional server/db args."
+        ),
     ),
-    make_dirs: str | None = typer.Option(
+    user: str | None = typer.Option(
         None,
-        "-d",
-        "--directories",
-        metavar="{0,1,t,f,y,n}",
-        help="Auto-create directories for EXPORT metacommand. [dim]n=no (default), y=yes[/dim]",
+        "-u",
+        "--user",
+        help="Database user name.",
     ),
+    port: int | None = typer.Option(
+        None,
+        "-p",
+        "--port",
+        help="Database server port.",
+    ),
+    no_passwd: bool = typer.Option(
+        False,
+        "-w",
+        "--no-passwd",
+        help="Skip password prompt when user is specified.",
+    ),
+    new_db: bool = typer.Option(
+        False,
+        "-n",
+        "--new-db",
+        help="Create a new SQLite or Postgres database if it does not exist.",
+    ),
+    # -- Encoding ----------------------------------------------------------
     database_encoding: str | None = typer.Option(
         None,
         "-e",
@@ -118,35 +146,13 @@ def main(
         "--import-encoding",
         help="Encoding for data files used with IMPORT.",
     ),
-    user_logfile: bool = typer.Option(
-        False,
-        "-l",
-        "--user-logfile",
-        help="Write a log file to [cyan]~/execsql.log[/cyan].",
-    ),
-    metacommands: bool = typer.Option(
-        False,
-        "-m",
-        "--metacommands",
-        help="List metacommands and exit.",
-    ),
-    new_db: bool = typer.Option(
-        False,
-        "-n",
-        "--new-db",
-        help="Create a new SQLite or Postgres database if it does not exist.",
-    ),
-    online_help: bool = typer.Option(
-        False,
-        "-o",
-        "--online-help",
-        help="Open the online documentation in the default browser.",
-    ),
-    port: int | None = typer.Option(
+    # -- Import/Export -----------------------------------------------------
+    import_buffer: int | None = typer.Option(
         None,
-        "-p",
-        "--port",
-        help="Database server port.",
+        "-z",
+        "--import-buffer",
+        metavar="KB",
+        help="Import buffer size in KB. [dim]Default: 32[/dim]",
     ),
     scanlines: int | None = typer.Option(
         None,
@@ -155,59 +161,36 @@ def main(
         metavar="N",
         help="Lines to scan for IMPORT format detection. [dim]0 = scan entire file.[/dim]",
     ),
-    db_type: str | None = typer.Option(
+    boolean_int: str | None = typer.Option(
         None,
-        "-t",
-        "--type",
-        metavar="{a,d,p,s,l,m,k,o,f}",
-        help=(
-            "Database type: [bold]a[/bold]=MS-Access, [bold]p[/bold]=PostgreSQL, "
-            "[bold]s[/bold]=SQL Server, [bold]l[/bold]=SQLite, [bold]m[/bold]=MySQL/MariaDB, "
-            "[bold]k[/bold]=DuckDB, [bold]o[/bold]=Oracle, [bold]f[/bold]=Firebird, "
-            "[bold]d[/bold]=DSN."
-        ),
+        "-b",
+        "--boolean-int",
+        metavar="{0,1,t,f,y,n}",
+        help="Treat integers 0 and 1 as boolean values.",
     ),
-    user: str | None = typer.Option(
+    make_dirs: str | None = typer.Option(
         None,
-        "-u",
-        "--user",
-        help="Database user name.",
+        "-d",
+        "--directories",
+        metavar="{0,1,t,f,y,n}",
+        help="Auto-create directories for EXPORT metacommand. [dim]n=no (default), y=yes[/dim]",
     ),
-    use_gui: str | None = typer.Option(
+    output_dir: str | None = typer.Option(
         None,
-        "-v",
-        "--visible-prompts",
-        metavar="{0,1,2,3}",
+        "--output-dir",
+        metavar="DIR",
         help=(
-            "GUI level: [bold]0[/bold]=none (default), [bold]1[/bold]=GUI for password/pause, "
-            "[bold]2[/bold]=GUI for password/pause + DB selection, [bold]3[/bold]=full GUI console."
+            "Default base directory for EXPORT output files. "
+            "Relative paths in EXPORT metacommands are joined to this directory. "
+            "Absolute paths and [cyan]stdout[/cyan] are unaffected."
         ),
     ),
-    gui_framework: str | None = typer.Option(
-        None,
-        "--gui-framework",
-        metavar="{tkinter,textual}",
-        help="GUI framework to use with [cyan]--visible-prompts[/cyan]. [dim]Default: tkinter[/dim]",
-    ),
-    no_passwd: bool = typer.Option(
-        False,
-        "-w",
-        "--no-passwd",
-        help="Skip password prompt when user is specified.",
-    ),
-    encodings: bool = typer.Option(
+    progress: bool = typer.Option(
         False,
-        "-y",
-        "--encodings",
-        help="List available encoding names and exit.",
-    ),
-    import_buffer: int | None = typer.Option(
-        None,
-        "-z",
-        "--import-buffer",
-        metavar="KB",
-        help="Import buffer size in KB. [dim]Default: 32[/dim]",
+        "--progress",
+        help="Show a progress bar for long-running IMPORT operations.",
     ),
+    # -- Execution ---------------------------------------------------------
     command: str | None = typer.Option(
         None,
         "-c",
@@ -221,7 +204,7 @@ def main(
     dry_run: bool = typer.Option(
         False,
         "--dry-run",
-        help=("Parse the script and print the command list without connecting to a database or executing anything."),
+        help="Parse the script and print the command list without connecting to a database or executing anything.",
     ),
     lint: bool = typer.Option(
         False,
@@ -232,51 +215,23 @@ def main(
             "and missing INCLUDE files (warnings). Exits 0 if no errors, 1 if errors found."
         ),
     ),
-    ping: bool = typer.Option(
+    parse_tree: bool = typer.Option(
         False,
-        "--ping",
-        help=(
-            "Test database connectivity and exit. "
-            "Prints connection details and the server version on success (exit 0), "
-            "or the error message on failure (exit 1). "
-            "No script file is required."
-        ),
-    ),
-    dsn: str | None = typer.Option(
-        None,
-        "--dsn",
-        "--connection-string",
-        metavar="URL",
-        help=(
-            "Database connection URL, e.g. [cyan]postgresql://user:pass@host:5432/db[/cyan]. "
-            "Supported schemes: postgresql, mysql, mssql, oracle, firebird, sqlite, duckdb. "
-            "Overrides [cyan]-t[/cyan]/[cyan]-u[/cyan]/[cyan]-p[/cyan] and positional server/db args."
-        ),
-    ),
-    output_dir: str | None = typer.Option(
-        None,
-        "--output-dir",
-        metavar="DIR",
+        "--parse-tree",
         help=(
-            "Default base directory for EXPORT output files. "
-            "Relative paths in EXPORT metacommands are joined to this directory. "
-            "Absolute paths and [cyan]stdout[/cyan] are unaffected."
+            "Parse the script into an abstract syntax tree and print the tree structure. "
+            "Does not connect to a database or execute anything."
         ),
     ),
-    progress: bool = typer.Option(
-        False,
-        "--progress",
-        help="Show a progress bar for long-running IMPORT operations.",
-    ),
-    dump_keywords: bool = typer.Option(
+    debug: bool = typer.Option(
         False,
-        "--dump-keywords",
-        help="Dump all metacommand keywords as JSON and exit.",
+        "--debug",
+        help="Start in step-through debug mode. The debug REPL pauses before each statement.",
     ),
-    list_plugins: bool = typer.Option(
+    no_system_cmd: bool = typer.Option(
         False,
-        "--list-plugins",
-        help="List all discovered plugins (metacommands, exporters, importers) and exit.",
+        "--no-system-cmd",
+        help="Disable the SYSTEM_CMD (SHELL) metacommand. Scripts that use SHELL will fail with an error.",
     ),
     profile: bool = typer.Option(
         False,
@@ -288,6 +243,24 @@ def main(
         "--profile-limit",
         help="Number of top statements to show in the --profile timing summary (default: 20).",
     ),
+    # -- GUI ---------------------------------------------------------------
+    use_gui: str | None = typer.Option(
+        None,
+        "-v",
+        "--visible-prompts",
+        metavar="{0,1,2,3}",
+        help=(
+            "GUI level: [bold]0[/bold]=none (default), [bold]1[/bold]=GUI for password/pause, "
+            "[bold]2[/bold]=GUI for password/pause + DB selection, [bold]3[/bold]=full GUI console."
+        ),
+    ),
+    gui_framework: str | None = typer.Option(
+        None,
+        "--gui-framework",
+        metavar="{tkinter,textual}",
+        help="GUI framework to use with [cyan]--visible-prompts[/cyan]. [dim]Default: tkinter[/dim]",
+    ),
+    # -- Configuration -----------------------------------------------------
     config_file: str | None = typer.Option(
         None,
         "--config",
@@ -298,18 +271,62 @@ def main(
             "The file may chain additional configs via its [cyan][config][/cyan] section."
         ),
     ),
-    parse_tree: bool = typer.Option(
+    init_config: bool = typer.Option(
         False,
-        "--parse-tree",
+        "--init-config",
+        help="Print a default [cyan]execsql.conf[/cyan] template to stdout and exit.",
+    ),
+    sub_vars: list[str] | None = typer.Option(
+        None,
+        "-a",
+        "--assign-arg",
+        metavar="VALUE",
+        help="Define the replacement string for a substitution variable [cyan]\\$ARG_x[/cyan].",
+    ),
+    user_logfile: bool = typer.Option(
+        False,
+        "-l",
+        "--user-logfile",
+        help="Write a log file to [cyan]~/execsql.log[/cyan].",
+    ),
+    # -- Information -------------------------------------------------------
+    metacommands: bool = typer.Option(
+        False,
+        "-m",
+        "--metacommands",
+        help="List metacommands and exit.",
+    ),
+    encodings: bool = typer.Option(
+        False,
+        "-y",
+        "--encodings",
+        help="List available encoding names and exit.",
+    ),
+    dump_keywords: bool = typer.Option(
+        False,
+        "--dump-keywords",
+        help="Dump all metacommand keywords as JSON and exit.",
+    ),
+    list_plugins: bool = typer.Option(
+        False,
+        "--list-plugins",
+        help="List all discovered plugins (metacommands, exporters, importers) and exit.",
+    ),
+    ping: bool = typer.Option(
+        False,
+        "--ping",
         help=(
-            "Parse the script into an abstract syntax tree and print the tree structure. "
-            "Does not connect to a database or execute anything."
+            "Test database connectivity and exit. "
+            "Prints connection details and the server version on success (exit 0), "
+            "or the error message on failure (exit 1). "
+            "No script file is required."
         ),
     ),
-    debug: bool = typer.Option(
+    online_help: bool = typer.Option(
         False,
-        "--debug",
-        help="Start in step-through debug mode. The debug REPL pauses before each statement.",
+        "-o",
+        "--online-help",
+        help="Open the online documentation in the default browser.",
     ),
     version: bool | None = typer.Option(
         None,
@@ -340,6 +357,10 @@ def main(
         _print_encodings()
         raise typer.Exit()
 
+    if init_config:
+        _init_config()
+        raise typer.Exit()
+
     if dump_keywords:
         import json as _json
 
@@ -580,6 +601,7 @@ def main(
         ping=ping,
         lint=lint,
         debug=debug,
+        no_system_cmd=no_system_cmd,
         config_file=config_file,
     )
 

{execsql2-2.16.15 → execsql2-2.16.16}/src/execsql/cli/help.py

@@ -11,7 +11,7 @@ from encodings.aliases import aliases as codec_dict
 from rich.console import Console
 from rich.table import Table
 
-__all__ = ["_console", "_err_console", "_print_encodings", "_print_metacommands"]
+__all__ = ["_console", "_err_console", "_init_config", "_print_encodings", "_print_metacommands"]
 
 _console = Console()
 _err_console = Console(stderr=True)
@@ -77,6 +77,15 @@ _SKIP_FROM_DISPATCH = {
 }
 
 
+def _init_config() -> None:
+    """Print the default execsql.conf template to stdout."""
+    import importlib.resources
+    import sys
+
+    template = importlib.resources.files("execsql.data").joinpath("execsql.conf.template").read_text(encoding="utf-8")
+    sys.stdout.write(template)
+
+
 def _print_metacommands() -> None:
     """Print the metacommands table using Rich.