dirsql 0.3.125 → 0.3.126

package/README.md

@@ -89,7 +89,7 @@ Each event has `.action` (`'insert'` | `'update'` | `'delete'` | `'error'`), `.t
 
 ## CLI
 
-`npx dirsql` runs an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Requires **Node >= 20.11**. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
+`npx dirsql "<sql>"` runs one query and prints the rows as JSON — the default. `npx 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. Requires **Node >= 20.11**. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
 
 ## License
 

package/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
 ```
 
 :::

package/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

package/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

package/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

package/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.
 :::
 

package/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

package/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]]`

package/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`

package/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.3.125",
+  "version": "0.3.126",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -212,15 +212,15 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.3.125",
-    "@dirsql/lib-linux-arm64-gnu": "0.3.125",
-    "@dirsql/lib-darwin-x64": "0.3.125",
-    "@dirsql/lib-darwin-arm64": "0.3.125",
-    "@dirsql/lib-win32-x64-msvc": "0.3.125",
-    "@dirsql/cli-linux-x64-gnu": "0.3.125",
-    "@dirsql/cli-linux-arm64-gnu": "0.3.125",
-    "@dirsql/cli-darwin-x64": "0.3.125",
-    "@dirsql/cli-darwin-arm64": "0.3.125",
-    "@dirsql/cli-win32-x64-msvc": "0.3.125"
+    "@dirsql/lib-linux-x64-gnu": "0.3.126",
+    "@dirsql/lib-linux-arm64-gnu": "0.3.126",
+    "@dirsql/lib-darwin-x64": "0.3.126",
+    "@dirsql/lib-darwin-arm64": "0.3.126",
+    "@dirsql/lib-win32-x64-msvc": "0.3.126",
+    "@dirsql/cli-linux-x64-gnu": "0.3.126",
+    "@dirsql/cli-linux-arm64-gnu": "0.3.126",
+    "@dirsql/cli-darwin-x64": "0.3.126",
+    "@dirsql/cli-darwin-arm64": "0.3.126",
+    "@dirsql/cli-win32-x64-msvc": "0.3.126"
   }
 }