Command API

Ashiba command contracts are exposed by the same CLI command catalog used by ashiba describe command and command help.

This page is for third-party readers who need to understand what commands exist, when to use them, and what their arguments and options mean.

Each command section includes the real Commander help output so the docs do not maintain a separate argument or option explanation.

npx ashiba --help
npx ashiba <command> --help
npx ashiba describe command --format json

Command List

npx ashiba check

Run the human-first Ashiba diagnostic gate.

Use when: Use the fast local loop while editing; add --full before push, review, or CI to include mapper tests.

CLI Help

Usage: ashiba check [options]

Run the human-first Ashiba diagnostic gate

Options:
  --root-dir <path>                Project root directory (default: ".")
  --format <format>                Output format: text or json (default:
                                   "text")
  --warnings-as-errors             Treat warnings as check failures (default:
                                   false)
  --fast                           Run the fast local check only. This is the
                                   default. (default: false)
  --full                           Run the fast check and the configured mapper
                                   test command. (default: false)
  --mapper-test-command <command>  Mapper test command used by --full (default:
                                   "npx vitest run")
  -h, --help                       display help for command

Catalog use case:
  Use the fast local loop while editing; add --full before push, review, or CI to include mapper tests.

Examples:
  npx ashiba check
  npx ashiba check --full --mapper-test-command "vitest run"

npx ashiba init

Create a SQL-first starter after the user has chosen a DBMS and driver.

Use when: Start a new Ashiba project with visible SQL, DDL, ZTD test support, and no AI behavior files.

CLI Help

Usage: ashiba init [options]

Create a SQL-first starter after the user has chosen a DBMS and driver

Options:
  --dir <path>               Target directory for the starter (default: ".")
  --db <dbms>                Database starter to scaffold. Currently supported:
                             postgres
  --driver <driver>          Wrapped driver starter to scaffold. Currently
                             supported: pg for postgres
  --with-demo-ddl            Create demo DDL under db/ddl for the starter
                             feature flow (default: false)
  --with-migration-demo-ddl  Create a temporary old DDL snapshot under tmp/ddl
                             for migration tutorial flow (default: false)
  --force                    Overwrite starter-owned files when they already
                             exist (default: false)
  --dry-run                  Print the files that would be created without
                             writing them (default: false)
  -h, --help                 display help for command

Catalog use case:
  Start a new Ashiba project with visible SQL, DDL, ZTD test support, and no AI behavior files.

Examples:
  npx ashiba init --db postgres --driver pg --with-demo-ddl

npx ashiba config

Emit Ashiba project configuration.

Use when: Create or inspect ashiba.config.json; use --compact for machine-readable one-line JSON.

CLI Help

Usage: ashiba config [options]

Emit Ashiba project configuration

Options:
  --compact   Print compact JSON (default: false)
  -h, --help  display help for command

Catalog use case:
  Create or inspect ashiba.config.json; use --compact for machine-readable one-line JSON.

Examples:
  npx ashiba config
  npx ashiba config --compact

npx ashiba describe command

Describe one command or list the command catalog for humans and AI agents.

Use when: Let an AI or reviewer understand the intended command surface before choosing a workflow.

CLI Help

Usage: ashiba describe command [options] [name...]

Describe one command or list the command catalog for humans and AI agents

Options:
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Let an AI or reviewer understand the intended command surface before choosing a workflow.

Examples:
  npx ashiba describe command
  npx ashiba describe command query optional add --format json

npx ashiba gate scaffold

Scaffold the standard passive check gates without adding hook libraries.

Use when: Run this once to create package scripts, GitHub Actions, and a native git hook file so drift is caught in the ordinary path.

CLI Help

Usage: ashiba gate scaffold [options]

Scaffold the standard passive check gates without adding hook libraries

Options:
  --target <target>  Advanced target: all, package-scripts, github-actions, or
                     git-hooks (default: "all")
  --root-dir <path>  Project root directory (default: ".")
  --force            Overwrite existing generated files when applicable
                     (default: false)
  -h, --help         display help for command

Catalog use case:
  Run this once to create package scripts, GitHub Actions, and a native git hook file so drift is caught in the ordinary path.

Examples:
  npx ashiba gate scaffold
  npx ashiba gate scaffold --target github-actions

npx ashiba ddl migration generate

Compare DDL snapshot files or recursive DDL directories, generate reviewable migration SQL, and include migration risk info.

Use when: Review a schema change before DB deployment without connecting to or mutating a database.

CLI Help

Usage: ashiba ddl migration generate [options]

Compare DDL snapshot files or recursive DDL directories, generate reviewable
migration SQL, and include migration risk info

Options:
  --from <path>          Current or old DDL snapshot file
  --to <path>            Desired or new DDL snapshot file
  --from-dir <path>      Current or old DDL snapshot directory; reads .sql
                         files recursively in stable order
  --to-dir <path>        Desired or new DDL snapshot directory; reads .sql
                         files recursively in stable order
  --from-git <ref:path>  Current or old DDL snapshot from a git ref, for
                         example main:db/ddl
  --to-git <ref:path>    Desired or new DDL snapshot from a git ref, for
                         example feature/schema:db/ddl
  --out <path>           Write generated migration SQL to this file
  --dry-run              Preview generated migration SQL without writing --out
                         (default: false)
  --no-drop-tables       Do not emit DROP TABLE statements even when table
                         drops are detected
  --no-drop-columns      Do not emit DROP COLUMN statements even when column
                         drops are detected
  --no-drop-constraints  Do not emit DROP CONSTRAINT statements even when
                         constraint drops are detected
  --no-drop-indexes      Do not emit DROP INDEX statements even when index
                         drops are detected
  --format <format>      Output format: text or json (default: "text")
  -h, --help             display help for command

Catalog use case:
  Review a schema change before DB deployment without connecting to or mutating a database.

Combinations and notes:
  - Use --from/--to for single DDL snapshot files, --from-dir/--to-dir for recursive DDL directories, or --from-git/--to-git for a committed git ref plus path.
  - --from, --from-dir, or --from-git means the current/old database shape. --to, --to-dir, or --to-git means the desired/new local DDL shape.
  - Use --out when you want a migration SQL artifact. Use --dry-run when you only want to preview.
  - Use --no-drop-tables, --no-drop-columns, --no-drop-constraints, and --no-drop-indexes when Ashiba should report destructive differences without emitting destructive SQL.
  - --format json is for machine-readable migration risk reporting; text is for review in a terminal.

Examples:
  npx ashiba ddl migration generate --from-dir path/to/current-db-ddl --to-dir db/ddl --out tmp/ddl/migration.sql --no-drop-tables --no-drop-columns --no-drop-constraints
  npx ashiba ddl migration generate --from-git main:db/ddl --to-dir db/ddl --out tmp/ddl/migration.sql

npx ashiba feature scaffold

Scaffold editable feature-local SQL boundaries.

Use when: Create a reviewable feature entrypoint, query.ts, SQL, DTO contracts, and mapper tests from DDL.

CLI Help

Usage: ashiba feature scaffold [options] <name>

Scaffold editable feature-local SQL boundaries

Options:
  --table <table>    Target table name
  --action <action>  Action: insert, update, delete, get-by-id, or list
  --root-dir <path>  Project root directory (default: ".")
  --dry-run          Print the files that would be created without writing them
                     (default: false)
  --force            Overwrite scaffold-owned files when they already exist
                     (default: false)
  -h, --help         display help for command

Catalog use case:
  Create a reviewable feature entrypoint, query.ts, SQL, DTO contracts, and mapper tests from DDL.

Examples:
  npx ashiba feature scaffold users-list --table users --action list

npx ashiba feature import

Import an existing SQL file into a feature query boundary.

Use when: Start from SQL that already exists, then generate the feature shell, DTO contracts, mapper metadata, and ZTD mapper tests around that visible SQL.

CLI Help

Usage: ashiba feature import [options] <feature> <query>

Import an existing SQL file into a feature query boundary

Options:
  --sql <path>       Existing SQL file to copy into the feature query boundary
  --root-dir <path>  Project root directory (default: ".")
  --dry-run          Print the files that would be created without writing them
                     (default: false)
  --force            Overwrite scaffold-owned files when they already exist
                     (default: false)
  -h, --help         display help for command

Catalog use case:
  Start from SQL that already exists, then generate the feature shell, DTO contracts, mapper metadata, and ZTD mapper tests around that visible SQL.

Combinations and notes:
  - The source SQL file is copied, not moved.
  - Ashiba formats the copied SQL only when the formatter safety check proves the token/comment/AST output is stable.
  - Generated mapper cases cover inferable DB/TypeScript mapping; business boundary-value cases remain human/AI-owned under tests/cases/.

Examples:
  npx ashiba feature import users-search search --sql tmp/search-users.sql

npx ashiba feature query scaffold

Add another editable query boundary under an existing feature.

Use when: Grow a feature by adding a second SQL behavior without regenerating or hiding existing code.

CLI Help

Usage: ashiba feature query scaffold [options] <feature> <query>

Add another editable query boundary under an existing feature

Options:
  --table <table>    Target table name
  --action <action>  Action: insert, update, delete, get-by-id, or list
  --root-dir <path>  Project root directory (default: ".")
  --dry-run          Print the files that would be created without writing them
                     (default: false)
  --force            Overwrite scaffold-owned query files when they already
                     exist (default: false)
  -h, --help         display help for command

Catalog use case:
  Grow a feature by adding a second SQL behavior without regenerating or hiding existing code.

Examples:
  npx ashiba feature query scaffold users get-by-id --table users --action get-by-id

npx ashiba feature query refresh

Refresh generated query model metadata after SQL-only edits.

Use when: Fix drift after a human or AI edits the SQL file.

CLI Help

Usage: ashiba feature query refresh [options] <feature> <query>

Refresh generated query model metadata after SQL-only edits

Options:
  --root-dir <path>  Project root directory (default: ".")
  --dry-run          Print the refresh result without writing generated query
                     metadata (default: false)
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Fix drift after a human or AI edits the SQL file.

Examples:
  npx ashiba feature query refresh users-list list

npx ashiba feature tests scaffold

Scaffold feature-local mapper and logic test files.

Use when: Add generated mapping cases and human-owned logic case placeholders to an existing query boundary.

CLI Help

Usage: ashiba feature tests scaffold [options] <feature>

Scaffold feature-local mapper and logic test files

Options:
  --query <name>     Limit scaffolding to one query boundary
  --root-dir <path>  Project root directory (default: ".")
  --dry-run          Print the files that would be created without writing them
                     (default: false)
  --force            Overwrite scaffold-owned test files when they already
                     exist (default: false)
  -h, --help         display help for command

Catalog use case:
  Add generated mapping cases and human-owned logic case placeholders to an existing query boundary.

Examples:
  npx ashiba feature tests scaffold users-list
  npx ashiba feature tests scaffold users-list --query list

npx ashiba feature tests check

Check and optionally fix generated mapping test assets.

Use when: Detect missing generated mapping coverage after DDL or query changes.

CLI Help

Usage: ashiba feature tests check [options] [feature]

Check and optionally fix generated mapping test assets

Options:
  --boundary-dir <path>  Explicit feature boundary directory, including
                         subgrouped boundaries
  --query <name>         Limit check to one query boundary
  --root-dir <path>      Project root directory (default: ".")
  --fix                  Rewrite generated mapping test assets and create
                         missing logic-case stubs (default: false)
  --format <format>      Output format: text or json (default: "text")
  -h, --help             display help for command

Catalog use case:
  Detect missing generated mapping coverage after DDL or query changes.

Examples:
  npx ashiba feature tests check
  npx ashiba feature tests check users-list --fix

npx ashiba feature generated-mapper check

Check named-parameter and result-column drift between SQL and editable query contracts.

Use when: Find contract drift before running or publishing generated application code.

CLI Help

Usage: ashiba feature generated-mapper check [options] [feature]

Check named-parameter and result-column drift between SQL and editable query
contracts

Options:
  --boundary-dir <path>  Limit drift check to one explicit feature boundary
                         directory, including subgrouped boundaries
  --query <name>         Limit drift check to one query boundary
  --root-dir <path>      Project root directory (default: ".")
  --format <format>      Output format: text or json (default: "text")
  -h, --help             display help for command

Catalog use case:
  Find contract drift before running or publishing generated application code.

Examples:
  npx ashiba feature generated-mapper check
  npx ashiba feature generated-mapper check users-list --query list

npx ashiba project check

Aggregate passive project safety checks for DDL, SQL, contracts, and generated feature assets.

Use when: Catch discontinuous-work drift in the normal verify path instead of relying on humans to remember each refresh step.

CLI Help

Usage: ashiba project check [options]

Aggregate passive project safety checks for DDL, SQL, contracts, and generated
feature assets

Options:
  --root-dir <path>     Project root directory (default: ".")
  --format <format>     Output format: text or json (default: "text")
  --warnings-as-errors  Treat warnings as check failures (default: false)
  -h, --help            display help for command

Catalog use case:
  Catch discontinuous-work drift in the normal verify path instead of relying on humans to remember each refresh step.

Examples:
  npx ashiba project check
  npx ashiba project check --warnings-as-errors

npx ashiba check-contract

Check visible SQL contracts against generated mapper boundaries.

Use when: Run a broad drift check before commit or release.

CLI Help

Usage: ashiba check-contract [options]

Check visible SQL contracts against generated mapper boundaries

Options:
  --root-dir <path>   Project root directory (default: ".")
  --feature <name>    Limit check to one feature
  --query <name>      Limit check to one query boundary
  --scope-dir <path>  Limit QuerySpec-like catalog checks to one subtree
  --sql-root <path>   Fallback root for shared sqlFile layouts
  --format <format>   Output format: text or json (default: "text")
  -h, --help          display help for command

Catalog use case:
  Run a broad drift check before commit or release.

Examples:
  npx ashiba check-contract
  npx ashiba check-contract --feature users-list --query list

npx ashiba model-gen

Generate editable query contracts and generated query metadata files from visible SQL.

Use when: Use Ashiba metadata generation outside the feature scaffold flow.

CLI Help

Usage: ashiba model-gen [options] <sqlFile>

Generate editable query contracts and generated query metadata files from
visible SQL

Arguments:
  sqlFile            SQL file to inspect

Options:
  --out <file>       Write the generated TypeScript scaffold to this file
  --id <id>          Override the query id
  --root-dir <path>  Project root directory (default: ".")
  --ddl-dir <path>   Optional DDL directory for static row type hints
  --dry-run          Print the generated scaffold without writing it (default:
                     false)
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Use Ashiba metadata generation outside the feature scaffold flow.

Examples:
  npx ashiba model-gen src/features/users/queries/list/list.sql --out src/features/users/queries/list/query.ts

npx ashiba lint

Aggregate SQL lint over a file or directory.

Use when: Run project-level SQL maintainability checks in CI or before review.

CLI Help

Usage: ashiba lint [options] <path>

Aggregate SQL lint over a file or directory

Arguments:
  path               SQL file or directory to lint

Options:
  --root-dir <path>  Project root for config and DDL-aware rules (default: ".")
  --ddl-dir <path>   DDL directory for DDL-aware table and column checks
  --format <format>  Output format: text or json (default: "text")
  --rules <list>     Comma-separated query lint rules
  -h, --help         display help for command

Catalog use case:
  Run project-level SQL maintainability checks in CI or before review.

Examples:
  npx ashiba lint src/features
  npx ashiba lint src/features --rules join-direction

npx ashiba query uses table

Find SQL assets that reference a table.

Use when: Estimate impact before renaming, dropping, or changing a table.

CLI Help

Usage: ashiba query uses table [options] <target>

Find SQL assets that reference a table

Options:
  --format <format>        Output format: text or json (default: "text")
  --view <view>            Investigation view: impact or detail (default:
                           "impact")
  --root-dir <path>        Project root to scan (default:
                           "/home/runner/work/ashiba/ashiba")
  --scope-dir <path>       Limit discovery to one QuerySpec subtree
  --sql-root <path>        Fallback root for shared sqlFile layouts
  --exclude-generated      Exclude QuerySpec files under generated directories
  --any-schema             Allow <table> lookup across schemas
  --allow-parser-fallback  Allow explicit regex fallback when AST parsing fails
                           for table usage
  -h, --help               display help for command

Catalog use case:
  Estimate impact before renaming, dropping, or changing a table.

Combinations and notes:
  - Use this before renaming, dropping, or changing a table to find SQL files that mention it.
  - --root-dir controls the project tree to scan. Use it when running outside the project root.
  - --scope-dir narrows discovery to one subtree when you only want to inspect one feature or package area.
  - --sql-root is a fallback for shared sqlFile layouts that are not under the discovered feature roots.
  - --any-schema lets users search by table name without requiring the schema prefix.
  - --view impact gives a compact review list. --view detail is better when investigating why a match was found.

Examples:
  npx ashiba query uses table public.users --root-dir .

npx ashiba query uses column

Find SQL assets that reference a column.

Use when: Estimate impact before renaming, dropping, changing type/nullability, or changing semantics of a column.

CLI Help

Usage: ashiba query uses column [options] <target>

Find SQL assets that reference a column

Options:
  --format <format>        Output format: text or json (default: "text")
  --view <view>            Investigation view: impact or detail (default:
                           "impact")
  --root-dir <path>        Project root to scan (default:
                           "/home/runner/work/ashiba/ashiba")
  --scope-dir <path>       Limit discovery to one QuerySpec subtree
  --sql-root <path>        Fallback root for shared sqlFile layouts
  --exclude-generated      Exclude QuerySpec files under generated directories
  --any-schema             Allow <table.column> or <column> lookup across
                           schemas
  --any-table              Allow <column> lookup across tables; requires
                           --any-schema
  --allow-parser-fallback  Allow explicit parser-failure diagnostics instead of
                           failing the command
  -h, --help               display help for command

Catalog use case:
  Estimate impact before renaming, dropping, changing type/nullability, or changing semantics of a column.

Combinations and notes:
  - Use this before renaming, dropping, changing type/nullability, or changing the meaning of a column.
  - --root-dir controls the project tree to scan. Use it when running outside the project root.
  - --any-schema allows schema-agnostic lookup. --any-table allows column-only lookup and requires --any-schema.
  - --view impact is for quick review. --view detail is for investigating individual matches.

Examples:
  npx ashiba query uses column public.users.email --root-dir .

npx ashiba query outline

Describe CTE and statement structure for a SQL file.

Use when: Understand a complex SQL file before editing it or refreshing metadata.

CLI Help

Usage: ashiba query outline [options] <sqlFile>

Describe CTE and statement structure for a SQL file

Options:
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Understand a complex SQL file before editing it or refreshing metadata.

Examples:
  npx ashiba query outline src/features/users/queries/list/list.sql

npx ashiba query graph

Build a dependency graph for CTE-heavy SQL.

Use when: See how CTEs depend on each other when reviewing a large query.

CLI Help

Usage: ashiba query graph [options] <sqlFile>

Build a dependency graph for CTE-heavy SQL

Options:
  --format <format>  Output format: text, json, or dot (default: "text")
  -h, --help         display help for command

Catalog use case:
  See how CTEs depend on each other when reviewing a large query.

Examples:
  npx ashiba query graph path/to/query.sql --format dot

npx ashiba query slice

Extract a runnable SQL slice around a target CTE or final query.

Use when: Debug a complex CTE by running one intermediate point in a SQL client to find where rows or values break.

CLI Help

Usage: ashiba query slice [options] <sqlFile>

Extract a runnable SQL slice around a target CTE or final query

Options:
  --cte <name>     Slice a specific CTE into a standalone debug query
  --final          Slice the final query while removing unused CTEs
  --limit <count>  Add LIMIT to the emitted debug query when supported
  -h, --help       display help for command

Catalog use case:
  Debug a complex CTE by running one intermediate point in a SQL client to find where rows or values break.

Examples:
  npx ashiba query slice path/to/query.sql --cte filtered_users --limit 50

npx ashiba query format

Format SQL using Ashiba SQL style when the rewrite is loss-safe.

Use when: Normalize generated or reviewed SQL while refreshing query metadata after writes and refusing rewrites that would drop comments or fail AST round-trip validation.

CLI Help

Usage: ashiba query format [options] [sqlFile]

Format SQL using Ashiba SQL style when the rewrite is loss-safe

Options:
  --format <format>  Output format: text or json (default: "text")
  --root-dir <path>  Project root for ashiba.config.json (default:
                     "/home/runner/work/ashiba/ashiba")
  --all              Format every .sql file under ashiba.config.json sqlRoots
  --write            Write formatted SQL back to the file when the rewrite is
                     safe
  --check            Fail when formatting would change the file or the rewrite
                     is unsafe
  --diff             Emit a unified diff instead of formatted SQL
  -h, --help         display help for command

Catalog use case:
  Normalize generated or reviewed SQL while refreshing query metadata after writes and refusing rewrites that would drop comments or fail AST round-trip validation.

Combinations and notes:
  - Ashiba formatting is AST-based, not CST-based. It validates round-trip output and refuses unsafe writes.
  - Comments are treated as review context. If formatting would lose comments, Ashiba skips the rewrite.
  - --write refreshes generated/query.meta.ts for feature query SQL so formatting does not create metadata drift.
  - --all uses the configured sqlRoots from ashiba.config.json and processes .sql files in stable order.

Examples:
  npx ashiba query format src/features/users/queries/list/list.sql --diff
  npx ashiba query format src/features/users/queries/list/list.sql --write
  npx ashiba query format --all --write
  npx ashiba query format --all --check

npx ashiba query lint

Report structural SQL maintainability risks.

Use when: Catch query shapes that are hard to review, maintain, or analyze before they enter a feature boundary.

CLI Help

Usage: ashiba query lint [options] <sqlFile>

Report structural SQL maintainability risks

Options:
  --format <format>  Output format: text or json (default: "text")
  --root-dir <path>  Project root for config and DDL-aware rules (default:
                     "/home/runner/work/ashiba/ashiba")
  --rules <list>     Comma-separated lint rules to enable, for example:
                     join-direction
  -h, --help         display help for command

Catalog use case:
  Catch query shapes that are hard to review, maintain, or analyze before they enter a feature boundary.

Examples:
  npx ashiba query lint path/to/query.sql

npx ashiba query optional add

Add an SSSQL optional search condition branch and refresh query metadata.

Use when: Use SSSQL notation, for example (:email is null or users.email = :email), while keeping runtime behavior metadata-backed.

CLI Help

Usage: ashiba query optional add [options] <sqlFile>

Add an SSSQL optional search condition branch and refresh query metadata

Options:
  --format <format>        Output format: text or json (default: "text")
  --filter <name>          Target column for scalar scaffold, or primary anchor
                           column for EXISTS/NOT EXISTS
  --parameter <name>       Explicit parameter name for structured
                           optional-condition scaffold
  --operator <operator>    Scalar operator
  --kind <kind>            Structured branch kind: scalar, exists, or
                           not-exists
  --query <sql>            Subquery SQL for EXISTS/NOT EXISTS scaffold
  --query-file <path>      Read subquery SQL for EXISTS/NOT EXISTS scaffold
                           from a file
  --anchor-column <names>  Comma-separated anchor columns used by $c0, $c1
                           placeholders
  --root-dir <path>        Project root for query metadata refresh (default:
                           "/home/runner/work/ashiba/ashiba")
  --ddl-dir <path>         Optional DDL directory for static row type hints
  --preview                Emit a unified diff without writing files
  --out <path>             Write output to file
  -h, --help               display help for command

Catalog use case:
  Use SSSQL notation, for example (:email is null or users.email = :email), while keeping runtime behavior metadata-backed.

Combinations and notes:
  - Ashiba writes only when rawsql-ts reports that the edit is limited to the target SSSQL branch.

Examples:
  npx ashiba query optional add path/to/query.sql --filter email --operator =
  npx ashiba query optional add path/to/query.sql --kind exists --filter user_id --query "select 1 from orders where orders.user_id = $c0"

npx ashiba query optional refresh

Refresh SSSQL optional-condition metadata after SQL edits.

Use when: Regenerate metadata when the SQL still owns the intended optional filter shape. See docs/guide/sssql.md for the notation.

CLI Help

Usage: ashiba query optional refresh [options] <sqlFile>

Refresh SSSQL optional-condition metadata after SQL edits

Options:
  --format <format>  Output format: text or json (default: "text")
  --preview          Emit a unified diff without writing files
  --out <path>       Write output to file
  -h, --help         display help for command

Catalog use case:
  Regenerate metadata when the SQL still owns the intended optional filter shape. See docs/guide/sssql.md for the notation.

Combinations and notes:
  - Ashiba refuses to write when refreshing SSSQL metadata would require reformatting unrelated SQL.

Examples:
  npx ashiba query optional refresh path/to/query.sql

npx ashiba query optional remove

Remove an SSSQL optional search condition branch and refresh query metadata.

Use when: Delete optional-condition scaffolding without hand-editing metadata.

CLI Help

Usage: ashiba query optional remove [options] <sqlFile>

Remove an SSSQL optional search condition branch and refresh query metadata

Options:
  --format <format>      Output format: text or json (default: "text")
  --all                  Remove all recognized optional condition branches in
                         the query
  --parameter <name>     Parameter name that identifies the target branch
  --kind <kind>          Optional branch kind filter
  --operator <operator>  Optional scalar operator filter
  --target <target>      Optional target column filter
  --preview              Emit a unified diff without writing files
  --out <path>           Write output to file
  -h, --help             display help for command

Catalog use case:
  Delete optional-condition scaffolding without hand-editing metadata.

Combinations and notes:
  - Ashiba removes only recognized SSSQL branches and refuses unsafe broad rewrites.

Examples:
  npx ashiba query optional remove path/to/query.sql --parameter email
  npx ashiba query optional remove path/to/query.sql --all

npx ashiba perf init

Scaffold the traditional performance lane.

Use when: Start an application-owned tuning scenario for realistic row counts and indexes.

CLI Help

Usage: ashiba perf init [options]

Scaffold the traditional performance lane

Options:
  --root-dir <path>  Project root directory (default: ".")
  --dry-run          Print the files that would be created without writing them
                     (default: false)
  --force            Overwrite perf scaffold files when they already exist
                     (default: false)
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Start an application-owned tuning scenario for realistic row counts and indexes.

Examples:
  npx ashiba perf init

npx ashiba perf run

Inspect a performance run plan without owning DB execution.

Use when: Check benchmark parameters before an application-owned traditional DB-backed performance test.

CLI Help

Usage: ashiba perf run [options]

Inspect a performance run plan without owning DB execution

Options:
  --query <path>     SQL file to benchmark in the application-owned performance
                     lane
  --params <path>    JSON parameter file for the benchmark query
  --root-dir <path>  Project root directory (default: ".")
  --dry-run          Inspect the run plan without executing a DB query
                     (default: false)
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Check benchmark parameters before an application-owned traditional DB-backed performance test.

Examples:
  npx ashiba perf run --query src/features/users/queries/list/list.sql --dry-run

npx ashiba perf scenario init

Scaffold a manual traditional DB-backed tuning scenario.

Use when: Record target row counts, response-time requirements, timeout policy, and sandbox/adopted index boundaries.

CLI Help

Usage: ashiba perf scenario init [options]

Scaffold a manual traditional DB-backed tuning scenario

Options:
  --scenario <name>            Scenario name
  --query <path>               Visible SQL file measured by this scenario
  --target-rows <table=count>  Expected table row count, repeatable (default:
                               [])
  --max-duration-ms <number>   Target response time in milliseconds
  --timeout-ms <number>        Measurement timeout in milliseconds (default:
                               "30000")
  --root-dir <path>            Project root directory (default: ".")
  --dry-run                    Print the files that would be created without
                               writing them (default: false)
  --force                      Overwrite scenario files when they already exist
                               (default: false)
  --format <format>            Output format: text or json (default: "text")
  -h, --help                   display help for command

Catalog use case:
  Record target row counts, response-time requirements, timeout policy, and sandbox/adopted index boundaries.

Examples:
  npx ashiba perf scenario init --scenario users-list --query src/features/users/queries/list/list.sql --target-rows public.users=100000

npx ashiba perf scenario measure

Record timing evidence and AI-oriented tuning guidance.

Use when: Return duration, timeout, requirement status, execution-plan evidence path, and next actions without making tuning decisions.

CLI Help

Usage: ashiba perf scenario measure [options]

Record timing evidence and AI-oriented tuning guidance

Options:
  --scenario <name>       Scenario name
  --duration-ms <number>  Observed query duration in milliseconds
  --timed-out             Mark the measurement as timed out (default: false)
  --explain <path>        Execution plan evidence file produced by the tuning
                          session
  --evidence-name <name>  Stable evidence file name, without extension
  --root-dir <path>       Project root directory (default: ".")
  --dry-run               Return evidence without writing the measurement file
                          (default: false)
  --format <format>       Output format: text or json (default: "text")
  -h, --help              display help for command

Catalog use case:
  Return duration, timeout, requirement status, execution-plan evidence path, and next actions without making tuning decisions.

Examples:
  npx ashiba perf scenario measure --scenario users-list --duration-ms 42 --explain tmp/perf/users-list-explain.json

npx ashiba perf report diff

Compare saved performance reports and evidence completeness.

Use when: Review whether a tuning change improved representative query duration.

CLI Help

Usage: ashiba perf report diff [options] <baseline> <candidate>

Compare saved performance reports and evidence completeness

Options:
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Review whether a tuning change improved representative query duration.

Examples:
  npx ashiba perf report diff perf/baseline.json perf/candidate.json

npx ashiba rfba inspect

Inspect feature/query review boundaries.

Use when: Confirm the project still exposes reviewable feature boundaries and query.ts files.

CLI Help

Usage: ashiba rfba inspect [options]

Inspect feature/query review boundaries

Options:
  --root-dir <path>  Project root directory (default: ".")
  --format <format>  Output format: text or json (default: "text")
  -h, --help         display help for command

Catalog use case:
  Confirm the project still exposes reviewable feature boundaries and query.ts files.

Examples:
  npx ashiba rfba inspect