dirsql 0.3.123__tar.gz → 0.3.124__tar.gz

{dirsql-0.3.123 → dirsql-0.3.124}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.123"
+version = "0.3.124"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.123 → dirsql-0.3.124}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.123
+Version: 0.3.124
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index
 Author: Kevin Scott
@@ -126,7 +126,7 @@ Each event has `.action` (`"insert"`, `"update"`, `"delete"`, or `"error"`), `.t
 
 ## CLI
 
-`pip install dirsql` also installs a `dirsql` console script that runs an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Run `dirsql` (or `uvx dirsql`) to start it. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
+`pip install dirsql` also installs a `dirsql` console script. `dirsql "<sql>"` (or `uvx dirsql "<sql>"`) runs one query and prints the rows as JSON — the default. `dirsql server` starts an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
 
 ## License
 

{dirsql-0.3.123/packages/python → dirsql-0.3.124}/README.md

@@ -116,7 +116,7 @@ Each event has `.action` (`"insert"`, `"update"`, `"delete"`, or `"error"`), `.t
 
 ## CLI
 
-`pip install dirsql` also installs a `dirsql` console script that runs an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Run `dirsql` (or `uvx dirsql`) to start it. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
+`pip install dirsql` also installs a `dirsql` console script. `dirsql "<sql>"` (or `uvx dirsql "<sql>"`) runs one query and prints the rows as JSON — the default. `dirsql server` starts an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
 
 ## License
 

{dirsql-0.3.123/packages/rust → dirsql-0.3.124}/docs/getting-started.md

@@ -68,11 +68,11 @@ this directory anyway — from inside `my-notes`, run one command:
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT COUNT(*) AS files FROM './'"
+npx dirsql "SELECT COUNT(*) AS files FROM './'"
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT COUNT(*) AS files FROM './'"
+uvx dirsql "SELECT COUNT(*) AS files FROM './'"
 ```
 
 :::
@@ -168,11 +168,11 @@ pass it explicitly with `-c`, **after** the SQL:
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+npx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+uvx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
 ```
 
 :::

{dirsql-0.3.123/packages/python → dirsql-0.3.124}/docs/howto/load-extension.md

@@ -53,7 +53,7 @@ entrypoint = "sqlite3_vec_init"
 ```
 
 ```bash
-uvx --with sqlite-vec dirsql -c ./.dirsql.toml
+uvx --with sqlite-vec dirsql server -c ./.dirsql.toml
 ```
 
 **Node (`npx dirsql`, TypeScript SDK).** Use the *npm package name* — but

{dirsql-0.3.123/packages/rust → dirsql-0.3.124}/docs/howto/persist.md

@@ -1,7 +1,7 @@
 # Keep the index across restarts
 
 By default the database is ephemeral: rebuilt from your files on every
-startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#server-mode)
+startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#dirsql-server)
 flag keeps the SQLite index on disk instead, so a restart only re-parses
 files that actually changed — the difference between seconds and
 milliseconds on large trees, and between re-running and skipping expensive

{dirsql-0.3.123/packages/python → dirsql-0.3.124}/docs/howto/react-to-changes.md

@@ -18,8 +18,8 @@ glob = "**/*"
 
 ## 1. Open the stream
 
-With the server running (`npx dirsql -c ./.dirsql.toml` /
-`uvx dirsql -c ./.dirsql.toml`), subscribe from another terminal:
+With the server running (`npx dirsql server -c ./.dirsql.toml` /
+`uvx dirsql server -c ./.dirsql.toml`), subscribe from another terminal:
 
 ```bash
 curl -N http://localhost:7117/events

{dirsql-0.3.123/packages/rust → dirsql-0.3.124}/docs/howto/search-by-meaning.md

@@ -10,7 +10,7 @@ embed each question at query time.
 ::: tip Just want it working?
 [`dirsql-plugin-embeddings`](https://pypi.org/project/dirsql-plugin-embeddings/)
 packages exactly what this guide builds, ready to install:
-`uvx --with dirsql-plugin-embeddings dirsql`. Keep reading to see how it's
+`uvx --with dirsql-plugin-embeddings dirsql server`. Keep reading to see how it's
 built — the same three pieces, from scratch.
 :::
 

{dirsql-0.3.123/packages/python → dirsql-0.3.124}/docs/reference/cli.md

@@ -1,39 +1,56 @@
 # CLI
 
-The `dirsql` binary has three modes:
+Query is the default: `dirsql "<sql>"` runs one query and prints JSON rows.
+The `dirsql` binary has these modes:
 
 | Invocation | Behavior |
 |---|---|
-| `dirsql` (no subcommand) | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
-| `dirsql query "<sql>"` | Query the file system as JSON |
-| `dirsql init` | Generate a `.dirsql.toml` |
+| `dirsql "<sql>"` | Run one query over the directory and print the rows as JSON. The default; identical to `dirsql query "<sql>"`. |
+| `dirsql query "<sql>"` | Explicit synonym for the default one-shot query. |
+| `dirsql server` | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
+| `dirsql init` | Generate a `.dirsql.toml`. |
+
+Bare `dirsql` with no SQL is a usage error pointing at `dirsql server` — it
+does **not** start the server.
 
 ## Installation
 
 ::: code-group
 
 ```bash [npm]
-npx dirsql
+npx dirsql "SELECT * FROM './'"
 ```
 
 ```bash [PyPI]
-uvx dirsql
+uvx dirsql "SELECT * FROM './'"
 ```
 
 ```bash [Cargo]
 # The `cli` feature is opt-in; this installs the binary only.
 cargo install dirsql --features cli
-dirsql
+dirsql "SELECT * FROM './'"
 ```
 
 :::
 
 The npm launcher requires **Node ≥ 20.11**.
 
-## Server mode
+## Default query mode
 
 ```bash
-dirsql
+# No -c: query the filesystem with a path-table.
+dirsql "SELECT basename, size FROM './' ORDER BY size DESC LIMIT 5"
+# [{"basename":"model.bin","size":104857600}, …]
+```
+
+`dirsql "<sql>"` is exactly [`dirsql query "<sql>"`](#dirsql-query) — same
+pipeline, same flags, same output. See that section for config discovery,
+`--persist`, `--on-file`, hooks, and exit codes.
+
+## `dirsql server`
+
+```bash
+dirsql server
 # Running at localhost:7117
 ```
 
@@ -43,12 +60,15 @@ requests, closes open `/events` streams, and exits.
 
 ### Flags
 
+Config flags are subcommand-local: pass them after `server`
+(`dirsql server -c <cfg>`).
+
 | Flag | Default | Description |
 |---|---|---|
-| `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql` from. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
+| `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql server` from. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
-| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches at `<root>/.dirsql/cache.db`; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query), passed after the subcommand. See [Keep the index across restarts](../howto/persist.md). |
+| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches at `<root>/.dirsql/cache.db`; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |
 | `--help` | | Print usage and exit. |
@@ -124,8 +144,9 @@ dirsql query "SELECT COUNT(*) AS n FROM posts" -c ./.dirsql.toml | jq '.[0].n'
 Pass `-c`/`--config`, `--persist`, and `--extension` **after** `query`
 (`dirsql query "<sql>" -c <cfg>`). A config flag placed *before* the subcommand
 is a hard error — `error: the subcommand 'query' cannot be used with
-'--config <CONFIG>'` — never silently dropped. (In server mode, with no
-subcommand, the same flags are passed directly: `dirsql -c <cfg>`.)
+'--config <CONFIG>'` — never silently dropped. (The default mode without the
+`query` keyword takes the same flags after the SQL: `dirsql "<sql>" -c <cfg>`;
+for the server they follow the subcommand: `dirsql server -c <cfg>`.)
 :::
 
 The subcommand builds the index, runs the SQL, prints the result rows as a
@@ -199,7 +220,7 @@ The output does **not** auto-load. Once you've tweaked it, pass it explicitly
 to run against it:
 
 ```bash
-dirsql -c ./.dirsql.toml
+dirsql "SELECT * FROM files" -c ./.dirsql.toml
 ```
 
 ### Flags

{dirsql-0.3.123/packages/python → dirsql-0.3.124}/docs/reference/config.md

@@ -40,7 +40,7 @@ hook-timeout = 300
 ```
 
 Persistence is not a config key. Keep the SQLite index on disk between runs
-with the [`--persist [PATH]` CLI flag](./cli.md#server-mode) — a machine-local
+with the [`--persist [PATH]` CLI flag](./cli.md#dirsql-server) — a machine-local
 operational choice that belongs to the runner, not to shareable config.
 
 ## `[[dirsql.extension]]`

{dirsql-0.3.123/packages/rust → dirsql-0.3.124}/docs/reference/http-api.md

@@ -1,6 +1,6 @@
 # HTTP API
 
-The [`dirsql` server](./cli.md#server-mode) (default `localhost:7117`)
+The [`dirsql` server](./cli.md#dirsql-server) (default `localhost:7117`)
 exposes two endpoints: `POST /query` and `GET /events`.
 
 ## `POST /query`

{dirsql-0.3.123/packages/rust → dirsql-0.3.124}/docs/reference/sdk.md

@@ -130,7 +130,7 @@ shortcut was removed in #603 — use
   ephemeral, rebuilt every startup). The cache lives at
   `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
   changed are re-parsed. (The CLI exposes the same switch as the
-  [`--persist [PATH]`](./cli.md#server-mode) flag; it is not a config key.)
+  [`--persist [PATH]`](./cli.md#dirsql-server) flag; it is not a config key.)
 - `persist_path` / `persistPath` — Override the cache location. Ignored when
   persistence is off. Constructor values are used as given. In Rust these two
   parameters collapse into a single builder method: `.persist(None)` enables

{dirsql-0.3.123 → dirsql-0.3.124}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.123"
+version = "0.3.124"
 # abi3 note: the `abi3-py311` pyo3 feature (below) builds ONE stable-ABI
 # `cp311-abi3` wheel per platform that loads on every CPython >= 3.11
 # (matching `pyproject.toml`'s `requires-python = ">=3.11"`), instead of

{dirsql-0.3.123 → dirsql-0.3.124/packages/python}/README.md

@@ -116,7 +116,7 @@ Each event has `.action` (`"insert"`, `"update"`, `"delete"`, or `"error"`), `.t
 
 ## CLI
 
-`pip install dirsql` also installs a `dirsql` console script that runs an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Run `dirsql` (or `uvx dirsql`) to start it. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
+`pip install dirsql` also installs a `dirsql` console script. `dirsql "<sql>"` (or `uvx dirsql "<sql>"`) runs one query and prints the rows as JSON — the default. `dirsql server` starts an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
 
 ## License
 

{dirsql-0.3.123 → dirsql-0.3.124/packages/python}/docs/getting-started.md

@@ -68,11 +68,11 @@ this directory anyway — from inside `my-notes`, run one command:
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT COUNT(*) AS files FROM './'"
+npx dirsql "SELECT COUNT(*) AS files FROM './'"
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT COUNT(*) AS files FROM './'"
+uvx dirsql "SELECT COUNT(*) AS files FROM './'"
 ```
 
 :::
@@ -168,11 +168,11 @@ pass it explicitly with `-c`, **after** the SQL:
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+npx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+uvx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
 ```
 
 :::

{dirsql-0.3.123/packages/rust → dirsql-0.3.124/packages/python}/docs/howto/load-extension.md

@@ -53,7 +53,7 @@ entrypoint = "sqlite3_vec_init"
 ```
 
 ```bash
-uvx --with sqlite-vec dirsql -c ./.dirsql.toml
+uvx --with sqlite-vec dirsql server -c ./.dirsql.toml
 ```
 
 **Node (`npx dirsql`, TypeScript SDK).** Use the *npm package name* — but

{dirsql-0.3.123 → dirsql-0.3.124}/packages/python/docs/howto/persist.md

@@ -1,7 +1,7 @@
 # Keep the index across restarts
 
 By default the database is ephemeral: rebuilt from your files on every
-startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#server-mode)
+startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#dirsql-server)
 flag keeps the SQLite index on disk instead, so a restart only re-parses
 files that actually changed — the difference between seconds and
 milliseconds on large trees, and between re-running and skipping expensive

{dirsql-0.3.123/packages/rust → dirsql-0.3.124/packages/python}/docs/howto/react-to-changes.md

@@ -18,8 +18,8 @@ glob = "**/*"
 
 ## 1. Open the stream
 
-With the server running (`npx dirsql -c ./.dirsql.toml` /
-`uvx dirsql -c ./.dirsql.toml`), subscribe from another terminal:
+With the server running (`npx dirsql server -c ./.dirsql.toml` /
+`uvx dirsql server -c ./.dirsql.toml`), subscribe from another terminal:
 
 ```bash
 curl -N http://localhost:7117/events

{dirsql-0.3.123 → dirsql-0.3.124/packages/python}/docs/howto/search-by-meaning.md

@@ -10,7 +10,7 @@ embed each question at query time.
 ::: tip Just want it working?
 [`dirsql-plugin-embeddings`](https://pypi.org/project/dirsql-plugin-embeddings/)
 packages exactly what this guide builds, ready to install:
-`uvx --with dirsql-plugin-embeddings dirsql`. Keep reading to see how it's
+`uvx --with dirsql-plugin-embeddings dirsql server`. Keep reading to see how it's
 built — the same three pieces, from scratch.
 :::
 

{dirsql-0.3.123/packages/rust → dirsql-0.3.124/packages/python}/docs/reference/cli.md

@@ -1,39 +1,56 @@
 # CLI
 
-The `dirsql` binary has three modes:
+Query is the default: `dirsql "<sql>"` runs one query and prints JSON rows.
+The `dirsql` binary has these modes:
 
 | Invocation | Behavior |
 |---|---|
-| `dirsql` (no subcommand) | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
-| `dirsql query "<sql>"` | Query the file system as JSON |
-| `dirsql init` | Generate a `.dirsql.toml` |
+| `dirsql "<sql>"` | Run one query over the directory and print the rows as JSON. The default; identical to `dirsql query "<sql>"`. |
+| `dirsql query "<sql>"` | Explicit synonym for the default one-shot query. |
+| `dirsql server` | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
+| `dirsql init` | Generate a `.dirsql.toml`. |
+
+Bare `dirsql` with no SQL is a usage error pointing at `dirsql server` — it
+does **not** start the server.
 
 ## Installation
 
 ::: code-group
 
 ```bash [npm]
-npx dirsql
+npx dirsql "SELECT * FROM './'"
 ```
 
 ```bash [PyPI]
-uvx dirsql
+uvx dirsql "SELECT * FROM './'"
 ```
 
 ```bash [Cargo]
 # The `cli` feature is opt-in; this installs the binary only.
 cargo install dirsql --features cli
-dirsql
+dirsql "SELECT * FROM './'"
 ```
 
 :::
 
 The npm launcher requires **Node ≥ 20.11**.
 
-## Server mode
+## Default query mode
 
 ```bash
-dirsql
+# No -c: query the filesystem with a path-table.
+dirsql "SELECT basename, size FROM './' ORDER BY size DESC LIMIT 5"
+# [{"basename":"model.bin","size":104857600}, …]
+```
+
+`dirsql "<sql>"` is exactly [`dirsql query "<sql>"`](#dirsql-query) — same
+pipeline, same flags, same output. See that section for config discovery,
+`--persist`, `--on-file`, hooks, and exit codes.
+
+## `dirsql server`
+
+```bash
+dirsql server
 # Running at localhost:7117
 ```
 
@@ -43,12 +60,15 @@ requests, closes open `/events` streams, and exits.
 
 ### Flags
 
+Config flags are subcommand-local: pass them after `server`
+(`dirsql server -c <cfg>`).
+
 | Flag | Default | Description |
 |---|---|---|
-| `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql` from. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
+| `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql server` from. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
-| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches at `<root>/.dirsql/cache.db`; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query), passed after the subcommand. See [Keep the index across restarts](../howto/persist.md). |
+| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches at `<root>/.dirsql/cache.db`; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |
 | `--help` | | Print usage and exit. |
@@ -124,8 +144,9 @@ dirsql query "SELECT COUNT(*) AS n FROM posts" -c ./.dirsql.toml | jq '.[0].n'
 Pass `-c`/`--config`, `--persist`, and `--extension` **after** `query`
 (`dirsql query "<sql>" -c <cfg>`). A config flag placed *before* the subcommand
 is a hard error — `error: the subcommand 'query' cannot be used with
-'--config <CONFIG>'` — never silently dropped. (In server mode, with no
-subcommand, the same flags are passed directly: `dirsql -c <cfg>`.)
+'--config <CONFIG>'` — never silently dropped. (The default mode without the
+`query` keyword takes the same flags after the SQL: `dirsql "<sql>" -c <cfg>`;
+for the server they follow the subcommand: `dirsql server -c <cfg>`.)
 :::
 
 The subcommand builds the index, runs the SQL, prints the result rows as a
@@ -199,7 +220,7 @@ The output does **not** auto-load. Once you've tweaked it, pass it explicitly
 to run against it:
 
 ```bash
-dirsql -c ./.dirsql.toml
+dirsql "SELECT * FROM files" -c ./.dirsql.toml
 ```
 
 ### Flags

{dirsql-0.3.123 → dirsql-0.3.124/packages/python}/docs/reference/config.md

@@ -40,7 +40,7 @@ hook-timeout = 300
 ```
 
 Persistence is not a config key. Keep the SQLite index on disk between runs
-with the [`--persist [PATH]` CLI flag](./cli.md#server-mode) — a machine-local
+with the [`--persist [PATH]` CLI flag](./cli.md#dirsql-server) — a machine-local
 operational choice that belongs to the runner, not to shareable config.
 
 ## `[[dirsql.extension]]`

{dirsql-0.3.123 → dirsql-0.3.124/packages/python}/docs/reference/http-api.md

@@ -1,6 +1,6 @@
 # HTTP API
 
-The [`dirsql` server](./cli.md#server-mode) (default `localhost:7117`)
+The [`dirsql` server](./cli.md#dirsql-server) (default `localhost:7117`)
 exposes two endpoints: `POST /query` and `GET /events`.
 
 ## `POST /query`

{dirsql-0.3.123 → dirsql-0.3.124}/packages/python/docs/reference/sdk.md

@@ -130,7 +130,7 @@ shortcut was removed in #603 — use
   ephemeral, rebuilt every startup). The cache lives at
   `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
   changed are re-parsed. (The CLI exposes the same switch as the
-  [`--persist [PATH]`](./cli.md#server-mode) flag; it is not a config key.)
+  [`--persist [PATH]`](./cli.md#dirsql-server) flag; it is not a config key.)
 - `persist_path` / `persistPath` — Override the cache location. Ignored when
   persistence is off. Constructor values are used as given. In Rust these two
   parameters collapse into a single builder method: `.persist(None)` enables

dirsql-0.3.124/packages/python/e2e-attestations/feat-662-query-default-cli.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1784897776,
+  "exit_code": 0,
+  "commit": "93084d576d3080073dc2e0af6c20201de7def162",
+  "branch": "feat/662-query-default-cli"
+}

{dirsql-0.3.123 → dirsql-0.3.124}/packages/rust/README.md

@@ -121,10 +121,10 @@ while let Some(event) = stream.next().await {
 
 ```bash
 cargo install dirsql --features cli
-dirsql
+dirsql "SELECT * FROM './'"
 ```
 
-Running `dirsql` starts an HTTP server bound to `localhost:7117` that exposes the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Override with `--host`, `--port`, `--config`. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
+`dirsql "<sql>"` runs one query and prints the rows as JSON — the default. `dirsql server` starts an HTTP server bound to `localhost:7117` that exposes the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Override the bind with `dirsql server --host`, `--port`, `--config`. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
 
 The `cli` feature is **opt-in** -- `cargo add dirsql` pulls no CLI dependencies. `cargo install dirsql` without `--features cli` silently installs nothing (`required-features` skips the bin target with no warning); always include the flag, or use `npx dirsql` / `uvx dirsql` for prebuilt binaries.
 

dirsql-0.3.124/packages/rust/changelog.d/2026-07-23-query-default-cli.md

@@ -0,0 +1 @@
+**Changed** Query is now the default CLI behavior. `dirsql "<sql>"` (no subcommand) runs one query and prints JSON rows — the epic headline `dirsql "SELECT * FROM './'"` works directly. The HTTP server moved behind a new `dirsql server` subcommand, and `--host`/`--port`/`--persist` are now `server`-local flags. `dirsql query "<sql>"` is retained as an explicit synonym and `dirsql init` is unchanged. **Breaking:** bare `dirsql` no longer starts a server; run `dirsql server`. Bare `dirsql` with no SQL now errors with a hint pointing at `dirsql server` (#662).

{dirsql-0.3.123/packages/python → dirsql-0.3.124/packages/rust}/docs/getting-started.md

@@ -68,11 +68,11 @@ this directory anyway — from inside `my-notes`, run one command:
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT COUNT(*) AS files FROM './'"
+npx dirsql "SELECT COUNT(*) AS files FROM './'"
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT COUNT(*) AS files FROM './'"
+uvx dirsql "SELECT COUNT(*) AS files FROM './'"
 ```
 
 :::
@@ -168,11 +168,11 @@ pass it explicitly with `-c`, **after** the SQL:
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+npx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+uvx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
 ```
 
 :::

{dirsql-0.3.123 → dirsql-0.3.124/packages/rust}/docs/howto/load-extension.md

@@ -53,7 +53,7 @@ entrypoint = "sqlite3_vec_init"
 ```
 
 ```bash
-uvx --with sqlite-vec dirsql -c ./.dirsql.toml
+uvx --with sqlite-vec dirsql server -c ./.dirsql.toml
 ```
 
 **Node (`npx dirsql`, TypeScript SDK).** Use the *npm package name* — but

{dirsql-0.3.123 → dirsql-0.3.124/packages/rust}/docs/howto/persist.md

@@ -1,7 +1,7 @@
 # Keep the index across restarts
 
 By default the database is ephemeral: rebuilt from your files on every
-startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#server-mode)
+startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#dirsql-server)
 flag keeps the SQLite index on disk instead, so a restart only re-parses
 files that actually changed — the difference between seconds and
 milliseconds on large trees, and between re-running and skipping expensive

{dirsql-0.3.123 → dirsql-0.3.124/packages/rust}/docs/howto/react-to-changes.md

@@ -18,8 +18,8 @@ glob = "**/*"
 
 ## 1. Open the stream
 
-With the server running (`npx dirsql -c ./.dirsql.toml` /
-`uvx dirsql -c ./.dirsql.toml`), subscribe from another terminal:
+With the server running (`npx dirsql server -c ./.dirsql.toml` /
+`uvx dirsql server -c ./.dirsql.toml`), subscribe from another terminal:
 
 ```bash
 curl -N http://localhost:7117/events

{dirsql-0.3.123/packages/python → dirsql-0.3.124/packages/rust}/docs/howto/search-by-meaning.md

@@ -10,7 +10,7 @@ embed each question at query time.
 ::: tip Just want it working?
 [`dirsql-plugin-embeddings`](https://pypi.org/project/dirsql-plugin-embeddings/)
 packages exactly what this guide builds, ready to install:
-`uvx --with dirsql-plugin-embeddings dirsql`. Keep reading to see how it's
+`uvx --with dirsql-plugin-embeddings dirsql server`. Keep reading to see how it's
 built — the same three pieces, from scratch.
 :::