feat: shorter CLI forms for selection, global flags, JSON output, scope targets and cursors

Accept --project-dir, --no-color and --debug after the subcommand as well as
before it. Treat positional arguments to compile, plan, build, test, seed,
freshness, audit and check as selectors, combined with any --select values.
Add --json as shorthand for --format json on lineage and query. Let sqb scope
take bare model, source, seed and function names, resolved with the shared
target resolver; macros, enums, constants, tests and audits keep their prefix
and fail with C960 when written bare. Add --start-cursor and --end-cursor to
build, plan and load, typed from the selected models' cursor type; a
selection mixing timestamp and integer cursors fails with S303. The -ts and
-int flags keep working.

Author: kvlonge

src/sqlbuild/.agents/skills/sqlbuild/SKILL.md

@@ -58,11 +58,11 @@ JOIN __ref("stg_payments") p USING (order_id)
    than guessing how pieces connect.
 2. **Look at the data.** `sqb query "SELECT ..." --limit 20` runs SQL on the active target. Profile
    inputs (counts, nulls, key uniqueness) before writing joins.
-3. **Compile.** `sqb compile --select <models>` after every edit. It is offline and fast.
-4. **Plan.** `sqb plan --select <models>` shows exactly what a build will do and why. Read it before
+3. **Compile.** `sqb compile <models>` after every edit. It is offline and fast.
+4. **Plan.** `sqb plan <models>` shows exactly what a build will do and why. Read it before
    building, especially for incremental models, full refreshes and anything destructive.
-5. **Test.** `sqb test --select <models>` runs SQL unit tests without building.
-6. **Build.** `sqb build --select <models>` runs tests, builds, and runs audits in DAG order.
+5. **Test.** `sqb test <models>` runs SQL unit tests without building.
+6. **Build.** `sqb build <models>` runs tests, builds, and runs audits in DAG order.
    Use `--defer-to <target>` to read unselected upstream models from another target instead of
    rebuilding them.
 7. **Verify.** Prove the result is right with `sqb diff` (below), not only that it built.
@@ -79,13 +79,13 @@ the trigger applies.
 |---|---|
 | Check a refactor did not change results, or compare dev with prod | `sqb diff prod:dev --full --select <model>` |
 | Compare two arbitrary queries (old vs new logic, before vs after a fix, two tables) | `sqb diff --left-query "..." --right-query "..." --key <col>` |
-| Know what a model can see: which macros, enums and constants are visible, used, or unavailable | `sqb scope model:<name>` |
-| Fix "unknown macro/enum/constant", or decide where a declaration should live | `sqb scope model:<name> --explain macro:<name>` |
-| Preview whether moving a file breaks declaration visibility | `sqb scope model:<name> --as-path <new/path.sql>` |
+| Know what a model can see: which macros, enums and constants are visible, used, or unavailable | `sqb scope <name>` |
+| Fix "unknown macro/enum/constant", or decide where a declaration should live | `sqb scope <name> --explain macro:<name>` |
+| Preview whether moving a file breaks declaration visibility | `sqb scope <name> --as-path <new/path.sql>` |
 | Rename a model, move a model file, or rename a column | `sqb rename <old> <new>`, `sqb mv <name> <path/or/folder/>`, `sqb rename <model>.<column> <new>` (`model:`/`column:` prefixes optional) |
 | Find what a model depends on, or what breaks if it changes | `sqb lineage <model> --direction both` |
 | Trace where a column comes from, or who consumes it before renaming or dropping it | `sqb lineage <model>.<column> --direction downstream` |
-| See which intermediate models a SQL test will really execute | `sqb test --select <model> --inspect` |
+| See which intermediate models a SQL test will really execute | `sqb test <model> --inspect` |
 | Inspect the full graph as data | `sqb dag --json`, `sqb plan --json`, `sqb compile --json` |
 | Adopt an existing warehouse table's columns into a contract | `sqb contract generate --from <target> --select <model>` |
 | Try syntax safely in a throwaway DuckDB project | `sqb playground /tmp/sqb-sandbox` |
@@ -167,7 +167,7 @@ SQLBuild models downstream of them.
 
 ## Selectors
 
-`--select a b` unions, `--exclude` subtracts. `+model` includes upstream, `model+` downstream.
+`sqb build a b` (or `--select a b`) unions, `--exclude` subtracts. `+model` includes upstream, `model+` downstream.
 `tag:<tag>`, `path:models/marts` (or any value containing `/`), `seed:<name>`, `source:<name>`,
 and quoted name globs such as `"stg_*"`. They work with plan, build, test, audit, seed, clone and
 diff.

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/audit.md

@@ -11,15 +11,18 @@ Runs all attached audits without rebuilding models. Useful for verifying data qu
 ## Usage
 
 ```bash
-sqb --project-dir <path> audit [flags]
+sqb audit [SELECTOR ...] [flags]
 ```
 
+Positional `SELECTOR` arguments work like `--select`, and both forms can be combined. `--project-dir <path>`, `--no-color`, and `--debug` can go before or after the command name.
+
 ## Flags
 
 | Flag | Description |
 |------|-------------|
 | `--no-sql-analysis` | Disable compile-time SQL analysis (`--no-sql-validation` is an alias) |
 | `--defer-to` | Resolve model references against another target |
+| `SELECTOR ...` | Positional selectors, the same as `--select` |
 | `--select`, `-s` | Select audits attached to specific models |
 | `--select-file` | Read selectors from a file |
 | `--exclude` | Exclude audits attached to specific models |
@@ -62,7 +65,7 @@ guarantee immediate cancellation of a query already running in the warehouse.
 sqb audit
 
 # Run audits for marts only
-sqb audit --select path:models/marts
+sqb audit path:models/marts
 
 # Run up to 8 audit queries concurrently
 sqb audit --concurrency 8

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/build.md

@@ -25,13 +25,17 @@ Compiles, plans, and executes the selected build lifecycle, running the full sel
 ## Usage
 
 ```bash
-sqb --project-dir <path> build [flags]
+sqb build [SELECTOR ...] [flags]
 ```
 
+Positional `SELECTOR` arguments work like `--select`, and both forms can be combined.
+
 ## Global options
 
-These options apply to every `sqb` command and go before the command name, as in
-`sqb --debug build`:
+These options apply to every `sqb` command. `--project-dir`, `--no-color`, and `--debug` go
+before or after the command name, as in `sqb --debug build` or `sqb build --debug`. Under
+`sqb dbt`, put `--project-dir` before `dbt`: after it, `--project-dir` is passed to dbt as dbt's
+own option. `--version` works only directly after `sqb`, as in `sqb --version`:
 
 | Option | Description |
 |--------|-------------|
@@ -56,6 +60,8 @@ These options apply to every `sqb` command and go before the command name, as in
 | `--fail-fast` | Stop on first failure and skip remaining nodes |
 | `--concurrency` | Number of worker connections (default: 1) |
 | `--verbose`, `-v` | Show lifecycle SQL inline after each model |
+| `--start-cursor` | Override the start cursor, typed from the selected incremental models' cursor type; fails with `S303` if the selection mixes timestamp and integer cursors. With no cursor model selected, an integer value is read as an integer cursor and anything else as an ISO timestamp |
+| `--end-cursor` | Override the end cursor, typed the same way as `--start-cursor` |
 | `--start-cursor-ts` | Override start cursor for timestamp incremental models (ISO format) |
 | `--end-cursor-ts` | Override end cursor for timestamp incremental models (ISO format) |
 | `--start-cursor-int` | Override start cursor for integer incremental models |
@@ -65,6 +71,7 @@ These options apply to every `sqb` command and go before the command name, as in
 | `--reload` | Reload managed sources (passes `is_reload=True` to loaders) |
 | `--selection-diagnostics` | Warn when a selected model will build on changed upstream models that are not selected; see [Selection and staleness](../concepts/planning/selection-and-staleness.md) |
 | `--manifest` | Generate `target/manifest.json` with plan-aware project metadata |
+| `SELECTOR ...` | Positional selectors, the same as `--select` |
 | `--select`, `-s` | Select specific models |
 | `--exclude` | Exclude specific models |
 | `--warehouse <name>` | Snowflake warehouse for this invocation; overrides the target's `build` [warehouse group](../concepts/project-configuration.md#command-group-warehouses) and the connection warehouse |
@@ -132,7 +139,7 @@ statement or step still prints its `FAIL` row.
 Use `--defer-to` to resolve unselected model references against another target. This lets you build a subset of models in dev while referencing production tables for everything else:
 
 ```bash
-sqb build --select fact_orders --defer-to prod
+sqb build fact_orders --defer-to prod
 ```
 
 No `manifest.json` is required. `--defer-to` selects only the namespace used for unselected

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/check.md

@@ -11,13 +11,16 @@ Runs Python [checks](../concepts/python-nodes/checks.md) in isolation. Checks va
 ## Usage
 
 ```bash
-sqb --project-dir <path> check [flags]
+sqb check [SELECTOR ...] [flags]
 ```
 
+Positional `SELECTOR` arguments work like `--select`, and both forms can be combined. `--project-dir <path>`, `--no-color`, and `--debug` can go before or after the command name.
+
 ## Flags
 
 | Flag | Description |
 |------|-------------|
+| `SELECTOR ...` | Positional selectors, the same as `--select` |
 | `--select`, `-s` | Select checks to run (by name, `check:`, `tag:`, or graph expansion) |
 | `--exclude` | Exclude checks from the selection |
 | `--no-sql-analysis` | Disable compile-time SQL analysis (`--no-sql-validation` is an alias) |
@@ -35,10 +38,10 @@ Selecting a non-check node is rejected; use [`sqb build`](build.md) to run tasks
 sqb check
 
 # Run one check and its required dependencies
-sqb check --select +check_orders_exported
+sqb check +check_orders_exported
 
 # Run checks by tag
-sqb check --select tag:exports
+sqb check tag:exports
 
 # Print results as JSON
 sqb check --json

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/compile.md

@@ -23,9 +23,11 @@ Discovers the complete project, resolves references, expands macros, validates S
 ## Usage
 
 ```bash
-sqb --project-dir <path> compile [flags]
+sqb compile [SELECTOR ...] [flags]
 ```
 
+Positional `SELECTOR` arguments work like `--select`, and both forms can be combined. `--project-dir <path>`, `--no-color`, and `--debug` can go before or after the command name.
+
 ## Flags
 
 | Flag | Description |
@@ -36,6 +38,7 @@ sqb --project-dir <path> compile [flags]
 | `--json` | Output the full compile report as JSON |
 | `--manifest` | Generate `target/manifest.json` with project metadata |
 | `--lineage-mode` | Column lineage mode: `fast` (default), `rich` (slower, more detail), or `none` |
+| `SELECTOR ...` | Positional selectors, the same as `--select` |
 | `--select`, `-s` | Analyze and report selected resources |
 | `--select-file` | Read selectors from a file, one selector per line |
 | `--exclude` | Remove resources from the selected scope |
@@ -58,7 +61,7 @@ Use normal selectors to limit expensive analysis and reporting while retaining c
 discovery and reference integrity:
 
 ```bash
-sqb compile --select fact_orders daily_revenue
+sqb compile fact_orders daily_revenue
 sqb compile --select-file selected-models.txt
 sqb compile --exclude deprecated_model
 ```
@@ -284,7 +287,7 @@ sqb compile --lineage-mode none
 sqb compile --manifest
 
 # Compile only selected models
-sqb compile --select fact_orders daily_revenue
+sqb compile fact_orders daily_revenue
 
 # Disable SQL analysis
 sqb compile --no-sql-analysis

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/freshness.md

@@ -22,9 +22,11 @@ Observes the current data version of each source and reports whether the data ha
 ## Usage
 
 ```bash
-sqb --project-dir <path> freshness [flags]
+sqb freshness [SELECTOR ...] [flags]
 ```
 
+Positional `SELECTOR` arguments work like `--select`, and both forms can be combined. `--project-dir <path>`, `--no-color`, and `--debug` can go before or after the command name.
+
 ## Flags
 
 | Flag | Description |
@@ -35,6 +37,7 @@ sqb --project-dir <path> freshness [flags]
 | `--json` | Output as JSON instead of human-readable text |
 | `--json-output` | Write JSON output to a file path (also prints text to stdout unless `--json` is set) |
 | `--no-sql-analysis` | Disable compile-time SQL analysis (`--no-sql-validation` is an alias) |
+| `SELECTOR ...` | Positional selectors, the same as `--select` |
 | `--select`, `-s` | Select specific sources or models (sources upstream of selected models are included) |
 | `--exclude` | Exclude specific sources or models |
 | `--warehouse <name>` | Snowflake warehouse for this invocation; overrides the target's `query` [warehouse group](../concepts/project-configuration.md#command-group-warehouses) and the connection warehouse |
@@ -48,10 +51,10 @@ Without `--select`, all sources in the project are observed. When `--select` is
 sqb freshness
 
 # Observe a specific source
-sqb freshness --select raw_orders
+sqb freshness raw_orders
 
 # Observe sources upstream of a model
-sqb freshness --select fact_orders
+sqb freshness fact_orders
 ```
 
 ## Observation without state

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/lineage.md

@@ -41,6 +41,7 @@ Exactly one of a positional target or `--select` is required.
 | `--direction` | `upstream` (default), `downstream`, or `both`. `both` is only available for model lineage. |
 | `--depth` | How many hops to traverse. An integer or `all` (default: `all`). |
 | `--format` | Output format: `tree` (default), `list`, or `json`. |
+| `--json` | Shorthand for `--format json`. |
 | `--mode` | Column lineage analysis mode: `rich` (default) or `fast`. |
 | `--no-sql-analysis` | Disable compile-time SQL analysis (`--no-sql-validation` is an alias). |
 | `--select`, `-s` | Select resources using the same selector syntax as `sqb compile`, `sqb plan` and `sqb build`, for example `path:models/marts`, `tag:finance` or `stg_*`. |
@@ -101,7 +102,7 @@ source:raw__payments        -> model:stg_payments
 Structured output with nodes, edges, and metadata:
 
 ```bash
-sqb lineage fact_orders --format json
+sqb lineage fact_orders --json
 ```
 
 ```json
@@ -173,7 +174,7 @@ raw__payments.amount_cents -> stg_payments.amount_cents direct
 ### JSON
 
 ```bash
-sqb lineage fact_orders.total_cents --format json
+sqb lineage fact_orders.total_cents --json
 ```
 
 ```json
@@ -240,7 +241,7 @@ sqb lineage --select "stg_orders~daily_activity_rollup"
 sqb lineage --select "+fact_orders"
 
 # JSON output for programmatic consumption
-sqb lineage fact_orders --format json --direction upstream
+sqb lineage fact_orders --json --direction upstream
 ```
 
 ## Depth limiting

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/load.md

@@ -22,6 +22,8 @@ sqb --project-dir <path> load [flags]
 | `--exclude` | Exclude specific sources or loaders |
 | `--reload` | Pass `is_reload=True` to loader functions |
 | `--concurrency` | Number of worker connections (default: from settings or 1) |
+| `--start-cursor` | Override the start cursor; an integer value sets `start_cursor_int`, anything else is read as an ISO timestamp and sets `start_cursor_ts` |
+| `--end-cursor` | Override the end cursor, typed the same way as `--start-cursor` |
 | `--start-cursor-ts` | Override start cursor for timestamp-based loaders (ISO format) |
 | `--end-cursor-ts` | Override end cursor for timestamp-based loaders (ISO format) |
 | `--start-cursor-int` | Override start cursor for integer-based loaders |
@@ -47,7 +49,7 @@ sqb load --concurrency 4
 sqb load --reload
 
 # Override cursor bounds
-sqb load --start-cursor-ts "2026-05-01T00:00:00"
+sqb load --start-cursor "2026-05-01T00:00:00"
 ```
 
 ## Execution order

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/plan.md

@@ -19,9 +19,11 @@ Shows the execution plan without making any changes. Useful for inspecting chang
 ## Usage
 
 ```bash
-sqb --project-dir <path> plan [flags]
+sqb plan [SELECTOR ...] [flags]
 ```
 
+Positional `SELECTOR` arguments work like `--select`, and both forms can be combined. `--project-dir <path>`, `--no-color`, and `--debug` can go before or after the command name.
+
 ## Flags
 
 | Flag | Description |
@@ -34,10 +36,13 @@ sqb --project-dir <path> plan [flags]
 | `--json` | Output the plan as JSON |
 | `--selection-diagnostics` | Warn when a selected model will build on changed upstream models that are not selected; see [Selection and staleness](../concepts/planning/selection-and-staleness.md) |
 | `--full-refresh` | Plan a full rebuild for selected models unless a model sets `full_refresh false`; `full_refresh true` forces a model without this flag |
+| `--start-cursor` | Override the start cursor, typed from the selected incremental models' cursor type; fails with `S303` if the selection mixes timestamp and integer cursors. With no cursor model selected, an integer value is read as an integer cursor and anything else as an ISO timestamp |
+| `--end-cursor` | Override the end cursor, typed the same way as `--start-cursor` |
 | `--start-cursor-ts` | Override start cursor for timestamp incremental models (ISO format) |
 | `--end-cursor-ts` | Override end cursor for timestamp incremental models (ISO format) |
 | `--start-cursor-int` | Override start cursor for integer incremental models |
 | `--end-cursor-int` | Override end cursor for integer incremental models |
+| `SELECTOR ...` | Positional selectors, the same as `--select` |
 | `--select`, `-s` | Select specific models |
 | `--exclude` | Exclude specific models |
 | `--warehouse <name>` | Snowflake warehouse for this invocation; overrides the target's `build` [warehouse group](../concepts/project-configuration.md#command-group-warehouses) and the connection warehouse |

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/query.md

@@ -6,6 +6,14 @@
 
 Online: https://sqlbuild.com/docs/cli/query/
 
+## Contents
+
+- Usage
+- Flags
+- Output formats
+- Errors
+- Examples
+
 Execute ad hoc SQL against the active project connection. Useful for inspecting data, debugging models, or running one-off queries without leaving the SQLBuild CLI.
 
 ## Usage
@@ -29,6 +37,7 @@ File paths are resolved from the current working directory.
 | `sql` | SQL to execute (positional argument) |
 | `--file` | Read SQL from a file instead of the command line |
 | `--format` | Output format: `long` (default), `table`, `json`, or `csv` |
+| `--json` | Shorthand for `--format json` |
 | `--limit` | Maximum rows to return (default: 20) |
 | `--no-limit` | Disable the row limit |
 | `--warehouse <name>` | Snowflake warehouse for this invocation; overrides the target's `query` [warehouse group](../concepts/project-configuration.md#command-group-warehouses) and the connection warehouse |
@@ -101,7 +110,7 @@ sqb query "SELECT * FROM dev.fact_orders"
 sqb query "SELECT * FROM dev.dim_customers" --format table --limit 50
 
 # Export to JSON
-sqb query "SELECT * FROM dev.daily_revenue" --format json --no-limit
+sqb query "SELECT * FROM dev.daily_revenue" --json --no-limit
 
 # Run SQL from a file
 sqb query --file debug_query.sql